FAQ

FAQ & Troubleshooting

What is "beads" and do I need it?

Beads (bd) is Steve Yegge's distributed, graph-based issue tracker designed for AI coding agents. For live mode you need the bd binary and a .beads repo. For a no-setup tour, you don't — the app falls back to Demo Mode.

Does this replace bd?

No. It's a visual UI on top of bd. bd remains the single source of truth; the app shells out to it and adds no schema of its own. See Architecture.

Is my data stored by the app?

No beads data is stored by the app. The only thing it persists is local UI config (repo path, attribution, theme, board ordering) in ~/.config/bead-me-up-scotty/config.json. Your beads stay entirely in bd/Dolt.

Can other people use it at the same time / over the network?

It's a local, single-user tool — localhost, no auth, single writer. Don't expose it to untrusted networks. It also has a local folder-browse endpoint; clamp it with BEADS_FS_ROOT. See Configuration.

Troubleshooting

The app says it's in demo mode but I have bd installed

• Make sure bd is on the PATH of the process running the server.
• If bd lives somewhere unusual, set BD_BIN=/path/to/bd.
• Check you didn't leave BEADS_DEMO=1 set, or the demo toggle on in Settings.
• Confirm you're pointing at a directory that actually has a .beads repo (BEADS_REPO, the project picker, or Settings).

No beads show up / "no repo found"

The active directory needs a .beads repo. Create one with bd init in your project, then point the app at that directory.

Everything renders as 🤖 (or my writes show as agent)

Attribution depends on your human actor and human allowlist. Set BEADS_ACTOR / the allowlist in Settings so your own actor is recognized as 👤. See Configuration.

My writes seem to conflict or get lost

The embedded Dolt backend is single-writer. The app serializes its own writes behind a mutex, but if agents are also writing via bd at the same instant, expect normal last-write-wins behavior. The board re-polls on an interval (pollIntervalMs) to stay current.

AI-assist says the Claude CLI wasn't found

The assist feature shells out to the Claude Code CLI. Install Claude Code, or set CLAUDE_BIN=/path/to/claude.

npm install -g . fails with a permissions error

Use a user-owned npm prefix:

npm config set prefix ~/.npm-global   # then add ~/.npm-global/bin to PATH

See Global Install and CLI.

The global scotty command is stale after I pulled changes

If you installed via npm link (Option A), re-run npm run build in the clone. The command is a symlink to the clone, so it reflects the latest build.

Still stuck?

Open an issue on the repo or check Contributing for how to build and verify locally.