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

# Trace coding agents

> Run Claude Code or Codex through to11 with to11 code, so every session's model requests are recorded in your project.

`to11 code` starts Claude Code or Codex with its model traffic going through the to11 gateway. Each model request the agent makes is recorded as a span in the project you name, and every request of one session carries the same conversation id. Routed through a passthrough provider, the agent keeps using your own credential, and to11 stores no key for it.

```text theme={null}
  claude / codex
        |
        v
  to11 code            local listener on 127.0.0.1, one per session
        |              adds your to11 credential to each request
        v
  to11 gateway  ---->  Anthropic (Claude Code) / OpenAI (Codex)
        |
        v
  your project  ---->  Projects -> Traces
```

## Before you start

* **The to11 CLI**, installed and signed in — `0.9.0` or later for `to11 code codex`. Check with `to11 version`; see [Install the CLI](/docs/skills/receiving-skills#install-the-cli).
* **The agent**, installed and on your `PATH`. `to11 code` runs your agent; it does not install it.
* **A project** you can write to, which holds the provider your sessions route through.

## Set it up

Once `to11 ui` has set up your skills, there is nothing more to set up. The first `to11 code claude` or `to11 code codex` routes through the first project your skills come from, using the passthrough provider at a fixed slug there: `anthropic-to11-cli` for Claude Code; for Codex, `chatgpt-to11-cli` when Codex is signed in with ChatGPT and `openai-to11-cli` otherwise. When the project has none, the session connects it. It then saves `code.claude.yaml` or `code.codex.yaml` beside your `skills.yaml`, says what it did, and starts the agent:

```text theme={null}
$ to11 code claude
connected Anthropic (to11 CLI) to sre/gateway, a passthrough provider for your own Claude Code login
saved ~/.to11/code.claude.yaml: claude sessions route through Anthropic (to11 CLI) in sre/gateway, Production
```

Every later session reads the saved file. Connecting a provider needs the `routing:write` permission on the project.

### Or choose the provider in `to11 ui`

```bash theme={null}
to11 ui
```

Routing is not part of onboarding. Run `to11 ui` again once onboarding is done, or leave onboarding with Esc, and the overview has one routing row per agent: **Code · Claude Code** and **Code · Codex**. A row is shown when that agent is on your `PATH` or its file already exists. Open it, pick the project, and pick one of its providers, each offered at the environments it is live in. Confirming writes `~/.to11/code.claude.yaml` or `~/.to11/code.codex.yaml`.

**Claude Code routes through an Anthropic provider, and Codex through an OpenAI or ChatGPT provider.** The step only uses providers of that vendor that are not archived, are live in at least one environment, and hold only passthrough credentials, so to11 stores no key and no key stored on the platform is billed for your sessions.

A provider holding a stored key is never used. When the project has none that qualifies, **+ Create a provider** at the end of the list connects one: by default `Anthropic (to11 CLI)` (slug `anthropic-to11-cli`) for Claude Code; for Codex, `ChatGPT (to11 CLI)` when Codex is signed in with ChatGPT and `OpenAI (to11 CLI)` otherwise. It is connected in passthrough mode with the **Allow by default** access policy, so every model the vendor serves is allowed, including models the vendor releases later. It is live in every environment of the project. To connect one in the dashboard instead, go to **Projects → AI Gateway → Providers** and use the **BYOK only** connect mode.

### Or write the file yourself

One file per agent, `code.claude.yaml` or `code.codex.yaml`, in `~/.to11/`. For Claude Code:

```yaml theme={null}
organization: acme        # optional
project: acme/platform    # workspace/project, or a project id
environment: production   # an environment slug, or its id
provider: anthropic-to11-cli   # a provider slug, or its id
```

`project`, `environment` and `provider` are required. See [`code.claude.yaml`](/docs/reference/cli/configuration#codeclaudeyaml) for every key and how the organization resolves.

<Warning>
  A file you write yourself can name any provider that is live in the environment — not only the passthrough providers `to11 ui` offers. If the provider holds a stored credential, the session may use that key, billed to it, instead of your own login. Name a provider connected in **BYOK only** mode to keep your own login.
</Warning>

## Run a session

```bash theme={null}
to11 code claude
to11 code codex
```

Everything after the agent name goes to the agent untouched, so run it the way you already do:

```bash theme={null}
to11 code claude <your usual claude arguments>
to11 code codex <your usual codex arguments>
```

`to11 code` prints nothing of its own on stdout and exits with the agent's exit code.

**Through a passthrough provider, your own agent login is used.** Claude Code sends your Claude subscription login or Anthropic API key; Codex sends the OpenAI API key stored with `codex login`. The gateway forwards it to the vendor. A ChatGPT sign-in does not work through a passthrough provider. To run Codex without an API key of your own, name a provider that holds its own OpenAI key in the file; the session then uses that key, billed to it. Your to11 credential is never forwarded upstream.

**Your to11 credential stays out of the agent.** The agent gets a session token valid only for the local listener; the CLI adds your to11 credential on each request. It does not appear in the agent's environment, the process list, logs or your terminal. The credential is the person signed in with `to11 login` or `to11 ui`, or `TO11_API_KEY` when nobody is.

**Your agent configuration is not edited.** Claude Code is pointed at the listener through its own process environment only. Codex runs with a profile written for the session, `<CODEX_HOME>/to11-code-<hex>.config.toml`, selected with `--profile` and deleted when the session ends; your `~/.codex/config.toml` is never written.

**The agent chooses its model.** There is no model setting in the file. The agent sends its own model name unchanged, and the CLI adds the `x-to11-provider-id` header naming the provider from the file, so the gateway knows where to send it. A model the provider's [access policy](/docs/deploy/concepts/models#access-policy) does not allow is refused with `404`.

## Route a repository's sessions

Run `to11 ui` inside a repository and choose **Repository**. A routing row on its overview then writes `<repo>/.to11/code.claude.yaml` or `<repo>/.to11/code.codex.yaml`. A first `to11 code` session in a repository whose `.to11/skills.yaml` exists saves its route there too. Commit it.

From then on, anyone who runs `to11 code <agent>` in that repository routes to the repository's provider instead of the one in their own `~/.to11/`. The repository file is used whole; no key merges with the home file.

## Group turns, change project, or skip routing

| Flag | Use it to |
| - | - |
| `--conversation-id <id>` | Group this run's turns under an existing conversation. A value with a line break is refused |
| `--project <name or id>` | Route to a project other than the configured one |
| `--organization <slug>` | The organization a `workspace/project` is looked up in; else `TO11_ORGANIZATION` |
| `--no-gateway` | Run the agent untouched. Nothing is checked or routed |

These flags go **before** the agent name: everything after `claude` or `codex` is passed to the agent untouched. `--no-gateway` cannot be combined with any of the others. The project is taken from `--project`, then `TO11_PROJECT_ID`, then `project` in the file. `--gateway-project` is the earlier name of `--project` and still works.

```bash theme={null}
to11 code --conversation-id cc-refactor-auth claude
```

## Find your session

Open **Projects → Traces** for the project the session routed to — the one in the file, unless `--project` or `TO11_PROJECT_ID` named another. Each model request is recorded as a span. A turn in which the agent calls tools makes several requests, which the gateway can group under one trace for that turn; the conversation id is what ties the whole session together. The **Provider** filter narrows by vendor — `anthropic` for Claude Code, `openai` for Codex — which includes any other traffic of that vendor in the project.

Every request of one `to11 code` run carries the same conversation id, recorded on each span as `gen_ai.conversation.id` (see [Span attributes](/docs/instrument/span-attributes)). Without `--conversation-id`, the id is generated: `cc-` followed by 24 hex characters.

## If it does not start

Errors print on stderr as `error: <what>` and exit `1`. The first line says which case you hit:

| First line | Fix |
| - | - |
| `claude is not on your PATH` / `codex is not on your PATH` | Install the agent, or add it to your `PATH` |
| `no code.claude.yaml — nothing says which provider to route to` | Set up your skills with `to11 ui`, or write the file. The same applies to `code.codex.yaml` |
| `X has a provider called anthropic-to11-cli, but it isn't a passthrough Anthropic provider …` | Choose a provider on the Code · Claude Code row of `to11 ui`, or write the file |
| `not signed in` | Run `to11 login`, or set `TO11_API_KEY` |
| `no such project: X` | Fix `project` in the file, or `--project` |
| `no such environment: X` | Fix `environment` in the file |
| `no such provider: X` | Fix `provider` in the file |
| ``provider `X` is archived`` | Name another provider, or reopen the routing row on the `to11 ui` overview |
| ``provider `X` is not active in `env` `` | Name an environment from the `it is live in …` line, or deploy the provider to `env` |
| `"X" is not an agent this client runs` | Use `claude` or `codex` |

`to11 code --no-gateway claude` still runs the agent while you fix the route; that session is not traced.

## Next steps

<CardGroup cols={2}>
  <Card title="CLI commands" icon="terminal" href="/docs/reference/cli/commands#to11-code">
    Every flag, check and error of `to11 code`.
  </Card>

  <Card title="CLI configuration" icon="file-code" href="/docs/reference/cli/configuration#codeclaudeyaml">
    The keys in `code.claude.yaml` and `code.codex.yaml`, and where they are read from.
  </Card>

  <Card title="Traces" icon="list-tree" href="/docs/observe/traces">
    Filter and inspect the traces your sessions produce.
  </Card>

  <Card title="Skills overview" icon="book-open" href="/docs/skills/overview">
    Deliver your company's skills to the same agents.
  </Card>
</CardGroup>


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