cxdb-observability

cxdb Claude Code Observability Plugin

Records every Claude Code session as structured turns in cxdb — a turn-DAG context store for AI agent trajectories. Browse full session histories, tool calls, token usage, and reasoning in the cxdb UI.

Requirements

• Claude Code (any recent version)
• bash, curl, jq, python3 (standard on macOS and most Linux)
• A running cxdb instance (local Docker or shared Tailscale instance)

Quick Start

1. Start cxdb

In the cxdb repo:

make dev-docker-up

Starts cxdb in Docker. Frontend at http://localhost:9080 · API at http://localhost:9010

2. Install the plugin

git clone https://github.com/prime-radiant-inc/claude-plugin-cxdb-integration
cd claude-plugin-cxdb-integration
make install

3. Start a new Claude Code session

Sessions started after installation are recorded automatically. Open http://localhost:9080 to watch them appear in real time.

How It Works

Seven Claude Code hooks record the full session lifecycle:

Hook	cxdb item_type	Notes
SessionStart	system (info)	Creates context, publishes type bundle, writes ContextMetadata + Provenance
UserPromptSubmit	user_input	Captures user message text (async)
PostToolUse	(buffered)	Buffers tool call + result to session state — no cxdb write yet
Stop	assistant_turn	Flushes buffered tool calls; parses transcript for text + token metrics
SubagentStop	handoff	Records agent-to-agent handoffs for Task tool calls
PreCompact	system (warning)	Notes when context window compaction occurs (async)
Notification	system (info)	Records Claude Code notifications (async)

Tool call results are captured per tool type — each tool's response has a different structure:

Tool	Content captured
Bash	stdout (+ stderr if non-empty)
Read	File contents (capped at 4000 chars)
Glob	Matched file paths
Grep	Matched file paths or content lines
Edit	"Edited <filepath>"
Task	Subagent's final text output (capped at 4000 chars)
WebFetch / WebSearch	Generic fallback

All cxdb writes are fire-and-forget — if cxdb is unreachable, your Claude Code session continues normally.

Configuration

Pointing at a different cxdb instance

Create ~/.claude/cxdb-observability.local.md with YAML frontmatter:

url: http://cxdb.your-tailnet.ts.net:9010

Or set the CXDB_URL environment variable before starting Claude Code.

URL resolution order:

1. $CXDB_URL environment variable
2. url: field in ~/.claude/cxdb-observability.local.md
3. http://localhost:9010 (default)

What Gets Recorded

Each session produces a chain of cxdb.ConversationItem turns:

system (info)        ← Session Started, with ContextMetadata + Provenance
  user_input         ← "Write a function that..."
    assistant_turn   ← Text + tool calls (Bash, Read, Edit, ...) + token metrics
      user_input     ← "looks good, now add tests"
        assistant_turn
          ...

Provenance fields captured per session:

• Git user name + email
• Hostname, architecture, OS user
• Session ID, working directory, permission mode
• Parent/root context IDs for subagent lineage

Install / Uninstall

make install      # registers plugin in ~/.claude/plugins/installed_plugins.json
make uninstall    # removes it

License

Apache 2.0 — see LICENSE.