Setting Up Beads Locally for Use with IBM Bob

This guide documents my process for installing Beads, initializing it in my project, and integrating it with IBM Bob.

Install Beads

Install the bd CLI using Homebrew:

brew install beads

For other installation options, see the Beads installation guide.

Initialize Beads in the Project

From inside the project directory:

bd init --stealth

What this does:

• Creates the .beads/ directory for Beads' local data
• Initializes storage (SQLite database + JSONL issues)
• --stealth keeps Beads artifacts out of version control

Integrate Beads With Bob

To preserve stealth mode, I avoided running bd setup commands, which would generate config files inside the project.

Instead, I:

1. Asked Bob to generate a rule describing how it should use Beads for issue tracking
2. Refined the rule by referencing the Beads guidelines in the .beads/ directory
3. Added the rule to Bob's configuration (.bob/rules/beads-project.md), not to project files

This made Bob aware of Beads without modifying tracked files.

Set Up Beads MCP Server for Bob

Bob's plan mode cannot run shell commands, so it needs the Beads MCP server to access Beads functionality.

Install the MCP server:

pipx install beads-mcp

This installs the beads-mcp executable, which exposes Beads operations through the Model Context Protocol (MCP).

Configure Bob to use the MCP server by updating .bob/mcp.json:

{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}

This allows Bob to launch beads-mcp and use Beads tools via MCP instead of shell commands.

Install the VS Code Extension (Optional)

Install the Beads extension from the VS Code Marketplace for visualizing Beads issues in your editor:

1. Open VS Code Extensions view (Cmd+Shift+X or Ctrl+Shift+X)
2. Search for "Beads"
3. Click Install

Requirements:

• bd on your PATH
• Project initialized with bd init

The extension reads from the .beads directory and surfaces issues inside VS Code.

Next Steps

Bob is now ready to use Beads for task tracking and planning.

Optional configurations:

• Auto-approve MCP calls - By default, Bob asks permission for each Beads MCP operation. Add specific tools to Bob's MCP auto-approval settings to skip prompts.

• Auto-approve bd commands - In code mode, Bob can run bd commands directly. Configure command auto-approval in Bob settings to skip confirmation prompts.

• Temporarily disable Beads - Rename .bob/rules/beads-project.md (e.g., add .disabled extension) to stop Bob from using Beads. Rename it back to re-enable.