`CODEX-INTEGRATION.md`

46 lines
# Codex integration

Codex and Claude use one ticket system and one append-only source of truth:

`~/.claude/tickets/events.jsonl`

Codex connects through the local stdio MCP server in `mcp-server.js`. The MCP is
registered as `tickets` in `~/.codex/config.toml`; the existing `tk` CLI remains
the fallback and the board at `tickets.agentabrams.com` remains a read/write view
of the same ledger.

## Native tools

- `tickets_list`, `ticket_get`, `ticket_create`, `ticket_take`
- `ticket_log`, `ticket_comment`, `ticket_status`
- `ticket_dm`, `ticket_inbox`, `ticket_reply`, `ticket_thread`

Every MCP mutation receives a correlation ID. Ticket actions/comments carry the
ID through `lib.js` and the board API as `last_correlation_id`; A2A DMs and replies
carry the same evidence in their raw events. Invalid mutations append nothing.

## Operating loop

For non-trivial work: check the inbox, scan for related tickets, create/take one,
log material actions, use ticket-linked DMs for ownership and handoffs, then mark
the ticket `done` or `blocked`. Subagents inherit the parent ticket. Approval gates
are unchanged.

Current Codex sessions need a restart or `/clear` to load a newly registered MCP.
The CLI fallback is always available:

```sh
TK_AGENT=codex ~/Projects/ticket-system/tk inbox
```

## Verification

```sh
node --test test/mcp-server.test.js
codex mcp get tickets
```

The public domain is protected by Cloudflare Access. Browser/API checks without a
valid Access session correctly land on the Access sign-in page; loopback board API
verification is the deterministic service-boundary proof.