[claudiusthebot]

Summary

Adds Codex (OpenAI's coding agent CLI, via @openai/codex-sdk) as
a fourth backend alongside Claude SDK / Kilo / OpenCode. Selectable
via backend: \"codex\" in ~/.talon/config.json.

Reference design taken from pingdotgg/t3code as requested. t3code's
effect-codex-app-server package writes its own JSON-RPC client against the
raw Codex app-server protocol. Talon takes the lighter path and uses
the official @openai/codex-sdk which already wraps that protocol
cleanly — fewer LOC and tracks upstream API changes for free.

Architecture

New src/backend/codex/:

• constants.ts — system-prompt suffix + default model (gpt-5-codex).
• state.ts — per-process state container.
• mcp-config.ts — flattens Talon's MCP plugin map into the mcp_servers.<name>.{command,args,env} TOML shape Codex's CLI accepts via --config overrides. Covers frontend-tools servers (telegram/discord/teams), plugin servers (mempalace/github/playwright/etc), and Brave Search.
• init.ts — lazy Codex instance construction, keyed by active chat id so per-chat MCP isolation survives the CLI's "configure-at-startup" constraint.
• handler.ts — main message handler. Subscribes to thread.runStreamed's ThreadEvent generator, translates agent_message / mcp_tool_call items into the shared stream state, persists thread id for resumeThread() continuity. Hooks AbortController so terminator tools (end_turn / send / react) can cancel further model generation.
• factory.ts — registerBackend({ id: \"codex\", ... }).
• index.ts — barrel.

Shared infrastructure reused

• backend/shared/stream-state for accumulator.
• backend/shared/delivery (routeDelivery) for end-of-turn routing — Codex gets the same 4-route decision (tool / synthetic-error / text-part / empty) as Kilo and OpenCode.
• backend/shared/{prompt-format,system-prompt,model-retry,session-name,usage}.
• core/tools/index.isTurnTerminator for tool-name detection.

Caveats / known limitations

• The Codex SDK doesn't expose system on runStreamed. Talon prepends the system prompt to the first user message on first turn; subsequent resumed turns inherit instructions from the persisted thread.
• MCP servers are configured at thread-creation time (CLI constraint). Chat-id-keyed cache rebuilds the Codex instance on chat switch so each chat sees its own MCP environment.
• Cache-write tokens always reported as 0 — Codex doesn't surface them in Usage.

Config

• New backend: \"codex\" accepted by configSchema.
• New openaiApiKey config option (falls back to OPENAI_API_KEY env var).

Prerequisites

• npm i -g @openai/codex (provides the codex CLI).
• codex login (ChatGPT auth) OR OPENAI_API_KEY env OR openaiApiKey in talon config.

Tests

13 new unit tests in codex-backend.test.ts:

• Constants exposed correctly.
• State lifecycle (uninit → init → reset).
• MCP-config flattening (frontend servers, plugin servers, brave-search opt-in, multi-frontend support, empty-frontends edge case).
• Factory registers as id: \"codex\" in the backend registry.

Full suite: 2274 passing (was 2261), 12 skipped (live-tier), 0 failing.

Live verification: not exercised — requires the codex CLI installed + OpenAI API key. A docker/codex-test/ harness can be added in a follow-up similar to docker/kilo-test/ once the SDK has been shaken out against real usage.

README

• Backends badge updated to include Codex.
• New "Backends" table row.
• Prerequisites + config-table rows updated.
• Architecture tree adds codex/.

Test plan

• npx tsc --noEmit clean
• npm test — 2274 passing, 12 skipped, 0 failing
• npm run lint — 0 errors, 15 pre-existing warnings unchanged
• npm run format:check clean
• CI matrix on push
• Live: codex login + backend: \"codex\" in talon.json + DM the bot

🤖 Generated with Claude Code