# Agentwatch

> Local-only observability for AI agents on your machine. One timeline across coding and non-coding agents.

- **Type:** MCP server
- **Install:** `agentstack add mcp-mishanefedov-agentwatch`
- **Verified:** Pending review
- **Seller:** [mishanefedov](https://agentstack.voostack.com/s/mishanefedov)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mishanefedov](https://github.com/mishanefedov)
- **Source:** https://github.com/mishanefedov/agentwatch
- **Website:** https://github.com/mishanefedov/agentwatch#readme

## Install

```sh
agentstack add mcp-mishanefedov-agentwatch
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 📟 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`](https://github.com/matt1398/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

```bash
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

```bash
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](https://github.com/NousResearch/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` — tool_input JSON + tool_result 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`:

```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:

```json
[
  { "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](https://github.com/mishanefedov)
- **Source:** [mishanefedov/agentwatch](https://github.com/mishanefedov/agentwatch)
- **License:** MIT
- **Homepage:** https://github.com/mishanefedov/agentwatch#readme

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mishanefedov-agentwatch
- Seller: https://agentstack.voostack.com/s/mishanefedov
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.