goccc: Instructions file for Claude Code

goccc

CLI tool that parses Claude Code JSONL logs from ~/.claude/projects/ and calculates API usage costs by model, day, project, and branch.

Stack

Go 1.26, stdlib only (zero external deps), GoReleaser for cross-platform builds

Commands

go build -o goccc .          # Build binary
go test ./...                # Run all tests
go vet ./...                 # Static analysis
go run . -days 7 -all        # Dev: run with flags directly

Verification

Run before every commit:

make check

JSONL Log Format

Claude Code stores logs at ~/.claude/projects/<project-slug>/. Sessions are <uuid>.jsonl with subagents in <uuid>/subagents/agent-<id>.jsonl. Workflow-spawned agents nest deeper, under <uuid>/subagents/workflows/wf_*/agent-<id>.jsonl.

• Only type: "assistant" entries carry message.model and message.usage — skip all others
• output_tokens already includes thinking tokens — no separate counter
• cache_creation sub-object breaks down 5m/1h tiers; cache_creation_input_tokens is the flat total (fallback for older logs)
• One API call produces multiple entries sharing the same requestId — dedup by keeping the last entry seen (file order, no output_tokens comparison)
• model: "<synthetic>" + isApiErrorMessage: true are rate-limit placeholders — filter out to avoid inflating counts

Conventions

• Flat package — all code in package main, one concern per file
• Externalized pricing — all pricing lives in pricing.json (embedded via //go:embed, remote-cached 6h; a log naming a Claude model or fast tier the table lacks refetches early). The fetch runs as a detached goccc -refresh-pricing process so nothing waits on the network; a .attempt stamp written before it throttles every fetch, failed ones included, to once per 15m. Adding a model or adjusting pricing = edit pricing.json only, no code changes. Cache fields are optional — fillCacheDefaults() derives from input price (0.1x read); Fable 5.1 / Mythos 5.1 read cache at 0.025x, so their cache_read is set explicitly. Fast mode pricing lives in fast_models map — same structure as models, resolved when usage.speed == "fast"
• Pricing resolution — exact model ID → longest family prefix → defaultPricing. A Vertex @date stamp is dropped first. Version-first legacy IDs (claude-3-5-haiku-…) reach their modern-style keys through claude-3-* family prefixes
• Display names — shortModel() derives them from the model ID (claude-opus-5-5-20260101 → "Opus 5.5"), so new models need no entry. display_names in pricing.json is only read by releases before this change; keep it for them, don't extend it
• Time-based pricing — a model's base price applies from the beginning of time; an optional schedule: [{ "from": "YYYY-MM-DD", ...prices }] adds dated overrides, and cost uses the entry with the greatest from ≤ the message timestamp. An entry is a diff over the base: omitted primaries (input/output, long-ctx) inherit the base — so a base bump keeps the long-context tier — but omitted cache tiers re-derive from the entry's own input, not the base's cache. from is midnight UTC, a billing boundary independent of the -utc display flag
• Billing modifiers from usage — inference_geo == "us" multiplies token cost by inference_geo_multipliers from pricing.json (1.1x; searches excluded). usage.iterations is folded by foldIterations() in the parser: each counter becomes the max of the top level and the sum across iterations, so a top level that only reports the last pass can't undercount. service_tier is read but not priced — Priority Tier is a capacity commitment, not a per-token rate
• Fast mode bucketing — parser appends :fast suffix to model key when speed == "fast", creating separate buckets. shortModel() and resolvePricing() strip the suffix for display/lookup. The statusline's model.id may also carry a context alias (claude-opus-5[1m]) — shortModel() strips it and never shows it
• Local timezone everywhere — day bucketing/cutoffs use parseLocation (defaults to time.Local). Never UTC() for user-facing dates. The -utc flag is the one sanctioned opt-in: it sets parseLocation = time.UTC to match Anthropic API reporting
• MCP detection is best-effort — returns nil/empty on error; statusline never fails due to missing config
• Config — ~/.goccc.json stores currency, thresholds, and statusline config. initConfig() loads once. JSON output costs always in USD
• Session end hook — writes to /dev/tty (bypasses Claude Code's stderr capture), falls back to stderr on Windows. Silently exits on any error
• Statusline segments — registry in statusline_config.go. Segments with no data auto-hide. "|" forces line break
• Powerline & pet — powerline.go reads the plain style's red/yellow value colors: by default (alert_style: "block") the whole block takes the warn/alert color, with "text" just the value does, and "none" drops them. pet.go reads per-session state written by the -pet-state hook into the user cache dir (goccc/sessions/, never shared /tmp), which -session-end removes and a new session sweeps after 24h. Interrupts fire no hook, so the transcript tail is checked for Claude Code's interrupt text block