> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slaunt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Slaunt with Codex

> Codex setup for Slaunt: config.toml, hooks.json lifecycle hooks via codex_hook_event, and per-thread routing with threadId.

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

```bash theme={null}
npx --yes slaunt@latest install --client codex
```

## Manual setup

```toml ~/.codex/config.toml theme={null}
[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`.

```json ~/.codex/hooks.json theme={null}
{
  "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
    }]}]
  }
}
```

To fill the agent's Chat tab with prompts and replies, also add `chat_hook_event` hooks ([Hooks and capture](https://docs.slaunt.ai/tools/hooks.md)).

## What each event does

| Event | Effect |
| - | - |
| `SessionStart` | Binds the Codex thread to a Slaunt thread and records the starting `model`. Resume and compaction reuse the same thread. |
| `UserPromptSubmit` | Starts the run. Codex can fire `SessionStart` before MCP connects; if that happens, a `UserPromptSubmit` that includes `model` recovers the binding. |
| `Stop`, `Interrupt` | Ends the matching turn's run |
| `SessionEnd` | Ends any active run; the thread stays open |
| Tool, subagent, compaction events | Recorded 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](https://docs.slaunt.ai/protocol/transport.md#thread-boundaries); the request is rejected with `-32602`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.