claude-code-logfire-plugin: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

A Claude Code plugin that captures sessions and exports pydantic-ai compatible OTel traces to Pydantic Logfire, with local JSONL fallback. The plugin is a single Python 3 script (stdlib only, no external dependencies).

Architecture

The entire plugin is a single Python script (scripts/log-event.py) invoked by every hook event defined in hooks/hooks.json. The plugin manifest lives at .claude-plugin/plugin.json.

Data flow: Claude Code hook fires -> stdin JSON piped to log-event.py -> appends JSONL locally -> if LOGFIRE_TOKEN set and event is SessionStart/Stop/SubagentStop/SessionEnd, builds OTLP/HTTP JSON payload and sends via urllib.

Session state: A temp file ($TMPDIR/claude-logfire-{session_id}.json) persists the root span ID, start time, transcript line offset, accumulated messages, usage totals, and cost details between hook invocations. Created on SessionStart, deleted on SessionEnd.

Trace correlation: trace_id is deterministically derived from session_id via SHA-256.

Span hierarchy (pydantic-ai style):

agent run (root span)              <- the session (emitted on SessionEnd)
├── chat claude-opus-4-6           <- LLM API call 1 (emitted on Stop)
├── chat claude-opus-4-6           <- LLM API call 2 (emitted on Stop)
└── chat claude-opus-4-6           <- LLM API call 3 (emitted on Stop)

OTLP processing model:

Hook Event	JSONL	OTLP
SessionStart	yes	pending root span (logfire.span_type=pending_span)
Stop / SubagentStop	yes	"chat {model}" child spans per LLM API call
SessionEnd	yes	finalized root "agent run" span with all_messages, usage, cost
All other events	yes	none (early exit)

Transcript parsing: On Stop events, the script reads new transcript lines (since last offset), deduplicates streaming fragments by message.id, identifies API call boundaries, and converts messages to pydantic-ai format (tool_use -> tool_call, tool_result -> tool_call_response, end_turn -> stop).