Claude Code Integration¶

Pisama captures and analyzes traces from Claude Code CLI sessions, detecting failure modes in Claude's tool-use patterns.

Overview¶

The Claude Code integration captures every tool call (Bash, Read, Edit, Write, Grep, etc.) as a span, enabling Pisama to detect:

• Infinite loops: Agent repeating the same tool calls without progress
• Task derailment: Agent going off-topic from the assigned task
• Context overflow: Token accumulation approaching model limits
• Cost tracking: Token usage and estimated costs per session
• Hallucination: Code suggestions that don't match the codebase

Installation¶

Install the Pisama Claude Code package:

pip install pisama-claude-code

Optional extras:

pip install "pisama-claude-code[proxy]"   # to also capture reasoning

Install the hooks into your Claude Code setup:

pisama-cc install

This installs Pisama hooks to ~/.claude/hooks/ (a PostToolUse capture hook and a Stop forward hook) and enables them in settings.local.json. Run pisama-cc verify to confirm. macOS and Linux are supported (the hooks are bash wrappers).

CLI Commands¶

Features by Mode¶

Privacy & forwarding¶

• Forwarding is opt-in. pisama-cc connect defaults to no auto-sync. Nothing leaves your machine until you run pisama-cc sync or reconnect with --auto-sync to forward every session on Stop.
• Secrets are scrubbed by default. A built-in redactor removes credential-shaped strings (API keys, JWTs, cloud tokens) from captured content before forwarding — no extras required. The [core] extra adds a reversible keychain tokenization vault on top.
• What's captured (full content): user prompt, AI output, tool input/output, model, token usage and cost. Extended-thinking reasoning is not in the transcript and requires the reasoning proxy below.

Reasoning capture (experimental)¶

Claude Code strips extended-thinking text before it touches disk, so the hooks can't see it. pisama-cc proxy runs a local logging proxy in front of the Anthropic API (ANTHROPIC_BASE_URL) and reassembles the full turn — including reasoning — from the live response stream.

pip install "pisama-claude-code[proxy]"
pisama-cc proxy serve                              # terminal 1
ANTHROPIC_BASE_URL=http://127.0.0.1:8788 claude    # terminal 2

Always-on (auto-started via launchd on macOS): pisama-cc proxy install --always-on.

:::warning Subscription users The proxy defaults to API-key usage. If you run Claude Code on a Pro/Max subscription, it handles your account OAuth token, which is Terms-of-Service sensitive. Use the proxy only if you understand and accept that. :::

The pisama-diagnose skill¶

pisama-cc install also drops a /pisama-diagnose skill into ~/.claude/skills (and ~/.codex/skills). Ask Claude to use it on a failing run to get a root-cause diagnosis; with a connected key it renders a ready-to-paste CLAUDE.md/.cursorrules guardrail and can auto-apply a fix to a live n8n workflow.

Trace Ingestion Endpoint¶

For direct API integration, use the Claude Code ingestion endpoint:

curl -X POST http://localhost:8000/api/v1/traces/claude-code/ingest \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "2026-03-11T10:00:00Z",
    "tool_name": "Bash",
    "hook_type": "post_tool",
    "session_id": "session-abc-123",
    "tool_input": {"command": "pytest tests/"},
    "tool_output": "5 passed, 0 failed",
    "working_dir": "/home/user/project",
    "trace_type": "tool_call",
    "model": "claude-sonnet-4",
    "tokens_in": 1500,
    "tokens_out": 800,
    "cost_usd": 0.012
  }'

Span Data Captured¶

Each tool call generates a span containing:

Package Architecture¶

┌─────────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│  pisama-claude-code │  │   pisama-core   │  │  pisama-skills  │
│      (PyPI)         │  │     (PyPI)      │  │   (Optional)    │
│                     │  │                 │  │                 │
│  - CLI (pisama-cc)  │  │  - Span format  │  │  - /diagnose    │
│  - Hook installer   │  │  - Storage      │  │  - /fix         │
│  - Local detection  │  │  - Detectors    │  │  - /config      │
│  - Cloud sync       │  │  - Converters   │  │  - /guardian    │
└─────────────────────┘  └─────────────────┘  └─────────────────┘
         │                       │                     │
         └───────────────────────┼─────────────────────┘
                                 ▼
         ┌──────────────────────────────────────────┐
         │           Pisama Platform                 │
         │  Dashboard - Analytics - Alerts - Fixes  │
         └──────────────────────────────────────────┘