[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-disler--claude-code-hooks-multi-agent-observability":3,"tool-disler--claude-code-hooks-multi-agent-observability":64},[4,17,27,35,43,56],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":16},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,3,"2026-04-05T11:01:52",[13,14,15],"开发框架","图像","Agent","ready",{"id":18,"name":19,"github_repo":20,"description_zh":21,"stars":22,"difficulty_score":23,"last_commit_at":24,"category_tags":25,"status":16},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",140436,2,"2026-04-05T23:32:43",[13,15,26],"语言模型",{"id":28,"name":29,"github_repo":30,"description_zh":31,"stars":32,"difficulty_score":23,"last_commit_at":33,"category_tags":34,"status":16},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107662,"2026-04-03T11:11:01",[13,14,15],{"id":36,"name":37,"github_repo":38,"description_zh":39,"stars":40,"difficulty_score":23,"last_commit_at":41,"category_tags":42,"status":16},3704,"NextChat","ChatGPTNextWeb\u002FNextChat","NextChat 是一款轻量且极速的 AI 助手，旨在为用户提供流畅、跨平台的大模型交互体验。它完美解决了用户在多设备间切换时难以保持对话连续性，以及面对众多 AI 模型不知如何统一管理的痛点。无论是日常办公、学习辅助还是创意激发，NextChat 都能让用户随时随地通过网页、iOS、Android、Windows、MacOS 或 Linux 端无缝接入智能服务。\n\n这款工具非常适合普通用户、学生、职场人士以及需要私有化部署的企业团队使用。对于开发者而言，它也提供了便捷的自托管方案，支持一键部署到 Vercel 或 Zeabur 等平台。\n\nNextChat 的核心亮点在于其广泛的模型兼容性，原生支持 Claude、DeepSeek、GPT-4 及 Gemini Pro 等主流大模型，让用户在一个界面即可自由切换不同 AI 能力。此外，它还率先支持 MCP（Model Context Protocol）协议，增强了上下文处理能力。针对企业用户，NextChat 提供专业版解决方案，具备品牌定制、细粒度权限控制、内部知识库整合及安全审计等功能，满足公司对数据隐私和个性化管理的高标准要求。",87618,"2026-04-05T07:20:52",[13,26],{"id":44,"name":45,"github_repo":46,"description_zh":47,"stars":48,"difficulty_score":23,"last_commit_at":49,"category_tags":50,"status":16},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",84991,"2026-04-05T10:45:23",[14,51,52,53,15,54,26,13,55],"数据工具","视频","插件","其他","音频",{"id":57,"name":58,"github_repo":59,"description_zh":60,"stars":61,"difficulty_score":10,"last_commit_at":62,"category_tags":63,"status":16},3128,"ragflow","infiniflow\u002Fragflow","RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在为大语言模型构建更精准、可靠的上下文层。它巧妙地将前沿的 RAG 技术与智能体（Agent）能力相结合，不仅支持从各类文档中高效提取知识，还能让模型基于这些知识进行逻辑推理和任务执行。\n\n在大模型应用中，幻觉问题和知识滞后是常见痛点。RAGFlow 通过深度解析复杂文档结构（如表格、图表及混合排版），显著提升了信息检索的准确度，从而有效减少模型“胡编乱造”的现象，确保回答既有据可依又具备时效性。其内置的智能体机制更进一步，使系统不仅能回答问题，还能自主规划步骤解决复杂问题。\n\n这款工具特别适合开发者、企业技术团队以及 AI 研究人员使用。无论是希望快速搭建私有知识库问答系统，还是致力于探索大模型在垂直领域落地的创新者，都能从中受益。RAGFlow 提供了可视化的工作流编排界面和灵活的 API 接口，既降低了非算法背景用户的上手门槛，也满足了专业开发者对系统深度定制的需求。作为基于 Apache 2.0 协议开源的项目，它正成为连接通用大模型与行业专有知识之间的重要桥梁。",77062,"2026-04-04T04:44:48",[15,14,13,26,54],{"id":65,"github_repo":66,"name":67,"description_en":68,"description_zh":69,"ai_summary_zh":69,"readme_en":70,"readme_zh":71,"quickstart_zh":72,"use_case_zh":73,"hero_image_url":74,"owner_login":75,"owner_name":76,"owner_avatar_url":77,"owner_bio":78,"owner_company":79,"owner_location":79,"owner_email":79,"owner_twitter":79,"owner_website":79,"owner_url":80,"languages":81,"stars":114,"forks":115,"last_commit_at":116,"license":79,"difficulty_score":117,"env_os":118,"env_gpu":119,"env_ram":119,"env_deps":120,"category_tags":128,"github_topics":79,"view_count":10,"oss_zip_url":79,"oss_zip_packed_at":79,"status":16,"created_at":129,"updated_at":130,"faqs":131,"releases":157},1367,"disler\u002Fclaude-code-hooks-multi-agent-observability","claude-code-hooks-multi-agent-observability","Real-time monitoring for Claude Code agents through simple hook event tracking.","claude-code-hooks-multi-agent-observability 像给 Claude Code 装上“全景摄像头”，实时捕捉并可视化多智能体的一举一动。它通过监听 Claude 的 12 类 Hook 事件，把每一次工具调用、任务交接、子代理启停都记录成可追踪的日志，并在浏览器里用动态仪表盘实时展示，帮你一眼看清“智能体蜂群”里谁在做什么、耗时多久、是否出错。\n\n它解决了多智能体并行时“黑盒”难调试的问题：过去只能盯着终端滚动条，现在可以像看监控一样回放、过滤、搜索事件，快速定位瓶颈或异常。\n\n适合正在用 Claude Code 做自动化脚本、复杂工作流、或研究多智能体协作的开发者与研究人员。只需把随包提供的 .claude 目录拷进项目、改一行配置，就能在本地跑起监控服务，零侵入、低门槛。\n\n亮点在于“事件流即数据”：用 SQLite + WebSocket 把轻量存储和实时推送结合，前端 Vue 面板自动热更新，既保留本地隐私，又能像 SaaS 一样顺滑体验。","# Multi-Agent Observability System\n\nReal-time monitoring and visualization for Claude Code agents through comprehensive hook event tracking. Watch the [latest deep dive on multi-agent orchestration with Opus 4.6 here](https:\u002F\u002Fyoutu.be\u002FRpUTF_U4kiw). With Claude Opus 4.6 and multi-agent orchestration, you can now spin up teams of specialized agents that work in parallel, and this observability system lets you trace every tool call, task handoff, and agent lifecycle event across the entire swarm.\n\n## 🎯 Overview\n\nThis system provides complete observability into Claude Code agent behavior by capturing, storing, and visualizing Claude Code [Hook events](https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code\u002Fhooks) in real-time. It enables monitoring of multiple concurrent agents with session tracking, event filtering, and live updates. \n\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdisler_claude-code-hooks-multi-agent-observability_readme_c64fa830be1a.png\" alt=\"Multi-Agent Observability Dashboard\" style=\"max-width: 800px; width: 100%;\">\n\n## 🏗️ Architecture\n\n```\nClaude Agents → Hook Scripts → HTTP POST → Bun Server → SQLite → WebSocket → Vue Client\n```\n\n![Agent Data Flow Animation](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdisler_claude-code-hooks-multi-agent-observability_readme_3b8dd3a3caf9.gif)\n\n## 📋 Setup Requirements\n\nBefore getting started, ensure you have the following installed:\n\n- **[Claude Code](https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code)** - Anthropic's official CLI for Claude\n- **[Astral uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002F)** - Fast Python package manager (required for hook scripts)\n- **[Bun](https:\u002F\u002Fbun.sh\u002F)**, **npm**, or **yarn** - For running the server and client\n- **[just](https:\u002F\u002Fgithub.com\u002Fcasey\u002Fjust)** (optional) - Command runner for project recipes\n- **Anthropic API Key** - Set as `ANTHROPIC_API_KEY` environment variable\n- **OpenAI API Key** (optional) - For multi-model support with just-prompt MCP tool\n- **ElevenLabs API Key** (optional) - For audio features\n- **Firecrawl API Key** (optional) - For web scraping features\n\n### Configure .claude Directory\n\nTo setup observability in your repo,we need to copy the .claude directory to your project root.\n\nTo integrate the observability hooks into your projects:\n\n1. **Copy the entire `.claude` directory to your project root:**\n   ```bash\n   cp -R .claude \u002Fpath\u002Fto\u002Fyour\u002Fproject\u002F\n   ```\n\n2. **Update the `settings.json` configuration:**\n   \n   Open `.claude\u002Fsettings.json` in your project and modify the `source-app` parameter to identify your project:\n   \n   ```json\n   {\n     \"hooks\": {\n       \"PreToolUse\": [{\n         \"matcher\": \"\",\n         \"hooks\": [\n           {\n             \"type\": \"command\",\n             \"command\": \"uv run .claude\u002Fhooks\u002Fpre_tool_use.py\"\n           },\n           {\n             \"type\": \"command\",\n             \"command\": \"uv run .claude\u002Fhooks\u002Fsend_event.py --source-app YOUR_PROJECT_NAME --event-type PreToolUse --summarize\"\n           }\n         ]\n       }],\n       \"PostToolUse\": [{\n         \"matcher\": \"\",\n         \"hooks\": [\n           {\n             \"type\": \"command\",\n             \"command\": \"uv run .claude\u002Fhooks\u002Fpost_tool_use.py\"\n           },\n           {\n             \"type\": \"command\",\n             \"command\": \"uv run .claude\u002Fhooks\u002Fsend_event.py --source-app YOUR_PROJECT_NAME --event-type PostToolUse --summarize\"\n           }\n         ]\n       }],\n       \"UserPromptSubmit\": [{\n         \"hooks\": [\n           {\n             \"type\": \"command\",\n             \"command\": \"uv run .claude\u002Fhooks\u002Fuser_prompt_submit.py --log-only\"\n           },\n           {\n             \"type\": \"command\",\n             \"command\": \"uv run .claude\u002Fhooks\u002Fsend_event.py --source-app YOUR_PROJECT_NAME --event-type UserPromptSubmit --summarize\"\n           }\n         ]\n       }]\n       \u002F\u002F ... (similar patterns for all 12 hook events: Notification, Stop, SubagentStop,\n      \u002F\u002F      SubagentStart, PreCompact, SessionStart, SessionEnd, PermissionRequest, PostToolUseFailure)\n     }\n   }\n   ```\n   \n   Replace `YOUR_PROJECT_NAME` with a unique identifier for your project (e.g., `my-api-server`, `react-app`, etc.).\n\n3. **Ensure the observability server is running:**\n   ```bash\n   # From the observability project directory (this codebase)\n   .\u002Fscripts\u002Fstart-system.sh\n   ```\n\nNow your project will send events to the observability system whenever Claude Code performs actions.\n\n## 🚀 Quick Start\n\nYou can quickly view how this works by running this repository's `.claude` setup.\n\n```bash\n# 1. Start both server and client\njust start          # or: .\u002Fscripts\u002Fstart-system.sh\n\n# 2. Open http:\u002F\u002Flocalhost:5173 in your browser\n\n# 3. Open Claude Code and run the following command:\nRun git ls-files to understand the codebase.\n\n# 4. Watch events stream in the client\n\n# 5. Copy the .claude folder to other projects you want to emit events from.\ncp -R .claude \u003Cdirectory of your codebase you want to emit events from>\n```\n\n### Using `just` (Recommended)\n\nA `justfile` provides convenient recipes for common operations:\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\u002Fclient 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## 📁 Project Structure\n\n```\nclaude-code-hooks-multi-agent-observability\u002F\n│\n├── apps\u002F                    # Application components\n│   ├── server\u002F             # Bun TypeScript server\n│   │   ├── src\u002F\n│   │   │   ├── index.ts    # Main server with HTTP\u002FWebSocket endpoints\n│   │   │   ├── db.ts       # SQLite database management & migrations\n│   │   │   └── types.ts    # TypeScript interfaces\n│   │   ├── package.json\n│   │   └── events.db       # SQLite database (gitignored)\n│   │\n│   └── client\u002F             # Vue 3 TypeScript client\n│       ├── src\u002F\n│       │   ├── App.vue     # Main app with theme & WebSocket management\n│       │   ├── components\u002F\n│       │   │   ├── EventTimeline.vue      # Event list with auto-scroll\n│       │   │   ├── EventRow.vue           # Individual event display\n│       │   │   ├── FilterPanel.vue        # Multi-select filters\n│       │   │   ├── ChatTranscriptModal.vue # Chat history viewer\n│       │   │   ├── StickScrollButton.vue  # Scroll control\n│       │   │   └── LivePulseChart.vue     # Real-time activity chart\n│       │   ├── composables\u002F\n│       │   │   ├── useWebSocket.ts        # WebSocket connection logic\n│       │   │   ├── useEventColors.ts      # Color assignment system\n│       │   │   ├── useChartData.ts        # Chart data aggregation\n│       │   │   └── useEventEmojis.ts      # Event type emoji mapping\n│       │   ├── utils\u002F\n│       │   │   └── chartRenderer.ts       # Canvas chart rendering\n│       │   └── types.ts    # TypeScript interfaces\n│       ├── .env.sample     # Environment configuration template\n│       └── package.json\n│\n├── .claude\u002F                # Claude Code integration\n│   ├── hooks\u002F             # Hook scripts (Python with uv)\n│   │   ├── send_event.py          # Universal event sender (all 12 event types)\n│   │   ├── pre_tool_use.py        # Tool validation, blocking & summarization\n│   │   ├── post_tool_use.py       # Result logging with MCP tool detection\n│   │   ├── post_tool_use_failure.py # Tool failure logging\n│   │   ├── permission_request.py  # Permission request logging\n│   │   ├── notification.py        # User interaction events (type-aware TTS)\n│   │   ├── user_prompt_submit.py  # User prompt logging & validation\n│   │   ├── stop.py               # Session completion (stop_hook_active guard)\n│   │   ├── subagent_stop.py      # Subagent completion with transcript path\n│   │   ├── subagent_start.py     # Subagent lifecycle start tracking\n│   │   ├── pre_compact.py        # Context compaction with custom instructions\n│   │   ├── session_start.py      # Session start with agent type & model\n│   │   ├── session_end.py        # Session end with reason tracking\n│   │   └── validators\u002F           # Stop hook validators\n│   │       ├── validate_new_file.py     # Validate file creation\n│   │       └── validate_file_contains.py # Validate file content sections\n│   │\n│   ├── agents\u002Fteam\u002F       # Agent team definitions\n│   │   ├── builder.md     # Engineering agent with linting hooks\n│   │   └── validator.md   # Read-only validation agent\n│   │\n│   ├── commands\u002F          # Custom slash commands\n│   │   └── plan_w_team.md # Team-based planning command\n│   │\n│   ├── status_lines\u002F      # Status line scripts\n│   │   └── status_line_v6.py # Context window usage display\n│   │\n│   └── settings.json      # Hook configuration (all 12 events)\n│\n├── justfile               # Task runner recipes (just start, just stop, etc.)\n│\n├── scripts\u002F               # Utility scripts\n│   ├── start-system.sh   # Launch server & client\n│   ├── reset-system.sh   # Stop all processes\n│   └── test-system.sh    # System validation\n│\n└── logs\u002F                 # Application logs (gitignored)\n```\n\n## 🔧 Component Details\n\n### 1. Hook System (`.claude\u002Fhooks\u002F`)\n\n> If you want to master claude code hooks watch [this video](https:\u002F\u002Fgithub.com\u002Fdisler\u002Fclaude-code-hooks-mastery)\n\nThe hook system intercepts Claude Code lifecycle events:\n\n- **`send_event.py`**: Core script that sends event data to the observability server\n  - Supports all 12 hook event types with event-specific field forwarding\n  - Supports `--add-chat` flag for including conversation history\n  - Forwards event-specific fields (`tool_name`, `tool_use_id`, `agent_id`, `notification_type`, etc.) as top-level properties for easier querying\n  - Validates server connectivity before sending\n\n- **Event-specific hooks** (12 total): Each implements validation and data extraction\n  - `pre_tool_use.py`: Blocks dangerous commands, validates tool usage, summarizes tool inputs per tool type\n  - `post_tool_use.py`: Captures execution results with MCP tool detection (`mcp_server`, `mcp_tool_name`)\n  - `post_tool_use_failure.py`: Logs tool execution failures\n  - `permission_request.py`: Logs permission request events\n  - `notification.py`: Tracks user interactions with `notification_type`-aware TTS (permission_prompt, idle_prompt, etc.)\n  - `user_prompt_submit.py`: Logs user prompts, supports validation with JSON `{\"decision\": \"block\"}` pattern\n  - `stop.py`: Records session completion with `stop_hook_active` guard to prevent infinite loops\n  - `subagent_stop.py`: Monitors subagent task completion with transcript path tracking\n  - `subagent_start.py`: Tracks subagent lifecycle start events\n  - `pre_compact.py`: Tracks context compaction with custom instructions in backup filenames\n  - `session_start.py`: Logs session start with `agent_type`, `model`, and `source` fields\n  - `session_end.py`: Logs session end with reason tracking (including `bypass_permissions_disabled`)\n\n### 2. Server (`apps\u002Fserver\u002F`)\n\nBun-powered TypeScript server with real-time capabilities:\n\n- **Database**: SQLite with WAL mode for concurrent access\n- **Endpoints**:\n  - `POST \u002Fevents` - Receive events from agents\n  - `GET \u002Fevents\u002Frecent` - Paginated event retrieval with filtering\n  - `GET \u002Fevents\u002Ffilter-options` - Available filter values\n  - `WS \u002Fstream` - Real-time event broadcasting\n- **Features**:\n  - Automatic schema migrations\n  - Event validation\n  - WebSocket broadcast to all clients\n  - Chat transcript storage\n\n### 3. Client (`apps\u002Fclient\u002F`)\n\nVue 3 application with real-time visualization:\n\n- **Visual Design**:\n  - Dual-color system: App colors (left border) + Session colors (second border)\n  - Gradient indicators for visual distinction\n  - Dark\u002Flight theme support\n  - Responsive layout with smooth animations\n\n- **Features**:\n  - Real-time WebSocket updates\n  - Multi-criteria filtering (app, session, event type)\n  - Live pulse chart with session-colored bars and event type indicators\n  - Time range selection (1m, 3m, 5m) with appropriate data aggregation\n  - Chat transcript viewer with syntax highlighting\n  - Auto-scroll with manual override\n  - Event limiting (configurable via `VITE_MAX_EVENTS_TO_DISPLAY`)\n\n- **Tool Emoji System**:\n  - Each tool type has a dedicated emoji (Bash: 💻, Read: 📖, Write: ✍️, Edit: ✏️, Task: 🤖, etc.)\n  - Tool events show combo emojis: event emoji + tool emoji (e.g., 🔧💻 for PreToolUse:Bash)\n  - MCP tools display with 🔌 prefix\n  - Tool name badge displayed alongside event type in the timeline\n\n- **Live Pulse Chart**:\n  - Canvas-based real-time visualization\n  - Session-specific colors for each bar\n  - Event type + tool combo emojis displayed on bars\n  - Smooth animations and glow effects\n  - Responsive to filter changes\n\n## 🔄 Data Flow\n\n1. **Event Generation**: Claude Code executes an action (tool use, notification, etc.)\n2. **Hook Activation**: Corresponding hook script runs based on `settings.json` configuration\n3. **Data Collection**: Hook script gathers context (tool name, inputs, outputs, session ID)\n4. **Transmission**: `send_event.py` sends JSON payload to server via HTTP POST\n5. **Server Processing**:\n   - Validates event structure\n   - Stores in SQLite with timestamp\n   - Broadcasts to WebSocket clients\n6. **Client Update**: Vue app receives event and updates timeline in real-time\n\n## 🎨 Event Types & Visualization\n\n| Event Type         | Emoji | Purpose                | Color Coding  | Special Display                      |\n| ------------------ | ----- | ---------------------- | ------------- | ------------------------------------ |\n| PreToolUse         | 🔧     | Before tool execution  | Session-based | Tool name + tool emoji & details     |\n| PostToolUse        | ✅     | After tool completion  | Session-based | Tool name + tool emoji & results     |\n| PostToolUseFailure | ❌     | Tool execution failed  | Session-based | Error details & interrupt status     |\n| PermissionRequest  | 🔐     | Permission requested   | Session-based | Tool name & permission suggestions   |\n| Notification       | 🔔     | User interactions      | Session-based | Notification message & type          |\n| Stop               | 🛑     | Response completion    | Session-based | Summary & chat transcript            |\n| SubagentStart      | 🟢     | Subagent started       | Session-based | Agent ID & type                      |\n| SubagentStop       | 👥     | Subagent finished      | Session-based | Agent details & transcript path      |\n| PreCompact         | 📦     | Context compaction     | Session-based | Trigger & custom instructions        |\n| UserPromptSubmit   | 💬     | User prompt submission | Session-based | Prompt: _\"user message\"_ (italic)    |\n| SessionStart       | 🚀     | Session started        | Session-based | Source, model & agent type           |\n| SessionEnd         | 🏁     | Session ended          | Session-based | End reason (clear\u002Flogout\u002Fexit\u002Fother) |\n\n### UserPromptSubmit Event (v1.0.54+)\n\nThe `UserPromptSubmit` hook captures every user prompt before Claude processes it. In the UI:\n- Displays as `Prompt: \"user's message\"` in italic text\n- Shows the actual prompt content inline (truncated to 100 chars)\n- Summary appears on the right side when AI summarization is enabled\n- Useful for tracking user intentions and conversation flow\n\n## 🔌 Integration\n\n### For New Projects\n\n1. Copy the event sender:\n   ```bash\n   cp .claude\u002Fhooks\u002Fsend_event.py YOUR_PROJECT\u002F.claude\u002Fhooks\u002F\n   ```\n\n2. Add to your `.claude\u002Fsettings.json`:\n   ```json\n   {\n     \"hooks\": {\n       \"PreToolUse\": [{\n         \"matcher\": \".*\",\n         \"hooks\": [{\n           \"type\": \"command\",\n           \"command\": \"uv run .claude\u002Fhooks\u002Fsend_event.py --source-app YOUR_APP --event-type PreToolUse\"\n         }]\n       }]\n     }\n   }\n   ```\n\n### For This Project\n\nAlready integrated! Hooks run both validation and observability:\n```json\n{\n  \"type\": \"command\",\n  \"command\": \"uv run .claude\u002Fhooks\u002Fpre_tool_use.py\"\n},\n{\n  \"type\": \"command\",\n  \"command\": \"uv run .claude\u002Fhooks\u002Fsend_event.py --source-app cc-hook-multi-agent-obvs --event-type PreToolUse\"\n}\n```\n\n## 🧪 Testing\n\n```bash\n# System validation\n.\u002Fscripts\u002Ftest-system.sh\n\n# Quick test event via just\njust test-event\n\n# Check server\u002Fclient health\njust health\n\n# Manual event test\ncurl -X POST http:\u002F\u002Flocalhost:4000\u002Fevents \\\n  -H \"Content-Type: application\u002Fjson\" \\\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# Test a hook script directly\njust hook-test pre_tool_use\n```\n\n## ⚙️ Configuration\n\n### Environment Variables\n\nCopy `.env.sample` to `.env` in the project root and fill in your API keys:\n\n**Application Root** (`.env` file):\n- `ANTHROPIC_API_KEY` – Anthropic Claude API key (required)\n- `ENGINEER_NAME` – Your name (for logging\u002Fidentification)\n- `OPENAI_API_KEY` – OpenAI API key (optional)\n- `ELEVENLABS_API_KEY` – ElevenLabs API key (optional, for TTS)\n- `FIRECRAWL_API_KEY` – Firecrawl API key (optional, for web scraping)\n\n**Client** (`.env` file in `apps\u002Fclient\u002F.env`):\n- `VITE_MAX_EVENTS_TO_DISPLAY=100` – Maximum events to show (removes oldest when exceeded)\n\n### Server Ports\n\n- Server: `4000` (HTTP\u002FWebSocket)\n- Client: `5173` (Vite dev server)\n\n## 🤖 Agent Teams\n\nThis project supports Claude Code Agent Teams for orchestrating multi-agent workflows. Teams are enabled via the `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` environment variable in `.claude\u002Fsettings.json`.\n\n### Team Agents\n\n- **Builder** (`.claude\u002Fagents\u002Fteam\u002Fbuilder.md`): Engineering agent that executes one task at a time. Includes PostToolUse hooks for `ruff` and `ty` validation on Write\u002FEdit operations.\n- **Validator** (`.claude\u002Fagents\u002Fteam\u002Fvalidator.md`): Read-only validation agent that inspects work without modifying files. Cannot use Write, Edit, or NotebookEdit tools.\n\n### Planning with Teams\n\nUse the `\u002Fplan_w_team` slash command to create team-based implementation plans:\n\n```bash\n\u002Fplan_w_team \"Add a new feature for X\"\n```\n\nThis generates a spec document in `specs\u002F` with task breakdowns, team member assignments, dependencies, and acceptance criteria. Plans are validated by Stop hook validators that ensure required sections are present.\n\nExecute a plan with:\n```bash\n\u002Fbuild specs\u002F\u003Cplan-name>.md\n```\n\n## 🔭 Multi-Agent Orchestration & Observability\n\n[![Multi-Agent Orchestration with Claude Code](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdisler_claude-code-hooks-multi-agent-observability_readme_5cf53fbe6650.png)](https:\u002F\u002Fyoutu.be\u002FRpUTF_U4kiw)\n\nThe true constraint of agentic engineering is no longer what the models can do — it's our ability to prompt engineer and context engineer the outcomes we need, and build them into reusable systems. Multi-agent orchestration changes the game by letting you spin up teams of specialized agents that each focus on one task extraordinarily well, work in parallel, and shut down when done. See the official [Claude Code Agent Teams documentation](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fagent-teams) for the full reference.\n\n### The Orchestration Workflow\n\nThe full multi-agent orchestration lifecycle follows this pattern:\n\n1. **Create a team** — `TeamCreate` sets up the coordination layer\n2. **Create tasks** — `TaskCreate` builds the centralized task list that drives all work\n3. **Spawn agents** — `Task` deploys specialized agents (builder, validator, etc.) into their own Tmux panes with independent context windows\n4. **Work in parallel** — Agents execute their assigned tasks simultaneously, communicating via `SendMessage`\n5. **Shut down agents** — Completed agents are gracefully terminated\n6. **Delete the team** — `TeamDelete` cleans up all coordination state\n\n### Why Observability Matters\n\nWhen you have multiple agents running in parallel — each with their own context window, session ID, and task assignments — you need visibility into what's happening across the swarm. Without observability, you're vibe coding at scale. With it, you can:\n\n- **Trace every tool call** across all agents in real-time via the dashboard\n- **Filter by agent swim lane** to inspect individual agent behavior\n- **Track task lifecycle** — see TaskCreate, TaskUpdate, and SendMessage events flow between agents\n- **Spot failures early** — PostToolUseFailure and PermissionRequest events surface issues before they cascade\n- **Measure throughput** — the live pulse chart shows activity density across your agent fleet\n\nThis is what separates engineers from vibe coders: understanding what's happening underneath the hood so you can scale compute to scale impact with confidence.\n\n## 🛡️ Security Features\n\n- Blocks dangerous `rm -rf` commands via `deny_tool()` JSON pattern (allowed only in specific directories)\n- Prevents access to sensitive files (`.env`, private keys)\n- `stop_hook_active` guard in `stop.py` and `subagent_stop.py` prevents infinite hook loops\n- Stop hook validators ensure plan files contain required sections before completion\n- Validates all inputs before execution\n\n## 📊 Technical Stack\n\n- **Server**: Bun, TypeScript, SQLite\n- **Client**: Vue 3, TypeScript, Vite, Tailwind CSS\n- **Hooks**: Python 3.11+, Astral uv, TTS (ElevenLabs or OpenAI), LLMs (Claude or OpenAI)\n- **Communication**: HTTP REST, WebSocket\n\n## Master AI **Agentic Coding**\n> And prepare for the future of software engineering\n\nLearn tactical agentic coding patterns with [Tactical Agentic Coding](https:\u002F\u002Fagenticengineer.com\u002Ftactical-agentic-coding?y=opsorch)\n\nFollow the [IndyDevDan YouTube channel](https:\u002F\u002Fwww.youtube.com\u002F@indydevdan) to improve your agentic coding advantage.\n\n","# 多智能体可观测性系统\n\n通过全面的钩子事件追踪，为 Claude Code 代理提供实时监控与可视化功能。欢迎点击此处观看【关于使用 Opus 4.6 进行多智能体编排的最新深度解析】（https:\u002F\u002Fyoutu.be\u002FRpUTF_U4kiw）。借助 Claude Opus 4.6 以及多智能体编排功能，您现在可以快速组建由专业代理组成的团队，这些代理可并行工作；而这一可观测性系统则能让您追踪整个集群中每一次工具调用、任务交接以及代理生命周期中的各类事件。\n\n## 🎯 概述\n\n本系统通过实时捕获、存储并可视化 Claude Code 的【钩子事件】（https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code），为 Claude Code 代理的行为提供完整的可观测性支持。借助会话跟踪、事件过滤以及实时更新等功能，该系统能够实现对多个并发代理的全方位监控。\n\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdisler_claude-code-hooks-multi-agent-observability_readme_c64fa830be1a.png\" alt=\"多智能体可观测性仪表板\" style=\"max-width: 800px; width: 100%;\">\n\n## 🏗️ 架构\n\n```\nClaude 代理 → 钩子脚本 → HTTP POST → Bun 服务器 → SQLite → WebSocket → Vue 客户端\n```\n\n![代理数据流动画](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdisler_claude-code-hooks-multi-agent-observability_readme_3b8dd3a3caf9.gif)\n\n## 📋 设置要求\n\n在开始之前，请确保已安装以下组件：\n\n- **[Claude Code](https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code)** - Anthropic 提供的 Claude 官方 CLI 工具\n- **[Astral uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002F)** - 快速 Python 包管理器（用于钩子脚本）\n- **[Bun](https:\u002F\u002Fbun.sh\u002F)**、**npm** 或 **yarn** - 用于运行服务器和客户端\n- **[just](https:\u002F\u002Fgithub.com\u002Fcasey\u002Fjust)**（可选） - 项目配方的命令行运行器\n- **Anthropic API 密钥** - 设置为 `ANTHROPIC_API_KEY` 环境变量\n- **OpenAI API 密钥**（可选） - 用于在使用“just-prompt MCP”工具时实现多模型支持\n- **ElevenLabs API 密钥**（可选） - 用于音频功能\n- **Firecrawl API 密钥**（可选） - 用于网页抓取功能\n\n### 配置 .claude 目录\n\n要在您的代码库中启用可观测性功能，需将 `.claude` 目录复制到项目根目录。\n\n要将可观测性钩子集成到您的项目中：\n\n1. **将整个 `.claude` 目录复制到项目根目录：**\n   ```bash\n   cp -R .claude \u002Fpath\u002Fto\u002Fyour\u002Fproject\u002F\n   ```\n\n2. **更新 `settings.json` 配置：**\n\n   打开项目中的 `.claude\u002Fsettings.json` 文件，并将 `source-app` 参数修改为您的项目标识：\n   \n   ```json\n   {\n     \"hooks\": {\n       \"PreToolUse\": [\n         {\n           \"matcher\": \"\",\n           \"hooks\": [\n             {\n               \"type\": \"command\",\n               \"command\": \"uv run .claude\u002Fhooks\u002Fpre_tool_use.py\"\n             },\n             {\n               \"type\": \"command\",\n               \"command\": \"uv run .claude\u002Fhooks\u002Fsend_event.py --source-app YOUR_PROJECT_NAME --event-type PreToolUse --summarize\"\n             }\n           ]\n         }\n       ],\n       \"PostToolUse\": [\n         {\n           \"matcher\": \"\",\n           \"hooks\": [\n             {\n               \"type\": \"command\",\n               \"command\": \"uv run .claude\u002Fhooks\u002Fpost_tool_use.py\"\n             },\n             {\n               \"type\": \"command\",\n               \"command\": \"uv run .claude\u002Fhooks\u002Fsend_event.py --source-app YOUR_PROJECT_NAME --event-type PostToolUse --summarize\"\n             }\n           ]\n         }\n       ],\n       \"UserPromptSubmit\": [\n         {\n           \"hooks\": [\n             {\n               \"type\": \"command\",\n               \"command\": \"uv run .claude\u002Fhooks\u002Fuser_prompt_submit.py --log-only\"\n             },\n             {\n               \"type\": \"command\",\n               \"command\": \"uv run .claude\u002Fhooks\u002Fsend_event.py --source-app YOUR_PROJECT_NAME --event-type UserPromptSubmit --summarize\"\n             }\n           ]\n         }\n       ]\n       \u002F\u002F ... （适用于所有 12 个钩子事件的类似模式：通知、停止、子代理停止、子代理启动、预压缩、会话启动、会话结束、权限请求、后工具使用失败）\n     }\n   }\n   ```\n   \n   请将 `YOUR_PROJECT_NAME` 替换为您的项目唯一标识（例如：`my-api-server`、`react-app` 等）。\n\n3. **确保可观测性服务器正在运行：**\n   ```bash\n   # 从可观测性项目目录（即该代码库）中运行\n   .\u002Fscripts\u002Fstart-system.sh\n   ```\n\n现在，每当 Claude Code 执行相关操作时，您的项目便会将事件发送至可观测性系统。\n\n## 🚀 快速入门\n\n您可以通过运行本仓库的 `.claude` 配置，快速了解其工作原理。\n\n```bash\n# 1. 启动服务器与客户端\njust start          # 或者：.\u002Fscripts\u002Fstart-system.sh\n\n# 2. 在浏览器中打开 http:\u002F\u002Flocalhost:5173\n\n# 3. 打开 Claude Code 并运行以下命令：\n运行 `git ls-files`，以了解代码库的整体结构。\n\n# 4. 在客户端中实时查看事件流\n\n# 5. 将 `.claude` 文件夹复制到其他希望发送事件的项目中。\ncp -R .claude \u003C您希望发送事件的代码库所在目录>\n```\n\n### 使用 `just`（推荐）\n\n`justfile` 可以为您提供便捷的常见操作配方：\n\n```bash\njust              # 列出所有可用的配方\njust start        # 启动服务器 + 客户端\njust stop         # 停止所有进程\njust restart      # 先停止再启动\njust server       # 仅启动服务器（开发模式）\njust client       # 仅启动客户端\njust install      # 安装所有依赖项\njust health       # 检查服务器\u002F客户端的状态\njust test-event   # 发送一个测试事件\njust db-reset     # 重置数据库\njust hooks        # 列出所有钩子脚本\njust open         # 在浏览器中打开仪表板\n```\n\n## 📁 项目结构\n\n```\nclaude-code-hooks-multi-agent-observability\u002F\n│\n├── apps\u002F                    # 应用组件\n│   ├── server\u002F             # Bun TypeScript 服务器\n│   │   ├── src\u002F\n│   │   │   ├── index.ts    # 主服务器，包含 HTTP 和 WebSocket 端点\n│   │   │   ├── db.ts       # SQLite 数据库管理与迁移\n│   │   │   └── types.ts    # TypeScript 接口\n│   │   ├── package.json\n│   │   └── events.db       # SQLite 数据库（已忽略）\n│   │\n│   └── client\u002F             # Vue 3 TypeScript 客户端\n│       ├── src\u002F\n│       │   ├── App.vue     # 主应用，支持主题与 WebSocket 管理\n│       │   ├── components\u002F\n│       │   │   ├── EventTimeline.vue      # 带自动滚动功能的事件列表\n│       │   │   ├── EventRow.vue           # 单个事件展示\n│       │   │   ├── FilterPanel.vue        # 多选筛选器\n│       │   │   ├── ChatTranscriptModal.vue # 聊天历史查看器\n│       │   │   ├── StickScrollButton.vue  # 滚动控制按钮\n│       │   │   └── LivePulseChart.vue     # 实时活动图表\n│       │   ├── composables\u002F\n│       │   │   ├── useWebSocket.ts        # WebSocket 连接逻辑\n│       │   │   ├── useEventColors.ts      # 颜色分配系统\n│       │   │   ├── useChartData.ts        # 图表数据聚合\n│       │   │   └── useEventEmojis.ts      # 事件类型表情符号映射\n│       │   ├── utils\u002F\n│       │   │   └── chartRenderer.ts       # Canvas 图表渲染\n│       │   └── types.ts    # TypeScript 接口\n│       ├── .env.sample     # 环境配置模板\n│       └── package.json\n│\n├── .claude\u002F                # Claude Code 集成\n│   ├── hooks\u002F             # Hook 脚本（Python + uv）\n│   │   ├── send_event.py          # 通用事件发送器（涵盖全部 12 种事件类型）\n│   │   ├── pre_tool_use.py        # 工具验证、阻断与汇总\n│   │   ├── post_tool_use.py       # 结果日志记录，并结合 MCP 工具检测\n│   │   ├── post_tool_use_failure.py # 工具失败日志记录\n│   │   ├── permission_request.py  # 权限请求日志记录\n│   │   ├── notification.py        # 用户交互事件（基于类型感知的 TTS）\n│   │   ├── user_prompt_submit.py  # 用户提示日志记录与验证\n│   │   ├── stop.py               # 会话结束（通过 stop_hook_active 保护机制）\n│   │   ├── subagent_stop.py      # 子代理完成任务，并跟踪转录路径\n│   │   ├── subagent_start.py     # 子代理生命周期启动追踪\n│   │   ├── pre_compact.py        # 根据自定义指令进行上下文压缩\n│   │   ├── session_start.py      # 以代理类型与模型启动会话\n│   │   ├── session_end.py        # 会话结束时进行原因追踪\n│   │   └── validators\u002F           # 保护机制验证器\n│   │       ├── validate_new_file.py     # 验证文件创建\n│   │       └── validate_file_contains.py # 验证文件内容部分\n│   │\n│   ├── agents\u002Fteam\u002F       # 代理团队定义\n│   │   ├── builder.md     # 工程化代理，配备 linting hook\n│   │   └── validator.md   # 只读验证代理\n│   │\n│   ├── commands\u002F          # 自定义斜杠命令\n│   │   └── plan_w_team.md # 团队协作规划命令\n│   │\n│   ├── status_lines\u002F      # 状态行脚本\n│   │   └── status_line_v6.py # 上下文窗口使用情况显示\n│   │\n│   └── settings.json      # Hook 配置（涵盖全部 12 种事件）\n│\n├── justfile               # 任务运行器脚本（just start、just stop 等）\n│\n├── scripts\u002F               # 实用脚本\n│   ├── start-system.sh   # 启动服务器与客户端\n│   ├── reset-system.sh   # 停止所有进程\n│   └── test-system.sh    # 系统验证\n│\n└── logs\u002F                 # 应用日志（已忽略）\n```\n\n## 🔧 组件详情\n\n### 1. Hook 系统（`.claude\u002Fhooks\u002F`）\n\n> 如果你想精通 Claude Code 的 Hook，请观看 [此视频](https:\u002F\u002Fgithub.com\u002Fdisler\u002Fclaude-code-hooks-mastery)。\n\nHook 系统可拦截 Claude Code 生命周期中的各类事件：\n\n- **send_event.py**：核心脚本，负责将事件数据发送至可观测性服务器\n  - 支持全部 12 种 Hook 事件类型，并对事件字段进行特定转发\n  - 支持使用 `--add-chat` 标志，以纳入对话历史\n  - 将事件特有字段（如 `tool_name`、`tool_use_id`、`agent_id`、`notification_type` 等）作为顶级属性进行转发，以便更便捷地进行查询\n  - 在发送前验证服务器连接是否正常\n\n- **事件专用 Hook**（共 12 个）：每个 Hook 都实现了验证与数据提取功能\n  - `pre_tool_use.py`：阻止危险命令，对工具使用情况进行验证，并按工具类型汇总工具输入\n  - `post_tool_use.py`：通过 MCP 工具检测（如 `mcp_server`、`mcp_tool_name`）捕捉执行结果\n  - `post_tool_use_failure.py`：记录工具执行失败的日志\n  - `permission_request.py`：记录权限请求事件\n  - `notification.py`：根据 `notification_type` 感知用户交互，通过 TTS 进行跟踪（如权限提示、空闲提示等）\n  - `user_prompt_submit.py`：记录用户提示，并支持 JSON 格式验证，符合 `{\"decision\": \"block\"}` 的模式\n  - `stop.py`：通过 `stop_hook_active` 保护机制记录会话结束，防止无限循环\n  - `subagent_stop.py`：监控子代理任务完成情况，并跟踪转录路径\n  - `subagent_start.py`：追踪子代理生命周期的启动事件\n  - `pre_compact.py`：根据自定义指令，对上下文进行压缩，并在备份文件名中保留相关指示\n  - `session_start.py`：记录会话启动时的 `agent_type`、`model` 以及 `source` 字段\n  - `session_end.py`：记录会话结束时的原因追踪（包括 `bypass_permissions_disabled`）\n\n### 2. 服务器（`apps\u002Fserver\u002F`）\n\nBun 提供的 TypeScript 服务器，具备实时能力：\n\n- **数据库**：SQLite，采用 WAL 模式，支持并发访问\n- **端点**：\n  - `POST \u002Fevents` - 接收来自代理的事件\n  - `GET \u002Fevents\u002Frecent` - 分页获取事件，并支持筛选\n  - `GET \u002Fevents\u002Ffilter-options` - 显示可用的筛选选项\n  - `WS \u002Fstream` - 实时广播事件\n- **功能**：\n  - 自动完成 Schema 迁移\n  - 事件验证\n  - 通过 WebSocket 向所有客户端进行广播\n  - 聊天转录数据存储\n\n### 3. 客户端（`apps\u002Fclient\u002F`）\n\n基于 Vue 3 的实时可视化应用：\n\n- **视觉设计**：\n  - 双色系统：应用颜色（左侧边框）+ 会话颜色（第二侧边框）\n  - 渐变指示器，用于实现清晰的视觉区分\n  - 支持深浅主题切换\n  - 响应式布局，搭配流畅的动画效果\n\n- **功能特性**：\n  - 实时 WebSocket 更新\n  - 多条件筛选（应用、会话、事件类型）\n  - 实时脉冲图，以会话色条和事件类型指示器呈现\n  - 时间范围选择（1分钟、3分钟、5分钟），并自动进行数据聚合\n  - 聊天记录查看器，支持语法高亮显示\n  - 自动滚动，同时支持手动控制\n  - 事件限制功能（可通过 `VITE_MAX_EVENTS_TO_DISPLAY` 进行配置）\n\n- **工具表情符号系统**：\n  - 每种工具类型都配有专属的表情符号（如 Bash：💻、阅读：📖、写作：✍️、编辑：✏️、任务：🤖 等）\n  - 工具事件会显示组合表情符号：事件表情符号 + 工具表情符号（例如，PreToolUse:Bash 代表 PreToolUse：Bash）\n  - MCP 工具以 🔌 前缀显示\n  - 工具名称徽章会与事件类型一同显示在时间轴上\n\n- **实时脉冲图**：\n  - 基于 Canvas 的实时可视化\n  - 每个柱状图均采用会话特定的颜色\n  - 柱状图上会显示事件类型与工具组合表情符号\n  - 动画流畅，且带有发光效果\n  - 对过滤器变化高度自适应\n\n## 🔄 数据流\n\n1. **事件生成**：Claude Code 执行某项操作（如工具使用、通知等）\n2. **钩子激活**：根据 `settings.json` 配置，运行相应的钩子脚本\n3. **数据采集**：钩子脚本收集上下文信息（工具名称、输入、输出、会话 ID）\n4. **数据传输**：`send_event.py` 通过 HTTP POST 将 JSON 数据包发送至服务器\n5. **服务器处理**：\n   - 验证事件结构\n   - 以 SQLite 存储数据，并附带时间戳\n   - 向 WebSocket 客户端广播事件\n6. **客户端更新**：Vue 应用接收事件，并实时更新时间轴\n\n## 🎨 事件类型与可视化\n\n| 事件类型         | 表情符号 | 用途                | 颜色编码  | 特殊显示                        |\n| ------------------ | ----- | ---------------------- | ------------- | ------------------------------------ |\n| PreToolUse         | 🔧     | 工具执行前            | 会话相关        | 工具名称 + 工具表情符号及详细信息     |\n| PostToolUse        | ✅     | 工具执行后            | 会话相关        | 工具名称 + 工具表情符号及结果       |\n| PostToolUseFailure | ❌     | 工具执行失败            | 会话相关        | 错误详情及中断状态             |\n| PermissionRequest  | 🔐     | 请求权限              | 会话相关        | 工具名称及权限建议               |\n| Notification       | 🔔     | 用户交互              | 会话相关        | 通知消息及类型                 |\n| Stop               | 🛑     | 响应完成              | 会话相关        | 总结与聊天记录               |\n| SubagentStart      | 🟢     | 子代理启动              | 会话相关        | 代理 ID 及类型                   |\n| SubagentStop       | 👥     | 子代理完成              | 会话相关        | 代理详情及记录路径               |\n| PreCompact         | 📦     | 上下文压缩              | 会话相关        | 触发器及自定义指令               |\n| UserPromptSubmit   | 💬     | 用户提示提交              | 会话相关        | 提示内容：“用户消息”（斜体）    |\n| SessionStart       | 🚀     | 会话启动              | 会话相关        | 来源、模型及代理类型           |\n| SessionEnd         | 🏁     | 会话结束              | 会话相关        | 结束原因（清除\u002F退出\u002F离开\u002F其他） |\n\n### 用户提示提交事件（v1.0.54+）\n\n`UserPromptSubmit` 钩子会在 Claude 处理用户提示之前捕获所有用户提示。在 UI 中：\n- 显示为“用户消息”（斜体文本）\n- 在内联中展示实际的提示内容（截断至 100 个字符）\n- 当启用 AI 摘要功能时，右侧会显示摘要\n- 有助于追踪用户意图和对话流程\n\n## 🔌 集成\n\n### 新项目\n\n1. 复制事件发送者：\n   ```bash\n   cp .claude\u002Fhooks\u002Fsend_event.py YOUR_PROJECT\u002F.claude\u002Fhooks\u002F\n   ```\n\n2. 在 `.claude\u002Fsettings.json` 中添加：\n   ```json\n   {\n     \"hooks\": {\n       \"PreToolUse\": [{\n         \"matcher\": \".*\",\n         \"hooks\": [{\n           \"type\": \"command\",\n           \"command\": \"uv run .claude\u002Fhooks\u002Fsend_event.py --source-app YOUR_APP --event-type PreToolUse\"\n         }]\n       }]\n     }\n   }\n   ```\n\n### 本项目\n\n已成功集成！钩子既可执行验证，又具备可观测性：\n```json\n{\n  \"type\": \"command\",\n  \"command\": \"uv run .claude\u002Fhooks\u002Fpre_tool_use.py\"\n},\n{\n  \"type\": \"command\",\n  \"command\": \"uv run .claude\u002Fhooks\u002Fsend_event.py --source-app cc-hook-multi-agent-obvs --event-type PreToolUse\"\n}\n```\n\n## 🧪 测试\n\n```bash\n# 系统验证\n.\u002Fscripts\u002Ftest-system.sh\n\n# 快速测试事件，仅需执行\njust test-event\n\n# 检查服务器\u002F客户端健康状况\njust health\n\n# 手动测试事件\ncurl -X POST http:\u002F\u002Flocalhost:4000\u002Fevents \\\n  -H \"Content-Type: application\u002Fjson\" \\\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# 直接测试钩子脚本\njust hook-test pre_tool_use\n```\n\n## ⚙️ 配置\n\n### 环境变量\n\n将 `.env.sample` 复制到项目根目录下的 `.env` 文件中，并填写您的 API 密钥：\n\n**应用根目录**（`.env` 文件）：\n- `ANTHROPIC_API_KEY` – Anthropic Claude API 密钥（必填）\n- `ENGINEER_NAME` – 您的姓名（用于日志记录\u002F身份识别）\n- `OPENAI_API_KEY` – OpenAI API 密钥（可选）\n- `ELEVENLABS_API_KEY` – ElevenLabs API 密钥（可选，用于 TTS）\n- `FIRECRAWL_API_KEY` – Firecrawl API 密钥（可选，用于网页抓取）\n\n**客户端**（`.env` 文件，位于 `apps\u002Fclient\u002F.env`）：\n- `VITE_MAX_EVENTS_TO_DISPLAY=100` – 最大显示事件数量（超出时会移除最旧的事件）\n\n### 服务器端口\n\n- 服务器：`4000`（HTTP\u002FWebSocket）\n- 客户端：`5173`（Vite 开发服务器）\n\n## 🤖 代理团队\n\n本项目支持 Claude Code 代理团队，用于协调多代理工作流。团队可通过 `.claude\u002Fsettings.json` 中的 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` 环境变量启用。\n\n### 团队代理\n\n- **构建者**（`.claude\u002Fagents\u002Fteam\u002Fbuilder.md`）：负责单次执行一项任务的工程代理。包含 PostToolUse 钩子，用于对 Write\u002FEdit 操作进行 `ruff` 和 `ty` 验证。\n- **验证者**（`.claude\u002Fagents\u002Fteam\u002Fvalidator.md`）：只读验证代理，可在不修改文件的情况下对工作进行检查。无法使用 Write、Edit 或 NotebookEdit 工具。\n\n### 与团队协作规划\n\n使用 `\u002Fplan_w_team` 切换命令，创建基于团队的实施计划：\n\n```bash\n\u002Fplan_w_team \"新增 X 功能\"\n```\n\n此命令会生成一个规格文档，位于 `specs\u002F` 目录下，其中包含任务分解、团队成员分配、依赖关系以及验收标准。计划会经过 Stop 钩子验证器的校验，确保各必填部分均已完整填写。\n\n执行计划的方式如下：\n```bash\n\u002Fbuild specs\u002F\u003Cplan-name>.md\n```\n\n## 🔭 多智能体编排与可观测性\n\n[![多智能体编排与 Claude 代码](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdisler_claude-code-hooks-multi-agent-observability_readme_5cf53fbe6650.png)](https:\u002F\u002Fyoutu.be\u002FRpUTF_U4kiw)\n\n智能体工程真正的挑战已不再在于模型能做什么——而是我们能否精准地引导工程师并为他们构建所需的结果，并将这些结果转化为可重用的系统。多智能体编排通过让您可以快速组建由专业智能体组成的团队，使每个智能体都能在某一特定任务上发挥卓越能力，实现并行工作，并在任务完成后自动关闭。如需完整参考，请参阅官方提供的 [Claude Code 智能体团队文档](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fagent-teams)。\n\n### 编排工作流\n\n完整的多智能体编排生命周期遵循以下模式：\n\n1. **创建团队** — `TeamCreate` 用于搭建协调层\n2. **创建任务** — `TaskCreate` 构建集中式任务列表，驱动所有工作流程\n3. **启动智能体** — `Task` 将专用智能体（如构建器、验证器等）部署到各自的 Tmux 窗口中，每个智能体拥有独立的上下文窗口\n4. **并行执行任务** — 智能体同时执行各自分配的任务，并通过 `SendMessage` 进行通信\n5. **终止智能体** — 完成任务的智能体将被优雅地终止\n6. **删除团队** — `TeamDelete` 清理所有协调状态\n\n### 可观测量的重要性\n\n当您有多个智能体并行运行——每个智能体都拥有自己的上下文窗口、会话 ID 和任务分配——您就需要实时了解整个群体中正在发生的一切。若缺乏可观测性，您只能在规模上进行“氛围式”编码。而有了可观测性，您就可以：\n\n- 通过仪表板实时追踪所有智能体间的每一条工具调用\n- 依据智能体所属的泳道进行筛选，以深入分析单个智能体的行为\n- 跟踪任务的生命周期——查看 TaskCreate、TaskUpdate 和 SendMessage 事件在各智能体之间流转的过程\n- 提前发现故障——在 PostToolUseFailure 和 PermissionRequest 事件中，问题会在连锁反应发生之前被及时发现\n- 测量系统的吞吐量——实时脉冲图能够清晰展示您的智能体群组中的活动密度\n\n正是这一点，将工程师与“氛围式”编码者区分开来：只有真正理解底层运作机制，您才能自信地扩展计算资源，从而以更稳健的方式提升影响力。\n\n## 🛡️ 安全功能\n\n- 通过 `deny_tool()` JSON 模式阻止危险的 `rm -rf` 命令（仅允许在特定目录中执行）\n- 防止访问敏感文件（`.env`、私钥）\n- 在 `stop.py` 和 `subagent_stop.py` 中加入 `stop_hook_active` 保护机制，防止无限循环的钩子触发\n- 钩子验证器确保在计划文件完成前，已包含必要的字段\n- 执行前对所有输入进行验证\n\n## 📊 技术栈\n\n- **服务器**：Bun、TypeScript、SQLite\n- **客户端**：Vue 3、TypeScript、Vite、Tailwind CSS\n- **钩子**：Python 3.11+、Astral uv、TTS（ElevenLabs 或 OpenAI）、大语言模型（Claude 或 OpenAI）\n- **通信**：HTTP REST、WebSocket\n\n## 主导 AI **智能体编码**\n> 并为软件工程的未来做好准备\n\n学习战术智能体编码模式，尽在 [战术智能体编码](https:\u002F\u002Fagenticengineer.com\u002Ftactical-agentic-coding?y=opsorch)\n\n关注 [IndyDevDan YouTube 频道](https:\u002F\u002Fwww.youtube.com\u002F@indydevdan)，不断提升您的智能体编码优势。","# Claude Code 多智能体可观测系统 · 快速上手指南\n\n## 环境准备\n\n| 组件 | 版本要求 | 安装命令（国内镜像） |\n|---|---|---|\n| Claude Code | 最新版 | `npm install -g @anthropic-ai\u002Fclaude-code` |\n| uv | ≥0.2 | `curl -LsSf https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.sh | sh` |\n| Bun | ≥1.1 | `curl -fsSL https:\u002F\u002Fbun.sh\u002Finstall | bash` |\n| just（可选） | ≥1.25 | `cargo install just` |\n\n> 国内用户可把 `https:\u002F\u002Fbun.sh\u002Finstall` 换成 `https:\u002F\u002Fmirrors.tuna.tsinghua.edu.cn\u002Fbun\u002Finstall.sh`\n\n**环境变量**\n```bash\nexport ANTHROPIC_API_KEY=\"sk-ant-xxx\"\n# 可选\nexport OPENAI_API_KEY=\"sk-xxx\"\nexport ELEVENLABS_API_KEY=\"xxx\"\nexport FIRECRAWL_API_KEY=\"xxx\"\n```\n\n## 安装步骤\n\n1. 克隆仓库\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fdisler\u002Fclaude-code-hooks-multi-agent-observability.git\ncd claude-code-hooks-multi-agent-observability\n```\n\n2. 一键安装依赖\n```bash\njust install        # 或手动：\n# cd apps\u002Fserver && bun install\n# cd apps\u002Fclient && bun install\n```\n\n3. 启动系统\n```bash\njust start          # 或 .\u002Fscripts\u002Fstart-system.sh\n```\n\n4. 浏览器打开 http:\u002F\u002Flocalhost:5173\n\n## 基本使用\n\n### 1. 体验演示\n```bash\n# 在任意目录启动 Claude Code\nclaude\n\n# 在 Claude 里执行\nRun git ls-files to understand the codebase.\n```\n浏览器会实时滚动显示事件。\n\n### 2. 接入自己的项目\n```bash\n# 复制钩子目录\ncp -R .claude \u002Fpath\u002Fto\u002Fyour\u002Fproject\u002F\n\n# 修改项目名\nsed -i 's\u002FYOUR_PROJECT_NAME\u002Fmy-app\u002Fg' \u002Fpath\u002Fto\u002Fyour\u002Fproject\u002F.claude\u002Fsettings.json\n```\n\n### 3. 常用命令\n```bash\njust open           # 打开仪表盘\njust test-event     # 发送测试事件\njust db-reset       # 清空数据\njust stop           # 停止服务\n```\n\n完成！现在所有 Claude Code 操作都会实时出现在仪表盘。","一家 6 人规模的初创公司正在用 Claude Code 的多 Agent 方案重构他们的 Node.js 微服务：一个 Agent 负责 API 文档生成、一个负责单元测试补全、一个负责依赖升级，三个 Agent 并行跑在 CI 里。\n\n### 没有 claude-code-hooks-multi-agent-observability 时\n- 每次 CI 跑完只能看到最终成功\u002F失败，不知道哪个 Agent 在哪一步卡住，得手动翻几千行日志  \n- 三个 Agent 同时写文件，偶尔互相覆盖，定位冲突要像侦探一样比对 Git diff 和本地缓存  \n- 测试 Agent 在 CI 里偷偷调了 17 次 `npm test`，本地复现不了，只能盲猜环境差异  \n- 老板问“昨晚那次失败的构建到底花了多少 Token”，只能耸肩——Anthropic 账单里只有总量，没有分 Agent 明细  \n- 新人加入后，没人能讲清楚“Agent 之间到底是怎么交接任务的”，知识全靠口口相传  \n\n### 使用 claude-code-hooks-multi-agent-observability 后\n- 打开实时仪表盘，一眼就能看到“文档 Agent 在 03:12:45 停在了 `PreToolUse:write_markdown`”，直接点进事件详情，发现是文件锁未释放  \n- 事件流里高亮显示“测试 Agent 与升级 Agent 同时改动了 package.json”，时间戳精确到毫秒，冲突根因 30 秒锁定  \n- 每条 `PostToolUse` 事件自动带上 exit code 与耗时，CI 日志里那 17 次 `npm test` 被折叠成一条可展开的调用链，本地复现命令一键复制  \n- 仪表盘右上角直接给出“昨晚 02:00–04:00 期间，测试 Agent 消耗 142 k tokens，升级 Agent 89 k tokens”，成本一目了然  \n- 新人第一天就能在浏览器里拖拽时间轴，看 Agent 如何依次触发、如何回滚，交接逻辑变成可视化故事  \n\nclaude-code-hooks-multi-agent-observability 把原本黑盒的多 Agent 协作变成了可观测、可复盘、可量化的流水线。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdisler_claude-code-hooks-multi-agent-observability_c64fa830.png","disler","IndyDevDan","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fdisler_796943fa.png","Betting the next 10 years of my career on AGENTIC software.\r\n\r\nJoin the journey on YT.",null,"https:\u002F\u002Fgithub.com\u002Fdisler",[82,86,90,94,98,102,106,110],{"name":83,"color":84,"percentage":85},"Python","#3572A5",38.8,{"name":87,"color":88,"percentage":89},"Vue","#41b883",28.7,{"name":91,"color":92,"percentage":93},"TypeScript","#3178c6",25.2,{"name":95,"color":96,"percentage":97},"CSS","#663399",3.9,{"name":99,"color":100,"percentage":101},"Shell","#89e051",1.5,{"name":103,"color":104,"percentage":105},"Just","#384d54",0.9,{"name":107,"color":108,"percentage":109},"JavaScript","#f1e05a",0.8,{"name":111,"color":112,"percentage":113},"HTML","#e34c26",0.1,1339,361,"2026-04-05T16:58:07",4,"Linux, macOS, Windows","未说明",{"notes":121,"python":119,"dependencies":122},"需要安装 Claude Code CLI、Astral uv（Python 包管理器）、Bun\u002Fnpm\u002Fyarn（Node 运行时）、just（可选命令运行器），并配置 ANTHROPIC_API_KEY 环境变量；可选 OpenAI、ElevenLabs、Firecrawl API Key",[123,124,125,126,127],"uv","bun","npm","yarn","just",[15,13,53],"2026-03-27T02:49:30.150509","2026-04-06T08:18:32.871722",[132,137,142,147,152],{"id":133,"question_zh":134,"answer_zh":135,"source_url":136},6274,"如何查看多智能体系统的整体 Token 消耗？","目前系统尚未实现整体 Token 仪表盘，但已规划在 Issue #25 中实现：\n1. 将新增「当前会话总计」显示输入\u002F输出\u002F缓存 Token 数\n2. 提供「每日总计」与「滚动 7\u002F30 天趋势」\n3. 支持进度条显示配额使用情况（若已知配额）\n4. 根据模型定价估算美元成本\n实现依赖 Issue #23 的 Token 基础设施完成后即可上线。","https:\u002F\u002Fgithub.com\u002Fdisler\u002Fclaude-code-hooks-multi-agent-observability\u002Fissues\u002F25",{"id":138,"question_zh":139,"answer_zh":140,"source_url":141},6275,"如何按智能体查看各自的 Token 用量？","Issue #26 已规划在 AgentSwimLane 头部新增 Token 用量徽章：\n1. 会话级 Token 总数（输入+输出）实时显示\n2. 点击可展开查看输入\u002F输出\u002F缓存细分\n3. 会话结束时展示最终统计\n4. 多智能体并列时可横向对比用量\n5. 同时显示上下文窗口占用百分比，避免超限\n该功能同样依赖 Issue #23 的 Token 基础设施。","https:\u002F\u002Fgithub.com\u002Fdisler\u002Fclaude-code-hooks-multi-agent-observability\u002Fissues\u002F26",{"id":143,"question_zh":144,"answer_zh":145,"source_url":146},6276,"如何追踪智能体之间的父子层级关系？","Issue #24 提供了层级追踪方案：\n1. 监听 `PreToolUse` 事件，当 `tool_name=\"Task\"` 时标记子智能体创建\n2. 记录 `parent_session_id`、`spawned_at`、`spawn_context` 等字段\n3. 通过 `SubagentStop` 事件记录完成时间 `completed_at`\n4. 后端存储完整的树形结构，支持 API 查询任意会话的完整层级\n5. 解决 Hook 事件不含显式 parent_id 的问题，通过时间关联推断\n实现后可在前端渲染 3 面板层级视图（Issue #27）。","https:\u002F\u002Fgithub.com\u002Fdisler\u002Fclaude-code-hooks-multi-agent-observability\u002Fissues\u002F24",{"id":148,"question_zh":149,"answer_zh":150,"source_url":151},6277,"Token 数据从哪里来？需要哪些基础设施？","Issue #23 说明了 Token 基础设施的关键点：\n1. 数据源：Claude Code Hook 事件中的 `transcript_path` 指向 JSONL 文件，内含每条消息的 `input_tokens \u002F output_tokens \u002F cache_read_tokens \u002F cache_creation_tokens`\n2. 扩展数据模型：HookEvent 与数据库表需新增 Token 相关字段\n3. 聚合存储：按会话预聚合统计，便于前端高效查询\n4. 新增 API：暴露 `\u002Fsessions\u002F{id}\u002Ftokens` 等端点给前端仪表盘\n5. 支持不同模型的差异化定价与组织配额限制","https:\u002F\u002Fgithub.com\u002Fdisler\u002Fclaude-code-hooks-multi-agent-observability\u002Fissues\u002F23",{"id":153,"question_zh":154,"answer_zh":155,"source_url":156},6278,"如何可视化多智能体的层级与通信流？","Issue #27 设计了 3 面板层级视图：\n- 左面板：树形展示所有子智能体及其工具（Agent 1 → Tool A\u002FB…）\n- 中间面板：时序化消息流，显示 Orchestrator→Agent1→ToolA→Agent1 的完整链路\n- 右面板：根智能体总览（状态、Token、子智能体数、上下文占用）\n布局采用响应式三栏，顶部保留全局控制条。实现依赖 Issue #24 的层级追踪后端数据。","https:\u002F\u002Fgithub.com\u002Fdisler\u002Fclaude-code-hooks-multi-agent-observability\u002Fissues\u002F27",[]]