Skip to content
Back to search

agents-observe

Real-time observability of claude code sessions & multi-agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/simple10--agents-observe/badge.svg)](/listings/simple10--agents-observe)

HTML

<a href="/listings/simple10--agents-observe"><img src="/api/listings/simple10--agents-observe/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 13 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "agents-observe",
  3. "owner": {
  4. "name": "simple10"
  5. },
  6. "plugins": [
  7. {
  8. "name": "agents-observe",
  9. "description": "Real-time observability dashboard for Claude Code agents",
  10. "source": "./"
  11. }
  12. ]
  13. }
README.md · README · 312 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Agents Observe
  2. Real-time observability dashboard for Claude Code and Codex agents.
  3. Includes powerful filtering, searching, and visualization of multi-agent sessions with full replay and token usage stats.
  4. <p align="center">
  5. <a href="https://raw.githubusercontent.com/simple10/agents-observe/videos/docs/assets/dashboard.gif">
  6. <img src="https://raw.githubusercontent.com/simple10/agents-observe/videos/docs/assets/dashboard.gif" alt="Agents Observe Dashboard Demo" />
  7. </a>
  8. </p>
  9. <p>
  10. <a href="https://raw.githubusercontent.com/simple10/agents-observe/videos/docs/assets/demo.mp4">Demo video</a>
  11. </p>
  12. <p align="center">
  13. <img src="https://raw.githubusercontent.com/simple10/agents-observe/main/docs/assets/dashboard2.png" alt="Agents Observe Dashboard Screenshot - Expanded Row" />
  14. </p>
  15. > Version 0.9.7 adds token usage and cost breakdowns in session stats.
  16. <p align="center">
  17. <img src="https://raw.githubusercontent.com/simple10/agents-observe/main/docs/assets/session-token-usage1.png" alt="Agents Observe Session Token Usage" />
  18. </p>
  19. ## Quick Start
  20. Install as a `claude code` plugin:
  21. ```bash
  22. # Add this repo as a marketplace
  23. claude plugin marketplace add simple10/agents-observe
  24. # Install the plugin
  25. claude plugin install agents-observe
  26. # Then just run claude
  27. # The plugin will auto start the MCP server and capture events
  28. claude
  29. # Use the /observe skill in claude to check status, restart the server, etc.
  30. > /observe status
  31. > /observe debug
  32. > /observe logs
  33. > /observe restart
  34. # Open the dashboard UI in a browser
  35. open http://localhost:4981
  36. ```
  37. Default dashboard URL: <http://localhost:4981>
  38. ## Data Location
  39. By default, the SQLite DB and logs live under:
  40. - `$CLAUDE_PLUGIN_DATA` when running as a Claude plugin. Claude Code names this dir
  41. `<plugin>-<marketplace>` — so a marketplace install lands at
  42. `~/.claude/plugins/data/agents-observe-agents-observe/`, and a `--plugin-dir`
  43. install lands at `~/.claude/plugins/data/agents-observe-inline/`.
  44. - `~/.agents-observe/` when running outside Claude (Codex, manual CLI, dev).
  45. The DB sits at `<root>/data/observe.db`, logs at `<root>/logs/`.
  46. To pin the location somewhere else — e.g. an external volume — set
  47. `AGENTS_OBSERVE_LOCAL_DATA_ROOT` in your `~/.claude/settings.json`:
  48. ```jsonc
  49. // ~/.claude/settings.json
  50. "env": {
  51. "AGENTS_OBSERVE_LOCAL_DATA_ROOT": "/path/to/your/dir"
  52. },
  53. ```
  54. Upgrading the plugin preserves your DB automatically. If you're upgrading
  55. from a pre-fix version (≤ 0.9.8) the server scans for a DB under the old
  56. version-scoped install dir on first start and copies it into the stable
  57. location. See `<root>/data/.migrated-from.json` for the record.
  58. ---
  59. ## Prerequisites
  60. - [Docker](https://www.docker.com/) — the server runs as a container
  61. - [Node.js](https://nodejs.org/) — hook scripts run via `node`
  62. - Bash - hooks are configured to use `hooks.sh` for fast fire and forget event logging
  63. If docker, node, or bash are not installed on your host, the plugin will fail to properly load.
  64. Use the `/observe debug` claude command to help troubleshoot and fix installation issues.
  65. ## Plugin Skills
  66. | Skill | Description |
  67. |-------|-------------|
  68. | `/observe view` | Open the current session in the dashboard |
  69. | `/observe stats` | Open the current session's stats modal in the dashboard |
  70. | `/observe` | Open the dashboard URL and check if the server is running |
  71. | `/observe status` | Show server health, version, runtime, and config details |
  72. | `/observe start` | Start the server |
  73. | `/observe stop` | Stop the server |
  74. | `/observe restart` | Restart the MCP server |
  75. | `/observe logs` | Show recent Docker container logs |
  76. | `/observe debug` | Diagnose server issues (health, docker logs, mcp.log, cli.log) |
  77. ## Why observability matters
  78. 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.
  79. 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.
  80. This matters because:
  81. - **Multi-agent work is opaque.** A coordinator spawns a code reviewer, a test runner, and a documentation agent in parallel. Without observability, you only see the final result. With it, you watch each agent work and catch problems as they happen.
  82. - **Tool calls are the ground truth.** The assistant's text output is a summary. The actual tool calls — the Bash commands, file reads, edits, grep patterns — tell you what Claude is really doing. Agents Observe shows you both.
  83. - **Debugging is time travel.** When a subagent makes a bad edit or runs a destructive command, you need to trace back through the exact sequence of events. The event stream gives you that timeline with full payloads.
  84. - **Sessions are ephemeral, but patterns aren't.** By capturing events across sessions, you can see how agents behave over time, which tools they favor, and where they get stuck.
  85. ## What you can do
  86. - Watch tool calls stream in as they happen (PreToolUse → PostToolUse with results)
  87. - See the full agent hierarchy — which subagent was spawned by which parent
  88. - Filter by agent, tool type, or search across all events
  89. - Expand any event to see the full payload, command, and result
  90. - Click timeline icons to jump to specific events in the stream
  91. - Browse historical sessions with human-readable names (e.g., "twinkly-hugging-dragon")
  92. ## Architecture
  93. ```
  94. Claude Code Hooks → observe_cli.mjs → API Server (SQLite) → React Dashboard
  95. (agent-lib build) (HTTP POST) (parse + store) (WebSocket live)
  96. ```
  97. `observe_cli.mjs` reads the raw event from stdin and dispatches to an agent-class-specific lib (`hooks/scripts/lib/agents/<class>.mjs`) whose `buildHookEvent()` constructs the envelope — including agent-class-aware flags like `meta.isNotification` / `meta.clearsNotification` — then POSTs it to the server. The server applies those flags mechanically to its stored state (e.g. `pending_notification_ts`) and forwards events to subscribed WebSocket clients; it stays agent-class-neutral. The React dashboard derives all agent state (status, event counts, timing) from the event stream.
  98. ## Standalone Installation
  99. > For development or running without the plugin. If you installed via the plugin above, skip this section.
  100. ### 1. Clone and install dependencies
  101. ```bash
  102. git clone https://github.com/simple10/agents-observe.git agents-observe
  103. cd agents-observe
  104. # Install just if needed
  105. brew install just
  106. # Start the docker container
  107. just start
  108. # Or start local dev servers
  109. just install
  110. just dev
  111. ```
  112. See [justfile](./justfile) for additional commands.
  113. ### 2. Configure Claude Code hooks
  114. Copy the hooks from `.claude/settings.json` into your project's settings.in this repo into your target project's Claude Code settings:
  115. - **Project-level** (recommended): `.claude/settings.json` in your project root
  116. - **User-level** (all projects): `~/.claude/settings.json`
  117. Update the `$CLAUDE_PROJECT_DIR` paths to point to your agents-observe install location.
  118. **Environment variables set in the config:**
  119. A few commonly used ones:
  120. | Variable | Default | Description |
  121. |----------|---------|-------------|
  122. | `AGENTS_OBSERVE_SERVER_PORT` | `4981` | Server port. |
  123. | `AGENTS_OBSERVE_NOTIFICATION_ON_EVENTS` | `Notification` | Comma-separated hook events that trigger the bell. Empty string disables bells. |
  124. | `AGENTS_OBSERVE_PROJECT_SLUG` | (auto-detected) | Project slug shown in the dashboard URL. If not set, derived from the session transcript path. |
  125. | `AGENTS_OBSERVE_API_BASE_URL` | `http://127.0.0.1:4981/api` | Full URL for the events endpoint. |
  126. See [`docs/ENVIRONMENT.md`](./docs/ENVIRONMENT.md) for the full list.
  127. ### 3. Verify it works
  128. ```bash
  129. # Check the server is running
  130. just health
  131. # Send a test event
  132. just test-event
  133. ```
  134. Navigate to **<http://localhost:5174>** (dev) or **<http://localhost:4981>** (Docker). You should see the test event appear. Start a Claude Code session in your configured project and events will stream in automatically.
  135. ## Standalone Commands
  136. If you have [just](https://github.com/casey/just) installed:
  137. ```bash
  138. # Development:
  139. just install # Install all dependencies
  140. just dev # Start server + client in dev mode (hot reload)
  141. just test # Run all tests (server + client)
  142. just test-event # Send a test event to the server
  143. just fmt # Format all source files
  144. # Server (Docker):
  145. just build # Build the Docker image locally
  146. just start # Start the server (same path as plugin MCP)
  147. just stop # Stop the server
  148. just restart # Restart the server
  149. just logs # Follow Docker container logs
  150. just start-local # Start server locally without Docker
  151. # Utilities:
  152. just health # Check server health
  153. just health # Check server health
  154. just db-reset # Delete the events database
  155. just cli <command> # Run CLI directly (hook, health, start, stop, restart, logs)
  156. just open # Open the dashboard in browser
  157. ```
  158. ## Project structure
  159. ```text
  160. app/
  161. server/ # Node server — Hono routes, SQLite, WebSocket
  162. client/ # React 19 + shadcn dashboard
  163. hooks/
  164. hooks.json # Plugin hook definitions
  165. scripts/ # CLI, MCP server, and shared libs
  166. skills/ # /observe skills
  167. scripts/ # Release tooling
  168. test/ # Integration tests
  169. docs/ # Plans and demo assets
  170. .claude-plugin/ # Plugin + marketplace manifests
  171. .env # Env config options used by cli & local server
  172. .mcp.json # MCP server configuration
  173. Dockerfile # Production container image
  174. docker-compose.yml # Container orchestration - not used by the plugin
  175. justfile # Task runner commands
  176. start.mjs # Local server entrypoint (non-Docker)
  177. vitest.config.ts # Test configuration
  178. package.json # Version metadata and workspace scripts
  179. ```
  180. ## How it works
  181. **Hooks** fire on every Claude Code event (tool calls, prompts, stops, subagent lifecycle). `observe_cli.mjs` reads the raw event from stdin and dispatches through `hooks/scripts/lib/agents/<class>.mjs` — each agent class's `buildHookEvent()` builds the envelope (project metadata plus agent-class-aware flags like `meta.isNotification` / `meta.clearsNotification`) and the CLI POSTs it to the server. If the server needs additional data (like the session's human-readable slug), it responds with a request — the hook reads it from the local transcript file and sends it back.
  182. **Server** receives raw events, extracts structural fields (type, tool name, agent ID), stores agent metadata (name, description, type, parentage), and saves everything in SQLite. Events are forwarded to WebSocket clients subscribed to the relevant session — each browser tab only receives events for the session it's viewing. The server tracks session status (active/stopped) but does not track agent status.
  183. **Client** fetches events via REST API on initial load, then receives real-time updates via WebSocket (events are appended to the local cache — no refetching). All agent state (status, event counts, timing) is derived from the event stream. Tool events are deduped client-side (PreToolUse + PostToolUse merged into a single row). The emoji icon mapping and summary generation are editable config files.
  184. ### Dev vs Production
  185. In dev mode, the client and server run as separate processes with separate ports.
  186. In production or docker mode, the client is bundled and served by the server. Both the API and dashboard are served from the same process and port.
  187. Both local dev and Docker flows default to using the same sqlite database in ./data. The database is auto created as needed.
  188. ## Troubleshooting
  189. **Docker not running?**
  190. The plugin requires Docker to run the server. Make sure Docker Desktop (or the Docker daemon) is running, then restart Claude Code.
  191. **Port 4981 in use?**
  192. The server auto-assigns a free port if 4981 is taken. To explicitly set a port, add `AGENTS_OBSERVE_SERVER_PORT=<port>` to your environment or `.env` file.
  193. **Plugin not capturing events?**
  194. Run `/observe debug` to diagnose. It checks server health, Docker container logs, MCP logs, and CLI logs. You can also run `/observe status` for a quick health check.
  195. **Events not appearing in the dashboard?**
  196. 1. **Is the server running?** Run `just health` to check.
  197. 2. **Is the hook script configured?** Copy the hooks from `.claude/settings.json` into your project's settings.
  198. 3. **Is `AGENTS_OBSERVE_PROJECT_SLUG` set?** If `AGENTS_OBSERVE_PROJECT_SLUG` is not set, the project is auto-detected from the session transcript path.
  199. 4. **Can the hook reach the server?** Run `just test-event` — if the event appears in the dashboard, the server is reachable.
  200. **WebSocket disconnected?**
  201. The client reconnects automatically every 3 seconds if the WebSocket connection drops. You'll see "Disconnected" in the sidebar footer. Events received during reconnection will appear once the connection is restored and the events are refetched.
  202. **Database issues?**
  203. Run `just db-reset` to delete the SQLite database and start fresh (stops the server, deletes the db, restarts). The database is auto-created on the next server start.
  204. ## ROADMAP
  205. - [ ] Add support for Codex
  206. - [ ] Add support for OpenClaw
  207. - [ ] Add support for pi-code agents
  208. --
  209. ## Reference
  210. - [Claude Hooks](https://code.claude.com/docs/en/hooks.md) - official list of currently supported hooks
  211. ## Related Projects
  212. - [Agent Super Spy](https://github.com/simple10/agent-super-spy) - full observability stack for agents, can be run locally or remotely
  213. - [Multi-Agent Observability System](https://github.com/disler/claude-code-hooks-multi-agent-observability) - inspired this project
  214. - [Claude DevTools](https://github.com/matt1398/claude-devtools) - visualization for claude session files, requires running on local machine
  215. ## License
  216. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.