Files and environment variables

The paths shown are defaults that environment variables can move.

The pitboard directory

pitboard’s directory is ~/.pitboard, or the path in PITBOARD_HOME. The command line and the app share it. pitboard creates each directory at mode 0700 and each file at 0600, except those in backups/. An existing directory keeps its mode. pitboard refuses a directory whose path contains Dropbox, Google Drive, OneDrive, com~apple~CloudDocs or Sync, because parked logins belong to one machine.

File	Holds	Written by
`state.json`	The enrolled accounts: label, tool, email address, account identifiers, and each parked login’s name and expiry	Every change pitboard makes, and renewals
`state.lock`	The lock that lets one change or renewal run at a time	Every change pitboard makes, and renewals
`journal.json`	The record of a switch while it runs. An interrupted switch leaves it behind, and the next change pitboard makes finishes or undoes it; see Interrupted switches.	A switch
`pending`	Names of parked logins about to be written, one per line. If a run is killed midway, the next change pitboard makes finds each login by its name here. Absent when there are none.	Switches, sign-ins and renewals
`signin.lock`	The lock that allows one sign-in at a time	A sign-in
`signin/`	The config directory a tool is given during a sign-in, so the login in use is left alone. Removed when the sign-in ends, or by the next sign-in if pitboard was stopped during one.	A sign-in
`vault/`	Linux only: parked logins, one file each	Switches, sign-ins and renewals
`usage.json`	The newest usage reading for each account	Reading usage, and the status line
`usage.lock`	The lock around `usage.json` and `sessions.json`	Reading usage, and the status line
`readings/`	One file per account, with 14 days of readings, to work out how long the account lasts	Reading usage
`asking.json`	When pitboard last asked Anthropic or OpenAI for each account’s usage, and how long to wait before asking again	Reading usage
`sessions.json`	The usage each Claude Code session last gave `pitboard statusline`, and the account in use then. A session not seen for 7 days is dropped.	The status line
`backups/`	Copies of Claude Code’s config from before each switch rewrote it. Each is named after the time it was made, in seconds since 1 January 1970, such as `claude.json.1790000000`. The 10 newest are kept. They hold no login, but do hold your email address and the path of each project Claude Code has opened. Each keeps the mode of Claude Code’s file.	A Claude Code switch
`audit.log`	One tab-separated line per change or renewal: the time, `cli` or `app` for where it was made, the verb such as `use`, the subject and the outcome. It holds no email address, and holds an account id only in a `reclaim` line with the outcome `discarded`, whose subject is a parked login’s name. `pitboard log` prints it.	Every change pitboard makes, and renewals
`audit.log.1`	The previous `audit.log`, moved aside once it passed 256 KiB	Every change pitboard makes, and renewals

Only files in vault/ and signin/ can hold a login. To delete the directory, see Remove pitboard.

Parked logins

On macOS, each parked login is an item in your default keychain, named pitboard-park-<account id>-<time>. Its keychain account is the one Claude Code’s item uses, usually your user name from USER. <account id> is a Claude Code account’s Anthropic UUID or, for OpenAI’s Codex CLI, is built from the account’s ChatGPT ids. <time> is when the login was parked or last renewed, in milliseconds since 1 January 1970. On Linux, each parked login is a file in ~/.pitboard/vault/, named pitboard-park-<account id>-<time>.json. For why parked logins are kept there, see Security and privacy.

Claude Code and Codex files

Path	What pitboard does with it
`~/.claude.json`	Reads the account the file records as in use. After a Claude Code switch, copies it to `backups/` and writes the incoming account into it. A `~/.claude/.config.json`, where one exists, is used instead.
Keychain item `Claude Code-credentials`	macOS: the Claude Code login in use. A switch reads and replaces it. With `CLAUDE_CONFIG_DIR` set, the name ends in `-` and 8 hex characters from a hash of the directory’s path.
`~/.claude/.credentials.json`	Linux: the Claude Code login in use. macOS: Claude Code’s fallback when a keychain write fails, which pitboard reads after the keychain item.
`~/.claude/.storage-write.lock`	The lock Claude Code takes around each write of its login. pitboard takes it during a switch.
`~/.claude/settings.json`	Read for `apiKeyHelper`, and for an `env` block that sets `CLAUDE_CODE_CUSTOM_OAUTH_URL` or a variable that overrides Claude Code’s login, listed in Environment variables. Managed settings are read too: `managed-settings.json` and `managed-settings.d/*.json` in `/Library/Application Support/ClaudeCode` on macOS or `/etc/claude-code` on Linux. A project’s settings are not read.
`~/.codex/auth.json`	The Codex login in use. A switch reads and replaces it.
`~/.codex/config.toml`	Read for `cli_auth_credentials_store`. For the values pitboard refuses, see Use pitboard with Codex.

For how a switch changes these files, see How switching works.

Renewal schedule

pitboard schedule install, or turning on Renew parked logins daily in Settings > General, writes these files. pitboard schedule uninstall, or turning it off, removes them. So does pitboard uninstall when pitboard’s directory is ~/.pitboard.

Item	macOS	Linux
Files	`~/Library/LaunchAgents/com.datlechin.pitboard.renew.plist`	`~/.config/systemd/user/pitboard-renew.service` and `~/.config/systemd/user/pitboard-renew.timer`, even when `XDG_CONFIG_HOME` is set
Name	launchd label `com.datlechin.pitboard.renew`	unit `pitboard-renew.timer`
Program	The `pitboard` that installed it, by the path it was started with, such as Homebrew’s link, so an upgrade does not break it. From the app: `Pitboard.app/Contents/Helpers/pitboard`	The `pitboard` that installed it, by the path it was started with, such as Homebrew’s link, so an upgrade does not break it
Runs	`<program> renew`	`<program> renew`
When	Once a day, first a day after it is written: `StartInterval` 86400, `RunAtLoad` false	Once a day: `OnUnitActiveSec=86400`, `OnStartupSec=900`

The app

The app is Pitboard.app, with the bundle identifier com.usepitboard.Pitboard.

Path inside `Pitboard.app`	What it is
`Contents/Helpers/pitboard`	The command line
`Contents/Resources/man/pitboard.1`	The man page
`Contents/Resources/completions/pitboard.bash`, `pitboard.zsh` and `pitboard.fish`	Shell completions

The app stores these keys in ~/Library/Preferences/com.usepitboard.Pitboard.plist:

Key	Holds
`hasBeenSeen`	Whether the app has opened its window at first launch
`secondAccountDeclined`	The tools for which you clicked Not Now when the Accounts pane suggested a second account
`menuBarShows`	Menu bar shows: `nameAndUsage`, `usage` or `icon`
`settingsTab`	The Settings tab shown last: `general`, `commandLine` or `updates`
Keys of Sparkle, the app’s updater	Its update settings and when it last checked

macOS keeps Open pitboard at login as a login item, outside this file. The app’s files can also be in ~/Library/Application Support, ~/Library/Caches and ~/Library/HTTPStorages, named after com.usepitboard.Pitboard. To remove them, see Remove pitboard.

Environment variables

Opened from Finder, the app does not see your shell’s variables, so the defaults apply. Daily renewal runs with the scheduler’s environment, not your shell’s.

Variable	Read by	Effect
`HOME`	Both	Your home directory, the `~` in every path here.
`PITBOARD_HOME`	Both	pitboard’s directory, in place of `~/.pitboard`. Daily renewal always renews `~/.pitboard`.
`PITBOARD_NO_ARGV`	Both	On macOS, when it is `1`, pitboard refuses to write a large login on `security`’s argument line, and does not renew a parked login it could not write back. A renewal schedule installed while it is set keeps it. See Large logins on macOS.
`PITBOARD_API_BASE`	Command line	For pitboard’s tests. Sends the requests meant for Anthropic and OpenAI to this URL, if it is an `http` URL whose host is a loopback IP address, such as `http://127.0.0.1:8080`.
`CLAUDE_CONFIG_DIR`	Both	Claude Code’s config directory, in place of `~/.claude`. The config file becomes `$CLAUDE_CONFIG_DIR/.claude.json`, and the keychain item’s name gets a suffix. Empty counts as unset.
`CLAUDE_SECURESTORAGE_CONFIG_DIR`	Both	The directory that picks Claude Code’s keychain item, `.credentials.json` and lock, in place of the config directory. Set but empty, it picks `~/.claude` and `Claude Code-credentials`.
`USER`	Both	macOS: the keychain account of Claude Code’s item and of parked logins. Unset or empty, your login name is used. A name with characters other than letters, digits, `.`, `_` and `-` becomes `claude-code-user`.
`CLAUDE_CODE_CUSTOM_OAUTH_URL`	Command line	Not empty: pitboard refuses every change to a Claude Code account, and refuses `repair`, `uninstall` and `abandon`, with the error `custom_oauth_endpoint`. Claude Code then keeps its login under a name pitboard does not read. The command line and the app also read it from an `env` block in Claude Code’s settings.
`ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`, `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`, `CLAUDE_CODE_USE_GATEWAY`, `CLAUDE_CODE_USE_ANTHROPIC_AWS`, `CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD`	Command line	Any of these not empty: Claude Code uses something other than the login pitboard switches. Changes to Claude Code accounts warn with `auth_overridden`, and `pitboard doctor` warns. The command line and the app also read these, and `apiKeyHelper`, from Claude Code’s settings.
`CODEX_HOME`	Both	Codex’s directory, in place of `~/.codex`. Empty counts as unset.
`PATH`	Command line	Where the command line looks for `claude` and `codex`, which it runs to sign in. Only absolute directories are searched.
`NO_COLOR`	Command line	Not empty: no colour in any output. `pitboard statusline` also drops its colour when `NO_COLOR` is set but empty.
`PITBOARD_CLAUDE`, `PITBOARD_CODEX`	App	The path of the `claude` or `codex` program the app runs to sign in, in place of the one it finds.

Get started

Install and remove

Use pitboard

Troubleshooting

How it works

Reference

Files and environment variables

The pitboard directory

Parked logins

Claude Code and Codex files

Renewal schedule

The app

Environment variables

​The pitboard directory

​Parked logins

​Claude Code and Codex files

​Renewal schedule

​The app

​Environment variables

The pitboard directory

Parked logins

Claude Code and Codex files

Renewal schedule

The app

Environment variables