Tracing agents

Attach thirdeye to Claude Code or Codex and capture structured turns.

thirdeye add --<platform> attaches thirdeye to a supported agent so every subsequent session is captured locally. From your perspective: run add once, then use your agent normally.

All captured data lives under ~/.thirdeye/traces/<platform>/<sid>/ (override the root with THIRDEYE_HOME). The on-disk format is append-only and never mutated — safe to copy, back up, or delete wholesale.

Supported integrations

Enable any of these with thirdeye add --<platform>. Each one is idempotent and takes effect on the platform's next agent run.

Platform	Command	What you should know
Claude Code	`thirdeye add --claude`	Captures the full session lifecycle and reconstructs every completed or interrupted turn, including nested subagents. Pairs with the bundled agent skills.
Codex	`thirdeye add --codex`	Combines Codex notify and JSON hook events with rollout data to reconstruct turns, model calls, tool calls, permissions, token usage, and subagents. Use `--force` only to replace an existing notify program.

Once captured, every platform shares the same query surface: thirdeye list / events / search / usage / tag / eval all work identically across them.

Structured turn traces

The tracing adapters assemble a whole turn before export: one user prompt through its final response, interruption, or error. Each turn includes its model calls, the tool calls requested by each model call, permission prompts, usage, and recursively nested subagent turns. This preserves parent-child relationships and real start/end timestamps instead of flattening hook events into an unordered timeline.

Local capture requires no remote service. If you enable Pydantic Logfire, the same completed-turn model is exported as a nested OpenTelemetry trace in a detached worker.

Verify

# Run any agent prompt, then:
thirdeye list --platform <name>     # session appears at the top

For a deeper look, agent skills walk an agent through inspecting its own runs — install use-thirdeye and ask your agent to "find recent sessions and summarize what they did."

Detaching

thirdeye remove --<platform> reverses the hook for that platform. Captured session data is left in place — you can re-enable later and your history is intact. To wipe captured data, delete ~/.thirdeye/traces/ (or the directory pointed to by THIRDEYE_HOME).

Troubleshooting

No sessions appear after add. add takes effect on the next agent run. Start a new session and check thirdeye list again.
Duplicate hook entries. Shouldn't happen — add is idempotent. If it does, run thirdeye remove --<platform> then thirdeye add --<platform> to reset.
A removed Cursor or Gemini hook still runs. Run thirdeye add --list; it reports stale hook commands that should be removed from those tools' config files.
Usage rows missing. See Token usage; the usage sidecar is written by a separate path that may need thirdeye usage reindex.