A local monitor server and dashboard for coding-agent runtimes. This repository ships a Claude Code plugin-based event collection path and a Codex bootstrap path based on official hooks. The server and MCP layers are also open to manual HTTP/MCP clients.
Agent Tracer currently supports:
- Claude Code via plugin
- Codex via generated repo-local hooks and repo-local config
npm install
npm run build
npm run devPick one — they are independent and should not be combined.
| Mode | Who it's for | Claude Code | Codex | Status line |
|---|---|---|---|---|
| A. Marketplace plugin | Just want Claude Code observability, no clone needed | /plugin install agent-tracer-monitor@agent-tracer |
not supported (no plugin surface yet) | bash ~/.claude/plugins/marketplaces/agent-tracer/scripts/install-statusline.sh |
B. Local clone + setup:external |
Want Codex too, or want to hack on the runtime | claude --plugin-dir <clone>/packages/runtime (printed by the script) |
.codex/hooks.json written into your target project |
served by the plugin's statusLine; the wrapper script is unnecessary |
Mode B is what the rest of this README assumes unless noted. Mode A users
can stop after /plugin install + install-statusline.sh.
- Install and Run — clone the repo, install dependencies, start the monitor server and web dashboard, verify the installation.
- Claude Code Setup — load the plugin and register the MCP server. Claude Code integration is complete after these two steps.
- Codex Setup — use plain
codexwith the generated repo-local hooks and config.
If you want to use Agent Tracer with a project outside this repository, follow an additional step:
- External Project Setup — run
npm run setup:externalto generate.claude/settings.json,.codex/config.toml, and.codex/hooks.jsonin your target project.
Claude Code plugins can register hook events but cannot register a
statusLine (it is a settings.json-only field). For Mode A
(marketplace) installs, install the wrapper once globally to get the
[monitor] ctx N% · 5h N% · $X segment in every project:
# After installing the agent-tracer-monitor plugin via Claude Code
npm run setup:statusline
# or, without npm:
bash ~/.claude/plugins/marketplaces/agent-tracer/scripts/install-statusline.shThe script is idempotent and preserves any existing status line script
(backed up to *.bak.<ts> and re-sourced as statusline-original.sh).
Then add the printed statusLine block to ~/.claude/settings.json and
restart Claude Code.
Mode B users do not need this —
setup:externalregisters astatusLinevia the plugin's ownhooks.json, so the segment is rendered through--plugin-dirautomatically.
When running Claude Code inside the Agent Tracer repository itself,
setup:externalis not needed. You can start withclaude --plugin-dir packages/runtimedirectly.
Latest guide: https://belljun3395.github.io/agent-tracer/guide/
npm install
npm run build
npm run dev- Dashboard: http://127.0.0.1:5173
- Monitor server: http://127.0.0.1:3847
| Purpose | Document |
|---|---|
| Local installation and running | docs/guide/install-and-run.md |
| Claude Code plugin setup | docs/guide/claude-setup.md |
| Codex setup | docs/guide/codex-setup.md |
| External project setup (optional) | docs/guide/external-setup.md |
| Runtime capabilities reference | docs/guide/runtime-capabilities.md |
To view Markdown under docs/ as a paginated documentation site, use the
VitePress entrypoint:
npm run docs:dev- Default URL:
http://127.0.0.1:5174 - Home:
docs/index.md - Guide section:
docs/guide/*
- Workflow:
.github/workflows/deploy-docs.yml - First-time setup: select
GitHub Actionsin your repository settings underSettings > Pages > Build and deployment > Source. - After setup, any documentation changes pushed to
mainare automatically deployed to GitHub Pages. - Current deployment URL:
https://belljun3395.github.io/agent-tracer/
- Publish:
npm run publish:all(publishes@monitor/serverto npm with public access; other workspaces are currently private). - Manual GitHub Actions run:
- Select
Run workflowin.github/workflows/publish-packages.yml - Set
dryRuntotrueto run with--dry-run(no upload)
- Select
- Tag-based release deployment:
- Push a tag in the format
v*(e.g.,v0.1.0) to trigger the publish job.
- Push a tag in the format
- Requires
NPM_TOKENsecret in your repository (Settings > Secrets and variables > Actions).
The dashboard supports a rule lane — a distinct timeline lane (orange) for commands you
designate as mandatory checks (e.g. npm run lint, npm run typecheck).
- Open the shield icon in the top bar to manage rule patterns
- Patterns are matched by case-insensitive substring against the executed command string
- Patterns can be global (apply to all tasks) or task-scoped
- Matching
terminal.commandevents are reclassified to therulelane server-side at ingest
See API integration map § Rule Commands for the REST endpoints.
The dashboard now displays diagnostic information alongside event timelines:
- Top bar diagnostics cards: prompt capture rate, trace-linked task rate, stale running tasks, average task duration
- Inspector
Flowtab: phase breakdown, active duration, session state, top files/tags, work item/goal/plan/handoff focus - Inspector
Healthtab: trace link coverage, action-registry gaps, question/todo closure rates, coordination/background activity, runtime lineage
See docs/guide/task-observability.md for detailed contracts and API specs.
| Package | Path | Role |
|---|---|---|
@monitor/server |
packages/server |
NestJS monitor server (HTTP + WebSocket + SQLite) with an MCP stdio adapter exposed through the ./mcp subpath export |
@monitor/web |
packages/web |
React 19 dashboard |
@monitor/runtime |
packages/runtime |
Runtime adapters. Plugin root is packages/runtime/ (.claude-plugin/plugin.json). Hooks live at hooks/hooks.json + bin/run-hook-claude.sh (Claude) and bin/run-hook-codex.sh (Codex, hydrated from hooks/hooks-codex.json by setup:external). Hook source .ts files under src/claude-code/hooks/ and src/codex/hooks/. |