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. |
| 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.