Configuration

birdclaw reads configuration from these layers:

1. Command flags — for example --account, --mode, and --transport.
2. Environment variables — global paths plus feature-specific overrides.
3. User config — ~/.birdclaw/config.json, or the file selected by BIRDCLAW_CONFIG.

#Storage root

The default root is ~/.birdclaw. It holds:

~/.birdclaw/
  birdclaw.sqlite              # canonical local truth
  config.json                  # user config
  media/                       # original media cache
  media/thumbs/avatars/        # avatar cache
  audit/                       # JSONL audit logs (e.g. bookmarks-sync.jsonl)
  logs/                        # launchd stdout/stderr
  locks/                       # job lock files

Override the root for one process:

export BIRDCLAW_HOME=/path/to/custom/root

The Playwright test home is .playwright-home in the repo, which is why CI never touches the production root.

#Config file

~/.birdclaw/config.json controls live transport, scheduled jobs, mention sourcing, and backup auto-sync.

{
	"accounts": {
		"default": "steipete"
	},
	"actions": {
		"transport": "auto"
	},
	"mentions": {
		"dataSource": "bird",
		"birdCommand": "/Users/steipete/Projects/bird/bird"
	},
	"backup": {
		"repoPath": "/Users/steipete/Projects/backup-birdclaw",
		"remote": "https://github.com/steipete/backup-birdclaw.git",
		"autoSync": true,
		"staleAfterSeconds": 900
	}
}

#accounts.default

Set a Birdclaw account username (with or without @) or stored account ID. Commands with an --account option use this value when the flag is omitted. An explicit --account always wins.

Selection is per operation. Birdclaw resolves the existing account row, routes xurl through that username for the command, then restores the process environment. It never creates an account, changes the database default, or binds a live credential to stored data.

#actions.transport

• auto — try bird first for block/unblock/mute, then fall back to verified xurl
• bird — force bird
• xurl — force xurl; verifies through bird status before mutating SQLite

Twitter still rejects pure OAuth2 block writes for many accounts, so auto is the safe default.

#mentions.dataSource

• birdclaw — local cache only
• bird — refresh through bird mentions --json, normalize, cache in SQLite
• xurl — refresh through xurl mentions, cache the response shape

mentions.birdCommand overrides the bird binary path when you want to point at a non-PATH build.

#backup.*

See Backup. When autoSync is enabled, read commands pull + merge from Git only when the last check is stale, and data-changing commands push back automatically. Set BIRDCLAW_BACKUP_AUTO_SYNC=0 to disable for one process.

#Environment variables

BIRDCLAW_DISABLE_LIVE_WRITES=1 is set automatically in CI and Playwright runs so test code can never publish a tweet, send a DM, or block an account.

#Multi-account

birdclaw was built around multiple accounts in a single shared database from day one. Pass --account <username> (or a stored account ID) on commands that support account selection, including moderation, profile hydration, profile reply inspection, mentions, DMs, live sync, and scheduled jobs.

birdclaw sync timeline --account steipete --mode xurl
birdclaw import hydrate-profiles --account @steipete
birdclaw compose post --account acct_primary "Ship it."

For a recurring choice, set accounts.default in config.json. Explicit flags remain reversible one-command overrides. xurl can select a named OAuth2 account; Bird has one active cookie identity, so Bird-backed operations verify that identity matches the selected Birdclaw account before reading or writing.

Per-account state — cursors, transport preferences, last-sync watermarks, OpenAI score caches — lives inside the same birdclaw.sqlite. There is no per-account directory tree.

#Transport selection

There is no single global transport order:

• Archive imports and local reads need no live transport.
• Sync commands select their source with --mode; supported modes and defaults vary by command.
• Mentions export resolves its data source separately.
• Moderation writes use command --transport, then BIRDCLAW_ACTIONS_TRANSPORT, then actions.transport, then auto.

For moderation, auto tries bird first and falls back to xurl. Persist that choice with birdclaw auth use <auto|bird|xurl>.

#Disabling live writes

For dry runs, demos, or development against a fresh archive:

export BIRDCLAW_DISABLE_LIVE_WRITES=1
birdclaw compose post "this will not actually post"
birdclaw blocks add @someone --account acct_primary

Both commands record the intent locally where applicable but skip every transport call. Tests and CI rely on this exact mechanism.