# AI tool sessions

Find out which AI tools give ATLAS exact sessions, which get estimated sessions, and which headers you can send to improve grouping. A session groups the requests of one working conversation in your usage view. It affects grouping only, not cost.

## Supported tools

| Tool                                                                                 | Sessions      | Setup                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Code                                                                          | Exact         | None. Set `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1` (v2.1.273 and later) to also record agent kind and name.                                                                                                 |
| opencode                                                                             | Exact         | None.                                                                                                                                                                                                   |
| Codex CLI                                                                            | Exact         | Use the Responses API (`wire_api = "responses"`).                                                                                                                                                       |
| Kilo Code                                                                            | Exact         | None.                                                                                                                                                                                                   |
| Qwen Code                                                                            | Exact         | Set `customHeaders: { "atlas-session-id": "${session_id}" }` and `outboundCorrelation.allowDynamicHeaderValues: true`.                                                                                  |
| Copilot CLI                                                                          | Exact         | Set `COPILOT_PROVIDER_WIRE_API=responses`. Copilot CLI cannot send custom headers.                                                                                                                      |
| SDK or custom code                                                                   | Exact         | Send `atlas-session-id` on each call. Optionally add `atlas-agent-*` and `atlas-client`.                                                                                                                |
| Copilot Chat bring-your-own-key (VS Code)                                            | Estimated     | None available. The tool sends no session ID.                                                                                                                                                           |
| Claude Desktop                                                                       | Estimated     | Anthropic documents no session headers. It connects through the Anthropic address. See [Connect Claude Desktop](https://docs.atlas.ilionx.dev/guides/user/gateway-connect-openai-and-anthropic-clients.md#connect-claude-desktop). |
| Roo Code                                                                             | Estimated     | The OpenAI Compatible provider uses Chat Completions. Optionally send `atlas-client`.                                                                                                                   |
| Cline                                                                                | Estimated     | Optionally send `atlas-client`.                                                                                                                                                                         |
| Continue                                                                             | Estimated     | Optionally send `atlas-client` through `requestOptions.headers`.                                                                                                                                        |
| Any OpenAI-compatible tool (Crush, Goose, Aider, Droid, Zed, Warp, Junie and others) | Estimated     | Optionally send `atlas-client`. Never set a fixed `atlas-session-id`, because it merges every session.                                                                                                  |
| Cursor                                                                               | Not supported | Cursor uses its own backend and sends no session information to custom endpoints.                                                                                                                       |
| Amp                                                                                  | Not supported | Amp has no custom endpoint.                                                                                                                                                                             |
| Gemini CLI                                                                           | Not supported | Gemini CLI uses the Gemini API only.                                                                                                                                                                    |

## Exact and estimated sessions

- **Exact:** the tool sends a session ID, so ATLAS groups requests precisely.
- **Estimated:** ATLAS recognises a multi-turn chat from its opening messages. A gap of 30 minutes ends the session.

Estimated sessions can split or merge conversations. Cost and token counts stay correct either way.

## Headers

Send these headers to the OpenAI address (`https://<atlas-host>/gateway/openai/v1`, including `/responses`) or the Anthropic address. ATLAS never forwards them to providers.

| Header                  | Value                                                        | Notes                                                                  |
| ----------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------- |
| `atlas-session-id`      | Your session ID, up to 512 characters, no control characters | Groups requests into one exact session.                                |
| `atlas-agent-id`        | Agent ID                                                     | Needs `atlas-session-id`.                                              |
| `atlas-parent-agent-id` | ID of the agent that started this one                        | Needs `atlas-session-id`.                                              |
| `atlas-agent-kind`      | `main`, `subagent`, `compaction` or `auxiliary`              | Needs `atlas-session-id`. Other values are recorded as `unknown`.      |
| `atlas-agent-name`      | Display name, up to 64 characters                            | Needs `atlas-session-id`.                                              |
| `atlas-client`          | Client name, up to 64 characters                             | Optional. Names your tool in the usage view. Does not affect grouping. |

`atlas-correlation-id` is for tracing only. ATLAS stores and echoes it, and it never groups requests into sessions. For more information, see [Gateway](https://docs.atlas.ilionx.dev/reference/gateway.md#headers).