How to Initialize Beads in Contributor Mode for Forked Repositories

Running bd init --contributor in a forked repository creates a private planning repository at ~/.beads-planning that isolates your personal issues while keeping the upstream pull request clean.

When contributing to open-source projects using gastownhall/beads, you need a way to track personal tasks without polluting the upstream repository. Initializing Beads in contributor mode sets up an isolated planning workflow that automatically detects forks and routes issues to a private local database. This architecture ensures your experimental branches and personal todo items remain separate from the maintainer's canonical issue tracker.

Role Detection and Prompting

The bd init command in cmd/bd/init.go first validates whether you are inside a Git repository. If no explicit --contributor, --team, or --role flag is supplied, and the terminal is interactive, Beads prompts you to choose between contributor or maintainer roles:

if isGitRepo() && !contributor && !team && roleFlag == "" && !nonInteractive && shouldPromptForRole() {
    promptedContributor, err := promptContributorMode()
    …
    if promptedContributor {
        contributor = true
    }
}

In non-interactive environments (CI pipelines), Beads defaults to maintainer mode unless you explicitly set --role=contributor or configure git config beads.role contributor.

The Contributor Wizard and Fork Detection

When the contributor flag is true, bd init invokes runContributorWizard (defined in cmd/bd/init.go):

if contributor {
    if err := runContributorWizard(ctx, store); err != nil { … }
    if isGitRepo() {
        _ = setBeadsRole("contributor")
    }
}

This wizard performs three critical actions:

• Fork detection: It calls detectForkSetup to look for an upstream remote. If found, Beads treats the current clone as a fork.
• Planning repository creation: It executes initContributor to create ~/.beads-planning/.beads/—a full Dolt database that serves as your personal issue store.
• Role persistence: It pins the contributor role via setBeadsRole, writing beads.role=contributor to your Git configuration so subsequent commands automatically stay in contributor mode.

Auto-Routing Configuration

After creating the planning repository, the wizard writes routing rules to the project's .beads/beads.db file:

routing:
  mode: auto
  contributor: ~/.beads-planning
  maintainer: .

These settings configure auto-routing, ensuring any issue you create is automatically directed to ~/.beads-planning instead of the upstream repository. The routing.mode=auto setting enables this behavior without requiring manual --repo flags on every command.

Git Exclude Integration

To prevent accidental commits of your private planning data, bd init auto-detects the fork and prompts to add the planning directory to .git/info/exclude. This occurs in the post-wizard logic of cmd/bd/init.go:

if isGitRepo() && !stealth {
    if isFork, upstreamURL := detectForkSetup(); isFork {
        // promptForkExclude or auto-configure
    }
}

Unless you run with stealth mode, this ensures ~/.beads-planning remains untracked by Git, keeping your personal issues local and excluded from pull requests.

Practical Setup Examples

One-time setup on a freshly forked repository

# Clone your fork and add upstream

git clone https://github.com/YOUR_USERNAME/beads.git
cd beads
git remote add upstream https://github.com/gastownhall/beads.git

# Initialize contributor mode

bd init --contributor

The wizard detects the upstream remote, creates ~/.beads-planning/.beads/, and configures auto-routing.

Verify the contributor configuration

# Should print "auto"

bd config get routing.mode

# Should print the planning repo path

bd config get routing.contributor

Create a planning issue (automatically routed)

bd create "Refactor authentication logic" -p 2

# → Stored in ~/.beads-planning/.beads/

List only planning repository issues

bd list --source-repo ~/.beads-planning

Override routing for a single upstream issue

bd create "Critical bug in production API" -p 1 --repo .

Force maintainer mode in CI environments

git config beads.role maintainer

# or

export BEADS_ROLE=maintainer
bd init

Summary

• Fork detection relies on the presence of an upstream remote configured in your local Git repository.
• Contributor mode creates a private planning repository at ~/.beads-planning that houses all personal issues separate from the upstream project.
• Auto-routing via routing.mode=auto ensures issues created by contributors automatically route to the planning repository.
• Role persistence is handled through the Git config key beads.role=contributor, set by setBeadsRole in cmd/bd/init.go.
• Git exclusion prevents the planning directory from being committed to the upstream repository by updating .git/info/exclude.

Frequently Asked Questions

How does Beads detect that I'm working on a fork?

Beads executes detectForkSetup during initialization to check for an upstream remote in your Git configuration. If this remote exists and points to the canonical repository, Beads identifies your local clone as a fork and activates contributor-specific workflows.

Can I use contributor mode in a non-interactive environment like CI?

Yes, but you must explicitly specify the role since the interactive prompt is skipped. Set the environment variable BEADS_ROLE=contributor or run bd init --role=contributor. Without these flags, Beads defaults to maintainer mode in non-interactive shells.

Where are my contributor issues actually stored?

Your issues are stored in a Dolt database located at ~/.beads-planning/.beads/. This path is registered as the contributor source repository and is referenced by the routing.contributor configuration key in your project's .beads/beads.db file.

How do I temporarily switch back to maintainer mode for a single command?

Unset the beads.role configuration or override the routing for that specific command. To create an issue in the upstream repository instead of your planning repo, use the --repo . flag: bd create "Upstream bug" --repo .. To switch modes entirely, run git config beads.role maintainer and reinitialize with bd init.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}