---

name: agent-lens aliases: [agent-lens] context: fork model: haiku description: | Agent Lens: Real-time observability dashboard for multi-agent Claude Code sessions.

Visualize agent interactions, tool usage, and session flows through a modern dual-pane interface. Track parent-child event relationships with hierarchical timeline visualization, HITL approvals, and comprehensive metrics.

Key Features:

• 👁️ Dual-pane layout (process timeline + results/metrics)
• 🌳 Span hierarchy visualization with parent-child relationships
• 🔴 Real-time event streaming via WebSocket
• 🤖 HITL interface with timeout indicators and three-action pattern
• 📊 Token usage, cost tracking, and performance metrics
• 🎨 OLED-optimized dark theme (2026 standards)
• 💾 Filesystem-based (no database required)

Version 2.0

Agent Lens

Real-time observability dashboard for multi-agent Claude Code sessions.

Features

Dual-Pane Interface

• Process Timeline - Hierarchical view of events with parent-child relationships
• Results & Metrics - Session statistics, event details, and performance data
• Resizable panes - Drag to adjust layout (25%-60% width)

Event Visualization

• Hierarchical timeline - Nested events show tool call relationships
• Collapse/expand - Show/hide child events
• Event icons - Visual indicators for tool types
• Session cards - Track individual sessions and lifecycle

Metrics & Monitoring

• Token tracking - Estimate usage per session
• Cost calculation - Track AI model costs (2026 pricing)
• Tool usage breakdown - Most frequently used tools
• Performance metrics - Latency, duration, error rates
• Context tracking - Monitor context window usage (CC 2.1.6)

HITL (Human-in-the-Loop)

• Approval interface - Review and approve/reject requests
• Timeout indicators - Visual countdown for time-sensitive actions
• Three-action pattern - Approve, Edit, or Reject
• Browser notifications - Alert on urgent requests

Event Types Captured

• SessionStart - New Claude Code session begins
• UserPromptSubmit - User sends a message
• PreToolUse - Before tool execution
• PostToolUse - After tool completion
• Stop - Main agent task completes
• SubagentStop - Subagent task completes
• SessionEnd - Session ends

Quick Start

Start the Dashboard

Copy# Terminal 1: Start server
cd ~/.claude/skills/agent-lens/apps/server
bun run dev

# Terminal 2: Start client
cd ~/.claude/skills/agent-lens/apps/client
bun run dev

# Or use the project convenience script:
cd /path/to/qara
bun run start-obs

Open browser: http://localhost:5173

Using with Claude Code

Once the dashboard is running:

1. Open Claude Code
2. Use any tool (Read, Write, Bash, etc.)
3. Launch subagents with Task tool
4. Watch events appear in real-time on the dashboard

Data Storage

Events are stored in JSONL (JSON Lines) format:

Copy~/.claude/history/raw-outputs/YYYY-MM/YYYY-MM-DD_all-events.jsonl

Each line is a complete JSON object:

Copy{"source_app":"qara","session_id":"abc123","hook_event_type":"PreToolUse","payload":{...},"timestamp":1234567890,"timestamp_aedt":"2025-01-28 14:30:00 AEDT"}

Configuration

Environment Variables

PAI_DIR - Path to PAI directory (defaults to ~/.claude/)

Copyexport PAI_DIR="/Users/yourname/.claude"

Session Tracking (CC 2.1.9+)

Agent Lens automatically tracks sessions using Claude Code's native session IDs:

• Current session: ${CLAUDE_SESSION_ID}
• Events file: ~/.claude/history/raw-outputs/YYYY-MM/YYYY-MM-DD_all-events.jsonl
• Session state: ~/.claude/state/agent-lens/sessions/${CLAUDE_SESSION_ID}.json

Each event includes the session_id field for correlation across the observability dashboard.

Hooks Configuration

Hooks should be configured in ~/.claude/settings.json. The capture-all-events hook is required for Agent Lens to function.

Troubleshooting

No events appearing

1. Check PAI_DIR: echo $PAI_DIR
2. Verify hooks exist: ls ~/.claude/hooks/capture-all-events.ts
3. Check hook is executable: ls -l ~/.claude/hooks/capture-all-events.ts
4. Verify today's events file: ls ~/.claude/history/raw-outputs/$(date +%Y-%m)/

Server won't start

1. Check Bun: bun --version
2. Install dependencies: cd apps/server && bun install
3. Check port: lsof -i :4000

Client won't connect

1. Ensure server is running first
2. Check browser console for WebSocket errors
3. Verify firewall not blocking localhost:4000

Architecture

CopyClaude Code (with hooks)
    ↓
capture-all-events.ts hook → JSONL files
    ↓
file-ingest.ts (Bun server) → In-memory stream
    ↓
Vue 3 Client → Real-time dashboard

Approach: Filesystem-based event capture with in-memory streaming. No database required.

Credits

Inspired by @indydevdan's work on multi-agent observability for Claude Code.

Our implementation uses filesystem-based event capture and in-memory streaming instead of SQLite database persistence.