---

Features

• Persistent sessions — Open a floating agent terminal, hide it, keep coding; the process keeps running until you exit it.
• Codex + Grok, first-class — One plugin surface for both CLIs: open, workspaces, missions, profiles, and status.
• Editor-native context — Send the current file, visual selection, diagnostics, or Git diff straight into the active agent.
• Permission profiles — Start with default, auto, or full access; new sessions default to plan mode for safer iteration.
• Codux workspaces — tmux-backed windows with isolated Git worktrees, instruction files, and saved state per stream of work.
• Mission Control — Launch multi-role crews around a shared objective, with a live dashboard, Manager coordination, and focus packets.
• Token & status monitoring — Live Codex rate windows in the which-key header without inference requests.
• Doctor & health — :checkhealth codux and :CoduxDoctor for CLI, tmux, and workspace diagnostics.

---

Requirements

Requirement	Notes
Neovim	Terminal + floating window support
Agent CLI	OpenAI Codex (codex) and/or xAI Grok (grok)

Optional

Dependency	Why
which-key.nvim	<leader>z group label + live Codux status header
tmux	Codux workspaces and Mission Control
Neo-tree, Oil.nvim, nvim-tree, or mini.files	Send explorer targets via review commands

Windows: use WSL2 with the Linux CLI install flow. For remote or headless Codex login:

codex login --device-auth

---

Installation

lazy.nvim (recommended)

Works unchanged in LazyVim:

{
  "BRONZowl/codux.nvim",
  opts = {},
}

Manual / other managers

Add codux.nvim to Neovim's runtimepath, then:

require("codux").setup({})

CLI setup

Codex (if codex is not installed):

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex login
codex --version

Grok (official setup):

curl -fsSL https://x.ai/cli/install.sh | bash
grok login
grok version

Restart Neovim, open a project, then verify:

:checkhealth codux
:Codux

---

Quick Start

1. Open the agent with :Codux or <leader>zc.
2. Pick a permission profile when nothing is running yet: d default · a auto · f full access.
3. Hide the popup with :CoduxClose or <C-q> — the agent keeps running.
4. Stop the process only with :CoduxExit.
5. Send context from the buffer you already have open.

Goal	Mapping	Command
Open / focus agent	<leader>zc	:Codux
Set default provider (Grok / Codex)	<leader>zP	:CoduxSetDefaultProvider
Send file / folder / explorer node	<leader>zf	:CoduxReview
Send visual selection	<leader>zs	:'<,'>CoduxReviewSelection
Send diagnostics	<leader>zd	:CoduxDiagnostics
Send Git diff	<leader>zg	:CoduxDiff
Mission Control	<leader>zM	:CoduxMissions
Toggle plan mode (in agent terminal)	<leader>zp	:CoduxTogglePlan

Provider default — Set once with <leader>zP (g Grok, c Codex). Used for open, workspace create, and mission create. Saved under stdpath("data")/codux/settings.json.

Startup precedence (highest wins): setup default_agent_provider → env CODUX_AGENT_PROVIDER → saved preference → "codex".

Session rules worth knowing

• If the popup is already open, :Codux / <leader>zc are a no-op until you hide it.
• Choosing a different default with <leader>zP ends the current agent session. The next :Codux / <leader>zc opens the chosen provider's permission-profile picker.
• If the agent is still running and its provider matches the default, those commands reopen and focus the same session (provider/profile unchanged).
• Mission Control and workspace Switch Profile menus still use a two-step provider + profile picker so roles can differ from the global default.
• Use full access only in repositories you trust. :CoduxOpenDanger / :CoduxOpenGrokDanger start with no approval prompts / no sandbox.

---

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Commands
• Configuration
• Workspaces
• Mission Control
• Token & Status Monitoring
• Troubleshooting
• FAQ
• License

---

Commands

Essentials

Action	Default key	Command
Open or focus agent	<leader>zc	:Codux / :CoduxOpen
Set default agent provider	<leader>zP	:CoduxSetDefaultProvider [codex|grok]
Hide popup (session keeps running)	<C-q> in popup	:CoduxClose
Toggle popup	—	:CoduxToggle
Stop agent process	—	:CoduxExit
Send file / folder / explorer node	<leader>zf	:CoduxReview
Send visual selection	<leader>zs	:CoduxReviewSelection
Send diagnostics + health context	<leader>zd	:CoduxDiagnostics
Send Git diff	<leader>zg	:CoduxDiff
Toggle plan mode	<leader>zp in agent terminal	:CoduxTogglePlan
Mission Control	<leader>zM	:CoduxMissions / :CoduxMissionDashboard
Health / Doctor	h in dashboards	:CoduxHealth / :CoduxDoctor

Providers & profiles

Action	Command
Open Codex (auto profile)	:CoduxOpenAuto
Open Codex (full access)	:CoduxOpenDanger
Open Grok	:CoduxOpenGrok
Open Grok (auto)	:CoduxOpenGrokAuto
Open Grok (full access)	:CoduxOpenGrokDanger
Open specific provider + profile	:CoduxOpenProvider <codex|grok> <default|auto|danger>
Preferred Grok TUI theme	:CoduxSetGrokTheme [theme]

Workspaces

Action	Command
Create workspace	:CoduxWorkspace / :CoduxWorkspaceCreate
Workspace dashboard	:CoduxWorkspaces
Open / select / rename / delete	:CoduxWorkspaceOpen · :CoduxWorkspaceSelect · :CoduxWorkspaceRename · :CoduxWorkspaceDelete
Restore state from tmux	:CoduxWorkspaceRestore
Close all workspace windows	:CoduxWorkspaceCloseAll
Ignore local workspace files	:CoduxWorkspaceIgnore

Mission Control

Action	Command
Create mission	:CoduxMissionCreate
Create Grok mission crew	:CoduxMissionCreateGrok
Dashboard	:CoduxMissions / :CoduxMissionDashboard
Edit objective / focus	:CoduxMissionEdit · :CoduxMissionFocus
Process Manager dispatch	:CoduxMissionProcessDispatch
Close / delete mission	:CoduxMissionClose · :CoduxMissionDelete

By default Codux maps core single-session actions and Mission Control only. Workspace create/list mappings are empty by default; every workspace command is still available by name. Plan-mode toggle is buffer-local in the agent terminal (mappings.mode, default <leader>zp), not a global which-key entry.

---

Configuration

Sensible defaults work out of the box. A solid starting point:

require("codux").setup({
  default_initial_mode = "plan",       -- safer default; use "execute" for older behavior
  default_agent_provider = "codex",    -- or "grok"
  providers = {
    codex = {
      default_cmd = 'codex -s workspace-write -a on-request -c approvals_reviewer="user"',
      auto_cmd = 'codex -s workspace-write -a on-request -c approvals_reviewer="auto_review"',
      danger_cmd = "codex -s danger-full-access -a never",
    },
    grok = {
      default_cmd = "grok --sandbox workspace",
      auto_cmd = "grok --sandbox workspace --always-approve",
      danger_cmd = "grok --sandbox off --always-approve",
      -- theme = "tokyonight", -- or :CoduxSetGrokTheme / CODUX_GROK_THEME
    },
  },
  token_monitor = {
    enabled = true,
    refresh_ms = 60000,
    timeout_ms = 5000,
  },
  -- Optional hardening (defaults shown). Do not put API keys in *_cmd strings.
  security = {
    scrub_prompts = false, -- mask common secret patterns in agent prompts
    audit_scrubs = false,  -- redaction counters in :CoduxDoctor / health_info().redact_audit
  },
  workspaces = {
    enabled = true,
    tmux_cmd = "tmux",
    worktree = {
      directory = "../codux-worktrees",
      branch_prefix = "dev/",
    },
    instruction_files = {
      enabled = true,
      directory = ".agents/codux",
    },
  },
})

Nested providers.* is preferred. Legacy top-level codex_cmd, workspace_auto_cmd, and danger_full_access_cmd still work; when both set the same profile, the nested field wins.

Environment overrides

Variable	Profile
CODEX_CMD	Codex default
CODEX_WORKSPACE_AUTO_CMD	Codex auto
CODEX_DANGER_FULL_ACCESS_CMD	Codex full access
GROK_CMD	Grok default
GROK_WORKSPACE_AUTO_CMD	Grok auto
GROK_DANGER_FULL_ACCESS_CMD	Grok full access
CODUX_AGENT_PROVIDER	Default provider seed
CODUX_GROK_THEME	Preferred Grok TUI theme

Grok themes — :CoduxSetGrokTheme (or setup / env) persists under stdpath("data")/codux/settings.json and syncs [ui].theme in ~/.grok/config.toml. Resolution: setup → env → saved preference → existing config. Themes: auto, groknight, grokday, tokyonight, rosepine-moon, oscura-midnight (aliases like dark / tokyo work).

New Codux-managed sessions start in plan mode. Set default_initial_mode = "execute" to restore older execute-mode startup.

---

Workspaces

Codux workspaces are tmux-backed Neovim windows with their own Codex or Grok session, instruction file, Git worktree, target path, provider/profile, and saved state — ideal for parallel streams (implement, review, debug, architecture).

Create one

Run :CoduxWorkspaceCreate inside tmux (add --grok or --codex to force a provider). Codux will:

1. Prompt for a name and permission profile (uses the global default provider unless forced)
2. Open a Vim-like instruction editor and preview before launch
3. Require a clean checkout
4. Create ../codux-worktrees/<workspace> from the current ref
5. Create a dev/<workspace> branch (or the next free namespace, e.g. dev1/<workspace>)
6. Write .agents/codux/<workspace>.md
7. Open a named tmux window and start the agent in plan mode

Grok workspaces keep first-launch CLI args minimal: configured profile command, --rules only when instructions exist, and any initial prompt pasted after the Grok TUI is ready (not as argv).

Outside tmux, creation stops with no tmux session running.

Dashboard & lifecycle

:CoduxWorkspaces opens the workspace dashboard: fuzzy search, <Tab> search/list, j/k, <CR> open, h Doctor, m menu.

Menu: start, rename, edit instructions, switch provider/profile, close, close all, delete.

• Switching profile on an active workspace restarts it with the new Codex/Grok command.
• Switching an inactive workspace updates saved startup profile for next launch.
• Delete removes saved state, instruction file, tmux window, worktree, and branch (destructive).
• When .agents/codux/ is not gitignored, Codux warns — run :CoduxWorkspaceIgnore once per project.

State lives in stdpath("data")/codux/workspaces.json. Non-empty project instruction files override the JSON copy.

---

Mission Control

Mission Control launches one or more Codux workspaces around a shared objective — multi-role agent crews with a live dashboard.

Launch a mission

:CoduxMissionCreate (or :CoduxMissionCreateGrok for a Grok crew): name → provider → profile → objective → preview → launch.

Every new mission creates:

Role	Responsibility
Manager	Owns objective + focus packet; plans and coordinates workers
Agent	Delivers the outcome accurately; keeps context tight; asks only high-impact questions

Add more workers anytime from the dashboard (create role workspace). Custom role lists still get a Manager injected if missing.

Focus packets & Manager dispatch

• Each mission carries a short focus packet (intent, direction, preferences, scope, next action) — separate from stable workspace instructions.
• The Manager can request sibling start/prompt/create via JSON files under
  .agents/codux/missions/<mission>/dispatch/pending/.
• Codux processes pending files while Mission Control is open, or via :CoduxMissionProcessDispatch.
• Ops: start, prompt, start_and_prompt, create_role, update_focus. Success → done/; failure → failed/.

Each role gets a clean Git worktree under ../codux-worktrees/<project>/<workspace>, mission metadata, the chosen provider/profile, and an initial plan-mode prompt. If plan mode cannot be confirmed for a new mission agent, Codux rolls back that workspace.

Dashboard

:CoduxMissions, :CoduxMissionDashboard, or <leader>zM.

Control	Action
Type in search	Fuzzy-filter missions / roles / workspaces
<Tab>	Search ↔ list
j / k	Move rows
<CR>	Focus highlighted mission or role
m	Mission menu (mission row) or workspace menu (role row)
n	Create mission
c	Clean empty Mission Control residue
h	Codux Doctor
<C-o>	Output control for highlighted active role

Output control: type into the agent session; <C-o> returns to the dashboard; <C-q> closes Mission Control; Esc stays with the agent.

Selecting the mission row previews/controls the Manager. Role rows preview that worker. Profile labels include the provider; switching an active role refreshes the output preview after restart.

Close vs delete: Close only closes role windows and preserves worktrees, branches, instructions, and metadata. Delete is destructive (confirmation required).

---

Token & Status Monitoring

With which-key, the <leader>z header shows live Codux status and usage, for example:

codux | 5hr 3% | wk 5%

Codux starts a short-lived codex app-server every 60 seconds and calls only account/rateLimits/read to read the five-hour and weekly account windows. This metadata request does not create a thread, turn, prompt, completion, or model inference, so it does not consume Codex tokens.

Grok usage is intentionally not monitored because xAI exposes the relevant rate-limit headers on inference responses; polling them would consume the API quota being measured. Grok sessions never start a Codux usage-monitor request.

Mission Control can refresh Codex usage without a main-session terminal. The usage line is hidden when a Grok role is selected.

If usage is unavailable, Codux shows --% (Mission Control may append (unavailable)). Inspect:

require("codux").health_info().token_usage.last_error

When an agent is working and the popup is hidden, a small agent is working... indicator appears near the bottom-right of the editor.

Privacy notes (local multi-user hosts)

Codux does not store provider API keys; auth stays with the Codex/Grok CLIs and your environment. Still:

• Initial prompts are pasted into the agent TUI after startup so they do not appear on process argv (ps / /proc/.../cmdline).
• Workspace instructions are written to on-disk instruction files; agent CLIs receive only a short path-based reference on argv (not the full rule body).
• Launch bootstrap scripts keep identifiers only. Prompts, objectives, focus packets, and instruction bodies go in a sibling private .payload.lua (user-only mode, deleted after one read).
• health_info().config is redacted: command fields are reduced to the executable name, and secret-like keys (api_key, tokens, passwords, …) are stripped.
• vim.notify paths mask common secret substrings (sk-…, Bearer tokens, known env assignments).
• Doctor warns if a provider *_cmd looks like it embeds an API key/token (prefer CLI login / standard env vars — do not put secrets in Codux command config).
• Workspace launch scripts, settings, instruction files, and workspace state are written with user-only permissions when the OS allows (rw------- / runtime dir rwx------).
• Runtime sockets and launch files live under stdpath("run") (or another private state/cache dir), not shared /tmp.
• Optional: security.scrub_prompts / security.audit_scrubs (see Configuration) — prompt masking and redaction counters; never log secret values.
• Residual risk: agent terminal buffers and CLI session logs can still contain secrets you paste into prompts; Neovim --listen sockets are local-trust. Prefer trusted single-user machines for agent work. Codux does not control Grok/Codex CLI telemetry — set that in the CLI configs if needed.

---

Troubleshooting

Check	Command / action
Plugin load	:checkhealth codux or :CoduxHealth
Runtime / tmux / workspaces	:CoduxDoctor (also h on dashboards)
Codex CLI	codex --version
Grok CLI	grok version
Stale workspace state after restart	:CoduxWorkspaceRestore

Doctor reports: tmux availability, Codex/Grok availability, workspace state readability/writability, project-root detection, .agents/codux/ ignore status, loaded workspaces, and window state.

Mission dashboards and output previews reconcile moved mission worktrees before using saved paths.

Development

make test

Runs plain Lua specs, headless Neovim specs (--headless -u NONE -i NONE --cmd 'set shadafile=NONE'), LuaJIT syntax loading, plugin setup, and checkhealth codux.

---

FAQ

Does hiding the Codux popup kill my agent?
No. :CoduxClose / <C-q> only hides the floating window. The session keeps running until :CoduxExit.

Is Grok a second-class citizen?
No. Grok is a first-class provider for open commands, permission profiles, workspaces, Mission Control, and theme preference. Usage polling is deliberately Codex-only because Grok monitoring would require inference requests.

Why do new sessions start in plan mode?
Plan mode is the safer default for review-first workflows. Toggle with :CoduxTogglePlan / <leader>zp in the agent terminal, or set default_initial_mode = "execute" if you prefer the older startup behavior.

Why do workspaces / Mission Control require tmux?
Each workspace is a dedicated tmux window with isolated Git worktree and agent session. Outside tmux, workspace creation reports no tmux session running. Single-session :Codux does not require tmux.

What’s the difference between close and delete for missions?
Close shuts role windows but keeps worktrees, branches, instructions, and metadata. Delete is destructive cleanup (with confirmation): worktrees, branches, instruction files, and mission residue.

Full access feels scary — how do profiles work?
Profiles map to CLI sandbox/approval settings (default / auto / full). Prefer default or auto for day-to-day work. Use full-access / danger commands only in trusted repos.

---

License

MIT © 2026 BRONZowl

---