Crate pitboard_core

Expand description

The engine behind pitboard: parking and restoring a person’s own Claude Code logins, and reading what each has left. It serves pitboard’s own front ends, the command line and the native apps, which reach it through service::Pitboard with an explicit context::Context.

§What is supported

This crate is published because the pitboard binary depends on it, not because it was designed for other programs to build on. The supported interface is service::Pitboard, context::Context, and the types those two return. Everything else is reachable so the front ends in this repository can reach it, and may change in any release.

What a version promises, for the part that is supported: a code is a name, and names are kept. Adding an error, warning or check code is not a breaking change, which is why every enum a caller reads codes out of is #[non_exhaustive] and every such caller needs a fallback arm. Renaming or removing a code is a breaking change and gets a major version.

What is deliberately not reachable: nothing outside this crate may write pitboard’s index. Every change goes through switch, which records what it is about to do first and finishes an interrupted one before starting another.

Modules§

api: What pitboard asks of Anthropic: who a login belongs to and how much it has left, both read with an access token, and fresh tokens for a parked login.
assumptions: How pitboard writes down what it believes about somebody else’s software.
audit: One line per change pitboard makes: when, which front end asked, what was asked, of what, and how it ended. Labels, codes and times only, no email addresses or account identifiers, so it is safe to paste into a bug report.
budget: How often pitboard is allowed to ask Anthropic about an account.
context: Everything pitboard takes from its environment, read in one place. The CLI builds a Context from the process environment once. A program linking the library builds one itself: an app started from Finder does not see a shell’s environment.
doctor: pitboard doctor: check, on this machine, that what pitboard relies on about Claude Code still holds, and say which assumption broke when one has. Gathering is kept apart from judging so every judgement can be tested.
error: Every way pitboard can fail. Each variant has a message naming the cause and an action, a stable code for programs to branch on, and an exit code.
history: What each account’s limits have been doing, rather than only what they are now.
label: Turning what somebody typed into one account.
provider: The boundary between pitboard’s own machinery and one particular coding tool’s login.
redact: Making a diagnosis safe to paste into a bug report.
schedule: Keeping parked logins alive without anybody running a command.
service: pitboard’s operations, each run the way every front end must run it: a change settles any interrupted switch first and is recorded in the audit log, and what went wrong on the way is reported alongside the result, whether or not the change then succeeds.
settings: What a session here would authenticate as, read from files rather than guessed from three environment variables.
state: Which accounts pitboard knows and where each one is parked. No secrets: the logins stay in the keychain or vault.
status: pitboard status: who is signed in, what each account has left, and which accounts can be switched to.
statusline: pitboard statusline: one line for Claude Code’s status bar, naming the account in use and what every enrolled account has left.
switch: Moving the signed-in identity from one enrolled account to another.
time: Time through jiff: epoch seconds in everything pitboard stores, the local time zone only in what it shows a person.
usage: One view of “how much is left”, whatever shape it arrived in. Usage comes as a limits[] array or as named five_hour/seven_day objects; both are normalised at the boundary, and a value that fails to normalise is dropped rather than drawn.