Configuration

Configuration

Bead Me Up, Scotty keeps its own settings outside of beads — your bd data is never touched by app configuration. Settings live in a small JSON file under your OS config directory:

$XDG_CONFIG_HOME/bead-me-up-scotty/config.json
# defaults to ~/.config/bead-me-up-scotty/config.json

You can change most of these from the in-app Settings screen; environment variables cover the rest (and are handy for scripted/CI use).

Settings (config.json)

Setting	Meaning
humanActor	The actor name the app stamps onto its writes, so they can be told apart from agent writes.
humanAllowlist	Actor names rendered as 👤 (human). Everyone else renders as 🤖 (agent).
pollIntervalMs	How often the board re-polls bd so it stays fresh while agents change data underneath you.
projects	The registry of beads projects the app has discovered (id, name, path, timestamps).
orders	App-local manual board ordering (project → column → ordered bead ids) for drag-to-reorder within a column.
gamification	Opt-in XP/level layer. Off by default.

Project identity is per-request, driven by the /p/<projectId> URL — so the "active" project is not stored in config; only the durable list of known projects is.

Environment variables

Variable	Purpose
BEADS_REPO	Path to the project directory containing the .beads repo to use.
BD_BIN	Path to the bd binary if it isn't on your PATH.
BEADS_DEMO	Force Demo Mode even if bd is installed (e.g. BEADS_DEMO=1).
BEADS_ACTOR	The human actor used to stamp writes (attribution).
BEADS_FS_ROOT	Clamp the in-app folder browser to a subtree. The app exposes a local filesystem-browse endpoint with no auth; set this to limit what it can see.
CLAUDE_BIN	Path to the Claude Code CLI used by the AI-assist feature (defaults to claude).
BMUS_SUPERVISED	Set to 1 when the app is launched under a supervisor; affects self-update behavior.
XDG_CONFIG_HOME	Where config.json is stored (defaults to ~/.config).

Example:

BEADS_REPO=/path/to/project BD_BIN=/opt/bin/bd npm run dev

Attribution: 👤 human vs 🤖 agent

Beads has no native human-vs-agent flag, so the app derives it:

1. When the app writes (creates a bead, adds a comment, changes status), it stamps the write with your configured human actor (BEADS_ACTOR / humanActor).
2. When rendering, any actor in the human allowlist shows as 👤; everyone else — typically your AI agents writing from the bd CLI — shows as 🤖.

Tune the actor and allowlist in Settings (or via BEADS_ACTOR) so your own writes are attributed correctly.

A note on security

This is a local, single-user tool: it runs on localhost with no auth and shells out to local binaries. The folder-browse endpoint can read your filesystem, so use BEADS_FS_ROOT to clamp it, and don't expose the server to untrusted networks. See FAQ for more.