agentwatch

Purpose

agentwatch provides local observability for users running multiple AI coding agents on the same machine. When using tools such as Claude Code, Codex, Gemini CLI, Cursor, Hermes, and OpenClaw simultaneously, each agent has its own logs, permission model, and session definitions, and they are mutually invisible to one another. agentwatch aggregates these events into a single unified timeline, helping users understand what each agent did, how much it cost, and when anomalies occurred.

Main Capabilities

• Multi-agent unified timeline: All events are sorted by event timestamp (not arrival order), with columns including time, agent, type, project summary, duration, and error.
• Event detail panel: Open with Enter, showing metadata, tokens/cost/duration, tool results (with syntax highlighting), full prompt or response text, extended thinking blocks, and tool input JSON.
• Sub-agent drill-down: Press x to limit the timeline to the internal tool calls of a particular sub-agent.
• Project and session navigation: The project grid summarizes each agent's session count, total cost, and recent activity.
• Cross-session search: Press ? to perform fuzzy substring search across all session files, preferring ripgrep.
• Per-session cost accounting: Built-in per-model rate table (Claude opus/sonnet/haiku, GPT-5/GPT-5-mini, Gemini 2.5 Pro/Flash), accounting for the billing weights of cache_read and cache_creation, to calculate the true dollar cost per turn.
• Per-turn token attribution: Press t to view a stacked bar chart per turn, distinguishing user, memory file, tool I/O, thinking, input/cache read/cache create/output.
• Context compaction visualization: Press C to view context fill percentage and auto-compaction markers, showing token counts before and after compaction.
• Budget alerts: Configure limits via ~/.agentwatch/budgets.json; when exceeded, display a red banner and trigger a system notification.
• Anomaly detection: MAD z-score outlier detection based on cost, duration, and input tokens, as well as detection of 1–4 cycle stuck-loop detectors.
• User-defined notification triggers: Configured via ~/.agentwatch/triggers.json, hot-reloaded.
• Desktop notifications: Alerts for sensitive events (such as .env access, rm -rf, sudo, curl | sh, tool errors, budget overruns, anomalies), rate-limited.
• Per-agent permission view: Press p to view each agent's permissions and configuration status.
• Session export: Press e to export Markdown and JSON.
• Syntax highlighting, stale session detection, clipboard copy.
• MCP server mode: Other agents can query their own history.
• OpenTelemetry export: After setting AGENTWATCH_OTLP_ENDPOINT, emit OTLP/HTTP spans following GenAI semantic conventions.

Usage

Requires Node ≥ 20, supports macOS or Linux (Windows is not yet in scope for v0.x). Install via npm (package name is in the @misha_misha scope); after installation the binary is named agentwatch. Web service binding can be controlled via --no-web (TUI only), --port/--host, or the AGENTWATCH_PORT/AGENTWATCH_HOST environment variables. The TUI is a real-time log stream; the Web UI is by default located at http://127.0.0.1:3456，按 w Open in browser. ⌘K / Ctrl+K opens the command palette, / focuses the timeline filter.

Applicable Scenarios

• Multi-agent task troubleshooting and postmortem review
• Cost overrun investigation
• Security auditing and .env leak alerts
• Stuck loop detection
• Sub-agent postmortem analysis

Limitations

• agentwatch is a viewer, not a daemon; it only captures events while the TUI is running, and a background capture daemon is still planned.
• On startup, backfill reads the last approximately 4 MB of each active session file, so long gaps may miss the earliest events.
• Cursor only captures configuration-level state; its AI activity is stored in a SQLite database that has not yet been parsed.
• Gemini CLI does not persist compaction markers; OpenClaw does not persist tool_result content and compaction markers, which are structural data limitations.
• Windsurf, Aider, and Cline can be detected but are not yet integrated.
• Only macOS and Linux are supported.
• The tokenizer is cl100k_base, which has about a 5% error rate for Claude and only affects the user/thinking/tool I/O/memory-file classification in the attribution view; exact tokens come from the model's own usage records.
• Positioning boundaries: not cloud-based, not SaaS, not the agent itself, not production-grade LLM application tracing, not enterprise compliance, not orchestration, not memory, and not a governance and policy enforcement tool.
• Local-first is a hard invariant: there are no network calls unless AGENTWATCH_OTLP_ENDPOINT is explicitly set; no telemetry; all files are read-only except for the clipboard and explicit exports.