Agents Observe
Real-time observability dashboard for Claude Code and Codex agents.
Includes powerful filtering, searching, and visualization of multi-agent sessions with full replay and token usage stats.
Demo video
Version 0.9.7 adds token usage and cost breakdowns in session stats.
Quick Start
Install as a claude code plugin:
# Add this repo as a marketplace
claude plugin marketplace add simple10/agents-observe
# Install the plugin
claude plugin install agents-observe
# Then just run claude
# The plugin will auto start the MCP server and capture events
claude
# Use the /observe skill in claude to check status, restart the server, etc.
> /observe status
> /observe debug
> /observe logs
> /observe restart
# Open the dashboard UI in a browser
open http://localhost:4981
Default dashboard URL: http://localhost:4981
Data Location
By default, the SQLite DB and logs live under:
$CLAUDE_PLUGIN_DATA when running as a Claude plugin. Claude Code names this dir
<plugin>-<marketplace> — so a marketplace install lands at
~/.claude/plugins/data/agents-observe-agents-observe/, and a --plugin-dir
install lands at ~/.claude/plugins/data/agents-observe-inline/.~/.agents-observe/ when running outside Claude (Codex, manual CLI, dev).
The DB sits at <root>/data/observe.db, logs at <root>/logs/.
To pin the location somewhere else — e.g. an external volume — set
AGENTS_OBSERVE_LOCAL_DATA_ROOT in your ~/.claude/settings.json:
// ~/.claude/settings.json
"env": {
"AGENTS_OBSERVE_LOCAL_DATA_ROOT": "/path/to/your/dir"
},
Upgrading the plugin preserves your DB automatically. If you're upgrading
from a pre-fix version (≤ 0.9.8) the server scans for a DB under the old
version-scoped install dir on first start and copies it into the stable
location. See <root>/data/.migrated-from.json for the record.
Prerequisites
- Docker — the server runs as a container
- Node.js — hook scripts run via
node
- Bash - hooks are configured to use
hooks.sh for fast fire and forget event logging
If docker, node, or bash are not installed on your host, the plugin will fail to properly load.
Use the /observe debug claude command to help troubleshoot and fix installation issues.
Plugin Skills
| Skill | Description |
|---|
/observe view | Open the current session in the dashboard |
/observe stats | Open the current session's stats modal in the dashboard |
/observe | Open the dashboard URL and check if the server is running |
/observe status | Show server health, version, runtime, and config details |
/observe start | Start the server |
/observe stop | Stop the server |
/observe restart | Restart the MCP server |
/observe logs | Show recent Docker container logs |
/observe debug | Diagnose server issues (health, docker logs, mcp.log, cli.log) |
Why observability matters
When Claude Code runs autonomously — spawning subagents, calling tools, reading files, executing commands — you have no visibility into what's actually happening. The terminal shows a fraction of the activity. Subagents are invisible. Tool calls blur together. And when something goes wrong three agents deep in a parallel execution, you're left reading through logs after the fact.
Agents Observe captures every hook event as it happens and streams it to a live dashboard. You see exactly what each agent is doing, which tools it's calling, what files it's touching, and how subagents relate to their parents. In real time.
This matters because:
