Summary

This project addresses the critical need for real-time observability in Claude Code's autonomous and multi-agent sessions, which are often opaque. It provides engineers and researchers with a powerful dashboard to visualize, filter, and debug complex agent interactions, tool calls, and file operations as they happen. The primary benefit is gaining deep, actionable insights into agent behavior, significantly improving development and troubleshooting workflows for autonomous AI systems.

How It Works

The system captures agent activity using custom "hooks" that intercept raw event data from Claude Code sessions. These hooks act as a data pipe, forwarding events via HTTP POST requests to a local server. The server processes these events, extracts structural information, stores agent metadata and session data in an SQLite database, and streams live updates to a React-based dashboard using WebSockets. This architecture provides a granular, real-time view of agent actions, tool calls, and hierarchical relationships, offering a more complete picture than traditional logging.

Quick Start & Requirements

Installation is primarily achieved via a Claude Code plugin (claude plugin marketplace add simple10/agents-observe followed by claude plugin install agents-observe and a Claude Code restart). Prerequisites include Docker (required for the server) and Node.js (for hook scripts). Standalone installation involves cloning the repository, running just install for dependencies, and just start for Docker. Configuration requires generating project-specific hooks using just setup-hooks my-project and adding the output to .claude/settings.json. The dashboard is accessible at http://localhost:4981.

Highlighted Details

• Real-time streaming of agent actions, including detailed PreToolUse and PostToolUse events with full payloads.
• Visualization of the complete agent hierarchy, clearly showing parent-child relationships between subagents.
• Powerful filtering and search capabilities across all captured events, enabling precise data retrieval.
• Detailed inspection of command outputs, file operations, and tool call arguments for in-depth analysis.
• Ability to browse historical sessions with human-readable names and analyze agent behavior patterns over time.

Maintenance & Community

The project roadmap includes adding support for Codex, OpenClaw, and pi-code agents. Related projects like "Agent Super Spy" and "Multi-Agent Observability System" are mentioned. No specific community links (Discord, Slack) or direct contributor information are detailed in the README.

Licensing & Compatibility

The project is released under the MIT license. This license is permissive and generally allows for commercial use, modification, and distribution, including integration within closed-source applications.

Limitations & Caveats

The system mandates Docker for server execution and Node.js for hook scripts. Plugin installation requires restarting the Claude Code environment. Potential setup blockers include ensuring the Docker daemon is running and avoiding port conflicts. While the MIT license is permissive, users must correctly configure the hooks for effective event capture. Support for agent frameworks beyond Claude Code is planned for future releases.