Usage Capture

Opt-in, local-only recorder for per-request LLM metrics. One JSONL file per Asia/Jerusalem calendar day under ~/.local/share/tamirs-superpowers/usage/. Nothing is sent to a collector in the cloud, to GitHub, or to Anthropic beyond the LLM call the user already configured.

Claude Code is captured through its native OpenTelemetry export (including a custom ANTHROPIC_BASE_URL). LiteLLM is supported as an explicitly labelled gateway; its URL and raw request IDs are never persisted. OpenCode is captured by an optional JS plugin that is not on by default. Cursor, Codex, and Gemini CLI are out of scope.

This is not /session-report. That skill post-parses Claude Code transcripts under ~/.claude/projects for token/cache rollups. This skill records live request timing, model, endpoint, and skill/command inventory. Point at session-report when the user wants historical Claude transcript spend.

Compatibility

Before enabling, confirm shell is available. The hooks capability is optional: without it, start the collector with collector.py --daemon yourself instead of relying on SessionStart.

Privacy default

Metadata only: model, Israel timestamps, duration / TTFT, tokens, skill and command names, session id, custom-endpoint label. No prompt text and no API JSON unless the user passes --bodies. Bodies are secret-bearing (conversation history, tool results, code). Say so before turning them on.

Workflow

0. Resolve the plugin / repo root

Try in order: $CLAUDE_PLUGIN_ROOT, $CLAUDE_SKILL_DIR/../../../.. (skill is skills/toolkit/usage-capture), then the current git toplevel. The collector lives at scripts/usage-capture/collector.py and the enabler at scripts/usage-capture/enable.sh.

1. Enable (Claude Code)

bash scripts/usage-capture/enable.sh

Every rewrite first saves settings.json.bak.<UTC timestamp> (0600) and reports its path.

Useful flags: --dry-run --json, --bodies, --disable, --dir DIR, --port PORT. For LiteLLM use --gateway-kind litellm --endpoint-label <opaque-label>; do not put a gateway URL in the label. The client collector sees end-to-end latency, not LiteLLM's internal retries/fallbacks or backend timing.

Then restart Claude Code so ~/.claude/settings.json env is picked up. Expect TAMIRS_USAGE_CAPTURE=1 plus OTEL pointing at http://127.0.0.1:17431 with http/json. OTEL_LOG_USER_PROMPTS stays unset. OTEL_LOG_TOOL_DETAILS=1 so skill/command names appear.

If OTEL_EXPORTER_OTLP_ENDPOINT is already set to something else, the script refuses unless --force.

2. Enable (OpenCode) — optional plugin

Do not add the plugin to this repo's opencode.json. In the user's ~/.config/opencode/opencode.json (or project config), add an absolute path under the OpenCode 2 plugins key (the plugin is an OpenCode 2 Plugin.define module since 5.0.0; OpenCode 1 does not run it):

{
  "plugins": ["/absolute/path/to/tamirs-superpowers/skills/toolkit/usage-capture/opencode-plugin.mjs"]
}

Start the collector the same way (collector.py --daemon, or the Claude enable script). Restart OpenCode. Mark this row partial in any report: the module loads on 2.0.32 (opencode plugin list); a live fire of its event subscription has not been recorded.

Bodies: TAMIRS_USAGE_CAPTURE_BODIES=1.

3. Confirm it is up

python3 scripts/usage-capture/collector.py --status --json

After a Claude turn, a file named YYYY-MM-DD.jsonl (Israel date) should appear in the log directory. Mode 0700 on the directory, 0600 on files.

4. Query a day

Do not invent numbers. If the file is missing, say capture is not running or no requests landed yet — not "zero usage".

p95 duration by model:

jq -s 'map(select(.event=="api_request" and .duration_ms!=null))
  | group_by(.model)
  | map({model: .[0].model, n: length, p95: (sort_by(.duration_ms) | .[(length*0.95|floor)].duration_ms)})' \
  ~/.local/share/tamirs-superpowers/usage/$(TZ=Asia/Jerusalem date +%Y-%m-%d).jsonl

Top skills by input tokens:

jq -s 'map(select(.skill_name and .input_tokens))
  | group_by(.skill_name)
  | map({skill: .[0].skill_name, input_tokens: (map(.input_tokens)|add)})
  | sort_by(-.input_tokens)' \
  ~/.local/share/tamirs-superpowers/usage/$(TZ=Asia/Jerusalem date +%Y-%m-%d).jsonl

Slowest custom-endpoint calls:

jq -s 'map(select(.event=="api_request")) | sort_by(-.duration_ms) | .[:10]
  | map({ts, model, endpoint, duration_ms, ttft_ms, skill_name})' \
  ~/.local/share/tamirs-superpowers/usage/$(TZ=Asia/Jerusalem date +%Y-%m-%d).jsonl

5. Disable

bash scripts/usage-capture/enable.sh --disable

The same backup applies. --stop signals only a PID whose command line is the collector. A stale pid file naming another process is removed, and that process is left running. Restart Claude Code. Remove the OpenCode plugin path if it was added. Logs on disk are left in place — ask before deleting.

JSONL fields (omit rather than invent)

ts, harness (claude_code | opencode), event (api_request | api_error | user_prompt | skill_activated | tool_result | session_start | llm_request), session_id, prompt_id, request_id, model, query_source, duration_ms, ttft_ms, token fields, request_bytes, skill_name, command_name, plugin_name, agent_name, mcp_server, mcp_tool, endpoint, success, status_code, stop_reason, cost_usd, body_ref (only with --bodies).

Fallback when hooks is missing

usage-capture-ensure.sh is env-gated SessionStart. On a surface without that event, run python3 scripts/usage-capture/collector.py --daemon yourself. The skill still enables Claude settings and still documents the OpenCode plugin.

Do not

• Merge this into session-report or parse ~/.claude/projects here.
• Claim OpenCode supported until a live fire is recorded.
• Enable managed/org OTEL settings in v1.
• Bind the collector anywhere but 127.0.0.1.