★ Open Source · MIT License · Built in Rust

Parallel development for humans and AI agents

Every feature gets its own Git worktree.
Configure devcontainers, services, and runtime isolation for your project.

macOS (Homebrew)

brew install branchbox/tap/branchbox

Linux / macOS (Script)

curl -fsSL https://raw.githubusercontent.com/branchbox/branchbox/main/install.sh | bash

⚠ The Collision Problem

Modern engineering means parallel work. Multiple features. Multiple agents. Multiple contexts. But nothing was built for this.

✕ Git branches collide when you switch contexts
✕ Docker ports & networks conflict
✕ Databases leak data across features
✕ AI agents break your main workspace
✕ Devcontainers drift out of sync
✕ Credentials scattered across environments

# The nightmare scenario
$ docker compose up
ERROR: port 3000 already in use

$ rails db:migrate
ERROR: production data corrupted

$ claude "refactor auth"
Agent modified wrong branch :(

✓ The BranchBox Fix

One command creates a feature workspace. Keep code in separate worktrees, isolate configured services, and choose what to share.

✓ Dedicated git worktree & branch
✓ Compose identity for configured services
✓ Database naming where configured
✓ Configurable runtime boundaries for agents
✓ Copy or link devcontainer configurations
✓ Shared credentials where configured

# Example: configured full setup
$ branchbox feature start "Add OAuth"

✓ Worktree created
✓ Devcontainer ready
✓ Database naming configured
✓ Tunnel provisioned
✓ Agent launched

See the setup

The CLI reports what each feature's configured setup actually did

Terminal

# Initialize BranchBox in your repo
$ branchbox init
✓ Initialized BranchBox (Rails project)

# Start an isolated feature workspace
$ branchbox feature start "OAuth Integration"

🚀 Feature workspace ready (full)
  Feature: oauth-integration

+------------------+------------+------------------------------------------+
| Step             | Result     | Details                                  |
+------------------+------------+------------------------------------------+
| Worktree         | ✓ ready    | ../oauth-integration                     |
| Branch           | ✓ ready    | feature/oauth-integration                |
| Runtime          | ✓ chosen   | container                               |
| Adapter          | ✓ detected | Rails · http://localhost:3000            |
| Feature URL      | ✓ recorded | https://oauth-integration.example.com   |
| Compose project  | ✓ isolated | branchbox-oauth-integration              |
| .env             | ✓ copied   | ../oauth-integration/.env                |
| Tunnel           | ✓ recorded | cloudflared (*.trycloudflare.com)       |
| Modules          | ✓ ready    | 4 ok                                     |
| Default agent    | ✓ chosen   | Claude Code via `claude`                 |
+------------------+------------+------------------------------------------+

# Work in your isolated environment
$ cd ../oauth-integration
oauth-integration$ _

Illustrative CLI output. Modules, URLs, runtime behavior, and agent launch depend on your project settings and installed tools.

Native Mac app · Preview

Your feature workspaces, in one window

BranchBox for Mac uses the same CLI and feature registry as Terminal. Add projects, start features, open your tools, and review changes before teardown.

Explore the Mac app

Silent, 24-second recording of real CLI operations in a disposable project: Full feature setup and Python completing with Exit 0 in the devcontainer. Container startup happened separately between clips. Read the walkthrough.

Manage projects and features

A project sidebar, Quick Open, feature details, and attention states keep your worktrees easy to find.

Review and recover

Teardown plans show changes and branch safety. Activity records operation results and recovery options.

Use your existing tools

Open an editor, terminal, or coding agent. Start and stop container environments when Docker and the Dev Container CLI are ready.

Requires macOS 26+ and BranchBox CLI 0.13.4+. Preview bundles are ad hoc signed and not notarized. Some settings need newer CLI capabilities; SBX and Local VM controls have runtime-specific limits.

The workflow

From idea to isolated environment in one command

Initialize

branchbox init

One-time setup. Detects your stack (Rails, Node, Rust, etc.) and prepares the registry.

→

Start

branchbox feature start "..."

Creates a worktree and runs configured setup modules. Start services and run your application's database setup when needed.

→

Work

cd ../feature-name

Code, test, debug, or launch an agent in the feature workspace. Start its devcontainer when needed.

→

Teardown

branchbox feature teardown

Clean removal of worktree, containers, tunnel. Optional branch deletion.

What you get

Configure real development environments for parallel work

📦

True Isolation

Separate Git worktrees and Compose identities keep feature code and configured services apart. Choose the runtime boundary and shared mounts for your project.

💻

Real Dev Environments

Devcontainer configuration and Docker Compose with stack adapters for Rails, Node.js, Rust, and generic projects.

⚡

Parallel Workflows

Keep multiple feature workspaces available at once. Open their tools and inspect setup results without switching your main branch.

🤖

Agent-Ready

Save feature prompts and launch a configured coding agent. Each feature has its own worktree and recorded runtime.

🌐

Tunnels Built In

Cloudflare tunnels for external access. Share your feature with reviewers before it’s merged.

🛠

Pluggable Isolation

Use the default container workflow, experimental Docker Sandbox, or Firecracker Local VM on a supported Linux/KVM host.

Built for the agentic era

Keep an agent's feature work in a dedicated worktree. Choose a runtime boundary, record its prompt, and review the workspace before cleanup.

✓ Auto-launch agents — Set BRANCHBOX_DEFAULT_AGENT_CMD to spawn your agent automatically
✓ Capture context — Use --prompt to store agent hand-off instructions
✓ Configured credentials — Host-container templates can share tool credentials; managed in-guest runtimes use a separate credential boundary
✓ JSON output — --json flag for scripting and automation pipelines

# Configure your default agent
$ export BRANCHBOX_DEFAULT_AGENT_CMD="claude"

# Start feature with agent context
$ branchbox feature start "Fix auth bug" \
    --prompt "Investigate login failures in auth.rs"

🚀 Feature workspace ready (full)
  Feature: fix-auth-bug
  ...
🤖 Launching claude via `claude`
   (cwd: ../fix-auth-bug)

# Agent runs in the feature's configured context

Full CLI reference

Everything you need to manage parallel feature development

branchbox init

Initialize project with devcontainer and BranchBox registry. Detects stack automatically.

branchbox feature start <name>

Create a worktree and run configured devcontainer, Compose, database naming, spec, and tunnel setup.

branchbox feature list

Show all features with status, tunnel info, devcontainer sync state, and agent readiness.

branchbox feature teardown <name>

Clean removal of worktree, containers, and tunnel. Handles dirty worktree detection.

branchbox devcontainer sync

Propagate devcontainer changes from main worktree to all active features.

branchbox tunnel open <name>

Provision or re-provision a Cloudflare tunnel for external feature access.

branchbox detect

Show detected stack, adapter, and enabled modules for the current project.

branchbox agent status

Show control plane connection status and telemetry for the background agent.

Key flags

--minimal Skip heavyweight modules for quick spikes

--prompt "..." Store agent hand-off context

--json Machine-readable output for automation

--complete-spec Move spec to completed on teardown

--skip-module <mod> Skip specific modules

--dry-run Review teardown before changing files

Start building in parallel

Install BranchBox, set up a project, and create your first feature workspace.

brew install branchbox/tap/branchbox

Read the Docs View on GitHub