Documentation
¶
Overview ¶
Package claudecode implements the event-level adapter for the Claude Code CLI. It reads append-only JSONL transcripts under each config root's projects/ tree, maps Anthropic-style usage (cache tokens additive), and deduplicates message replays (including sidechain replays) within a cycle.
CRITICAL: strictly read-only. Files are opened O_RDONLY; nothing under the agent's directories is created, locked, or modified.
Index ¶
- Constants
- func New() adapter.Adapter
- type Adapter
- func (Adapter) Capabilities() model.ToolCapability
- func (a Adapter) Collect(ctx context.Context, src adapter.Source) (adapter.Observation, error)
- func (a Adapter) CollectIncremental(ctx context.Context, src adapter.Source, cp *model.SourceCheckpoint) (adapter.Observation, error)
- func (a Adapter) Discover(ctx context.Context, cfg adapter.DiscoverConfig) ([]adapter.Source, error)
- func (Adapter) DisplayName() string
- func (Adapter) ID() string
Constants ¶
const ConfigDirEnv = "CLAUDE_CONFIG_DIR"
ConfigDirEnv names the environment variable that moves the Claude Code configuration root, and with it every transcript this adapter reads. It is exported because a caller that copies this process's discovery into another one - the systemd units internal/service writes - has to know that the environment, not the defaults, decided what gets collected.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Adapter ¶
type Adapter struct{}
Adapter reads Claude Code usage transcripts.
func (Adapter) Capabilities ¶
func (Adapter) Capabilities() model.ToolCapability
Capabilities declares what this project can say about Claude Code.
Cost is COMPUTED: nothing here calls SetCost, so every row is valued from the public rate card by collect.stampCost or left unpriced. Activity is an EXACT join because a tool_use block and the .message.usage it was billed under sit in the SAME message, so mintActivity can name the usage row that paid for each call.
func (Adapter) Collect ¶
Collect walks <root>/projects/**/*.jsonl, parses every usage line, applies in-cycle dedup, and returns the surviving events with any per-file errors. A bad transcript does not discard observations from readable files.
func (Adapter) CollectIncremental ¶
func (a Adapter) CollectIncremental(ctx context.Context, src adapter.Source, cp *model.SourceCheckpoint) (adapter.Observation, error)
CollectIncremental gates the whole root on a per-file size+mtime manifest: when no transcript under projects/ changed, the walk is stats only and no file is opened. Any change re-parses EVERY file — the deduper's sidechain consolidation spans all files of a root in one pass, so per-file tail reads would break cross-file dedup. Correctness of the full re-parse is carried by the persisted dedup keys (INSERT OR IGNORE collapses re-derived events).
func (Adapter) Discover ¶
func (a Adapter) Discover(ctx context.Context, cfg adapter.DiscoverConfig) ([]adapter.Source, error)
Discover locates Claude Code config roots that contain a projects/ tree.
Resolution order:
- An explicit override (DiscoverConfig.Overrides[claude-code]), normalised.
- env CLAUDE_CONFIG_DIR (comma list), each entry normalised.
- BOTH <home>/.config/claude and <home>/.claude.
A path ending in /projects is normalised to its parent. A root is accepted only if <root>/projects/ exists as a directory. Results are path-deduped.
func (Adapter) DisplayName ¶
DisplayName returns the human-friendly name.
Source Files