Agenttrail: local observability for AI coding agents, with a Map and a 3D Kitchen

The gap Agenttrail targets: agents work, terminals do not show it

A coding agent edits files, reports todos and moves between roles, and the only window onto that is a scrolling terminal. Agenttrail takes the evidence that already exists on disk (file changes, PLAN.md, native todos, supported agent events) and renders it as a live view. The README frames the goal plainly: 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.

The audience is narrow and specific. You need a local project folder, Node.js 20+, and a browser with WebGL. You also need agents whose activity is discoverable on the same machine, which in practice means Codex CLI or local Codex desktop sessions and Claude Code. The project is explicit that it does not run the agents, assign their work or decide that a task is finished. It is an observer, and anyone expecting a controller will be disappointed.

Map and Kitchen are two views with separate services and adapters

The repository ships two views under one project name. Agenttrail Map shows project structure, progress and which components are changing, drawing on PLAN.md, file changes and optional Claude Code hooks. Agenttrail Kitchen shows current tasks, role contributions and completed work, drawing on available native todos, local Codex and Claude activity, and optional Claude or Cursor hooks. Kitchen can also read a running Map's context.

The README is careful about this split: they currently have separate local services and provider adapters, and their activity coverage and history are not identical. That is an honest admission of a real cost. If you want both views, you are running two local services and reasoning about two evidence sets. The npm packages are separate too, agenttrail for the Map and agenttrail-kitchen for the Kitchen, with the Map package at version 0.2.0 and Kitchen at 0.1.0-alpha.3.

The Map is the older, lighter half. Its package description says it works through PLAN.md, file activity and Claude Code hooks, and the README calls it independently installable. Kitchen is the newer, heavier half, published as an experimental preview. Treating them as one product with one mental model will lead you to expect shared history that the README says is not there.

Install Agenttrail Kitchen and watch a real repo

Kitchen is the view with the most moving parts, so it makes the better first test. Run the command inside the repository you want to watch. The README gives this exact form, and the browser opens at localhost:4780 or the next free port.

npx agenttrail-kitchen .

Keep that terminal open and keep working in your coding agent. Codex and Claude Code activity is discovered from available local logs. According to the README, no PLAN.md, no Map installation, no copied files, no API key and no new agent session is required for basic observation. The watcher does not launch agents or edit your repo.

If you want to see the interface before connecting anything, add the example flag. The README describes the result as a labeled, scripted example, and says you click Next example step to advance it and Live to return to your real repo.

npx agenttrail-kitchen . --example

The README notes the npm package includes the graphics and fonts, so there is no build step. To pin the release rather than track the latest preview, use the versioned form the README shows:

npx [email protected] .

For the Map, the README's own sequence changes directory first and then runs the shorter command:

cd your-repo
npx agenttrail

The Map's plan file is optional for file activity but needed for the component map, which is a distinction worth remembering before you conclude the map is broken.

Chefs, tickets and the conveyor: what the metaphor actually encodes

Kitchen's metaphor is not decoration; each element maps to a specific piece of evidence. A chef is a project responsibility, and the README notes the actual provider and session remain inspectable. A ticket or dish is an available native todo with its own wording and status. Cooking is observed work associated with that responsibility. Plate transfer means explicit artifact revision and receipt metadata. The delivery conveyor means a native todo reported complete.

The most useful row in that table is several chefs on one ticket, which the README defines as contributions from roles or sessions associated with the same todo. That is the multi-agent case people actually struggle to follow, and it is also where the README draws its sharpest line. What happens automatically is local activity, supported native todos, inferred responsibilities and todo completion. What needs extra metadata is confirmed handoffs and explicitly sharing one todo across separate sessions. The recorded multi-agent demo used these bindings, and the README states plainly that merely opening any repo does not create them.

So the impressive screenshot is a configured state, not a default one. Roles adapt to the project and can be refined with an optional workflow configuration under examples/kitchen-workflow, and multiple kitchens organize larger workflows. If you open a repo and see nothing resembling the demo, that is the documented behavior, not a bug.

Where Agenttrail stops: no plans, no native todos, no remote logs

Two failure modes are stated outright. Missing plans stay progress unknown, and ending a turn does not mean a deliverable shipped. Both are correct conservatism, and both will frustrate anyone who reads a quiet dashboard as good news. A repo with no PLAN.md and no native todos gives the Kitchen very little to render.

Platform coverage is uneven. Local observation has been exercised on macOS, while automated package and adapter checks run on Linux. Windows and native Cursor validation remain pending. Cloud or remote sessions with no logs on the Kitchen host are not automatically discovered, which rules out a common setup where the agent runs in a container or a remote machine and only the editor is local.

Cursor support is the thinnest of the named integrations. You choose Connect agents then Cursor and review the repo hook setup; the README says adapter tests pass but native Cursor live validation is pending. VS Code is not an extension at all. You run the Kitchen command in its integrated terminal and keep the browser beside your editor, and the README states no Agenttrail editor extension has shipped yet. Hook setup is explicit and reversible, and the README warns that you should restart an agent conversation if it does not load newly installed hooks. Tools with no supported adapter fall back to file observation only.

How Agenttrail compares with a general tracing stack

The obvious alternative is a general observability or tracing stack, the kind you would wire into a service to collect spans and ship them to a backend. That approach assumes your agent emits structured telemetry you control, and it usually assumes a collector and a remote store. Agenttrail inverts both assumptions. It is local-first, it reads artifacts the agent already leaves on disk (logs, todos, file changes, PLAN.md), and the README says nothing about sending that evidence anywhere.

The trade-off runs the other way too. A tracing backend gives you retention, query and alerting across machines; Agenttrail gives you a live browser view of one project on one host, with the README noting that Map and Kitchen do not even share identical history. If your question is what happened across a fleet of agents last month, Agenttrail is the wrong shape of tool. If your question is what this agent is doing to this repo right now, a span pipeline is a large amount of infrastructure for a question a file watcher can answer.

There is also a lighter alternative worth naming: reading the agent's own log files and watching git status yourself. That costs nothing and needs no install, and for a single agent in a single repo it may be enough. Agenttrail earns its place when several responsibilities or sessions touch the same todo and you want the contribution split visible rather than reconstructed by hand.

Maintenance, licensing and what the release cadence implies

The repository is not archived and the last push was on 2026-09-09, so it is close to current. That date is also the date of all three recent releases: kitchen-v0.1.0-alpha.1, alpha.2 and alpha.3, published within roughly forty minutes of each other, with alpha.1 marked superseded. Three alphas in one sitting reads as a single publishing session, not a track record, and the Kitchen label says public experimental preview.

The Map package sits at 0.2.0 and is described as independently installable, which makes it the more settled half. Kitchen is where interface and adapter churn should be expected. The version string 0.1.0-alpha.3 is the one to pin if you want reproducibility, and the README shows exactly how.

Licensing is MIT for the repository, and the npm packages carry the same license field. MIT permits commercial and private use with the usual requirement to preserve the licence and copyright notice. That is a statement about the licence text, not legal advice for your situation; if your organisation has rules about dependency licences, run it past whoever owns that policy. Note that the README does not document rollback, so if you install hooks through Connect agents, removing them is something you should plan for before you start rather than after.

Editorial conclusion

Adopt Agenttrail if you already run Codex or Claude Code locally and want a second window that shows file activity, native todos and role contributions without sending data anywhere. Skip it if your agents run in cloud or remote sessions with no logs on the host, if you need Windows support today, or if you expect it to assign or finish work, because the README states it does not run the agents or decide that a task is finished. Before relying on it, check whether your provider writes discoverable local logs, confirm Node.js 20+, and try the npx agenttrail-kitchen . --example flow to see the labeled scripted scene before connecting a real agent.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. sodiumsun/agenttrail on GitHub