Agenttrail draws a live map of your project and shows where your coding agents are working on it: which part is changing, which tasks each session has reported, and what it is doing now. You see that in one browser tab instead of piecing it together from several terminal windows.
Your agents keep running in tools such as Claude Code and Codex. Agenttrail reads local files, your plan and the agents' local logs, and shows that evidence. It does not run agents, assign their work or decide that a task is finished.
You need Node.js 20+ and a local project folder.
cd your-repo
npx agenttrailThe map opens in your browser at localhost:5330, or the next free port. Keep working in your coding agent. Claude Code and Codex sessions in this repo appear as run cards from their local logs, with nothing to install. File changes appear as they happen.
Watching does not change your repo. In an interactive terminal, starting without a PLAN.md offers to set one up, and you can decline.
File activity and run cards work on their own. With no plan, the map is inferred from git, read-only and across every branch and worktree: the handful of branches and worktrees with recent work, drawn as the plan's cards flowing from the trunk by what grew out of what. Each card shows the folders it touched, its latest commit, a bar of its commits in the window against the busiest branch, any agent session in it, and more commit subjects underneath. Commit subjects stay on your machine. A repo with one branch shows code areas only, and a folder with no commits keeps the plain Watching view. Add a plan for real tasks and progress.
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. Noninteractive init assumes yes, so run it only when you intend to configure the repo.
The map combines declared intent in PLAN.md with observed file changes. A completed component lights up when its files change again. It also 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.
The PLAN.md convention
# 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 stuckneeds:draws dependency arrows;links:draws dashed connectionsby:records who did the work;from:separates agent intent from roadmap intentkind: knowledgerenders a component as a purple knowledge organ;kind: humanrenders it dashed in its own color — the step where a person enters the loop;url:with anhttp(s)address 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
| Tool | How Map sees it | What you get |
|---|---|---|
| Claude Code | Local logs in ~/.claude/projects, automatically. Hooks are optional |
Sessions, tool activity, file trails, sub-agents, and task lists from TaskCreate/TaskUpdate or TodoWrite |
| Codex | Local logs in ~/.codex/sessions, automatically |
Sessions, tool activity and file trails. Plans appear only when the log contains an update_plan call, which recent versions rarely write, so they usually show as unknown |
| pi | The Agenttrail extension for pi | Sessions, tool activity, file trails, and todo lists from a todo tool |
| Any other agent | Events it posts to Map, see Reporting runs from any agent | Whatever it reports: sessions, tools, written files and task lists |
| Cursor and other tools | No session adapter | File changes and whatever the agent records in PLAN.md |
Claude Code hooks are not needed to see a session. They add three things: events the moment they happen rather than within a few seconds, a reminder to the agent when the plan has fallen behind the code, and a terminal id in Map's data when the terminal sets HC_TERMINAL_ID. A session seen through both hooks and its log stays one run.
Map reads logs touched in the last two hours and at most the last 2 MiB of each. Cloud sessions with no logs on this machine are not visible. Local log formats can change between agent versions. How observability works
A mod for the Herdr desktop app draws Map natively beside your agents: the same cards and connectors from PLAN.md, in a side panel that expands to full size and follows the repo of the focused terminal. With no plan it falls back to a simple view from git. It only reads. See herdr/README.md.
Map binds to 127.0.0.1. It needs no account, telemetry, transcript upload, model call or cloud service, and it opens agent logs read-only. Run cards can show shortened command text, search terms and other tool details, and Map saves recent activity under ~/.agenttrail. Review what is visible before sharing a recording. Data sources and local storage
Map is a dependency-free Node daemon and a static page. It does not control your agents, send prompts, approve actions or mark their tasks complete.
Is Agenttrail an agent framework? No. You run agents in their existing tools, and Agenttrail shows the available evidence of what they are doing. Token billing and full model traces are not implemented.
Will this work in an existing repo? Yes, run it from that folder. Git and PLAN.md are optional.
Why is a session missing? A new session can take about ten seconds to appear. It must be working inside the watched repo, with its logs on this machine. A session that has been silent for two hours drops off the live view.
Does a finished task mean the work shipped? No. It means the agent reported the task complete. A turn ending or a file changing does not prove an outcome either.
What changes in my repo? Watching changes nothing. init creates the plan and agent instructions, offers hooks in .claude/settings.local.json, and adds a .gitignore entry.
What is still unverified? Windows has not been tested. Automated checks run on Linux and macOS.
What happened to Kitchen? The experimental 3D view has been retired so the project can focus on Map. Its last release stays on npm as agenttrail-kitchen, without further updates.
MIT for the project code and original assets.