{"_id":"@ajbmachon/setup-observability","_rev":"3-f8e707bc9305f3b5b4d21a4de9757812","name":"@ajbmachon/setup-observability","dist-tags":{"latest":"1.1.1"},"versions":{"1.0.0":{"name":"@ajbmachon/setup-observability","version":"1.0.0","keywords":["claude-code","observability","hooks","multi-agent","dashboard"],"license":"MIT","_id":"@ajbmachon/setup-observability@1.0.0","maintainers":[{"name":"ajbmachon","email":"andre.machon@distech.solutions"}],"homepage":"https://github.com/ajbmachon/claude-code-hooks-multi-agent-observability#readme","bugs":{"url":"https://github.com/ajbmachon/claude-code-hooks-multi-agent-observability/issues"},"bin":{"setup-observability":"scripts/setup-observability.ts"},"dist":{"shasum":"fe381bc7126cc35e7a96d374fd9485cdcff5bb3c","tarball":"https://registry.npmjs.org/@ajbmachon/setup-observability/-/setup-observability-1.0.0.tgz","fileCount":108,"integrity":"sha512-jh7kFmhb5OGLUEl4OrmVdpsMOAnxdiv+Iheo9gPgdkUyooywD2aFj7wGl2auPwjE0W3xHUsjtpOc+X3vLsY8uw==","signatures":[{"sig":"MEYCIQDPR7ye4N1qMRRTZyps/KND7wxqlur/hQXqCYegQ1IhFgIhAJ3F+NrVpG2n1f5MIx9VixabBrBnyLphT2qjBs83RegF","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":617641},"type":"module","engines":{"bun":">=1.0.0"},"gitHead":"1999f3cd98f8e3ff551b79801dc3fc2fe8440547","_npmUser":{"name":"ajbmachon","email":"andre.machon@distech.solutions"},"repository":{"url":"git+https://github.com/ajbmachon/claude-code-hooks-multi-agent-observability.git","type":"git"},"_npmVersion":"11.6.0","description":"Add Claude Code observability to any JS/TS or Python project with a single command","directories":{},"_nodeVersion":"22.14.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/setup-observability_1.0.0_1771428385583_0.4289477398701318","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@ajbmachon/setup-observability","version":"1.1.0","keywords":["claude-code","observability","hooks","multi-agent","dashboard"],"license":"MIT","_id":"@ajbmachon/setup-observability@1.1.0","maintainers":[{"name":"ajbmachon","email":"andre.machon@distech.solutions"}],"homepage":"https://github.com/ajbmachon/claude-code-hooks-multi-agent-observability#readme","bugs":{"url":"https://github.com/ajbmachon/claude-code-hooks-multi-agent-observability/issues"},"bin":{"setup-observability":"scripts/setup-observability.ts"},"dist":{"shasum":"913ed723a0062e05b8f05785dc4ccf724b1b1e65","tarball":"https://registry.npmjs.org/@ajbmachon/setup-observability/-/setup-observability-1.1.0.tgz","fileCount":117,"integrity":"sha512-/Di7EhlOLafTzgZZtKoHSnqVkJtL3vWYUS3CWB9736epdKt7XoWCBEBkiYk0I4IAHSR4uvkMSlCV1Ec5GwzyqA==","signatures":[{"sig":"MEYCIQCanvYE8fyGCHc3wxsur6+KTxIM6YH9/EJclYvog2AqXQIhAMr6mgcKNeOP0drMhaYwgHmgNESKlu6opCYHqHorqAYS","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":628040},"type":"module","engines":{"bun":">=1.0.0"},"gitHead":"c7d249450b10a0e79b74dccce6ab301c1eea3225","_npmUser":{"name":"ajbmachon","email":"andre.machon@distech.solutions"},"repository":{"url":"git+https://github.com/ajbmachon/claude-code-hooks-multi-agent-observability.git","type":"git"},"_npmVersion":"11.6.0","description":"Add Claude Code observability to any JS/TS or Python project with a single command","directories":{},"_nodeVersion":"22.14.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/setup-observability_1.1.0_1771432238895_0.3983112479223754","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@ajbmachon/setup-observability","version":"1.1.1","description":"Add Claude Code observability to any JS/TS or Python project with a single command","type":"module","bin":{"setup-observability":"scripts/setup-observability.ts"},"keywords":["claude-code","observability","hooks","multi-agent","dashboard"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/ajbmachon/claude-code-hooks-multi-agent-observability.git"},"engines":{"bun":">=1.0.0"},"_id":"@ajbmachon/setup-observability@1.1.1","gitHead":"3c613c3d309a90800dbad2d55ef3660e12257e5c","bugs":{"url":"https://github.com/ajbmachon/claude-code-hooks-multi-agent-observability/issues"},"homepage":"https://github.com/ajbmachon/claude-code-hooks-multi-agent-observability#readme","_nodeVersion":"22.14.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-I9aRb6kbHXodE8KkK0nKwy/f7R1f6IKreHpOiCSr/0jk7leZ/qe7djnYjm5wY0nrT5SGu1w+qwIZltnMdXdIsg==","shasum":"d077efd15556a7232ae99be7c0c69dde3aaf608d","tarball":"https://registry.npmjs.org/@ajbmachon/setup-observability/-/setup-observability-1.1.1.tgz","fileCount":117,"unpackedSize":628543,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBbEWJYG7+ui1icEo3GTw+hrWnlb68+YzQbhObteiirWAiEAoh/IHvaR5kmlNU/SLInbbPxme/I+NeLnba12nQrMvbM="}]},"_npmUser":{"name":"ajbmachon","email":"andre.machon@distech.solutions"},"directories":{},"maintainers":[{"name":"ajbmachon","email":"andre.machon@distech.solutions"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/setup-observability_1.1.1_1771433322489_0.36656598715966204"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-18T15:26:25.441Z","modified":"2026-02-18T16:48:42.816Z","1.0.0":"2026-02-18T15:26:25.855Z","1.1.0":"2026-02-18T16:30:39.107Z","1.1.1":"2026-02-18T16:48:42.700Z"},"bugs":{"url":"https://github.com/ajbmachon/claude-code-hooks-multi-agent-observability/issues"},"license":"MIT","homepage":"https://github.com/ajbmachon/claude-code-hooks-multi-agent-observability#readme","keywords":["claude-code","observability","hooks","multi-agent","dashboard"],"repository":{"type":"git","url":"git+https://github.com/ajbmachon/claude-code-hooks-multi-agent-observability.git"},"description":"Add Claude Code observability to any JS/TS or Python project with a single command","maintainers":[{"name":"ajbmachon","email":"andre.machon@distech.solutions"}],"readme":"# Claude Code Multi-Agent Observability\n\nOne-command observability for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) projects. Real-time monitoring and visualization for Claude Code agents through comprehensive [hook event](https://docs.anthropic.com/en/docs/claude-code/hooks) tracking.\n\n> Forked from [disler/claude-code-hooks-multi-agent-observability](https://github.com/disler/claude-code-hooks-multi-agent-observability). Extended with setup scaffolding, TypeScript hook ports, server API extensions, auto-detection rules, CLI signal logger, observability skill, and npm package distribution.\n\n<img src=\"images/app.png\" alt=\"Multi-Agent Observability Dashboard\" style=\"max-width: 800px; width: 100%;\">\n\n## What It Does\n\nThis toolkit captures, stores, and visualizes every Claude Code hook event in real-time. When you (or your agents) use Claude Code, each tool call, prompt submission, notification, session start/stop, subagent lifecycle event, and permission request is sent to a local SQLite database and streamed live to a Vue dashboard.\n\nKey capabilities:\n\n- **12 hook event types** captured automatically (PreToolUse, PostToolUse, Stop, SubagentStart, etc.)\n- **Multi-agent swim lanes** showing parallel agent activity side by side\n- **Live pulse chart** with session-colored bars and event type indicators\n- **Filtering** by app, session, and event type\n- **Query, tag, and export APIs** for programmatic access to trace data\n- **Learning signals** with auto-detection rules for test failures, build errors, and permission issues\n\n## Architecture\n\n```\nClaude Agents --> Hook Scripts --> HTTP POST --> Bun Server (port 4000) --> SQLite\n                                                      |\n                                                WebSocket --> Vue Dashboard (port 5173)\n```\n\n![Agent Data Flow Animation](images/AgentDataFlowV2.gif)\n\n## Quick Start\n\n### Install into Your Project\n\nRun the setup script to scaffold observability into any JS/TS or Python project:\n\n```bash\n# Via bunx (recommended)\nbunx @ajbmachon/setup-observability --project /path/to/your/project --source-app my-app\n\n# Or clone this repo and run directly\nbun scripts/setup-observability.ts --project /path/to/your/project --source-app my-app\n```\n\nThe setup script is **idempotent** -- running it twice produces identical results. It will:\n\n1. Copy hook scripts (TypeScript or Python, auto-detected)\n2. Merge hook configuration into `.claude/settings.json`\n3. Copy the server and client into `.observability/`\n4. Install dependencies\n5. Add management commands to your project\n\n### Managing the Dashboard\n\n**For JS/TS projects** (scripts added to your `package.json`):\n\n```bash\nbun run obs:start     # Start server + client in background\nbun run obs:stop      # Stop all observability processes\nbun run obs:status    # Check if server and client are running\n```\n\n**For Python projects** (shell script created at `.observability/obs.sh`):\n\n```bash\n./.observability/obs.sh start    # Start server + client\n./.observability/obs.sh stop     # Stop all processes\n./.observability/obs.sh status   # Check service status\n```\n\nThen open **http://localhost:5173** in your browser and run Claude Code -- events will stream in automatically.\n\n### Setup Options\n\n```\nUsage:\n  bun scripts/setup-observability.ts --project <path> --source-app <name> [--port 4000] [--language ts|py]\n\nOptions:\n  --project      Target project directory (required)\n  --source-app   Application identifier for hook events (required)\n  --port         Observability server port (default: 4000)\n  --language     Hook language: ts or py (auto-detect if omitted)\n```\n\n## Requirements\n\n- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** -- Anthropic's official CLI\n- **[Bun](https://bun.sh/)** -- JavaScript/TypeScript runtime (for server, client, and TS hooks)\n- **[Astral uv](https://docs.astral.sh/uv/)** -- Fast Python package manager (only if using Python hooks)\n\n## Hook System\n\nThe toolkit supports all 12 Claude Code hook event types:\n\n| Event Type | Purpose | Special Features |\n|---|---|---|\n| PreToolUse | Before tool execution | Tool blocking, input summarization |\n| PostToolUse | After tool completion | MCP tool detection, result logging |\n| PostToolUseFailure | Tool execution failed | Error details, interrupt status |\n| PermissionRequest | Permission requested | Tool name, permission suggestions |\n| Notification | User interactions | Type-aware TTS support |\n| Stop | Response completion | Chat transcript capture |\n| SubagentStart | Subagent started | Agent ID and type tracking |\n| SubagentStop | Subagent finished | Transcript path tracking |\n| PreCompact | Context compaction | Custom instructions |\n| UserPromptSubmit | User prompt submission | Prompt logging, validation |\n| SessionStart | Session started | Source, model, agent type |\n| SessionEnd | Session ended | End reason tracking |\n\nEach hook sends events to the server via `send_event.py` (or `send_event.ts`), which includes `--source-app` and `--event-type` flags for routing. Events include `source_app` and `session_id` fields to uniquely identify each agent instance.\n\n## Dashboard Features\n\n- **Agent Swim Lanes** -- Side-by-side view of parallel agent activity\n- **Event Timeline** -- Chronological event list with auto-scroll and manual override\n- **Live Pulse Chart** -- Canvas-based real-time activity visualization with session-colored bars\n- **Filter Panel** -- Multi-select filtering by app, session, and event type\n- **Tool Emoji System** -- Visual tool identification (Bash: terminal, Read: book, Write: pen, etc.)\n- **Chat Transcript Viewer** -- Inspect full conversation history from Stop events\n- **Dark/Light Theme** -- Dual theme support with smooth transitions\n\n## API Endpoints\n\nThe server exposes REST and WebSocket endpoints:\n\n| Endpoint | Method | Description |\n|---|---|---|\n| `/events` | POST | Receive events from hooks |\n| `/events/recent` | GET | Paginated event retrieval with filtering |\n| `/events/filter-options` | GET | Available filter values |\n| `/events/query` | GET | Search and filter past events |\n| `/events/export` | GET | Export events (json, jsonl, csv) |\n| `/events/<id>/tag` | POST | Tag events with labels and notes |\n| `/signals` | POST | Log learning signals |\n| `/signals/rules` | GET/POST | Manage auto-detection rules |\n| `/health` | GET | Server health check |\n| `/stream` | WS | Real-time event broadcast |\n\n### Query Examples\n\n```bash\n# Recent failures\ncurl -s \"http://localhost:4000/events/query?type=PostToolUseFailure&limit=10\" | jq .\n\n# Learning signals from last hour\ncurl -s \"http://localhost:4000/events/query?signal_only=true&since=$(date -v-1H +%s000)&limit=20\" | jq .\n\n# Export all events as JSONL\ncurl -s \"http://localhost:4000/events/export?format=jsonl\" > events.jsonl\n\n# Tag an event as a learning signal\ncurl -s -X POST \"http://localhost:4000/events/42/tag\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"tags\": [\"learning_signal\", \"test_failure\"], \"note\": \"Flaky auth test\"}'\n```\n\n### CLI Signal Logger\n\n```bash\nbun .observability/scripts/log-signal.ts \\\n  --type test_failure \\\n  --context '{\"test\": \"auth.test.ts\", \"error\": \"timeout\"}' \\\n  --tags flaky,needs-retry\n```\n\n## Project Structure\n\n```\nclaude-code-hooks-multi-agent-observability/\n|\n|-- apps/\n|   |-- server/              # Bun TypeScript server (port 4000)\n|   |   |-- src/\n|   |   |   |-- index.ts     # HTTP/WebSocket endpoints\n|   |   |   |-- db.ts        # SQLite database & migrations\n|   |   |   |-- types.ts     # TypeScript interfaces\n|   |   |-- package.json\n|   |   |-- events.db        # SQLite database (gitignored)\n|   |\n|   |-- client/              # Vue 3 TypeScript client (port 5173)\n|       |-- src/\n|       |   |-- App.vue\n|       |   |-- components/  # EventTimeline, FilterPanel, LivePulseChart, etc.\n|       |   |-- composables/ # useWebSocket, useEventColors, useChartData\n|       |   |-- types.ts\n|       |-- package.json\n|\n|-- .claude/\n|   |-- hooks/               # Python hook scripts (14 files)\n|   |-- hooks-ts/            # TypeScript hook ports\n|   |-- skills/observability/ # Observability skill for Claude Code\n|   |-- settings.json        # Hook configuration (all 12 event types)\n|   |-- observability.json   # Auto-detection rules and tag vocabulary\n|\n|-- scripts/\n|   |-- setup-observability.ts  # Setup scaffolding script (the npm bin)\n|   |-- observability/          # CLI tools (log-signal.ts)\n|   |-- start-system.sh        # Launch server & client\n|   |-- reset-system.sh        # Stop all processes\n|\n|-- justfile                 # Task runner for development of THIS repo\n|-- package.json             # npm package config (@ajbmachon/setup-observability)\n```\n\n## Multi-Agent Orchestration\n\nWith Claude Opus 4 and multi-agent orchestration, you can spin up teams of specialized agents that work in parallel. This observability system traces every tool call, task handoff, and agent lifecycle event across the entire swarm.\n\n[![Multi-Agent Orchestration with Claude Code](images/claude-code-multi-agent-orchestration.png)](https://youtu.be/RpUTF_U4kiw)\n\nThe orchestration lifecycle:\n\n1. **Create a team** -- `TeamCreate` sets up the coordination layer\n2. **Create tasks** -- `TaskCreate` builds the centralized task list\n3. **Spawn agents** -- `Task` deploys specialized agents into independent context windows\n4. **Work in parallel** -- Agents execute simultaneously, communicating via `SendMessage`\n5. **Shut down agents** -- Completed agents are gracefully terminated\n6. **Delete the team** -- `TeamDelete` cleans up coordination state\n\nSee the official [Claude Code Agent Teams documentation](https://code.claude.com/docs/en/agent-teams) for the full reference.\n\n## Development\n\nThis section is for contributing to **this repository itself** (the observability toolkit), not for using it in your projects.\n\n### Prerequisites\n\n- [Bun](https://bun.sh/) (runtime and package manager)\n- [just](https://github.com/casey/just) (task runner for dev workflows)\n- [Astral uv](https://docs.astral.sh/uv/) (for Python hooks)\n\n### Dev Commands (justfile)\n\nThe `justfile` at the repo root provides recipes for developing this toolkit:\n\n```bash\njust              # List all available recipes\njust start        # Start server + client\njust stop         # Stop all processes\njust restart      # Stop then start\njust server       # Start server only (dev mode)\njust client       # Start client only\njust install      # Install all dependencies\njust health       # Check server/client status\njust test-event   # Send a test event\njust db-reset     # Reset the database\njust hooks        # List all hook scripts\njust open         # Open dashboard in browser\n```\n\n### Testing\n\n```bash\n# System validation\n./scripts/test-system.sh\n\n# Send a test event\njust test-event\n\n# Manual event test\ncurl -X POST http://localhost:4000/events \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source_app\": \"test\",\n    \"session_id\": \"test-123\",\n    \"hook_event_type\": \"PreToolUse\",\n    \"payload\": {\"tool_name\": \"Bash\", \"tool_input\": {\"command\": \"ls\"}}\n  }'\n```\n\n## Security\n\n- Blocks dangerous `rm -rf` commands via `deny_tool()` JSON pattern\n- Prevents access to sensitive files (`.env`, private keys)\n- `stop_hook_active` guard prevents infinite hook loops\n- Stop hook validators ensure plan files contain required sections\n- All hooks exit 0 always -- they never block Claude Code\n\n## Technical Stack\n\n- **Server**: Bun, TypeScript, SQLite (WAL mode)\n- **Client**: Vue 3, TypeScript, Vite, Tailwind CSS\n- **Hooks**: Python 3.11+ (uv) or TypeScript (Bun)\n- **Communication**: HTTP REST, WebSocket\n\n## License\n\n[MIT](LICENSE)\n\n## Credits\n\n- **Original project**: [Peter Disler](https://github.com/disler) ([disler/claude-code-hooks-multi-agent-observability](https://github.com/disler/claude-code-hooks-multi-agent-observability))\n- **Fork maintainer**: [Andre Machon](https://github.com/ajbmachon) ([Two Magnitudes](https://twomagnitudes.com))\n- **Learn more**: [Tactical Agentic Coding](https://agenticengineer.com/tactical-agentic-coding?y=opsorch) | [IndyDevDan YouTube](https://www.youtube.com/@indydevdan)\n","readmeFilename":"README.md"}