Tracing agents

Attach thirdeye to Claude Code, Cursor, Codex, Gemini, and Copilot.

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 full session lifecycle. Pairs with the `use-thirdeye`, `thirdeye-evals`, and `thirdeye-review` agent skills.
Cursor	`thirdeye add --cursor`	Captures session lifecycle, prompts, shell, MCP, and file events. A thirdeye fault never blocks Cursor — failures are logged, not surfaced.
Codex	`thirdeye add --codex`	Preserves Codex's `--sandbox read-only`. thirdeye observes; it does not relax the sandbox.
Gemini	`thirdeye add --gemini`	Gemini's `plan` / `default` / `yolo` approval modes pass through unchanged.
Copilot	`thirdeye add --copilot`	GitHub Copilot CLI.

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

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.
Usage rows missing. See Token usage; the usage sidecar is written by a separate path that may need thirdeye usage reindex.