Codex (limited)

Technical chapter.codex raw

Codex is OpenAI's coding CLI. It is supported, not the main harness: Claude Code is the harness the rest of this handbook assumes, and this section holds only what differs when you run Codex instead. Read Start here first; its Step 2 has a Codex variant, shown below this chapter.

What a Codex seat is

A Codex seat is the native codex binary running in a herdr pane. It carries the UCC skills through one symlink and reaches the daemon through Codex's own hooks, so after its first turn it has a card and a live row in the fleet like any other seat. What it does not have is the Meridian MCP server: no put, no sql, no board or memo writes, no fleet verbs. Its record access is mrd read, its output is a report file, and its human contact is a Codex tool, not the fleet's Telegram path.

flowchart LR
  you[You] -->|herdr agent start --kind codex| seat[Codex seat]
  seat -->|hooks.json| daemon[ccc-statusd]
  daemon --> card[Card + fleet row]
  seat -->|mrd read root:path| root[(Sessions root)]
  seat -->|curl, with network_access| pages[page.sui.pics records]
  seat --> report[Report file]
  seat --x|no put, no sql, no ccc-agent| root

Two directions share the name, so keep them apart:

The recommended way to take part in the fleet is the second row: a UCC gateway profile is a Claude Code seat on your ChatGPT-backed model and gets every Meridian tool. Native Codex is for when you want Codex itself.

What is installed for Codex

The skills link goes into ~/.codex/skills, never over it: ~/.codex/skills is a real directory holding Codex's own skills. Codex reads skills at session start, so a skill added to the tree is visible to the next codex, not the running one. Instructions come from AGENTS.md, never CLAUDE.md, found by walking up from the pane's working directory — start the pane in the tree you are working on, not in a wiki or sessions directory.

hooks.json accepts only description and hooks at the top level. One foreign top-level key makes Codex refuse the whole file with a single startup line, and then no hook runs at all — no card, no fleet row, no dialog.

The network setting

Codex runs commands in a sandbox. Under sandbox_mode = "workspace-write" the sandbox has no network: a prompt that names a URL fails with curl: (6) Could not resolve host. The key that opens the network and nothing else is:

[sandbox_workspace_write]
network_access = true

in ~/.codex/config.toml (the same key per invocation: codex -c sandbox_workspace_write.network_access=true). Every handbook prompt ends with the web address it lives at, which the seat re-reads, so set it before your first session. sandbox_mode = "danger-full-access" also passes but grants far more than a fetch needs. Codex's own web tool is not the path that carries these fetches; curl in the sandboxed shell is, and that is exactly what this key governs.

Starting a seat

A native seat starts inside herdr, never through ccc-agent spawn (it appends --session-id, which Codex refuses) and never through a ucc-codex* wrapper (that is Claude Code on a proxy). The pane sequence, run from any herdr pane:

herdr pane split --current --direction right --cwd <tree under work> --no-focus \
  --env HERDR_AGENT= --env UCC_PROFILE= --env CLAUDE_CONFIG_DIR= --env CCC_ROLE= --env CCC_CARD_SEED=
herdr agent start <name> --kind codex --pane <pane id>
herdr agent read <name> --source visible          # a dialog may be up
herdr agent prompt <name> "<one sentence>" --wait --timeout 180000
herdr agent get <name>                            # .result.agent.agent_session.value = the Codex session id
herdr pane close <pane id>

The name matches [a-z][a-z0-9_-]{0,31}. Clearing the five environment variables matters: empty reads as absent, so the card is born role: worker with no leaked seed.

Two dialogs can sit on the screen while herdr agent start already reports interactive_ready: true, so read the pane after every start:

• Hooks need review — N hooks are new or changed, once per host and again whenever a hook entry's bytes change. Answer option 2, Trust all and continue: herdr agent send-keys <name> down enter. Option 3 persists nothing and asks again next time.
• Do you trust the contents of this directory?, once per directory Codex has not seen. Answer option 1, Yes, continue: herdr agent send-keys <name> enter.

Codex signs in with your ChatGPT account through its own sign-in, not through /login.

Identity

SessionStart fires at the first prompt, not at process start. Until the seat's first turn there is no card, no id in herdr agent get and no row in ccc-agent list --table. After it, the seat is a daemon/live/worker row.

Codex session ids are UUIDv7. The short id is the last 8 hex characters, not the first 8: the first 8 are a timestamp every seat born in the same minute shares.

What the seat can and cannot do

Can:

• Read any record — mrd read 'sessions:<path>' (the root-qualified form works from any working directory), --section <n> for one section. The transcript in the Codex variant of Step 2 below shows it.
• Fetch a handbook record by URL with curl, once the network key is set.
• Be a fleet seat — card, daemon row, the developer-message context the daemon injects each turn.
• Ask its own user and run its own sub-agents through Codex-native tools (request_user_input; the collaboration.* family). These reach Codex only: they are not fleet verbs and do not reach the fleet's Telegram relay.
• Write a report file in its working directory. That file is the proof of its work.

Cannot:

• Write any record. There is no Meridian put tool in the seat — no memos, cards, rosters, board moves. The mrd CLI's write doors refuse or need a workspace the pane does not sit in; an able model driving it landed nothing in four attempts.
• Use any ccc-agent verb (spawn, send, screen, transcript, wait, get, list, kill) or any lifecycle verb (session killme, restart, forkme, schedule). Its exit is the spawner's herdr pane close.
• Reach the fleet's AskUserQuestion-to-Telegram path or receive hook sensors (tokens>, idle>, auq>). A question for a human that its own tool cannot settle becomes an open item in the report.
• Be prompted from outside except by herdr agent prompt. A ccc-statusd session send from its shell arrives as from="cli", so the reply line must carry the agent name and the report path.

skill: ccc-native — the seat's own contract: its verbs, its must-not list, the reply protocol, and references/codex.md for every setup detail above.

Step 2 — First session (Codex)

Technical step.02-first-session.codex raw

This record holds only what differs from Step 2 of Start here when the harness is Codex. Everything not named here is the same.

What you will see. There is no ucc-<profile> launcher and no /login: Codex is signed in through its own ChatGPT sign-in, and the seat starts inside a herdr pane with herdr agent start --kind codex. Before the first prompt Codex may show one or both trust dialogs — Hooks need review (once per host) and Do you trust the contents of this directory? (once per directory) — while herdr already reports the seat ready. There is no joined … as agent … banner you can read on screen: the daemon's context lands as a hidden developer message the model will not quote, so the proof of a joined seat is read from outside the pane. Every handbook prompt ends with the web address it lives at, which the seat re-reads; that needs [sandbox_workspace_write] network_access = true in ~/.codex/config.toml (the Codex chapter above explains the key).

Do.

1. Confirm the three pieces once: readlink ~/.codex/skills/ucc prints $UCC_HOME/shared/skills; grep -c '"_ccc"' ~/.codex/hooks.json prints 3; grep -n 'network_access = true' ~/.codex/config.toml prints one line. Missing pieces are the chapter's table.

2. From a herdr pane, in the directory you will work in:

   herdr pane split --current --direction right --cwd "$PWD" --no-focus \
     --env HERDR_AGENT= --env UCC_PROFILE= --env CLAUDE_CONFIG_DIR= --env CCC_ROLE= --env CCC_CARD_SEED=
   herdr agent start first --kind codex --pane <pane id from the split>
   herdr agent read first --source visible
   

   If the screen shows Hooks need review, answer option 2: herdr agent send-keys first down enter. If it shows Do you trust the contents of this directory?, answer option 1: herdr agent send-keys first enter.

3. Send the first turn as one sentence — type it in the pane, or from another terminal:

   herdr agent prompt first "Read https://page.sui.pics/d/handbook-c3002f99fc0fee31/release?raw=1 and print what it says." --wait --timeout 180000
   

   A pass prints a short JSON line with "version" and "label" fields. curl: (6) Could not resolve host: page.sui.pics means the network key is not set — set it and start a new seat; the running one keeps its old sandbox.

4. Ask the seat to read a record your own root holds — its card, which the daemon wrote at the first turn: Run mrd read 'sessions:agents/<short-id>/<short-id>.md' and print the toc. — where <short-id> is the last 8 hex of the seat's Codex session id, the id herdr agent get first prints under agent_session (the verify: line below reads the same field). It answers with path:, file_rev:, words: and the toc[…] rows; --section 1 serves a section's body. There is no write: the seat has no put tool, and the handbook's prompts are written for a Claude Code seat that has one. On Codex, treat every prompt record as reading material and carry out its shell commands yourself.

What this agent cannot do, in one line each: write a record (no memo, card, roster or board move); run any ccc-agent or session killme/restart/forkme/schedule verb; reach the fleet's AskUserQuestion-to-Telegram path — it can ask you only through Codex's own request_user_input, and it can spawn only Codex's own sub-agents, never fleet seats. Findings go into a report file, which is its proof.

verify: after the first turn, outside the pane: ccc-agent list --table | grep -c "$(herdr agent get first | python3 -c 'import json,sys;print(json.load(sys.stdin)["result"]["agent"]["agent_session"]["value"])')" — pass prints 1: the seat's row, with the full Codex session id under AGENT_ID, daemon under SOURCE and live under LIVENESS (its short id on the card is the last 8 hex of that id). Then herdr pane close <pane id>.

skill: ccc-native — the seat's contract, with references/codex.md for the setup and the trust dialogs.