Crate pitboard_core

Expand description

The engine behind Pitboard: parking and restoring a person’s own Claude Code and Codex 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: a new minor version while Pitboard is at 0.x, as Cargo reads one, and a new major version after 1.0. A report a caller reads, such as what uninstall returns, may likewise say more in a later release, so those structs are #[non_exhaustive] too.

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.
app: What an app has to find for itself that a command typed at a prompt is given.
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.
autoswitch: Switching Claude Code by itself, before the account in use runs out.
budget: How often Pitboard is allowed to ask Anthropic about an account.
context: Everything Pitboard takes from its environment, read in one place. Every front end builds its Context from the variables it was started with, by the same code: the command line from its own, once. An app passes the ones it was started with, which are not a shell’s, so it also looks for each tool’s program itself, in crate::app.
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.
holder: What keeps a tool’s login in memory while it runs, and what makes each kind take a switch.
host: The machine Pitboard runs on, behind one seam.
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.
release: Whether this build of Pitboard may do anything on the system it was built for.
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.
words: What Pitboard says in more than one place, each written once as a function of typed values: its sentences, the words of its columns, and the level a limit’s usage is at, where the command line’s colours and the app’s tints change. The command line calls these functions directly, and pitboard-ffi’s model calls them as it makes what an app shows, so where both say a thing they say it in the same words. The bindings export none of them: an app shows what the snapshot says. A thing said both in a column and in a sentence, such as a limit’s name or a parked login’s life, has a function for each form.