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
| Target | Status | Why |
|---|---|---|
| Claude Code | supported | Native OTEL logs + traces → local collector |
| Claude Desktop | partial | Same settings file may apply; not verified here — check for JSONL before claiming it works |
| OpenCode CLI | partial | Optional opencode-plugin.mjs (OpenCode 2 Plugin.define, ctx.event.subscribe); not loaded by this repo's opencode.json; a live fire has not been recorded |
| Codex, Cursor, Gemini CLI | unsupported | No capture path shipped |
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-reportor parse~/.claude/projectshere. - Claim OpenCode
supporteduntil a live fire is recorded. - Enable managed/org OTEL settings in v1.
- Bind the collector anywhere but
127.0.0.1.