Agenttrail Map and Kitchen: watching Codex and Claude Code from the outside
Local observability for AI coding agents. Agenttrail Map shows project structure and activity; Agenttrail Kitchen visualizes tasks and role contributions in 3D.
At a glance
- What is it?
- One JavaScript repository publishes two unrelated local viewers for coding agents, a component map driven by PLAN.md and a 3D kitchen driven by native agent todos. The interesting part is how little either one touches: neither launches an agent, assigns work, or decides a task shipped.
- Who is it for?
- Agenttrail fits people who already run Codex or Claude Code locally and want to see which files and todos are moving without tailing logs. Skip it if you need it to judge whether a task is actually finished, because the project itself says a completed turn is not a shipped deliverable, and verify your platform first, since Windows and native Cursor sessions are still unvalidated.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 15 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- sodiumsun/agenttrail1,048 ★ · +388
| Repository | 2026-09-11 | 2026-11-21 |
|---|---|---|
| sodiumsun/agenttrail | 660 | 1k |
388 Stars in the last 71 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Two npm commands, two services, one repository
The Map is the older piece and keeps its own package. The root `package.json` is named `agenttrail`, sits at version 0.2.0, declares one binary named `agenttrail` pointing at `bin/agenttrail.mjs`, and publishes three things: `bin`, `public` and `docs/demo.gif`. Kitchen is a separate npm package on a separate version line, `agenttrail-kitchen`, published as 0.1.0-alpha.3. You launch the two views with different commands in the same checkout, `npx agenttrail` for the component view and `npx agenttrail-kitchen .` for the 3D one.
Neither view is remote. Both open a browser tab against a local service, and both read state that already exists on disk. What they do not share is the plumbing underneath: each runs its own local service with its own provider adapters, and the project states plainly that their activity coverage and their history are not identical. Kitchen can read the context of a Map that is already running, so you can hold the project overview and the task scene open at once, but a session that shows up in one is not promised the same history in the other. The repository layout backs that split up: `packages/`, `assets/`, `bin/`, `public/` and a `docs/kitchen/` folder sit next to a root `PLAN.md`, `AGENTS.md`, `CLAUDE.md` and `CONTRIBUTING.md`.
The Kitchen watcher reads logs and never launches anything
Point the watcher at a repository and leave the terminal open:
npx agenttrail-kitchen .The browser comes up at `localhost:4780`, or the next free port when 4780 is taken. Codex and Claude Code activity is discovered from whatever local logs those tools already leave behind, which is why the barrier to entry is low: Node.js 20 or newer, a browser with WebGL, and a folder with local project files. No `PLAN.md`, no Map install, no copied files, no API key and no new agent session is required for basic observation, and the watcher neither launches agents nor edits your repo.
There is a scripted path for evaluating it without an agent attached. Add `--example` to the command and the scene advances with a Next example step button; it is a labeled demo, and the Live button takes you back to your real repo. The npm package ships the graphics and fonts, so there is no build step between you and the 3D scene. Because the tag line is moving fast, the docs suggest pinning instead of floating:
npx [email protected] .What Kitchen infers, and what stays progress unknown
The scene draws a kitchen and maps your work onto it: a chef is a project responsibility, a ticket is an available native todo with its own wording and status, cooking is observed work tied to that responsibility, and the delivery conveyor carries a native todo that the agent reported complete. Plate transfer carries explicit artifact revision and receipt metadata.
Some of this is free and some of it has to be declared. Local activity, supported native todos, inferred responsibilities and todo completion happen on their own. Confirmed handoffs, and explicitly sharing one todo across separate sessions, need extra metadata. The recorded multi-agent demo used those bindings, so opening any repository does not create them for you.
The project is careful about the difference between evidence and conclusion, and the honest parts are the most useful. Missing plans stay marked progress unknown rather than being guessed at. Ending a turn is not treated as a shipped deliverable. Chefs represent responsibilities rather than separate agent processes, and clicking a chef or a ticket opens the evidence behind it. One session can move between chefs as its work changes, roles adapt to the project, and you can refine them through an optional workflow configuration under `examples/kitchen-workflow`. Larger workflows get more than one kitchen.
Kitchen's ticket vocabulary is your agent's own todo list
The reason Kitchen can show tasks at all is that it reads the todos agents already keep, rather than asking you to restate your backlog somewhere else. A ticket carries the native todo's own wording and status, so what you see in the kitchen is the same phrase your agent wrote. When several roles or sessions touch one todo, they show up as several chefs on a single ticket, which is a view of shared work that a per-process log would miss.
Adapters exist for the tools people actually run. Codex CLI and local Codex desktop sessions are picked up from local session logs automatically. Claude Code is read from local project logs, with optional additive hooks installed through a Connect agents flow. Cursor needs the same explicit hook setup, reviewed in the repo before you rely on it. Anything else shows file changes and nothing more, because file observation works for every tool while native sessions and todos need a supported adapter.
The boundary matters when you read the scene. A delivery on the conveyor means a todo was reported complete, not that a reviewer accepted the change. A plate transfer only appears when artifact revision and receipt metadata were recorded. Roles are inferred from observed activity, so a quiet repository produces quiet chefs until you give the workflow configuration something to work with.
The Cursor adapter passes tests without a live run
The verification status is uneven across tools, and it is written down per row rather than averaged. Codex CLI and local Codex desktop sessions and Claude Code are marked as exercised by real local collaboration. Cursor shows adapter tests passing with native live validation still pending. VS Code has no Agenttrail extension shipped at all; you run the Kitchen command in its integrated terminal and keep the browser beside your editor. Other tools get file observation only.
For VS Code and Cursor the integration is described as a local companion rather than a Marketplace extension. Hook setup is explicit and reversible, and if newly installed hooks do not load, you restart the agent conversation rather than patching config.
Platform coverage is narrower than the package count suggests. Local observation has been exercised on macOS, and the automated package and adapter checks run on Linux. Windows and native Cursor validation remain pending. There is also a host rule that is easy to miss: cloud or remote sessions that leave no logs on the Kitchen host are not discovered automatically, so a team whose agents run somewhere other than the laptop watching the scene will see an empty kitchen and no error.
Map reads PLAN.md and file changes, not Claude's TaskCreate lists
The Map is the lighter half and starts in your repo:
cd your-repo
npx agenttrailIts model is declared intent plus observed evidence. `PLAN.md` holds the component structure, file changes supply the activity, and a component that was already complete lights up again when its files change. Claude Code hooks add session and tool activity plus legacy `TodoWrite` lists. Map does not yet parse Claude's newer `TaskCreate` and `TaskUpdate` lists, which is the concrete gap between what the two views of the same repo can tell you. Codex, Cursor and other tools contribute through file observation and the shared plan convention; their native session adapters currently belong to Kitchen.
Setting up the full component map writes files, which normal watching does not. Running `npx agenttrail init` adds the convention to `CLAUDE.md` and `AGENTS.md`, creates a starter plan, offers local Claude Code hooks, and puts `.agenttrail/` into `.gitignore`. You review the setup, then hand your agent the backfill prompt from the board so the plan gets filled in with real components.
Three Kitchen alpha tags shipped within forty minutes
The release history explains the preview label. On 2026-09-09 the Kitchen package published `kitchen-v0.1.0-alpha.1` at 02:22 UTC, marked superseded, then `kitchen-v0.1.0-alpha.2` at 02:26, then `kitchen-v0.1.0-alpha.3` at 02:58 as the npm preview. The last repository push carries the same date. Meanwhile the Map package at the root is already at 0.2.0 on its own independent line, so the version numbers you compare across the two commands do not mean the same thing.
Treat the alpha number as the thing to pin, not a sign of a broken build: alpha.1 and alpha.2 were superseded within minutes, and alpha.3 is the one the docs name. The repository is MIT licensed, written in JavaScript as ES modules, declares Node 20 or newer, and had 716 stars with 54 forks and 6 open issues when this snapshot was taken. The root `package.json` keyword list reads like a positioning statement: local-first, file-watcher, plan, agent-observability, live-map, live-dashboard.
Documentation is split the same way as the code. Kitchen has `docs/kitchen/README.md`, a connecting and troubleshooting guide, and a release and verification page; the Map side points at `docs/OBSERVABILITY.md`. Anyone judging this project should read the connecting guide first, because most of the surprising behavior comes from what a host does not have rather than from what the viewer does.
Editorial conclusion
Agenttrail fits people who already run Codex or Claude Code locally and want to see which files and todos are moving without tailing logs. Skip it if you need it to judge whether a task is actually finished, because the project itself says a completed turn is not a shipped deliverable, and verify your platform first, since Windows and native Cursor sessions are still unvalidated.
Frequently asked questions
Does Agenttrail run my coding agents or assign them work?
No. It observes local files, plans and supported agent events and visualizes that evidence. The watcher does not launch agents, assign their work, or decide that a task is finished.
What do I need installed before Agenttrail Kitchen shows anything?
Node.js 20 or newer, a browser with WebGL, and a local project folder. No PLAN.md, Map install, copied files, API key or new agent session is required for basic observation.
Which coding agents does Agenttrail Kitchen read?
Codex CLI and local Codex desktop sessions are read from local logs automatically, and Claude Code is read from local project logs with optional hooks. Cursor uses an explicit hook setup and its live validation is still pending.
Does Agenttrail work on Windows or with remote cloud agent sessions?
Windows and native Cursor validation remain pending, and local observation has been exercised on macOS. Cloud or remote sessions that leave no logs on the Kitchen host are not discovered automatically.
What does npx agenttrail init change in my repository?
It adds the convention to CLAUDE.md and AGENTS.md, creates a starter plan, offers local Claude Code hooks, and adds .agenttrail/ to .gitignore. Normal watching writes none of those files.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/sodiumsun-agenttrail)Star history chart for your README
[](https://hysenlabs.com/projects/sodiumsun-agenttrail)Was this useful?