Getting started

Prerequisites

Banyan runs on macOS and Linux. Windows isn't supported — use WSL2.

Optional: Docker (compose stacks), gh / glab (merge against remotes), fzf (feature picker UI).

OpenRouter API key (free tier works) — required when you want bn wt -p "<prompt>" to auto-name the branch from the prompt. Not needed if you always pass an explicit feature name. Set via the OPENROUTER_API_KEY env var or in ~/.config/banyan/config.yaml under llm.openrouterApiKey.

Install

npm install -g banyan-cli
bn doctor

Doctor walks every requirement and prints exactly what's missing plus the command to fix each thing. Run it any time the setup feels off.

The npm package is named banyan-cli because the unscoped banyan name was already taken on the registry. The installed binary is bn (with banyan as an alias) — same name, same behaviour.

On first bn init, banyan renders ~/.config/banyan/banyan.tmux.conf and offers to wire it into your ~/.tmux.conf. Say yes once and the Alt-shortcuts are live forever.

Install from source (for contributors)

git clone https://github.com/LoicBch/banyan-cli
cd banyan-cli && npm install && npm run build && npm link

Your first project

Two paths — pick one.

Via the dashboard wizard

bn serve
# http://localhost:4242 → "+ new project"

The wizard walks you through naming the project, adding repos (with tech auto-detection), and saving the config.

Via the CLI + dashboard

cd ~/my-frontend-repo
bn init my-project                  # bootstraps with the cwd as first repo
bn serve                            # open the dashboard, add remaining repos there
bn ls                               # check the lot

bn init is the only CLI config command — every other mutation (add/remove repo, set base branch, edit run command) goes through the dashboard Config tab or direct YAML editing.

Open the workspace

bn my-project start

You're now in a tmux session with two panes: the project orchestrator (Claude with --add-dir on every repo) and a free terminal for ad-hoc commands.

Spin up a feature

bn my-project wt my-feature

This:

• Creates a worktree in every repo on branch feature/my-feature
• Seeds gitignored files (.env.local, etc.) into each worktree
• Spawns a Claude agent with --add-dir on all worktrees
• Starts compose stacks for the feature (on dynamically-allocated ports)

Run it

bn my-project start my-feature

Each repo's run command spawns in its own tmux pane, with its allocated port + env vars injected.

Merge and clean

bn my-project merge my-feature
bn my-project cleanup my-feature

Done. Read Concepts next for the mental model, or jump to Commands for the full reference.