banyan

Top-level

bn ls                                 list all projects
bn init <project>                     create a project (registers cwd as the first repo)
bn doctor                             check the environment is ready: node, tmux, git,
                                      claude CLI, gh, glab, OpenRouter key, config.
bn serve [opts]                       web dashboard
  -p, --port <n>                      port to bind (default: first free from 4242)
  --no-open                           don't open the browser
  --remote                            expose via HTTPS tunnel (Cloudflare/ngrok) with
                                      token auth + QR code. See [Remote access](/docs/remote).
  --tunnel <provider>                 force cloudflared | ngrok
  --rotate-token                      regenerate the auth token (invalidates old QRs)

Run bn doctor first on a fresh machine — it prints exactly what's missing and the command to fix each thing.

Per-project workflow

The six commands you'll use every day. All accept a [feature] arg that's optional from inside a worktree (banyan infers from cwd).

bn <project> wt <feature>             create worktrees in every repo +
                                      spawn the agent pane
bn <project> wt -p "<prompt>"         same, but OpenRouter generates the
                                      branch name from the prompt and the
                                      prompt becomes the agent's first
                                      message (mode: delegated)

bn <project> start [feature]          launch the workspace (no feature)
                                      or run the dev stack for a feature
bn <project> stop [feature]           stop run processes
bn <project> merge [feature]          rebase + push + MR/PR + auto-resolve
                                      cross-feature conflicts
bn <project> cleanup [feature]        full teardown: stop tests + remove
                                      worktree + delete branch + drop
                                      compose volumes
bn <project> wt-rm [feature]          remove worktree only (keeps the
                                      branch local + remote)

Agent modes:

live — conversational, no ceremony. Banyan-aware claude, you drive. Default when no prompt.
delegated — pipeline-gated: Setup → Plan → human review → Execute → Report → Done. Loops via Stop hook. Default when -p is given.

Other commands exist for the long tail (rebase, status, resume, restart-orchestrator, ports, close, …). Run bn <project> --help for the full list with flags.

By default bn wt <name> creates feature/<name> — convenient when you're starting fresh, less so when the branch already exists under a different naming convention. Two knobs cover the common cases.

`--prefix` to match your team's convention

bn <project> wt <feature> [--prefix <p>]

The prefix replaces the default feature segment:

Your existing branch	What to run
`feature/login`	`bn wt login`
`fix/crash-on-startup`	`bn wt crash-on-startup --prefix fix`
`android/refactor/ui-setup`	`bn wt ui-setup --prefix android/refactor`
`hotfix-truc` (no prefix)	`bn wt hotfix-truc --prefix ""`

Multi-segment prefixes (android/refactor) are supported.

Existing-branch fallback

When the computed branch name (<prefix>/<feature>) already exists in the repo, banyan checks it out as-is rather than failing. So spawning a worktree on a branch you already pushed earlier just works:

git checkout main
bn p4n wt ui-setup --prefix android/refactor
# branch 'android/refactor/ui-setup' already exists
# → worktree is created from that branch, no new commit, no rewrite

The agent then sees the existing branch's contents and the worktree runs in parallel to any other features.

Pitfalls

"branch is already checked out elsewhere" — git refuses to put the same branch in two worktrees at once. If the branch is currently checked out in your main repo or in another worktree, switch the other one off it first (git switch main) and retry. The reverse also applies: don't git switch to a feature's branch in the main checkout while a banyan worktree is using it.
Stale worktrees from pre-v1 layouts — banyan used to put worktrees in <repo>-<feature>/ sibling folders. v1 uses worktree-<repo>/<feature>/ under the repo's parent. If you still have a sibling-style worktree on the same branch, banyan can't reuse it (the name doesn't match the convention). Either move it with git worktree move <old> <new> or remove it (git worktree remove --force <old>) before re-spawning.
Cleanup is destructive — bn cleanup <feature> removes the worktree AND deletes the branch. Use bn wt-rm <feature> if you only want to drop the worktree but keep the branch local + remote.

Compose stacks

bn <project> env ls
bn <project> env up <feature>
bn <project> env down <feature>         keeps volumes
bn <project> env recreate <feature>     wipe volumes + restart
bn <project> env logs <feature> [service]
bn <project> env exec <feature> <service> [cmd…]

CWD inference

Inside a configured repo (or worktree, or parent), drop the project name — banyan infers from cwd:

cd ~/Dev/myproject
bn wt login              # ≡ bn myproject wt login
 
cd ~/Dev/myproject/worktree-front/login
bn start                 # ≡ bn myproject start login

Or symlink to skip the project arg entirely:

ln -s "$(which banyan)" ~/.local/bin/myproject
myproject start
myproject wt login

Commands