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.

pipx / uv

pipx install thrdi
# or
uv tool install thrdi

Verify the install:

thirdeye --help

Enable tracing

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

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.

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
 
$ thirdeye tail a3f2c8 -n 3

Detach

Disable hooks for a platform without removing thirdeye itself:

thirdeye remove --claude
thirdeye remove --codex

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.