Tracing agents

Attach thirdeye to Claude Code, Codex, Cursor, or GitHub Copilot CLI 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.
Cursor	`thirdeye add --cursor`	Registers hooks in `~/.cursor/hooks.json` for both the IDE and `cursor-agent` CLI. Reconstructs generations, model usage, shell and MCP calls, file edits and reads, generic tool events, and completed subagents.
Copilot	`thirdeye add --copilot`	Local, archive-first capture of the GitHub Copilot CLI: derives turns and usage from a durable, immutable local archive.

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

Platform differences

Capture format and storage layout are identical everywhere. A couple of setup details differ on Windows:

Hook paths. Hooks normally record the resolved absolute path to the thirdeye/thrdi binary. On Windows, if that path contains a space (common under C:\Users\First Last\...), thirdeye writes the bare binary name into the tool's config instead and lets PATH resolve it — this sidesteps shell-quoting differences between cmd.exe, PowerShell, and direct process creation.
Concurrent reads. POSIX locks let multiple readers share a lock; Windows locks are exclusive-only, so concurrent reads serialize instead of running in parallel. This only affects throughput under heavy contention — reads and writes are equally correct on both platforms.

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 Gemini hook still runs. Run thirdeye add --list; it reports stale hook commands that should be removed from Gemini's config file.
Usage rows missing. See Token usage; the usage sidecar is written by a separate path that may need thirdeye usage reindex.