agenttrail

Local observability for AI coding agents.

Agenttrail watches your coding agents' available activity and turns it into a live view of their work. See which part of a project is changing, what tasks an agent has reported, and where it needs your attention—without piecing together several terminal windows.

Your agents keep running in tools such as Codex and Claude Code. Agenttrail observes local files, plans and supported agent events; it visualizes that evidence for you. It does not run the agents, assign their work or decide that a task is finished.

One project, two views

Agenttrail is the open-source project. Map and Kitchen are its two views:

Choose Map for the project overview and Kitchen to follow the work as a shared cooking scene. Each runs independently in your browser. They currently have separate local services and provider adapters; Kitchen can also read a running Map's context. Their activity coverage and history are not identical. How observability works

Agenttrail Kitchen

Recorded while real Codex and Claude sessions built a small 3D maze game. Chefs represent responsibilities, not necessarily separate agent processes.

Run Kitchen in your repo

You need Node.js 20+, a browser with WebGL, and a local project folder. Run this in the repo you want to watch:

npx agenttrail-kitchen .

The browser opens at localhost:4780 (or the next free port). Keep this terminal open and keep working in your coding agent. Codex and Claude Code activity is discovered from available local logs. No PLAN.md, Agenttrail Map installation, copied files, API key or new agent session is required for basic observation. The watcher does not launch agents or edit your repo.

Want to see it before connecting an agent? Add --example to the command, then click Next example step. This is a labeled, scripted example. Click Live to return to your real repo.

This is a public experimental preview. The npm package includes the graphics and fonts, so users do not need a build step. To pin this release, use npx agenttrail-kitchen@0.1.0-alpha.3 .. The separate npx agenttrail command opens the Map.

Kitchen guide · Connect agents and troubleshoot · Release and verification

Watch the work become dishes

One session can move between several chefs as its work changes. Roles adapt to the project; you can refine them with an optional workflow configuration. Multiple kitchens organize larger workflows. Click a chef or ticket to inspect its evidence.

What happens automatically: local activity, supported native todos, inferred responsibilities and todo completion. What needs extra metadata: confirmed handoffs and explicitly sharing one todo across separate sessions. The recorded multi-agent demo used these bindings; merely opening any repo does not create them. Missing plans stay progress unknown, and ending a turn does not mean a deliverable shipped.

Use it with your coding agent or editor

For VS Code or Cursor, keep the browser beside your editor. The current integration is a local companion, not a Marketplace extension. Hook setup is explicit and reversible; restart an agent conversation if it does not load newly installed hooks.

Local observation has been exercised on macOS; automated package and adapter checks run on Linux. Windows and native Cursor validation remain pending. Cloud/remote sessions with no logs on the Kitchen host are not automatically discovered. Details and limits

Run the project map

The original map stays lightweight and independently installable:

cd your-repo
npx agenttrail

The Map combines declared intent in PLAN.md with observed file changes. A completed component lights up when its files change again. Claude Code hooks add session and tool activity plus legacy TodoWrite lists. Map does not yet parse Claude's newer TaskCreate/TaskUpdate lists. Codex, Cursor and other tools contribute through file observation and the shared plan convention; their native session adapters currently belong to Kitchen.

For the full component map, run npx agenttrail init, review the setup, then give your agent the backfill prompt from the board. It adds the convention to CLAUDE.md and AGENTS.md, creates a starter plan, offers local Claude Code hooks, and adds .agenttrail/ to .gitignore. Setup writes these files; normal watching does not. In an interactive terminal, starting Map without a plan also offers this setup. Noninteractive init assumes yes, so run it only when you intend to configure the repo.

The map has a live file tree, dependency links, session trails and an overview of multiple repos. npx agenttrail up relaunches saved boards after a reboot; npx agenttrail autostart configures startup at login.

# my project

## Capture the audio {#capture}
tech: coreaudio tap + ring buffer
files: [src/audio/**]
- [x] Grab the mic feed {#capture-mic}
  by: claude
- [~] Keep the last 30 seconds ready {#capture-ring}
  by: claude

## Classify the alerts {#classify}
needs: [capture]
links: [notify]
- [ ] Score events by urgency {#classify-score}
  from: roadmap

## decisions
- 2026-08-21: dropped redis for summaries; in-process queue instead

• Components use stable {#id} values and concrete, owner-readable names
• files: connects observed writes to the component they belong to
• [~] means working, [x] means done, and [!] means stuck
• needs: draws dependency arrows; links: draws dashed connections
• by: records who did the work; from: separates agent intent from roadmap intent
• kind: knowledge renders a component as a purple knowledge organ; kind: human renders it dashed in its own color — the step where a person enters the loop; url: makes the card clickable, opening the artifact it produces
• Backfilled completed tasks cite their implementing file as evidence
• Agents record plan-affecting decisions before they act on them

Build Kitchen from source

git clone https://github.com/sodiumsun/agenttrail.git
cd agenttrail
npm ci --prefix packages/kitchen
npm run build --prefix packages/kitchen
npm start --prefix packages/kitchen -- --project /absolute/path/to/your/repo

Rebuild after frontend changes. The source, tests, original scene assets and third-party notices are all available in this repo. Contributor setup and checks

Local by construction

Both services bind to 127.0.0.1. No account, telemetry, transcript upload, model calls or cloud service is required. Fonts and graphics are available loc