@misha_misha/agentwatch 0.0.3 → 0.1.0

package/README.md

@@ -2,25 +2,42 @@
 
 # agentwatch
 
-**See what every AI coding agent on your machine is doing — in one terminal.**
+**Local observability + control plane for every AI coding agent on your machine.**
 
-Local-only observability for Claude Code, Codex, Gemini CLI, Cursor, and
-OpenClaw — unified timeline, real token + cost accounting, compaction and
-anomaly detection, an MCP server agents can query their own history from,
-and an OpenTelemetry exporter with `gen_ai.*` semantic conventions. All
-local. No cloud. No telemetry. No sign-in.
+A terminal live-tail *and* a browser dashboard — one process, one event
+stream, served from `localhost`. Unified timeline across Claude Code,
+Codex, Gemini CLI, Cursor, Hermes, and OpenClaw. Token + cost accounting,
+compaction + anomaly detection, hybrid search, SVG call graphs,
+monaco-style diff attribution, agent-aware replay ("what would the agent
+say if I edited the prompt?"), policy editor, MCP server agents can query
+their own history from, and an OpenTelemetry exporter with `gen_ai.*`
+semantic conventions. All local. No cloud. No telemetry. No sign-in.
 
 [![npm](https://img.shields.io/npm/v/@misha_misha/agentwatch.svg)](https://www.npmjs.com/package/@misha_misha/agentwatch)
 [![CI](https://github.com/mishanefedov/agentwatch/actions/workflows/ci.yml/badge.svg)](https://github.com/mishanefedov/agentwatch/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 [![Node >=20](https://img.shields.io/badge/node-%E2%89%A520-brightgreen.svg)](./package.json)
+[![MCP server](https://glama.ai/mcp/servers/mishanefedov/agentwatch/badges/score.svg)](https://glama.ai/mcp/servers/mishanefedov/agentwatch)
 
 </div>
 
 <div align="center">
-  <img src="./docs/demo.gif" alt="agentwatch demo" width="820" />
+
+[![agentwatch on Glama](https://glama.ai/mcp/servers/mishanefedov/agentwatch/badges/card.svg)](https://glama.ai/mcp/servers/mishanefedov/agentwatch)
+
+</div>
+
+<div align="center">
+  <img src="./docs/timeline.png" alt="agentwatch web UI — unified timeline across 5 agents, each in its own workspace" width="1100" />
+  <br />
+  <img src="./docs/event-detail.png" alt="agentwatch event detail view — full command, tool I/O, usage + cost" width="1100" />
 </div>
 
+**The TUI is the live tail. The web UI is where you drill in** — projects,
+sessions, token charts, compaction sparklines, SVG call graphs, diff
+attribution, replay, anomaly triage, policy editing. Both run in one
+process. Press `w` in the TUI to open the browser.
+
 ---
 
 ## Table of contents
@@ -63,6 +80,37 @@ 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
@@ -85,11 +133,18 @@ name was already taken by a CyberArk tool. The installed binary on your
 
 ```bash
 agentwatch doctor   # detects installed agents + readiness
-agentwatch          # launches the TUI
+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 <n>` / `--host <addr>` — override web server bind
+- `AGENTWATCH_PORT=… AGENTWATCH_HOST=…` — env equivalents
+
 `doctor` output looks like:
 
 ```
@@ -99,15 +154,40 @@ 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 the TUI and every event your agents emit streams in. The last 4 MB
-of each active session is backfilled on startup so you have immediate
-context. Press **`?`** to see every hotkey.
+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.
 
 ---
 
@@ -117,21 +197,22 @@ 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 |
-| ------------------------------ | :---------: | :---: | :--------: | :----: | :------: |
-| 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             | ✅          | —     | 🟡         | —      | 🟡       |
-| Agent memory file overhead     | `CLAUDE.md` | `AGENTS.md` | `GEMINI.md` | `.cursorrules` | `OPENCLAW.md` |
-| OTel span coverage             | ✅          | ✅    | ✅         | 🟡     | ✅       |
-| MCP server exposes history     | ✅          | ✅    | ✅ (raw)   | ❌     | ❌       |
+| 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
@@ -140,6 +221,12 @@ triggers, search, stale detection, clipboard yank).
   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 <prompt> -Q --max-turns 1`.
 
 ---
 
@@ -153,11 +240,11 @@ Columns: time · agent · type · `[project]` summary · duration · error.
 
 ```
 09:54:01  openclaw     response       [content_agent] <think> Checked the KB…
-09:52:53  claude-code  response       [auraqu] Commit bddc363. q now exits instantly…
+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      [auraqu] Edit: src/ui/App.tsx · 7ms
+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      [auraqu] Agent: Competitive landscape ▸ 52 child events
+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.
@@ -406,6 +493,7 @@ clipboard (on explicit `y`) / disk (on explicit `e` to export).
 | `~/.gemini/settings.json` + `trustedFolders.json`            | Gemini permissions                       |
 | `~/.openclaw/agents/*/sessions/*.jsonl`                      | OpenClaw sub-agent sessions              |
 | `~/.openclaw/logs/config-audit.jsonl` + `openclaw.json`      | OpenClaw config audit + agent roster     |
+| `~/.hermes/state.db` (SQLite)                                | Hermes Agent sessions + messages         |
 | `~/.cursor/{mcp.json, cli-config.json, ide_state.json}`      | Cursor config state                      |
 | Any `.cursorrules` / `.cursor/rules/*.mdc` under WORKSPACE   | Cursor project rules                     |
 | `{CLAUDE,AGENTS,GEMINI,OPENCLAW}.md` + `.windsurfrules` etc. | Per-agent memory files for token attribution |
@@ -546,7 +634,7 @@ TypeScript monorepo. Three-layer mental model:
                           │  EventSink.emit / enrich
 ┌─────────────────────────┴───────────────────────────────────┐
 │  Adapter layer  (one per agent)                             │
-│    claude-code · codex · gemini · cursor · openclaw         │
+│    claude-code · codex · gemini · cursor · openclaw · hermes │
 │    fs-watcher (generic)                                     │
 └─────────────────────────▲───────────────────────────────────┘
                           │  files read-only
@@ -595,7 +683,7 @@ Local-first is a hard invariant.
 - **All files read-only** except the clipboard (on `y`) and `./agentwatch-export/` (on `e`).
 - Every path agentwatch reads is documented in [SECURITY.md](./SECURITY.md).
 
-Report vulnerabilities privately: `misha@auraqu.com` or via a
+Report vulnerabilities privately via a
 [Security Advisory](https://github.com/mishanefedov/agentwatch/security/advisories/new).
 
 ---