A little setup.
A lot to make your own.

Requirements

• Node.js 22 or later. The curl installer prepares Node.js 24 when needed; Homebrew, mise and the WSL helper also supply Node.js.
• Git 2.40 or later, which moving a contribution onto the latest target branch needs.
• The GitHub CLI (gh), signed in with gh auth login. BELL PR uses it to publish Draft PRs and to find projects.
• One AI coding CLI, installed and signed in: the OpenAI Codex CLI, or Claude Code with your Claude plan or Anthropic API key. Usage counts against your own account.
• On Linux, bubblewrap and socat (for example sudo apt-get install bubblewrap socat), so that Claude Code agents that change code run in the operating system's sandbox.

bell-pr doctor checks all of this and says how to fix what is missing.

Platforms

• macOS and Linux: choose curl, Homebrew, Bun, mise or npm.
• Windows: use the ps1 installer with WSL2 Ubuntu or Debian. Native Windows is unsupported; this setup has not been verified on a real Windows host. Follow the Windows steps below.
• Docker (beta): an image you build from the source, with Git, the GitHub CLI and the Codex CLI.

Sign in to your tools

Set your Git identity with git config --global user.name "Your Name" and git config --global user.email "you@example.com", replacing the sample values with yours. Sign in with gh auth login, then codex login or claude auth login. Run bell-pr doctor (or npx bell-pr doctor when using npx) to check what is ready.

Open your workbench

The curl installer prints a launch command and a PATH setting; use those so your terminal finds the installed tools. With npx, run npx bell-pr again. With Homebrew or Bun, run bell-pr. With mise, run mise exec -- bell-pr. Keep the terminal open while you work; Ctrl+C stops BELL PR.

To try the sample project before signing in, use bell-pr start --force. The sample makes no AI call and sends nothing to GitHub; real agent work waits for a signed-in provider.

Windows with WSL2

1. If WSL2 is missing, run this in an Administrator PowerShell:

   wsl --install -d Ubuntu

   Restart Windows if prompted. Open Ubuntu and create your regular Linux user and password. Use wsl --list --verbose to check for version 2; if needed, run wsl --set-version Ubuntu 2.

2. Run the ps1 command above in a normal PowerShell. It prepares Git, GitHub CLI, Node.js, BELL PR and Codex CLI inside Ubuntu. It may ask for your Linux sudo password. The installer also supports an existing Debian distribution and Claude Code; it does not sign in for you.
3. Enter Ubuntu with wsl -d Ubuntu. Set your Git identity there, then run these commands in the Linux terminal:

   gh auth login
   codex login
   bell-pr doctor
   bell-pr

   If you selected Claude Code, use claude auth login instead. Keep your projects in WSL, for example ~/projects; sign-ins from Windows copies of these tools do not carry over.

4. For later launches, run this from PowerShell:

   wsl -d Ubuntu -- bash -lc '$HOME/.local/bin/bell-pr'

   Use your distribution's name if it is not Ubuntu. If no browser opens, run bell-pr open --print --print-token in another WSL terminal and open that link in Windows. The link contains a credential; keep it private.

Start with npm

npx bell-pr

BELL PR starts on http://127.0.0.1:4311, where only this computer can reach it, and opens it in your browser. Keep the terminal open while you work; Ctrl+C stops BELL PR.

To install the bell-pr command instead:

npm install -g bell-pr
bell-pr

Useful commands

• bell-pr doctor checks Git, the GitHub CLI and the AI coding CLIs, and says how to fix what is missing.
• bell-pr start --port 4400 uses another port.
• bell-pr start --data-dir ./bellpr-data keeps the data somewhere other than the default ~/.bellpr.

Run with Docker (beta)

Docker support is in beta. Under Docker's default security settings the agents cannot start their sandbox, so analysis, reviews and code changes stall. To let them work, add --security-opt seccomp=unconfined --security-opt apparmor=unconfined --security-opt systempaths=unconfined to docker run. These options relax the container's own confinement so that the agent sandbox can start; use them only on a machine you control.

Build the image from a checkout of the source, then run it:

docker build -t bell-pr .

docker run -d --name bell-pr \
  -p 127.0.0.1:4311:4311 \
  -v bellpr-data:/data \
  -v bellpr-home:/home/node \
  -e GH_TOKEN \
  -e OPENAI_API_KEY \
  -e BELLPR_PUBLIC_URL=http://localhost:4311 \
  bell-pr

• -p 127.0.0.1:4311:4311 publishes the port on this computer's loopback interface only, so nothing else on your network can reach BELL PR. Inside the container BELL PR listens on every interface, so never publish the port without 127.0.0.1:. Public exposure leaves only the API token protecting full access. Keep the port private; use tailscale serve with BELLPR_PUBLIC_URL or ssh -L for remote access.
• The bellpr-data volume keeps your repositories, runs and notes; bellpr-home keeps the sign-ins of the tools inside the container.
• Get the address again with docker exec bell-pr bell-pr open --print --print-token. --print-token includes the API token; do not share that address.
• The image includes Git, the GitHub CLI and the Codex CLI. -e OPENAI_API_KEY passes your OpenAI key to the Codex CLI; you can sign in inside the container instead. Set the Git identity for commits with -e GIT_AUTHOR_NAME, -e GIT_AUTHOR_EMAIL, -e GIT_COMMITTER_NAME and -e GIT_COMMITTER_EMAIL.
• Claude Code is not preinstalled. To use it, run docker exec -it bell-pr npm install -g @anthropic-ai/claude-code and then docker exec -it bell-pr claude auth login.

Next steps

Open the sample project to see a finished contribution, then import a repository you want to contribute to. BELL PR publishes your changes to GitHub only with your approval. AI tasks send relevant code and instructions to your chosen provider. The source repository explains what the agents may do on your computer in docs/security-model.md, and what leaves it in docs/privacy-and-data.md.