codexmux

codexmux launches independent interactive Codex sessions inside a private tmux server, gives them automatic codex-N labels, lets managed sessions exchange deliberate queued messages, and provides a read-only live monitor.

The normal workflow does not require knowing tmux commands or remembering instance names:

$ codexmux
$ codexmux
$ codexmux monitor

Requirements

• Linux or WSL
• Go 1.24 or newer to build
• codex and tmux at runtime

Codexmux never uses sudo, never changes the global Codex configuration, and never touches the user's ordinary tmux server.

Install

From the repository:

./scripts/install.sh

The installer formats-checks, tests, vets, builds, and atomically installs ~/.local/bin/codexmux. That directory must be on PATH; it is already configured on the development host.

Commands

codexmux [CODEX_OPTIONS] [PROMPT]  launch a new managed instance
codexmux resume [SESSION_ID]       resume a saved chat, with a picker by default
codexmux attach [INSTANCE]         attach to a running instance, with a picker by default
codexmux monitor                   open the read-only live dashboard
codexmux send [TARGET] [MESSAGE]   queue a deliberate message

Plain codexmux always starts a new instance. Closing the terminal leaves its tmux-hosted Codex process running; use codexmux attach to recover it without remembering its generated label.

Ordinary Codex arguments are forwarded as-is. If the first argument could be mistaken for a codexmux subcommand, put -- before it:

$ codexmux --model gpt-5.6 "Inspect this checkout"
$ codexmux -- "monitor is the prompt, not a subcommand"
$ codexmux resume 019f...

Each launch receives the lowest free display name (codex-1, codex-2, ...) and an immutable UUID. Names may be reused after exit; history and explicit references remain unambiguous through the UUID.

Monitor guarantees

The monitor observes only codexmux-managed instances. It reads codexmux metadata, managed tmux/process state, and versioned Codex rollout events. Its code path cannot paste text, send keys, interrupt, stop, or attach with write access. The optional raw-pane view uses tmux's read-only attachment mode.

Summaries are deterministic and sanitized. The monitor does not display reasoning, copy transcript text into its own state, or make additional model calls. Unsupported Codex rollout versions degrade individual fields to unavailable instead of guessing.

Monitor keys are j/k (or arrows) to select, enter for detail, f or / to filter, r for an explicit tmux read-only raw view, and q to quit. Exited instances remain visible for seven days.

Peer messaging

Each wrapped Codex process receives an ephemeral local MCP server exposing peer discovery and explicit send tools. Messages are stored in a per-target FIFO and delivered through the normal Codex composer only when its current UI state is recognized as safe. Responses are never relayed automatically.

From a shell, the equivalent deliberate send is:

$ codexmux send codex-2 "Please review the parser changes"
$ printf 'Please review the parser changes\n' | codexmux send codex-2

When the target is busy, Codex's native Tab queue receives the prompt. During an approval dialog, picker, draft, or unrecognized TUI version, the broker keeps the envelope queued. If the target exits first, the envelope is marked failed instead of being retried silently.

Runtime data

Codexmux uses the private tmux socket tmux -L codexmux; it never lists or modifies sessions on the default tmux server. Versioned instance and message records live under ${XDG_STATE_HOME:-~/.local/state}/codexmux, while locks use ${XDG_RUNTIME_DIR}/codexmux or the secured fallback /tmp/codexmux-$UID. The monitor opens those records passively and does not create, prune, or update them.

Development

Read PLAN.md and AGENTS.md before changing behavior.

gofmt -w $(find . -type f -name '*.go')
go test ./...
go vet ./...
git diff --check