# How to Initialize Beads in Contributor Mode for Forked Repositories

> Initialize Beads in contributor mode for forked repos using bd init --contributor. Keep upstream PRs clean and manage personal issues privately.

- Repository: [Gas Town Hall/beads](https://github.com/gastownhall/beads)
- Tags: how-to-guide
- Published: 2026-04-27

---

**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`](https://github.com/gastownhall/beads/blob/main/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:

```go
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`](https://github.com/gastownhall/beads/blob/main/cmd/bd/init.go)):

```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:

```yaml
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`](https://github.com/gastownhall/beads/blob/main/cmd/bd/init.go):

```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

```bash

# 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

```bash

# 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)

```bash
bd create "Refactor authentication logic" -p 2

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

```

### List only planning repository issues

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

```

### Override routing for a single upstream issue

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

```

### Force maintainer mode in CI environments

```bash
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`](https://github.com/gastownhall/beads/blob/main/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`.