GitHub Browse tools

cox documentation

One event stream behind every surface.

cox is a modular terminal coding agent in Rust. One core state machine turns submissions into typed events; the same stream powers the TUI, headless runs, editor clients (ACP), and MCP.

Start with Getting started About cox

12 pages from pyrlyn/cox/docs at 8dbc1da, in development

  1. Build 
    mise exec -- cargo build -p cox
  2. Check 
    ./target/debug/cox doctor
  3. One turn 
    ./target/debug/cox -p "create hello.txt containing hi"
  4. TUI 
    ./target/debug/cox

How it works

From install to first result.

  1. Build it

    Rust is pinned with mise. Prefer mise exec -- cargo … over a global toolchain.

    git clone https://github.com/pyrlyn/cox && cd cox
mise exec -- cargo build -p cox

  2. Add a key and check

    Export ANTHROPIC_API_KEY (or OPENAI_API_KEY) and run cox doctor — green except prices? You are good.

    ./target/debug/cox doctor

  3. Run a turn

    cox opens the TUI: Enter sends, Esc interrupts. y / s / n answer approval prompts, /model switches tiers, /compact compacts context now.

    ./target/debug/cox

  4. Script it

    cox run -p is the headless form. --output-format stream-json prints the same Event JSON the TUI renders, one object per line.

    ./target/debug/cox run -p "summarise the diff" --output-format stream-json

How it works

Submission in, events out.

A Submission goes into a pure core state machine, a sequence of Events comes out, and every surface renders that same sequence: the TUI, headless cox run -p, the ACP editor server, the MCP server, the JSONL rollout on disk, and the test suite.

Everything the core needs from outside — models, files, shells, stored sessions — arrives through traits (Provider, Tool, Store, Hook, Archive), which is what makes the loop testable without a model.

{"type":"tool_call_requested","call":{"name":"write","input":{"path":"hello.txt","content":"hi\n"}}}
{"type":"tool_call_done","call_id":"…","result":{"ok":true,"visible":"wrote 3 bytes to hello.txt","bytes":3}}
{"type":"text_delta","text":"Created hello.txt."}
{"type":"turn_done","stop":"end_turn"}
The events of one turn, from How it works

Paths into the docs

Pick where to go next.

Scriptable exit codes

Headless runs report what happened.

Exit codeMeaning
0ok
1error
2denied — a call the policy would ask about was refused
3budget
4interrupted

Questions the docs answer

Good to know.

Can I use cox from my editor?

Yes. cox acp serves cox over the Agent Client Protocol on stdio — the same Event stream as the TUI, so prompts, tool calls, approvals and diffs show up in Zed, JetBrains or Neovim.

How are approvals handled in scripts?

Under the headless default (--approve never), a Write/Exec call the policy would ask about is denied instead, with the reason in the tool result so the model can try another approach; the run exits 2.

What happens to large tool output?

Every tool writes untruncated output to the archive first; the model sees the capped visible form plus an expand pointer.

Where do costs show up?

Costs land in cox stats, and the status line shows the session spend against the session cap (budget.session_usd).

Next steps

Read these first.

  1. Getting started cox is a modular terminal coding agent in Rust. One core state machine turns submissions into typed events; the same stream powers the TUI, headless runs, editor clients (ACP), and MCP.
  2. How it works One idea explains cox: a Submission goes into a pure core state machine, a sequence of Events comes out, and every surface renders that same sequence.
  3. Configuration Every cox configuration key with its default value, generated from config/default.toml.