claudecode

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.

Functions

func New

func New() adapter.Adapter

New returns a Claude Code adapter with an in-memory per-file parse cache. Keep the adapter or its registry across passes to reuse unchanged files.

Types

type Adapter

type Adapter struct {
	// contains filtered or unexported fields
}

Adapter reads Claude Code usage transcripts. The zero value is usable; New also retains parsed files between passes.

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

func (a Adapter) Collect(ctx context.Context, src adapter.Source) (adapter.Observation, error)

Collect returns a full root observation, reusing cached parses when available and applying in-cycle dedup, 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 skips unchanged roots using a size+mtime manifest. On a changed pass, adapters created by New parse only changed files and deduplicate fresh and cached candidates across the whole root. A cold cache reads all files. Workflow journals under subagents/workflows carry no usage and are excluded. Persisted event identities keep replayed observations idempotent.

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:

1. An explicit override (DiscoverConfig.Overrides[claude-code]), normalised.
2. env CLAUDE_CONFIG_DIR (comma list), each entry normalised.
3. 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

func (Adapter) DisplayName() string

DisplayName returns the human-friendly name.

func (Adapter) ID

func (Adapter) ID() string

ID returns the stable tool identifier.