{"id":47712368,"url":"https://github.com/simple10/agents-observe","last_synced_at":"2026-05-11T04:18:18.561Z","repository":{"id":347865695,"uuid":"1192464649","full_name":"simple10/agents-observe","owner":"simple10","description":"Real-time observability of claude code sessions \u0026 multi-agents.","archived":false,"fork":false,"pushed_at":"2026-04-01T22:31:38.000Z","size":29563,"stargazers_count":245,"open_issues_count":1,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-03T04:54:15.858Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simple10.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-26T08:42:14.000Z","updated_at":"2026-04-03T03:32:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/simple10/agents-observe","commit_stats":null,"previous_names":["simple10/claude-observe","simple10/agents-observe"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/simple10/agents-observe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simple10%2Fagents-observe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simple10%2Fagents-observe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simple10%2Fagents-observe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simple10%2Fagents-observe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simple10","download_url":"https://codeload.github.com/simple10/agents-observe/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simple10%2Fagents-observe/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31506580,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-02T18:40:01.447Z","updated_at":"2026-05-11T04:18:18.553Z","avatar_url":"https://github.com/simple10.png","language":"TypeScript","funding_links":[],"categories":["Observability"],"sub_categories":[],"readme":"# Agents Observe\n\nReal-time observability dashboard for Claude Code agents.\n\nIncludes powerful filtering, searching, and visualization of multi-agent sessions.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://raw.githubusercontent.com/simple10/agents-observe/videos/docs/assets/dashboard.gif\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/simple10/agents-observe/videos/docs/assets/dashboard.gif\" alt=\"Claude Observe Dashboard Demo\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n\u003ca href=\"https://raw.githubusercontent.com/simple10/agents-observe/videos/docs/assets/demo.mp4\"\u003eDemo video\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/simple10/agents-observe/main/docs/assets/dashboard2.png\" alt=\"Claude Observe Dashboard Screenshot - Expanded Row\" /\u003e\n\u003c/p\u003e\n\n## Quick Start\n\nInstall as a `claude code` plugin:\n\n```bash\n# Add this repo as a marketplace\nclaude plugin marketplace add simple10/agents-observe\n\n# Install the plugin\nclaude plugin install agents-observe\n\n# Then just run claude\n# The plugin will auto start the MCP server and capture events\nclaude\n\n# Use the /observe skill in claude to check status, restart the server, etc.\n\u003e /observe status\n\u003e /observe debug\n\u003e /observe logs\n\u003e /observe restart\n\n# Open the dashboard UI in a browser\nopen http://localhost:4981\n```\n\nDefault dashboard URL: \u003chttp://localhost:4981\u003e\n\n### Prerequisites\n\n- [Docker](https://www.docker.com/) (required — the server runs as a container)\n- [Node.js](https://nodejs.org/) (required — hook scripts run via `node`)\n\nIf docker or node are not installed on your host, the plugin will fail to properly load.\n\nUse the `/observe debug` claude command to help troubleshoot and fix installation issues.\n\n## Plugin Skills\n\n| Skill | Description |\n|-------|-------------|\n| `/observe` | Open the dashboard URL and check if the server is running |\n| `/observe status` | Show server health, version, runtime, and config details |\n| `/observe start` | Start the server |\n| `/observe stop` | Stop the server |\n| `/observe restart` | Restart the server |\n| `/observe logs` | Show recent Docker container logs |\n| `/observe debug` | Diagnose server issues (health, docker logs, mcp.log, cli.log) |\n\n## Why observability matters\n\nWhen 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.\n\nClaude 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.\n\nThis matters because:\n\n- **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.\n- **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. Claude Observe shows you both.\n- **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.\n- **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.\n\n## What you can do\n\n- Watch tool calls stream in as they happen (PreToolUse → PostToolUse with results)\n- See the full agent hierarchy — which subagent was spawned by which parent\n- Filter by agent, tool type, or search across all events\n- Expand any event to see the full payload, command, and result\n- Click timeline icons to jump to specific events in the stream\n- Browse historical sessions with human-readable names (e.g., \"twinkly-hugging-dragon\")\n\n## Architecture\n\n```\nClaude Code Hooks  →  observe_cli.mjs  →  API Server (SQLite)  →  React Dashboard\n  (agent-lib build)     (HTTP POST)        (parse + store)        (WebSocket live)\n```\n\n`observe_cli.mjs` reads the raw event from stdin and dispatches to an agent-class-specific lib (`hooks/scripts/lib/agents/\u003cclass\u003e.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.\n\n## Standalone Installation\n\n\u003e For development or running without the plugin. If you installed via the plugin above, skip this section.\n\n### 1. Clone and install dependencies\n\n```bash\ngit clone https://github.com/simple10/agents-observe.git agents-observe\ncd agents-observe\n\n# Install just if needed\nbrew install just\n\n# Start the docker container\njust start\n\n# Or start local dev servers\njust install\njust dev\n```\n\nSee [justfile](./justfile) for additional commands.\n\n### 2. Configure Claude Code hooks\n\nCopy the hooks from `.claude/settings.json` into your project's settings.in this repo into your target project's Claude Code settings:\n\n- **Project-level** (recommended): `.claude/settings.json` in your project root\n- **User-level** (all projects): `~/.claude/settings.json`\n\nUpdate the `$CLAUDE_PROJECT_DIR` paths to point to your agents-observe install location.\n\n**Environment variables set in the config:**\n\nA few commonly used ones:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `AGENTS_OBSERVE_SERVER_PORT` | `4981` | Server port. |\n| `AGENTS_OBSERVE_NOTIFICATION_ON_EVENTS` | `Notification` | Comma-separated hook events that trigger the bell. Empty string disables bells. |\n| `AGENTS_OBSERVE_PROJECT_SLUG` | (auto-detected) | Project slug shown in the dashboard URL. If not set, derived from the session transcript path. |\n| `AGENTS_OBSERVE_API_BASE_URL` | `http://127.0.0.1:4981/api` | Full URL for the events endpoint. |\n\nSee [`docs/ENVIRONMENT.md`](./docs/ENVIRONMENT.md) for the full list.\n\n### 3. Verify it works\n\n```bash\n# Check the server is running\njust health\n\n# Send a test event\njust test-event\n```\n\nNavigate to **\u003chttp://localhost:5174\u003e** (dev) or **\u003chttp://localhost:4981\u003e** (Docker). You should see the test event appear. Start a Claude Code session in your configured project and events will stream in automatically.\n\n## Standalone Commands\n\nIf you have [just](https://github.com/casey/just) installed:\n\n```bash\n# Development:\njust install      # Install all dependencies\njust dev          # Start server + client in dev mode (hot reload)\njust test         # Run all tests (server + client)\njust test-event   # Send a test event to the server\njust fmt          # Format all source files\n\n# Server (Docker):\njust build        # Build the Docker image locally\njust start        # Start the server (same path as plugin MCP)\njust stop         # Stop the server\njust restart      # Restart the server\njust logs         # Follow Docker container logs\njust start-local  # Start server locally without Docker\n\n# Utilities:\njust health              # Check server health\njust health              # Check server health\njust db-reset            # Delete the events database\njust cli \u003ccommand\u003e       # Run CLI directly (hook, health, start, stop, restart, logs)\njust open                # Open the dashboard in browser\n```\n\n## Project structure\n\n```text\napp/\n  server/                    # Node server — Hono routes, SQLite, WebSocket\n  client/                    # React 19 + shadcn dashboard\nhooks/\n  hooks.json                 # Plugin hook definitions\n  scripts/                   # CLI, MCP server, and shared libs\nskills/                      # /observe skills\nscripts/                     # Release tooling\ntest/                        # Integration tests\ndocs/                        # Plans and demo assets\n.claude-plugin/              # Plugin + marketplace manifests\n.env                         # Env config options used by cli \u0026 local server\n.mcp.json                    # MCP server configuration\nDockerfile                   # Production container image\ndocker-compose.yml           # Container orchestration - not used by the plugin\njustfile                     # Task runner commands\nstart.mjs                    # Local server entrypoint (non-Docker)\nvitest.config.ts             # Test configuration\npackage.json                 # Version metadata and workspace scripts\n```\n\n## How it works\n\n**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/\u003cclass\u003e.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.\n\n**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.\n\n**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.\n\n### Dev vs Production\n\nIn dev mode, the client and server run as separate processes with separate ports.\n\nIn 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.\n\nBoth local dev and Docker flows default to using the same sqlite database in ./data. The database is auto created as needed.\n\n## Troubleshooting\n\n**Docker not running?**\n\nThe plugin requires Docker to run the server. Make sure Docker Desktop (or the Docker daemon) is running, then restart Claude Code.\n\n**Port 4981 in use?**\n\nThe server auto-assigns a free port if 4981 is taken. To explicitly set a port, add `AGENTS_OBSERVE_SERVER_PORT=\u003cport\u003e` to your environment or `.env` file.\n\n**Plugin not capturing events?**\n\nRun `/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.\n\n**Events not appearing in the dashboard?**\n\n1. **Is the server running?** Run `just health` to check.\n2. **Is the hook script configured?** Copy the hooks from `.claude/settings.json` into your project's settings.\n3. **Is `AGENTS_OBSERVE_PROJECT_SLUG` set?** If `AGENTS_OBSERVE_PROJECT_SLUG` is not set, the project is auto-detected from the session transcript path.\n4. **Can the hook reach the server?** Run `just test-event` — if the event appears in the dashboard, the server is reachable.\n\n**WebSocket disconnected?**\n\nThe 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.\n\n**Database issues?**\n\nRun `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.\n\n## ROADMAP\n\n- [ ] Add support for Codex\n- [ ] Add support for OpenClaw\n- [ ] Add support for pi-code agents\n\n--\n\n## Reference\n\n- [Claude Hooks](https://code.claude.com/docs/en/hooks.md) - official list of currently supported hooks\n\n## Related Projects\n\n- [Agent Super Spy](https://github.com/simple10/agent-super-spy) - full observability stack for agents, can be run locally or remotely\n- [Multi-Agent Observability System](https://github.com/disler/claude-code-hooks-multi-agent-observability) - inspired this project\n- [Claude DevTools](https://github.com/matt1398/claude-devtools) - visualization for claude session files, requires running on local machine\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimple10%2Fagents-observe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimple10%2Fagents-observe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimple10%2Fagents-observe/lists"}