agentwatch: Monitor AI Agent Activity Locally

Overview

agentwatch is a local observability tool for developers running multiple AI agents on one machine. It reads agent session and configuration files and brings supported activity into a shared timeline, helping users investigate unexpected actions, compare costs, and understand what happened across separate sessions.

It is most useful when switching between agents makes their independent logs difficult to follow. It is a viewer rather than an agent runner or background capture service, and its terminal interface can launch a local web UI for deeper inspection.

Key Features

• Combines supported agent events in a live terminal timeline, with a local web interface for session details.
• Tracks token usage and estimated costs, including cache accounting for supported models.
• Provides event details, session search, exports, and subagent drilldown where the source data supports it.
• Flags cost, duration, and token outliers, as well as repeated event loops.
• Supports configurable session and daily budget alerts and user-defined notification triggers.
• Offers an MCP server for querying session history and an optional OpenTelemetry exporter.
• Reads local agent logs and settings; the project states it has no telemetry and makes no network calls unless an OTLP endpoint is configured.

Use Cases

• Developers using Claude Code alongside Codex, Gemini CLI, or other supported agents can review activity in one timeline instead of checking separate logs.
• A developer investigating a surprising file change or command can inspect event details and session history to trace what the agent did.
• Users managing agent spend can monitor session and daily budgets and investigate unusually costly turns.
• Teams or individuals diagnosing repeated agent retries can use anomaly indicators to spot likely loops.
• Developers with an observability stack can optionally export agent events as OpenTelemetry spans.

Getting Started

Requires Node.js 20 or later and macOS or Linux. Install and run:

npm i -g @misha_misha/agentwatch
agentwatch

See the README for agent coverage, configuration, and usage details.

Alternatives

• agenttrail: Agenttrail maps file changes and agent activity in a 3D task view, while agentwatch focuses on searchable event timelines, costs, and alerts.

Considerations

• It captures activity while the TUI is running. It is not a background daemon, and startup backfill is bounded.
• Agent coverage varies. Cursor activity is limited to configuration data, while some other agents do not persist all event details that the tool can display.
• Windows is out of scope for the current v0.x release; documented support is for macOS and Linux.
• Node.js 20 or later is required. The repository describes the project as v0.0.3 in its agent coverage notes, so capabilities and support may evolve.
• Cost and token-attribution figures can involve estimates for some categories. The README notes that its tokenizer is approximate for Claude, while usage records provide exact model-reported input, cache, and output counts where available.