agenttrail: local observability for coding agents, split across two views

The problem agenttrail addresses: agent work is spread across terminals

A coding agent running in Codex or Claude Code leaves evidence in several places at once. There are local session logs, file writes in the working tree, a PLAN.md if the project keeps one, and whatever native todo list the agent maintains. Reading all of that means switching between terminal windows and editor tabs. Agenttrail's stated goal is to watch the activity that is already available and turn it into a live view, so you can see which part of a project is changing and where attention is needed. The README is explicit about the boundary: agenttrail does not run the agents, assign their work, or decide that a task is finished. It observes. That framing matters because it sets the tool's ceiling. It is a viewer over local evidence, not an orchestrator, and the README repeats the point in several places, including the note that ending a turn does not mean a deliverable shipped. The audience is a developer who already runs an agent locally and wants a second window that answers questions the agent's own terminal does not: which components are moving, which responsibilities are active, and what has been reported complete.

Map and Kitchen are two products sharing one repository

The repository ships two views with different jobs. Agenttrail Map follows project structure, progress and which components are changing, drawing on PLAN.md, file changes and optional Claude Code hooks. Its entry point is npx agenttrail, run inside the repository you want to watch. Agenttrail Kitchen follows current tasks, role contributions and completed work, drawing on available native todos, local Codex and Claude activity, and optional Claude or Cursor hooks. Its entry point is npx agenttrail-kitchen . The README states plainly that the two currently have separate local services and provider adapters, and that their activity coverage and history are not identical. Kitchen can also read a running Map's context, but that is a one-way read, not a merge. A plan file is optional for Map's file activity and needed for its component map; for Kitchen it is optional because native todos supply order tickets when available. Anyone expecting one dashboard over one data model should read that table carefully. Two install commands, two ports, two adapter layers.

How Kitchen turns agent activity into a cooking scene

Kitchen's metaphor is a working kitchen, and the README maps each visual element to a concrete data source. A chef is a project responsibility, not necessarily a separate agent process, and the underlying provider and session stay inspectable. A ticket or dish is an available native todo, keeping its own wording and status. Cooking is observed work associated with that responsibility. Several chefs on one ticket means contributions from roles or sessions tied to the same todo. Plate transfer corresponds to explicit artifact revision and receipt metadata. The delivery conveyor lights up when a native todo is reported complete. One session can move between several chefs as its work changes, and roles adapt to the project, refinable through an optional workflow configuration under examples/kitchen-workflow. Larger workflows can be split across multiple kitchens. The README separates what happens automatically (local activity, supported native todos, inferred responsibilities, todo completion) from what needs extra metadata (confirmed handoffs, and explicitly sharing one todo across separate sessions). That distinction is the honest part of the design: handoffs are not inferred from timing, they require bindings, and the recorded multi-agent demo used those bindings. Opening any repository does not create them.

Getting it running: two npx commands and a port

Requirements are Node.js 20+, a browser with WebGL, and a local project folder. Kitchen starts with npx agenttrail-kitchen . run inside the target repo. The browser opens at localhost:4780, or the next free port, and the terminal must stay open. To pin the release, the README gives npx agenttrail-kitchen@0.1.0-alpha.3 . Adding --example runs a labeled, scripted demonstration with a Next example step button, and a Live button returns to the real repo. No PLAN.md, no Map installation, no API key and no new agent session are required for basic observation, and the watcher does not launch agents or edit the repository. Map starts separately with cd your-repo followed by npx agenttrail. The npm package for Kitchen bundles graphics and fonts, so there is no build step for users. Agent connections are configured through a Connect agents control in the interface, with a dedicated Cursor path that asks you to review the repo hook setup. Hook installation is described as explicit and reversible, and the README notes that an agent conversation may need restarting if newly installed hooks do not load.

Coverage gaps: Windows, Cursor and remote sessions

The verification table is the most useful part of the README because it says what has not been checked. Codex CLI and local Codex desktop sessions read available local session logs automatically, and real local collaboration has been exercised. Claude Code reads local project logs, with optional additive hooks. Cursor agents go through Connect agents, and the status is that adapter tests pass while native Cursor live validation is pending. VS Code works only as a browser companion in its integrated terminal; no Agenttrail editor extension has shipped. Other tools get file observation only, with native sessions and todos requiring a supported adapter. Local observation has been exercised on macOS, while automated package and adapter checks run on Linux, and Windows validation remains pending. Cloud or remote sessions with no logs on the Kitchen host are not automatically discovered at all. That last constraint is structural rather than a bug: if the logs are not on the machine running the watcher, there is nothing to read. A team running agents in a remote container will see file changes at best, and only if the files are mounted locally.

Where agenttrail is the wrong tool

The clearest failure mode is a missing plan combined with an agent that keeps no native todos. Kitchen then has no order tickets, and Map shows file activity without a component map. The README states that missing plans stay progress unknown, which is a deliberate refusal to guess rather than a temporary limitation. Anyone who wants a progress percentage derived from heuristics will not get one. The second case is multi-agent coordination. If your workflow depends on knowing that one session handed a task to another, that requires explicit artifact revision and receipt metadata, plus bindings across sessions. Without them, contributions from separate sessions to the same todo will not be linked. The third case is remote execution, covered above. And the fourth is the alpha status itself. The three most recent releases are all Kitchen 0.1.0 alpha builds published on the same day, with alpha.1 marked superseded and alpha.2 labeled an experimental preview. The README calls the current package a public experimental preview. Pinning the version is the only way to avoid drift, and pinning means missing fixes.

What it does not replace: a diff, a test runner, or host-level monitoring

The obvious alternative for reviewing agent output is git itself. A diff shows exactly what changed in the working tree, and it is already installed, already understood, and already part of every review workflow. What git does not show is which responsibility produced a change, which native todo is in flight, or how a session moved between tasks over time. That is the gap agenttrail targets, and it is a real one for long agent sessions where the diff grows faster than you can read it. The difference in approach is worth stating precisely: git records state, agenttrail records activity, and the activity view is only as good as the local evidence available. Host-level monitoring tools such as system or process monitors answer a different question again, about resource use rather than task progress. None of these overlap enough to make agenttrail redundant, and none of them are replaced by it. A developer who wants a permanent audit trail should not expect one here either: the README describes a live view over local files and events, and says the two views' history is not identical, not that either view persists a durable record.

Maintenance cost, licence and what to verify first

The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement, and nothing in the supplied material suggests additional terms, though anyone embedding it in a product should read the LICENSE file rather than rely on a summary. The maintenance picture is mixed. The last push is dated 2026-09-09, the same day as the three Kitchen alpha releases, so the project is active, but the release cadence so far is a single day of alpha tags rather than a track record. Kitchen and Map version independently, with agenttrail-kitchen and agenttrail published as separate npm packages, which means two upgrade paths to track and two sets of adapter behaviour to re-check after each bump. Hook setup is described as reversible, and the watcher does not edit the repository, so the blast radius of trying it is small. The practical first step is to run npx agenttrail-kitchen . in one repository and check whether native todos appear as tickets. If they do not, the tool is showing file activity only, and the decision about adopting it should be made on that basis.

Editorial conclusion

Adopt agenttrail if you run Codex or Claude Code locally on macOS or Linux and want a read-only view of file activity, plans and native todos without sending anything off the machine. Skip it if you need Windows support, native Cursor validation, or a single unified dashboard, since Map and Kitchen currently run as separate local services with different activity coverage. Before relying on it, run npx agenttrail-kitchen . in one repo, confirm the browser opens on localhost:4780, and check whether your agent's todos appear as order tickets. If they do not, the view falls back to file observation only.

Official sources

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