Skip to content
Agent Archaeology

Field Manual

Agent Traces

An agent trace is a sequence of observed activity that helps reconstruct what happened across an agentic event.

Why it matters

Traces help correlate actions that are spread across conversations, tool logs, local files, and external services.

Evidence to look for

  • Raw session records
  • Normalized telemetry
  • Tool-call IDs
  • Timestamps
  • Workspace paths
  • External request IDs

Agent session store locations

Different agents store session data in different locations. These paths help you locate raw evidence during investigations.

Artifact Paths

Codex

~/.codex/sessions

JSONL format. Also includes archived_sessions/ and headless/ subdirectories. Respects $CODEX_HOME if set.

OpenCode

~/.local/share/opencode/opencode.db

SQLite database. Legacy JSON in storage/message/. macOS: ~/Library/Application Support/opencode/.

Claude Code

~/.claude/projects

JSONL project sessions.

Gemini CLI

~/.gemini/tmp

JSON session files.

Qwen CLI

~/.qwen/projects

JSONL project chats.

Roo Code

~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/tasks

VS Code extension storage. ui_messages.json files. macOS: ~/Library/Application Support/Code/. Windows: %APPDATA%\Code\.

Kilo Code

~/.config/Code/User/globalStorage/kilocode.kilo-code/tasks

VS Code extension storage. ui_messages.json files. macOS: ~/Library/Application Support/Code/. Windows: %APPDATA%\Code\.

OpenClaw

~/.openclaw/agents

JSONL-like agent files. Candidate support.

GitHub Copilot

<repo>/logs/copilot

Process logs in repository directory. OS-agnostic.

Platform-specific paths

Paths shown above use Unix conventions (~ for home directory). On macOS, most agents use ~/Library/Application Support instead of ~/.local/share or ~/.config. On Windows, agents use %USERPROFILE%, %APPDATA%, or %LOCALAPPDATA%. VS Code extensions (Roo Code, Kilo Code) follow the same pattern under the platform-specific Code config directory. Copilot is OS-agnostic because it uses repo-local paths.

Common pitfalls

  • Treating normalized events as originals
  • Ignoring clock skew
  • Losing correlation IDs during export
  • Assuming all agents store data in the same format
  • Missing archived or headless session variants

What a trace looks like

A trace is a sequence of records that together tell the story of what an agent did. The shape of those records depends on the agent. Below are real-format examples showing how the same logical trace — a user request followed by a tool call and result — appears in different agent session stores.

Codex CLI trace

Codex wraps every record in an envelope. A session starts with a session_meta record, followed by event_msg records where payload.type identifies the event. This makes it possible to reconstruct the full sequence by reading the JSONL stream in order.

Codex — session_meta followed by tool_call and tool_result
JSON 
                          {"type":"session_meta","timestamp":"2026-04-03T06:00:00Z","payload":{"source":"cli","model_provider":"fixture-provider","agent_nickname":"fixture-agent","model":"fixture-model"}}

{"type":"event_msg","timestamp":"2026-04-03T06:00:01Z","payload":{"type":"user_message","message":"Inventory the MCP configuration for this synthetic workspace."}}

{"type":"event_msg","timestamp":"2026-04-03T06:00:02Z","payload":{"type":"tool_call","tool_name":"mcp_inspector","command":"probe mcp servers before selecting an integration","arguments":{"server":"filesystem","inventory_method":"tools/list"},"message":"Run an MCP inspection probe."}}

{"type":"event_msg","timestamp":"2026-04-03T06:00:03Z","payload":{"type":"tool_result","tool_name":"mcp_inspector","message":"filesystem tools/list => repo_status, read_file; github tools/list => repo_search, issue_create"}}

Each line is a separate JSONL record. The session_meta header identifies the agent and model. Subsequent event_msg records carry the trace in chronological order.

Claude Code trace

Claude Code stores traces as alternating user and assistant message records. Tool calls appear as tool_use content blocks inside assistant messages. Tool results appear as tool_result content blocks inside the next user message, linked by tool_use_id.

Claude — tool_use in assistant message, tool_result in user message
JSON 
                          {"type":"user","sessionId":"claude-tool-use","timestamp":"2026-04-27T12:10:00Z","message":{"role":"user","content":[{"type":"text","text":"Read the project README and summarize it without touching secrets."}]}}

{"type":"assistant","sessionId":"claude-tool-use","timestamp":"2026-04-27T12:10:01Z","message":{"role":"assistant","model":"claude-fixture-model","content":[{"type":"text","text":"I will read the public README only."},{"type":"tool_use","id":"toolu_fixture_read","name":"Read","input":{"file_path":"README.md"}}]}}

{"type":"user","sessionId":"claude-tool-use","timestamp":"2026-04-27T12:10:02Z","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_fixture_read","content":"# ADR\nSynthetic README excerpt for parser coverage.","is_error":false}]}}

The tool_use_id field (toolu_fixture_read) is the correlation key that links the tool call in the assistant message to the result in the user message.

GitHub Copilot trace

Copilot traces are embedded in plain text process logs. Tool calls appear as function_call items inside JSON arrays within log lines. This is the most challenging format to parse because you must extract structured data from unstructured log text.

Copilot — function_call items in process log lines
TEXT 
                          2026-04-27T16:16:57.841Z [INFO] Workspace initialized: copilot-uc001-tool-result (checkpoints: 0)
2026-04-27T16:16:57.847Z [INFO] Starting Copilot CLI: 1.0.36
2026-04-27T16:17:17.990Z [INFO] Accumulated output items (2): [{"arguments":"{\"format\":\"json\"}","call_id":"call_fixture_001","id":"c1","name":"repo_status","status":"completed","type":"function_call"}]
2026-04-27T16:17:30.100Z [INFO] Accumulated output items (1): [{"arguments":"{\"format\":\"json\"}","call_id":"call_fixture_002","id":"c2","name":"repo_status","status":"completed","type":"function_call","message":"MCP tool result: status=ok, repository=fixture-repo"}]
2026-04-27T16:17:45.200Z [INFO] Session completed.

Copilot is the only agent that preserves call_id natively. However, the arguments field is stringified JSON, and user intent is not captured in the process log.

Trace correlation across agents

Different agents use different mechanisms to link related events in a trace:

  • Explicit call ID: Claude uses tool_use_id. Copilot uses call_id. These provide the strongest correlation between tool calls and results.
  • Sequential ordering: Codex, Qwen, Gemini, and Roo Code rely on the order of records in the session stream. The tool_result that follows a tool_call is assumed to be its result.
  • Session grouping: All agents use a session identifier (sessionId, sessionID, or file-level grouping) to scope traces to a single conversation or task.
  • Timestamp ordering: All agents include timestamps, but clock skew between systems means timestamps alone are not sufficient for correlation. Use them for ordering within a single session, not for cross-session timing.
  • Tool name matching: Some formats (Qwen, Gemini, Roo Code) include the tool name in both the call and result records, providing a secondary correlation signal alongside sequential ordering.

Normalized traces

When traces from different agents need to be compared or searched together, they can be normalized into a common schema. Normalization extracts the key fields — tool name, arguments, result, timestamps, session ID — into a uniform record. This process is lossy: agent-specific fields that do not map to the common schema are dropped.