https://github.com/BRONZowl/codux.nvim
Persistent OpenAI Codex workflows for Neovim. OpenAI Codex integration for Neovim with persistent sessions, workspaces and token monitoring.
https://github.com/BRONZowl/codux.nvim
ai ai-tools codex codux codux-nvim developer-tools lazyvim lua neovim neovim-plugin nvim openai openai-codex productivity terminal tmux vim
Last synced: about 5 hours ago
JSON representation
Persistent OpenAI Codex workflows for Neovim. OpenAI Codex integration for Neovim with persistent sessions, workspaces and token monitoring.
- Host: GitHub
- URL: https://github.com/BRONZowl/codux.nvim
- Owner: BRONZowl
- License: mit
- Created: 2026-06-13T14:43:57.000Z (12 days ago)
- Default Branch: main
- Last Pushed: 2026-06-21T12:42:59.000Z (4 days ago)
- Last Synced: 2026-06-21T14:28:14.273Z (4 days ago)
- Topics: ai, ai-tools, codex, codux, codux-nvim, developer-tools, lazyvim, lua, neovim, neovim-plugin, nvim, openai, openai-codex, productivity, terminal, tmux, vim
- Language: Lua
- Homepage:
- Size: 18.2 MB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-neovim - BRONZowl/codux.nvim - Run OpenAI Codex in a persistent floating terminal and send files, selections, diagnostics, or file explorer targets. (AI / Diagnostics)
- awesome-ccamel - BRONZowl/codux.nvim - Persistent OpenAI Codex workflows for Neovim. OpenAI Codex integration for Neovim with persistent sessions, workspaces and token monitoring. (Lua)
README
⭐ If codux.nvim helps your workflow, consider starring the repo — it helps other Neovim users discover it.
What is Codux?
Codux is a Neovim plugin that runs OpenAI Codex inside a persistent floating terminal.
Unlike chat-style AI plugins, Codux keeps you connected to a real Codex CLI session.
Send files, visual selections, diagnostics, Git diffs, and file explorer targets directly from Neovim without leaving your editor.
Close the window at any time; the Codex session keeps running in the background.
Codux helps preserve and organize Codex context so you waste fewer tokens rebuilding prompts.
Why Codux?
Persistent Codex sessions
Floating terminal workflow
Built-in token monitoring
Native Neovim experience
No context loss between prompts
Why not just use Codex in a terminal?
Using Codex in a separate terminal works, but it means:
Switching between editor and terminal
Losing focus while reviewing changes
Managing window layouts manually
No editor-native visibility into token usage
codux.nvim keeps your Codex workflow inside Neovim with:
Persistent sessions
Floating terminal integration
Built-in token monitoring
Fast toggling between code and AI
Codux Workspaces with tmux
Large development tasks rarely involve a single conversation.
With tmux, you can dedicate a Codux session to a specific objective and keep that context alive while you work.
Window 1 - Feature Development
Implementing a new gameplay system
Codux focused on design decisions, code generation, and implementation details
Window 2 - Code Review
Reviewing your current branch
Codux focused on bugs, edge cases, performance issues, and refactoring opportunities
Window 3 - Debugging
Investigating a failing test or runtime issue
Codux focused on logs, diagnostics, stack traces, and root-cause analysis
Window 4 - Architecture
Planning larger changes
Codux focused on project structure, APIs, and long-term design decisions
Each Codux session maintains its own conversation and context.
Instead of constantly changing topics within a single AI conversation, you can keep dedicated Codux sessions attached to specific workflows and switch between them instantly with tmux.
Use :CoduxWorkspaceCreate or <leader>zw inside tmux to create a guided Codex workspace.
The create flow prompts for a name, opens the Vim-like instruction editor, then previews the instruction before launch.
New workspace windows launch in the current file or explorer target's project root, so the workspace follows the same worktree and branch as the code you are working on.
Inside tmux, Codux creates or reuses a backend-debug window in the current tmux session, restores Neo-tree to the same target when available, and starts new workspaces with your current Codex permission profile.
Reopened saved workspaces keep their stored profile.
Template workspaces use the requested workspace name for the tmux window.
New template and custom-instruction workspaces open the Codux popup so you can confirm the startup prompt is running.
Workspace names are persisted per project in stdpath("data")/codux/workspaces.json.
Creating a workspace with an existing name shows workspace already exists.
Use :CoduxWorkspaces or <leader>zW to open current codux workspaces.
From that window, press <CR> to open a saved workspace, r to rename it, e to edit its saved template, d to delete it, or h to run doctor.
Statuses show active, inactive, or missing.
The target column updates as each workspace moves between files or supported file explorer targets.
Outside tmux, Codux shows no tmux session running and does not create a workspace.
Workspace names are user-defined and sanitized for tmux window safety.
Empty names and sanitized-name collisions are rejected with a clear error.
Workspace Templates
New workspaces default to custom instructions, and explicit templates remain available for repeatable task-specific starts:
```vim
:CoduxWorkspaceCreate token-review
:CoduxWorkspaceCreate fix-tests --template debug
:CoduxWorkspaceCreate add-feature --template implementation
:CoduxWorkspaceCreate review-pr --template review
```
Templates provide task-specific starting instructions for Codex without starting autonomous loops.
New workspaces default to custom instructions; pass --template <template> to create a workspace from a built-in, configured, or saved template.
The guided create preview lets you press <CR> to create, e to edit the instruction for just this workspace, or q to cancel.
Custom instructions open in a Vim-like multi-line scratch editor with bottom command hints; use :w to save or :q to cancel.
Saved custom instructions become reusable templates named after the workspace and appear in future template lists.
A newly created template workspace opens Codux visibly for confirmation; regular workspaces keep the hidden startup behavior.
Built-in templates include implementation, debug, review, planning, and docs.
Codux stores the resolved startup instruction with the workspace so future template edits do not change what that workspace was created with.
```lua
require("codux").setup({
workspaces = {
templates = {
release = "You are working in a release workspace. Focus on verification, notes, and final checks.",
},
},
})
```
Use :CoduxTemplateList and :CoduxTemplatePreview <template> to inspect available templates.
Use :CoduxTemplateDelete <template> to remove a saved template or hide a built-in/configured template from future template lists.
Long-form commands are also available: :CoduxWorkspaceTemplateList, :CoduxWorkspaceTemplatePreview, and :CoduxWorkspaceTemplateDelete.
Workspace and template commands support tab completion.
Workspace Restore and Doctor
Use :CoduxWorkspaceRestore to reconcile saved workspace state with tmux after restarts.
Use :CoduxDoctor, or press h in the workspace dashboard, when troubleshooting external dependencies and saved workspace targets.
## Manual Install
1. Add codux.nvim with lazy.nvim or LazyVim:
```lua
{
"BRONZowl/codux.nvim",
opts = {},
}
```
2. Run `:Lazy sync`, restart Neovim, then open Codux:
```vim
:Codux
```
In LazyVim, `` is usually Space. Codux also maps open to `zc`.
3. Install the Codex CLI and sign in if `codex` is not already available:
```bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex login
```
Confirm the CLI is available:
```bash
codex --version
```
4. Open a project and verify the setup:
```bash
cd ~/Projects/your-project
nvim
```
```vim
:checkhealth codux
:Codux
```
Or just have Codex do it.
Ask Codex: Install BRONZowl/codux.nvim in my LazyVim config.
## Requirements
- Neovim with terminal and floating window support
- OpenAI Codex CLI available as `codex`
- lazy.nvim or LazyVim
Optional:
- which-key.nvim for the `z` group label
- tmux for `:CoduxWorkspaceCreate `
- Neo-tree, Oil.nvim, nvim-tree, or mini.files for file explorer targets
This plugin was developed using Neo-tree in LazyVim.
Windows users can use WSL2 with the Linux install command above, or follow the official Codex Windows setup guide.
For remote or headless login:
```bash
codex login --device-auth
```
Codux sends requested files, selections, diagnostics, and health output through your configured Codex CLI session.
Usage
Action
Key
Command
Open or focus Codex
<leader>zc
:Codux
Open Codex autopilot with approve-for-me permissions
<leader>za
:CoduxOpenAuto
Open Codex danger zone with no sandbox
<leader>zA
:CoduxOpenDanger
Create a guided tmux workspace
<leader>zw
:CoduxWorkspaceCreate
Manage current Codux workspaces
<leader>zW
:CoduxWorkspaces
Send current file or explorer node
<leader>zf
:CoduxReview
Send selected code
<leader>zs
:'<,'>CoduxReviewSelection
Send diagnostics and health output
<leader>zd
:CoduxDiagnostics
Send Git changes
<leader>zg
:CoduxDiff
Toggle Codex plan mode
<leader>zp
:CoduxTogglePlan
Hide the popup
<C-q>
:CoduxClose
Start typing after scrolling
Type normally
Stop Codex
:CoduxExit
Troubleshoot Codux setup
h in workspace dashboard
:CoduxDoctor
:CoduxOpenDanger starts Codex with no approval prompts and no sandbox. Use it only in repositories you trust.
Token Monitoring
The <leader>z menu header shows the current Codux-tracked status and token usage while Codux is running:
codux execute | 5hr 3% | wk 5%
codux plan | 5hr 3% | wk 5%
Token monitoring refreshes in the background only while Codux is running. The popup can be hidden, but the Codex session must still be active. If usage is unavailable while Codux is running, Codux shows --% placeholders. Status text is green for execute, purple for plan, and red when Codex is not running.
When Codex is actively working and the popup is hidden, Codux shows a small codex is working... indicator near the bottom-right of the editor. The indicator clears when Codex goes idle, is interrupted, or exits.
Roadmap
codux.nvim is focused on persistent, organized Codex context rather than autonomous background loops.
Upcoming work will focus on remaining saved template management, including renaming reusable workspace prompts.
Future task-run features should stay bounded and human-approved, with explicit step limits, visible token awareness, and pauses before continuing.