Getting Started

Install thirdeye and capture your first agent session.

Local-first by default. Every trace, tag, and eval lives on your filesystem under ~/.thirdeye/. Remote export is off unless you explicitly enable Pydantic Logfire.

Install

thirdeye ships as thrdi on PyPI and thirdeye on Homebrew. The installed commands are thirdeye and thrdi — aliases of each other.

Homebrew (recommended)

brew install duncankmckinnon/tap/thirdeye

The Homebrew package includes the browser UI and Pydantic Logfire dependencies. You do not need to install the ui or logfire extras separately. Homebrew is macOS/Linux only — on Windows, install with pipx or uv instead.

pipx / uv

pipx install thrdi
# or
uv tool install thrdi

Verify the install:

thirdeye --help

Interactive setup

Run the setup wizard to configure tracing, install the bundled agent skills, and optionally enable live Pydantic Logfire export in one flow:

thirdeye setup

The wizard asks which agent platforms to trace, whether to install skills, and whether to enable Logfire. Logfire remains opt-in and, when selected, the wizard signs you in through the browser and mints the write token for you — there is no key to paste.

Skills are installed for the selected agents: .claude/skills/ for Claude Code, .codex/skills/ for Codex, and the shared .agents/skills/ directory for Cursor and Copilot. If you skip every tracing platform but choose skills, the shared directory is used.

Enable tracing

If you prefer to configure each piece separately, attach thirdeye to whichever agent CLIs you use. Each add is idempotent — running it twice leaves a single hook entry in place.

thirdeye add --claude        # Claude Code
thirdeye add --codex         # OpenAI Codex CLI
thirdeye add --cursor        # Cursor IDE and CLI
thirdeye add --copilot       # GitHub Copilot CLI

After the next agent run on that platform, a session will appear in thirdeye list. See Tracing agents for what each integration does under the hood and how to verify it's wired up.

Supported interfaces

PlatformIDECLINon-interactive
Claude Code✅✅✅
Codex✅✅✅
Cursor✅✅✅
Copilot✅✅✅

Read your first session

Once you've used your agent at least once after enabling tracing, your history is queryable:

thirdeye list                  # every session, newest first
thirdeye list --tree           # human-readable layout
thirdeye events <id>           # one session's events, terse
thirdeye event <id> <seq>      # one event, fully expanded
thirdeye tail <id> -n 5        # the last few events of a session

Session IDs accept any unique prefix, so thirdeye events abc1 works as long as abc1 is unambiguous. Add --json to any read command for parseable JSONL.

A typical first look:

$ thirdeye list --tree
claude    a3f2c8b1   ~/code/thrdi-web      2026-05-20 14:22   running
claude    91e4d20a   ~/code/thirdeye       2026-05-20 11:03   done
codex     7d12c9b3   ~/code/wbcli-web      2026-05-19 18:41   done
cursor    62bc14fa   ~/code/workbench      2026-05-19 09:12   done
copilot   1a9d7e5c   ~/code/valcore        2026-05-19 08:47   done
 
$ thirdeye tail a3f2c8 -n 3

Detach

Disable hooks for a platform without removing thirdeye itself:

thirdeye remove --claude
thirdeye remove --codex
thirdeye remove --cursor
thirdeye remove --copilot

Existing session data on disk is untouched — you can re-enable later and pick up where you left off.

What's next

  • Tracing agents — per-platform install details and verification steps.
  • Pydantic Logfire — optionally mirror structured turn traces live.
  • Search & tags — slice your history by content, tag, platform, or time.
  • Token usage — per-turn input/output token rollups.
  • Evaluations — grade recorded sessions with LLM-as-judge rubrics.
  • Browser UI — explore sessions, traces, evals, and usage charts in a local browser.
  • Agent skills — let your agents inspect their own history.
  • Workbench integration — group parallel agent sessions by plan, task, role, and pipeline step.