Content
# Codex Conductor
Codex Conductor is a local cockpit, CLI, and MCP server for watching your Codex sessions across projects.
It reads the local Codex transcript trail under `~/.codex/sessions/`, joins it with `~/.codex/session_index.jsonl` when available, and turns scattered runs into a status board grouped by working, open, recent, and idle sessions.
## Why
Codex already stores local transcripts so you can resume work later. Codex Conductor turns those transcripts into operational awareness:
- `codex-conductor` gives you a fast terminal table of recent sessions.
- `codex-conductor up` opens a local cockpit on `127.0.0.1`.
- `codex-conductor mcp` lets an MCP-aware agent ask what is active, what is blocked, and what is left.
- Managed tmux windows let you launch or drive Codex sessions from one board.
- The irreversibility gate refuses unattended deploy, send, delete, and spend approvals.
## Install
```bash
git clone https://github.com/yksanjo/codex-conductor ~/codex-conductor
cd ~/codex-conductor
npm link
```
No build step and no runtime dependencies.
## Usage
```bash
codex-conductor # table of recent Codex sessions
codex-conductor --minutes 120 # widen the lookback window
codex-conductor --all # include older local sessions
codex-conductor --json # structured output
codex-conductor up # local web cockpit
codex-conductor mcp # MCP server over stdio
```
The cockpit binds to localhost. State-changing endpoints require a local origin and the `X-Conductor: 1` header.
## Codex Adapter
The default `codex-code` adapter reads:
- `~/.codex/sessions/YYYY/MM/DD/*.jsonl`
- `~/.codex/session_index.jsonl`
Labels come from the session working directory. Override labels with:
```json
{
"my-project": "My Product",
"codex-conductor": "Codex Conductor"
}
```
Save that as `~/.codex-conductor/labels.json`.
## Managed Codex Windows
Managed windows run inside a dedicated tmux session. This is the reliable control channel for sending replies or keys.
```bash
codex-conductor run review
codex-conductor say review "continue"
codex-conductor attach review
codex-conductor managed
codex-conductor stop review
```
Adopting an existing Codex session opens it with `codex resume <SESSION_ID>` in tmux:
```bash
codex-conductor ls --all
codex-conductor adopt 019f1111 review
```
If you keep the original tab open too, you will have two clients pointed at related work. Close the old tab when you want one control surface.
## MCP
Run the server:
```bash
codex-conductor mcp
```
Useful tools:
- `list_sessions` lists Codex sessions by default.
- `summarize_session` expands one session by id, short id, or label.
- `whats_left` returns inferred goals and recent actions.
- `pending_questions` lists live sessions that appear blocked on a human.
- `auto_continue` sends `continue` only when the irreversibility gate allows it.
- `reply_to_session`, `send_key`, and `run_window` drive managed tmux windows.
Example Codex MCP config:
```toml
[mcp_servers.codex_conductor]
command = "node"
args = ["/Users/you/codex-conductor/mcp.js"]
```
## Development
```bash
npm test
```
The test suite builds a temporary Codex transcript fixture and verifies the Codex-first CLI path plus the irreversibility gate.
## License
MIT
