Skip to content

PLAN.md

Latest commit

 

History

History
54 lines (43 loc) · 5.21 KB

PLAN.md

File metadata and controls

54 lines (43 loc) · 5.21 KB
Raw

Codexmux v1 Plan

Summary

Build codexmux as a Linux/WSL-focused Go application that:

  • Launches every interactive Codex instance inside an isolated tmux server.
  • Assigns the lowest available label automatically: codex-1, codex-2, etc.
  • Provides explicit agent-to-agent messaging through injected MCP tools.
  • Provides a strictly read-only live monitor for managed instances.
  • Installs user-globally as ~/.local/bin/codexmux; no sudo or global Codex configuration changes.
  • Retains exited-instance metadata and sanitized summaries for seven days.

Bootstrap and public interfaces

  1. Initialize this directory as a Git repository before application code.
  2. Keep this plan and AGENTS.md at the repository root as the controlling implementation documents.
  3. Build one Go binary with these public commands:
    • codexmux [interactive Codex options/prompt]: always launch and attach a new managed instance while forwarding ordinary interactive Codex arguments.
    • codexmux resume [SESSION_ID]: resume through Codex's picker when omitted or use an explicit saved-session ID.
    • codexmux attach [INSTANCE]: attach to an existing managed instance, using a picker when omitted.
    • codexmux monitor: open the live, strictly read-only dashboard.
    • codexmux send [TARGET] [MESSAGE]: human-facing message delivery with target picker and stdin support.
    • Internal MCP, supervisor, and relay modes remain hidden from ordinary help.
  4. Provide scripts/install.sh to test, vet, build, and atomically install into ~/.local/bin without privilege escalation.

Runtime and messaging

  • Run managed sessions on a dedicated tmux -L codexmux server so ordinary tmux sessions are never inspected or modified.
  • Give each instance an immutable UUID and an automatic codex-N display label. Reuse the lowest free number after an instance exits; disambiguate history with UUID, timestamps, cwd, and state.
  • Run a supervisor inside each tmux session. It launches Codex, records PID/version/cwd/start and exit times, discovers root and subagent rollout paths through /proc/<pid>/fd, and preserves work when the original terminal disconnects.
  • Inject the installed binary as an ephemeral per-launch MCP server using Codex -c overrides; never edit the user's global Codex configuration.
  • Expose list_instances and send_message MCP tools. Relay only deliberate messages.
  • Persist per-target FIFO message envelopes. For a supported Codex version and recognized normal composer, deliver with sanitized bracketed paste followed by Tab. Hold messages during approval dialogs, pickers, nonempty drafts, or unrecognized UI states.
  • Serialize delivery per target and strip terminal-control bytes. If a target exits before delivery, mark the envelope failed and require an explicit resend.

Read-only monitor

  • Keep monitor code behind a read-only observer interface. It may list/display/capture managed tmux panes, inspect process metadata, and open registry/rollout files read-only. It must not invoke send, paste, interrupt, attach-writable, stop, or kill operations.
  • Do not connect the monitor to Codex app-server in v1. Parse managed rollouts through a versioned adapter initially supporting installed codex-cli 0.144.x; tolerate unknown records and display unavailable fields plus a compatibility warning rather than guessing.
  • Default table: NAME | STATE | CWD | UP | MODEL | TOKENS | AGENTS | NOW, with a detail view for current work, recent completed work, sanitized result excerpts, token breakdown, subagent state, and pending/failed messages.
  • Make summaries deterministic and local. Exclude reasoning, raw command output, and likely credentials; make no additional model calls and persist no copied transcript text.
  • For resumed chats, emphasize tokens consumed since the codexmux launch baseline and show lifetime usage secondarily.
  • Calculate aggregate usage as the root delta plus each descendant's post-spawn delta, avoiding inherited-history double counting.
  • Offer an explicit raw-screen view through tmux's read-only attach mode. Monitor navigation may select, filter, refresh, view detail, or quit, but never mutate Codex state.
  • Show active instances first and retain exited records for seven days. The monitor hides expired entries without writing; launcher/supervisor maintenance prunes them.

Verification and acceptance

  • Unit-test concurrent name allocation/reuse, registry locking, retention, message FIFO/failure behavior, sanitization, redaction, partial JSONL records, unknown events, token baselines, and nested subagent accounting.
  • Integration-test new launch, argument forwarding, resume, detach persistence, picker attach, normal/failed exits, idle/busy message delivery, unsafe-state deferral, FIFO ordering, MCP peer discovery, and monitor read-only enforcement against an isolated test tmux socket.
  • Add sanitized 0.144.x rollout fixtures covering active/completed work, model changes, token updates, interrupted turns, and nested subagents.
  • Run gofmt, go test ./..., go vet ./..., and git diff --check.
  • Install through scripts/install.sh, verify resolution outside the repository, then smoke-test two disposable managed sessions, monitor metrics, queued delivery, terminal disconnect/reattach, and one saved-chat resume.