What is agtail

ag(ent) + tail — a forensic search tool for the histories of coding agents (Claude Code, Codex).

Agents are useful but opaque, and "what did that operation actually do?" is hard to reconstruct after the fact. The transcripts (~/.claude/projects/**/*.jsonl and friends) hold enough information, yet they have three limits: (1) raw JSONL isn't human-followable and can't be grepped across sessions, (2) it's tool-owned, volatile data — not an audit log, and (3) it's scattered per project, per session, per machine.

agtail fills those gaps. It normalizes the scattered transcripts into one searchable projection you can grep across tools and projects. Search is the point; viewing is secondary. See Concepts for the full rationale.

TIP

The screenshots throughout these docs use a small, fictional sample dataset (the "northwind" projects) — not anyone's real history. See docs/screenshots/README.md in the repo for how they're generated.

Try it without installing

The playground runs agtail entirely in your browser over that same fictional sample — search, the timeline, hooks, export/import, and a terminal view. Nothing is uploaded; imports stay in memory and reset on reload.

It's deliberately offline (no LiteLLM, no backend): you can import your own bundle, but cost is priced only for the sample's models and plugin attribution only resolves the sample's plugins. Run agtail locally for full pricing and your own plugins.

Requirements

• Node.js 20+
• pnpm
• The agent(s) whose history you want to read (Claude Code at ~/.claude/projects, Codex at ~/.codex/sessions)

Install and build

pnpm install
pnpm build      # builds the web SPA (dist-web) and the CLI (dist)

Run the CLI with node dist/cli/index.js <command> (or pnpm link --global for agtail).

First steps

# the primary command: search across every session
node dist/cli/index.js grep blogsync

# list sessions, newest first, source-tagged
node dist/cli/index.js list

# launch the web UI (127.0.0.1 only)
node dist/cli/index.js serve
# → http://127.0.0.1:8765

See CLI and Web UI for details.

Scope & non-goals

agtail is a local, zero-setup, read-only forensic viewer. Cross-agent browsing and full-text search are table stakes; its focus is depth — beyond messages and tool calls it reconstructs a run's execution mechanics from the saved transcript: hook firings (PreToolUse / PostToolUse / Stop), subagent (Task) nesting, plugin attribution, and SDK/programmatic origin — retroactively, with no instrumentation. It is deliberately not an observability tool. It does not, and will not:

• collect fleet metrics, dashboards, or alerts — use OpenTelemetry → Datadog/Grafana for that (see agtail vs OpenTelemetry);
• run as a real-time monitor or telemetry pipeline;
• keep histories continuously in sync across machines — import/export is evidence portability (portable, provenance-tagged records), not sync (use git/rsync for raw sync);
• treat skills as a first-class concept, or chase content that isn't in the transcript.

Token, tool, and model data exist only as reading aids for a session, not as a metrics surface. New agents are added as in-tree adapters (a small parser that maps a transcript into agtail's normalized model — see Adapters); the --dir <agent>=<path> flag points a known agent at a non-default session root.

About these docs

The documentation site is managed independently from the app (it has its own package.json under docs/).

cd docs
pnpm install
pnpm dev        # local preview
pnpm build      # generate the static site (.vitepress/dist)