Observability

PopKit includes hooks for capturing event metadata from Claude Code sessions. The current public launch documents local hook behavior and optional private cloud delivery. It does not include a hosted public dashboard, public signup flow, pricing page, or multi-tenant SaaS surface.

Current Surface

PopKit can capture local metadata for:

Tool calls and results
Agent starts and completions
Error status
Workflow phase changes

The agent-observability.py hook is designed to fail closed for the host session: if cloud delivery is unavailable, the coding session continues.

Optional Private Cloud Delivery

If you operate a private PopKit Cloud deployment, set both values before enabling remote delivery:

export POPKIT_API_URL="https://your-popkit-cloud.example.com"
export POPKIT_API_KEY="pk_live_your_key_here"

Without both variables, the hook stays local-only and does not attempt to send telemetry to a hosted service.

Claude Code -> Hook -> optional private PopKit Cloud API

Dashboard setup, account management, pricing, and hosted observability are intentionally deferred until the hosted product surface is verified.

Register The Hook

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

To verify PopKit hooks are installed:

/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

Troubleshooting

Events Do Not Reach A Private Deployment

Check that both environment variables are set:
Terminal window
```
echo $POPKIT_API_URL
echo $POPKIT_API_KEY
```
Check that the hook is registered:
Terminal window
```
claude hooks list
```

Test manually from the hook directory:

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

Privacy

The hook is intended to capture metadata, not code or chat content. It captures:

Tool names and execution timing
Agent types and session IDs
Error status

It should not capture:

Tool inputs or outputs
File contents
Conversation history
Personal data