Tracing agents

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

thirdeye add --<platform> registers a hook with each supported agent so every subsequent session is captured into your local trace store. Hooks are platform-specific — usually a config entry that runs a thirdeye shim wrapping the agent's session lifecycle — but the surface area is identical from your perspective: run the add command, then use your agent normally.

All captured data lives under <thirdeye_home>/traces/<platform>/<sid>/, where <thirdeye_home> defaults to ~/.thirdeye (override with THIRDEYE_HOME).

File	Purpose
`events.alog`	Append-only event log (msgpack frames). Never mutated.
`events.idx`	Index of frame offsets for fast `seq` lookup.
`tags.jsonl`	Sidecar with tag add/remove operations (append-only, replayable).
`meta.yaml`	Session metadata (`platform`, `cwd`, timestamps, status).
`usage.jsonl`	Per-turn token usage sidecar (see Token usage).
`evals.jsonl`	Eval results, if any (see Evaluations).

Claude Code

thirdeye add --claude

Registers a session lifecycle hook with the claude CLI so each session emits events into <thirdeye_home>/traces/claude/<sid>/. Includes the use-thirdeye and use-thirdeye-evals skills if you've installed them.

Verify:

claude        # run any prompt, exit
thirdeye list --platform claude

You should see a new session at the top.

Cursor

thirdeye add --cursor

Wires the Cursor agent CLI through thirdeye. Cursor sessions land under <thirdeye_home>/traces/cursor/<sid>/.

Verify with thirdeye list --platform cursor after running an agent session in Cursor.

Codex

thirdeye add --codex

Hooks the OpenAI Codex CLI (codex). Codex's read-only sandbox is preserved — thirdeye only observes events, it doesn't relax the sandbox.

Verify with thirdeye list --platform codex.

Gemini

thirdeye add --gemini

Hooks the Gemini CLI (gemini). Gemini's approval modes (plan / default / yolo) pass through unchanged.

Verify with thirdeye list --platform gemini.

Copilot

thirdeye add --copilot

Hooks the GitHub Copilot CLI (copilot).

Verify with thirdeye list --platform copilot.

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.