Troubleshooting

Start with doctor. It names the failing check and shows the last lines of the hook log.

$node <plugin>/dist/cli.js doctor --project .

No events logged

Hooks haven't fired in this folder. Make sure the plugin is installed (/plugin lists it) and that Node 22.13+ is the node on your PATH; older Node lacks the built-in SQLite the hooks use. Then run one tool call in a session and check again.

The status line says stale, or the budget is unknown

The last usage reading is over two hours old or none succeeded. Usually the credentials file isn't where the sampler looks (~/.claude/.credentials.json, or $CLAUDE_CONFIG_DIR; the Keychain on macOS). The hook log has the exact error. The sampler also backs off when the endpoint rate-limits it; it recovers on its own.

The numbers don't match /usage

They come from the same endpoint, so a mismatch is a timing difference: Orstrum samples at session start and at most every two minutes at turn end. Doctor's "latest reading" has the timestamp. If it's recent and still off, that's a bug; please report it with both numbers.

Pro tools still say "available on Orstrum Pro"

The tier is decided when the MCP server starts, so a key added mid-session takes effect in the next one. Doctor shows the tier and the last verification; "server rejected the key" means it was revoked or the subscription lapsed.

Checkpoints unavailable

git isn't on the PATH Claude Code runs with. Install it or add it; nothing else needs it.

The hook log

~/.orstrum/hook.log collects every error the hooks swallowed. Hooks never crash Claude Code; if something is wrong, it's in that file.

Reporting a bug

Open an issue on GitHub with the doctor output. analyze <transcript.jsonl> can produce a report from a Claude Code transcript if you want to share what a session did without sharing the project.