codexm

codexm launches multiple Codex CLI instances with separate Git worktrees, identities, configuration, session state, and logs. It is Windows-first and has no base runtime dependencies beyond PowerShell, Git, and Codex CLI.

Its optional control plane adds contract-first LangGraph orchestration, a real-time agent event bus, explicit ontology and uncertainty boundaries, Weighted Value of Information diagnostics, and a React Flow interface with avatar text and browser voice conversations.

Why

Running several agents in one checkout invites branch collisions, overwritten files, and confused context. codexm gives every instance:

• its own Git branch and worktree;
• an isolated CODEX_HOME for configuration and sessions;
• a durable identity prompt;
• independent model and reasoning settings;
• optional unattended execution;
• a predictable state directory that stays out of Git.

Quick start

git clone https://github.com/fieldproofhq/codexm.git
cd codexm
./codexm.ps1 doctor

./codexm.ps1 add backend -Repo C:\src\my-app `
  -Identity 'Own backend code, migrations, and API tests.' `
  -Model gpt-5.6-sol -Reasoning high -Auto

./codexm.ps1 add frontend -Repo C:\src\my-app `
  -Identity 'Own UI code and browser tests.'

./codexm.ps1 start backend -Prompt 'Implement the next API milestone.'
./codexm.ps1 start frontend -Prompt 'Build the matching user interface.'
./codexm.ps1 list

# Launch the runtime and visual control plane
npm install
./codexm.ps1 serve

start opens a new PowerShell window by default. Use -NoTerminal to run interactively in the current terminal. Use run for non-interactive codex exec jobs:

./codexm.ps1 run backend -Prompt 'Run tests, fix failures, and commit the result.'

Arguments after -- are passed to Codex:

./codexm.ps1 start backend -- --search

Commands

Command	Purpose
init	Create the local runtime directories.
add NAME -Repo PATH	Create a branch, worktree, identity, and isolated Codex home.
start NAME	Launch an interactive Codex session.
run NAME -Prompt TEXT	Run a non-interactive Codex job.
serve	Start the LangGraph runtime, live Codex workers, event bus, and React Flow UI.
list	Show managed instances.
remove NAME	Remove a clean worktree and runtime state; preserve its branch.
doctor	Check required tools and state-directory access.

By default, instance state lives in .codexm/. Set CODEXM_HOME to place it elsewhere:

$env:CODEXM_HOME = 'D:\codexm-state'

Identities and authentication

Identity text is injected into every launch and stored beside the instance metadata. Each instance has an independent CODEX_HOME; codexm never copies API keys, auth files, or other credentials. If your Codex installation does not use the OS credential store, run codex login with that instance's CODEX_HOME before launch.

Instances named for personas (orchestrator, diagnostician, builder, or critic) automatically subscribe as live workers when serve starts. They can invoke one another through POST /api/invoke, stream correlated output over WebSocket, and execute only validated task contracts through the LangGraph workflow.

See the architecture for contracts, graph flow, ontology, uncertainty policy, Weighted VoI, and scaling trade-offs.

Safety

Without -Auto, instances use workspace-write and ask for approval when needed. -Auto writes approval_policy = "never" and sandbox_mode = "danger-full-access" into that instance's config. This is intentionally unrestricted and should only be used on machines and repositories you trust.

remove refuses to remove a dirty worktree unless -Force is supplied. It never deletes the instance branch.

Development

./tests/smoke.ps1

MIT licensed.