Skip to main content
Early pricing is live. Start free for up to 3 AI systems — no card, no time limit.Early pricing is live. Free for up to 3 AI systems.
All docs
Reference

oabo-collector command reference

Commands, options, config keys, file paths per operating system, exit codes, and what the collector reads.

5 minFor: Engineer

oabo-collector scans local AI-harness logs and pushes token-usage measurements to your workspace. Token counts and metadata only, never transcript content. Python 3.10 or newer. Version 0.1.0.

Commands

CommandDoesNetwork
scanDry run. Aggregates local logs into one row per fingerprint, day, harness and model and prints the table.None
pushScans, authenticates, pushes the day-keys that changed since the last push, and saves the state file.HTTPS to api_url
statusPrints the state file path, how many files are tracked and how many day-keys were pushed.None
scan output
fingerprint          day         harness      model                             in       out   cache_r  sess
---------------------------------------------------------------------------------------------------------
invoice-bot          2026-11-17  claude_code  claude-fable-5                  1200      3400         0     1
support-triage       2026-11-17  hermes       claude-sonnet-4                 8800     12100      4200     3

Options

Options go after the command (push --since 30), never before it.

OptionCommandsMeaning
--config PATHallPath to config.toml. Default: the config path under Paths.
--since DAYSallLookback window in days. Default: since_days from the config, else 7.
--token JWTpushA session token to use instead of email and password. An ingest_key in the config still wins.

Config file

TOML. Every key is listed in Settings and toggles. The minimum the installer writes:

~/.config/oabo-collector/config.toml
api_url = "https://your-workspace.oaboscorecard.com"
ingest_key = "<the key from Developer machines>"
since_days = 30

Credential precedence at push: ingest_key, then --token, then token, then email and password exchanged for a token.

Paths

WhatDefaultOverride
Command~/.oabo-collector/venv/bin/oabo-collector
Config~/.config/oabo-collector/config.tomlOABO_COLLECTOR_CONFIG, XDG_CONFIG_HOME
State~/.local/state/oabo-collector/state.jsonOABO_COLLECTOR_STATE, XDG_STATE_HOME
Claude Code logs~/.claude/projectsOABO_COLLECTOR_CLAUDE_DIR
Hermes state~/.hermes/state.dbOABO_COLLECTOR_HERMES_DB
Home~OABO_COLLECTOR_HOME

Exit codes

CodeMeaning
0Done. For push: every fingerprint group was accepted, or there was nothing new to push.
1push: at least one fingerprint group failed or was partly skipped. It was not marked as pushed and is retried next run. The output names the unmarked fingerprints.
2push: the config has no ingest_key, no token and no email and password.

What it reads

  • Claude Code: the JSONL transcripts under ~/.claude/projects, main sessions and subagents. Only the usage fields are read. A file's whole cumulative total is attributed to the day of its last modification; when that crosses midnight between pushes, the old day-key is retracted with a zero record so nothing is counted twice.
  • Hermes: ~/.hermes/state.db, opened read-only. The collector never writes to it.
  • Fingerprint: the project directory's basename, lowercased, anything outside a-z0-9_- replaced by a hyphen, a leading letter forced, 64 characters at most. An explicit [mapping] entry wins.
  • Provider: clamped to anthropic, openai, google, bedrock, vertex, self_hosted, other. Billing mode: clamped to api, subscription, local, else the config default.
  • Origin: the machine's hostname and the OS user name, sanitized the same way, travel with each record as reported-not-verified provenance.

What crosses the network, and what does not: What leaves your machine.

Previous

Roles and permissions

Last documented 2026-11-18 against master fb17e1c5. Live release 0.3.1.