slaunt
DOCUMENTATION

Codex

Codex reports its lifecycle through mcp_tool hooks that call codex_hook_event. The installer sets this up:

npx slaunt install --client codex

Manual setup

# ~/.codex/config.toml
[mcp_servers.slaunt]
url = "https://central-mcp-ccr-production.up.railway.app/mcp"

These three hooks are the minimum for threads and runs to appear in Quaero. They send metadata only. Each hook's server value must match the server name in config.toml.

{
  "hooks": {
    "SessionStart": [{ "hooks": [{
      "type": "mcp_tool", "server": "slaunt", "tool": "codex_hook_event",
      "input": { "event_name": "SessionStart", "session_id": "${session_id}", "model": "${model}" },
      "timeout": 30
    }]}],
    "UserPromptSubmit": [{ "hooks": [{
      "type": "mcp_tool", "server": "slaunt", "tool": "codex_hook_event",
      "input": { "event_name": "UserPromptSubmit", "session_id": "${session_id}", "turn_id": "${turn_id}" },
      "timeout": 30
    }]}],
    "Stop": [{ "hooks": [{
      "type": "mcp_tool", "server": "slaunt", "tool": "codex_hook_event",
      "input": { "event_name": "Stop", "session_id": "${session_id}", "turn_id": "${turn_id}" },
      "timeout": 30
    }]}]
  }
}

That goes in ~/.codex/hooks.json. To fill the agent's Chat tab with prompts and replies, also add chat_hook_event hooks (Hook and capture tools).

What each event does

EventEffect
SessionStartBinds the Codex thread to a Slaunt thread and records the starting model. Resume and compaction reuse the same thread.
UserPromptSubmitStarts the run. Codex can fire SessionStart before MCP connects; if that happens, a UserPromptSubmit that includes model recovers the binding.
Stop, InterruptEnds the matching turn's run
SessionEndEnds any active run; the thread stays open
Tool, subagent, compaction eventsRecorded as activity. They can't create a thread.

Thread routing

One Codex process can run several conversations over one MCP connection. Slaunt keeps them apart using the params._meta.threadId Codex attaches to every request, including ordinary tool calls.

  • Same threadId means same Slaunt thread and run; a different one means a different thread.
  • Calls with no selector belong to the connection's own runtime, separate from every hook thread, and need their own thread_begin.
  • To get a new Codex thread, start a new conversation. new_thread: true on a hook thread is rejected.
  • A bridge that can't forward threadId can send the native ID as _meta["ai.slaunt/codex-session-id"] or the X-Slaunt-Codex-Session-Id header. If both are present they must match.
  • Don't combine Codex selectors with the generic boundary headers; the request is rejected with -32602.