Observability

PopKit includes observability hooks for capturing event metadata from Claude Code sessions. The public docs currently cover the hook behavior and optional cloud delivery path; hosted dashboard access is deferred until the hosted product surface is verified.

Dashboard

Hosted dashboard setup is not part of the current public launch surface. If you run a private PopKit Cloud deployment, configure its dashboard and API endpoint from that deployment’s operator docs.

The dashboard shows:

• Activity Feed: Real-time stream of events (tool calls, agent starts/ends, errors)
• Active Agents: Which agents are currently working
• Tool Usage: Most frequently used tools
• Session Stats: Today’s totals for events, agent starts, and errors

How It Works

1. Claude Code fires hook events (PreToolUse, PostToolUse, etc.)
2. The agent-observability.py hook captures these events
3. Events are sent to PopKit Cloud API
4. Dashboard receives events via SSE (Pro) or polling (Free)

Claude Code → Hook → PopKit Cloud API → Dashboard
                          ↓
                    Redis Stream

Setup

1. Get Your API Key

/popkit-core:account login

If you do not have a PopKit Cloud account or deployment, skip cloud delivery and use the local setup paths.

2. Set Environment Variable

Add to your shell profile (.bashrc, .zshrc, etc.):

export POPKIT_API_KEY=pk_live_your_key_here

3. Register the Hook

The observability hook is included in popkit-core. If you’ve installed PopKit, it’s already available.

To verify it’s active:

/popkit-core:plugin status

Event Types

Event	Description
agent_start	An agent was spawned
agent_end	An agent completed
tool_call	A tool was invoked
tool_result	A tool returned a result
error	An error occurred
workflow_phase	A workflow phase changed

Pro vs Free

Feature	Free	Pro
Event capture	Yes	Yes
Dashboard access	Yes	Yes
Update method	Polling (3s)	SSE streaming
Event history	Last 50	Last 1000
Stats retention	Today only	7 days

Troubleshooting

Events Not Appearing

1. Check API key is set:

   echo $POPKIT_API_KEY

2. Check hook is registered:

   claude hooks list

3. Test manually:

   echo '{"tool_name":"Read","tool_input":{}}' | python agent-observability.py

Connection Issues

The hook is designed to fail silently - it won’t block your Claude Code session if the API is unreachable. Check the dashboard connection status indicator:

• 🟢 Live (SSE) - Real-time streaming active (Pro)
• 🔵 Polling (3s) - Polling mode active (Free)
• 🟡 Connecting - Establishing connection
• 🔴 Error - Connection failed

Privacy

Events are scoped to your user account. We capture:

• Tool names and execution times
• Agent types and session IDs
• Error status (not error messages)

We do NOT capture:

• Tool inputs/outputs
• File contents
• Conversation history
• Personal data

See our Privacy Policy for details.