oabo-collector command reference
Commands, options, config keys, file paths per operating system, exit codes, and what the collector reads.
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
| Command | Does | Network |
|---|---|---|
| scan | Dry run. Aggregates local logs into one row per fingerprint, day, harness and model and prints the table. | None |
| push | Scans, authenticates, pushes the day-keys that changed since the last push, and saves the state file. | HTTPS to api_url |
| status | Prints the state file path, how many files are tracked and how many day-keys were pushed. | None |
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 3Options
Options go after the command (push --since 30), never before it.
| Option | Commands | Meaning |
|---|---|---|
| --config PATH | all | Path to config.toml. Default: the config path under Paths. |
| --since DAYS | all | Lookback window in days. Default: since_days from the config, else 7. |
| --token JWT | push | A 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:
api_url = "https://your-workspace.oaboscorecard.com"
ingest_key = "<the key from Developer machines>"
since_days = 30Credential precedence at push: ingest_key, then --token, then token, then email and password exchanged for a token.
Paths
| What | Default | Override |
|---|---|---|
| Command | ~/.oabo-collector/venv/bin/oabo-collector | |
| Config | ~/.config/oabo-collector/config.toml | OABO_COLLECTOR_CONFIG, XDG_CONFIG_HOME |
| State | ~/.local/state/oabo-collector/state.json | OABO_COLLECTOR_STATE, XDG_STATE_HOME |
| Claude Code logs | ~/.claude/projects | OABO_COLLECTOR_CLAUDE_DIR |
| Hermes state | ~/.hermes/state.db | OABO_COLLECTOR_HERMES_DB |
| Home | ~ | OABO_COLLECTOR_HOME |
| What | Default | Override |
|---|---|---|
| Command | %USERPROFILE%\.oabo-collector\venv\Scripts\oabo-collector.exe | |
| Config | %USERPROFILE%\.config\oabo-collector\config.toml | OABO_COLLECTOR_CONFIG, XDG_CONFIG_HOME |
| State | %USERPROFILE%\.local\state\oabo-collector\state.json | OABO_COLLECTOR_STATE, XDG_STATE_HOME |
| Claude Code logs | %USERPROFILE%\.claude\projects | OABO_COLLECTOR_CLAUDE_DIR |
| Hermes state | %USERPROFILE%\.hermes\state.db | OABO_COLLECTOR_HERMES_DB |
| Home | %USERPROFILE% | OABO_COLLECTOR_HOME |
Note
The collector has no Windows-specific paths: it uses the same dot-directories under your profile that it uses under a home directory on macOS and Linux.
| What | Default | Override |
|---|---|---|
| Command | ~/.oabo-collector/venv/bin/oabo-collector | |
| Config | $XDG_CONFIG_HOME/oabo-collector/config.toml, else ~/.config/... | OABO_COLLECTOR_CONFIG |
| State | $XDG_STATE_HOME/oabo-collector/state.json, else ~/.local/state/... | OABO_COLLECTOR_STATE |
| Claude Code logs | ~/.claude/projects | OABO_COLLECTOR_CLAUDE_DIR |
| Hermes state | ~/.hermes/state.db | OABO_COLLECTOR_HERMES_DB |
| Home | $HOME | OABO_COLLECTOR_HOME |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Done. For push: every fingerprint group was accepted, or there was nothing new to push. |
| 1 | push: 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. |
| 2 | push: 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 toapi, 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.