Agentwatch

📟 agentwatch

Five AI agents on one machine, and no idea what any of them just did.

agentwatch is one local timeline for every coding agent you run — Claude Code, Codex, Gemini CLI, Cursor, Hermes, OpenClaw. What they ran, what it cost, and when they went off the rails. All local: no cloud, no telemetry, no sign-in.

[](https://www.npmjs.com/package/@misha_misha/agentwatch) [](https://github.com/mishanefedov/agentwatch/actions/workflows/ci.yml) [](./LICENSE) [](./package.json) [](https://glama.ai/mcp/servers/mishanefedov/agentwatch)

[Install](#install) • [First 60 seconds](#first-60-seconds) • [Features](#features) • [MCP](#mcp-server-mode) • [Compare](#how-it-compares)

---

> 🤖 Reading this as an AI agent? Go straight to [AGENTS.md](./AGENTS.md) — it > self-onboards you in three steps (install → verify → run), no account needed.

The TUI is the live tail; the web UI is where you drill in — projects, sessions, token charts, compaction sparklines, call graphs, diff attribution, replay, anomaly triage. Both run in one process. Press w in the TUI to open the browser.

---

Table of contents

• [Why this exists](#why-this-exists)
• [Install](#install)
• [First 60 seconds](#first-60-seconds)
• [Agent coverage](#agent-coverage)
• [Features](#features)
• [Keyboard reference](#keyboard-reference)
• [Configuration](#configuration)
• [What agentwatch reads](#what-agentwatch-reads)
• [MCP server mode](#mcp-server-mode)
• [OpenTelemetry exporter](#opentelemetry-exporter)
• [How it compares](#how-it-compares)
• [Limitations](#limitations)
• [Non-goals](#non-goals)
• [Architecture](#architecture)
• [Development](#development)
• [Security](#security)
• [License](#license)

---

Why this exists

You run three AI coding agents on one laptop. Claude Code in a terminal, Codex alongside it, Cursor as your IDE, maybe Gemini CLI for a quick review, maybe an OpenClaw sub-agent churning on a long task. Every one of them has its own log file, its own permission model, its own idea of what a "session" is. None of them tells you what the others are doing.

When something goes wrong — a file rewritten unexpectedly, a spend spike, an rm you don't remember running — you're piecing it together from five JSONLs and guessing.

claude-devtools does this well for Claude Code. agentwatch does it for the whole multi-agent stack, in the terminal, with zero infrastructure and zero network.

---

Why this over claude-devtools if you run multiple agents?

Short, factual diff. claude-devtools is a great tool for Claude-only workflows — if you only use Claude Code, it's probably the better pick. agentwatch is the answer when you run more than one agent on the same machine and want one timeline + one cost ledger + one alerting surface across all of them.

| What | claude-devtools | agentwatch | | -------------------------------------------- | ----------------------- | ------------------------------------- | | Claude Code coverage | ✅ full | ✅ full | | Codex coverage | ❌ | ✅ tokens + tools + cost + compaction | | Gemini CLI coverage | ❌ | ✅ tokens + tools + cost | | OpenClaw coverage | ❌ | ✅ tokens + cost | | Hermes Agent coverage | ❌ | ✅ tokens + tools + cost (SQLite) | | Cursor coverage | ❌ | 🟡 config level | | Per-agent budget alarms | ❌ | ✅ session + daily caps | | Statistical anomaly detection (loops / spikes) | rule-based only | ✅ MAD z-score + period-1-to-4 loops | | OpenTelemetry exporter (gen_ai.*) | ❌ | ✅ Jaeger / Tempo / Grafana ready | | MCP server — agents query their own history | ❌ | ✅ 5 tools over stdio | | User-defined regex/threshold triggers | ❌ | ✅ live-reloaded | | Install | Homebrew / Electron ~150 MB | npm i -g · 220 KB · TUI | | Data boundary | local | local |

If "every agent on one pane of glass + programmatic access via MCP + pipeline-friendly OTel" matches your setup, agentwatch is the tool. If you're Claude-only and want the Electron polish, claude-devtools is still excellent.

---

Install

npm i -g @misha_misha/agentwatch
agentwatch

Requires:

• Node ≥ 20 (tested on 20 + 22 in CI)
• macOS or Linux (Windows intentionally out of scope for v0.x)

Published under the @misha_misha npm scope — the unscoped agentwatch name was already taken by a CyberArk tool. The installed binary on your $PATH is simply agentwatch.

---

First 60 seconds

agentwatch doctor   # detects installed agents + readiness
agentwatch          # TUI live-tail + web UI at http://127.0.0.1:3456
agentwatch serve    # web UI only (remote boxes / server cron)
agentwatch mcp      # runs the MCP stdio server (for agents, not humans)
agentwatch --help

Flags:

• --no-web — TUI only, don't start the web server
• --port / --host — override web server bind
• AGENTWATCH_PORT=… AGENTWATCH_HOST=… — env equivalents

doctor output looks like:

workspace: /Users/you/IdeaProjects

agents:
  ● Claude Code        installed (events captured)
  ● Codex              installed (events captured)
  ● Gemini CLI         installed (events captured)
  ● Hermes Agent       installed (events captured)
  ● Cursor             installed (config-level only)
  ● OpenClaw           installed (events captured)
  ○ Aider              not detected
  ○ Cline (VS Code)    not detected

Launch agentwatch and every event your agents emit streams in. The TUI shows a live tail; the web UI at http://127.0.0.1:3456 is where you drill in — projects, sessions, token charts, SVG call graphs, diff attribution, prompt replay, trends. Press w in the TUI to open it.

Web UI map

| Route | What it is | | ------------------------------------ | ------------------------------------------------------- | | / | Live timeline (SSE-streamed) with agent + type filters | | /projects | Grid of detected projects + cost + session counts | | /projects/:name | Sessions table for one project | | /sessions/:id | Chronological event list · export .md / .json | | /sessions/:id/tokens | Stacked-area token chart per turn | | /sessions/:id/compaction | Context fill % over time + compaction markers | | /sessions/:id/graph | Call graph (d3-hierarchy SVG) — click nodes to drill | | /sessions/:id/diffs | Writes paired with the prompt that triggered them | | /sessions/:id/replay | Edit prompt → re-run the agent in single-turn exec | | /search | Unified search (live / cross / semantic) | | /agents | Grid of every supported agent + install status | | /permissions | Per-agent permission config | | /cron | OpenClaw cron jobs + heartbeats | | /trends | Cost, cache-hit ratio, events per agent (30d default) | | /settings/{budgets,anomaly,triggers} | Form editors for ~/.agentwatch/*.json |

⌘K / Ctrl+K opens the command palette. / focuses the timeline filter.

---

Agent coverage

What actually works per agent, as of v0.0.3. Features not listed here work across every agent (timeline, export, syntax highlighting, notifications, triggers, search, stale detection, clipboard yank).

| Feature | Claude Code | Codex | Gemini CLI | Cursor | OpenClaw | Hermes | | ------------------------------ | :---------: | :---: | :--------: | :----: | :------: | :----: | | Live events on timeline | ✅ | ✅ | ✅ | 🟡 | ✅ | ✅ | | Token usage + cost | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | | Tool call + result pairing | ✅ | ✅ | ✅ | ❌ | 🟡 | ✅ | | Per-turn token attribution | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | | Budget alarms (session + day) | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | | Anomaly detection (cost/loops) | ✅ | ✅ | ✅ | 🟡 | ✅ | ✅ | | Compaction visualizer | ✅ | ✅ | ❌ | — | ❌ | ❌ | | Permissions view | ✅ | ✅ | ✅ | ✅ | ✅ | — | | Cross-session search | ✅ | ✅ | ✅ | ❌ | ❌ | 🟡 | | Subagent drilldown | ✅ | — | 🟡 | — | 🟡 | 🟡 | | Replay (agent-aware exec) | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | | Agent memory file overhead | CLAUDE.md | AGENTS.md | GEMINI.md | .cursorrules | OPENCLAW.md | SOUL.md | | OTel span coverage | ✅ | ✅ | ✅ | 🟡 | ✅ | 🟡 | | MCP server exposes history | ✅ | ✅ | ✅ (raw) | ❌ | ❌ | ❌ |

• Cursor exposes config state (MCP servers, .cursorrules, approval

mode, sandbox) but its actual AI activity lives in a SQLite database we haven't parsed yet. A thin read-only adapter is a follow-up.

• Gemini CLI doesn't persist context-compaction markers to disk, so

compaction detection is Claude + Codex only.

• OpenClaw doesn't persist tool_result content or compaction markers

to its JSONL — structural limit of what's on disk, not an adapter gap.

• Hermes Agent (by

Nous Research — the OpenClaw successor with a closed learning loop) persists sessions to ~/.hermes/state.db (SQLite + FTS5). The adapter polls the DB over chokidar + 2s safety-net and emits the full session/prompt/response/tool-call stream. Replay re-runs single turns via hermes chat -q -Q --max-turns 1.

---

Features

Live multi-agent timeline

Main screen. Every event your agents emit, ordered by event timestamp (not arrival order, so backfill from different sessions merges correctly). Columns: time · agent · type · [project] summary · duration · error.

09:54:01  openclaw     response       [content_agent]  Checked the KB…
09:52:53  claude-code  response       [example] Commit bddc363. q now exits instantly…
09:52:48  codex        shell_exec     [dataset_research] ls -la · 12ms
09:52:43  claude-code  tool_call      [example] Edit: src/ui/App.tsx · 7ms
09:51:51  gemini       file_write     [landing] write_file: public/llms.txt
09:51:51  claude-code  tool_call      [example] Agent: Competitive landscape ▸ 52 child events

Rows with an anomaly fire a red ◎ prefix on the type column.

Event detail pane

Press Enter on any row. Opens a full-screen pane with:

• Metadata (time, agent, type, tool, path, cmd)
• Tokens / cost / duration (in=6 cache_create=25508 cache_read=16827 out=353 · $0.08 (claude-opus-4-6) · 151ms)
• Tool result — stdout for Bash, file content for Read/Write, search matches for Grep — with syntax highlighting inferred from the tool + file extension
• Full prompt or response text
• Extended thinking block when present
• Tool input JSON

Scrollable with ↑↓ or j/k. esc closes.

Subagent drilldown

Parent Agent tool_use events show ▸ 52 child events. Press x to scope the timeline to only that subagent's inner tool calls. X unscopes. Applies to Claude Code (Task tool) and partially to OpenClaw (per-agent delegation) and Gemini (subagent sessions).

Project + session navigation

P → projects grid (one workspace per row, across all agents)
     ↓ enter → sessions list (grouped Today / Yesterday / 7d / Older)
             ↓ enter → scoped timeline

Projects grid aggregates across agents: per-agent session counts, total cost, last activity. esc walks back one level.

Cross-session search (?)

Press ? — fuzzy-substring search across every session file on disk (~/.claude, ~/.codex, ~/.gemini). Uses ripgrep if installed, falls back to a native scan. Enter on a hit scopes the timeline to that session.

Different from in-buffer search:

• / — search the 500-event live buffer
• ? — search every session file ever written

Per-session cost with cache accounting

Naive token counters are 3–10× wrong on Claude because cache_read is billed at 10% of input and cache_creation at 125%. agentwatch ships a per-model rate table (Claude opus/sonnet/haiku, GPT-5 / GPT-5-mini, Gemini 2.5 Pro/Flash) and computes true USD cost per turn. Cost shows:

• Per-agent total in the side panel
• Per-event in the detail pane
• Per-session in the sessions list
• Aggregate in the session's token attribution view ([t])

Per-turn token attribution ([t])

Inside a scoped session, press t. Stacked bar per turn showing:

• user — the preceding prompt (tokenized with gpt-tokenizer)
• memory file — CLAUDE.md / AGENTS.md / GEMINI.md / .cursorrules / etc., read from the session's cwd
• tool I/O — toolinput JSON + toolresult text
• thinking — extended thinking block
• input (fresh) / cache read / cache create / output — exact from the model's own usage record

Compaction visualizer ([C])

Inside a scoped session, press C. Horizontal bar of context fill % across turns, with ⋈ markers where the agent auto-compacted. Selected compaction shows before / after token counts and the dropped-token delta. Works on Claude Code (via isCompactSummary) and Codex (via event_msg/turn_truncated).

Budget alarms

~/.agentwatch/budgets.json:

{ "perSessionUsd": 5, "perDayUsd": 20 }

Red banner in the Header when either cap is crossed; OS notification fires once per crossing. No kill switch — we don't control agents; we just shout.

Anomaly detection

Three detectors, all fully local, all running on the 500-event buffer:

• MAD z-score outliers on cost, duration, and input tokens per agent

(|z| > 3.5 by default — tune in ~/.agentwatch/anomaly.json)

• Stuck-loop detector with periods 1–4 — catches A-A-A-… and

A-B-A-B-… "apologize and retry" loops

• Per-session rollup + OS notification on first flag + timeline ◎ marker
• [D] to dismiss the banner

User-defined notification triggers

~/.agentwatch/triggers.json — live-reloaded via chokidar:

[
  { "match": "curl .* \\| (bash|sh)", "title": "pipe-to-shell", "body": "{{agent}}: {{cmd}}" },
  { "type": "file_write", "pathMatch": "^/etc/", "title": "/etc write" },
  { "thresholdUsd": 0.5, "title": "expensive turn", "body": "cost {{cost}}" }
]

Placeholders: {{agent}} {{type}} {{cmd}} {{path}} {{tool}} {{summary}} {{cost}}.

Desktop notifications

Built-in alerts fire on sensitive events — .env access, ~/.ssh / ~/.aws / ~/.gnupg paths, rm -rf, sudo, curl | sh, tool errors, budget breach, anomaly. Rate-limited (60s per rule key). Silent during backfill.

Platform dispatch: osascript on macOS, notify-send on Linux, PowerShell `Me

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mishanefedov
• Source: mishanefedov/agentwatch
• License: MIT
• Homepage: https://github.com/mishanefedov/agentwatch#readme

Install and usage instructions live in the source repository linked above.