agent-lens

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

Start the Dashboard

```bash

# 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

Events are stored in JSONL (JSON Lines) format:

```

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

```

Each line is a complete JSON object:

```jsonl

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

```

Environment Variables

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

```bash

export 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.

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

```

Claude 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.

Inspired by [@indydevdan](https://github.com/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.