rimba

README

rimba

A CLI tool to create, sync, merge, and organize git worktrees — so you can work on multiple branches in parallel without the hassle.

rimba automates the full git worktree lifecycle — branch naming, file copying, dependency sharing, post-create hooks, and cleanup — so you can develop across multiple branches simultaneously with zero friction.

---

Table of Contents

• Features
• Installation
  • Verifying releases
• Quick Start
• Commands
• Configuration
• Trust model
• Troubleshooting
• Contributing
• License

Features

🌿 Core Workflow

• Automatic branch naming — fixed prefix types (feature/, bugfix/, hotfix/, docs/, test/, chore/) selected per task via flags
• File & directory copying — rimba init auto-detects gitignored local files and dirs (.env, .claude, .vscode, etc) and copies them into new worktrees; falls back to a sensible default set when nothing is detected
• Duplicate worktrees — copy an existing worktree with auto-suffixed or custom name
• Local merge — merge worktree branches into main or other worktrees with auto-cleanup
• Sync worktrees — rebase or merge onto the latest main branch, with bulk sync support
• Monorepo support — service-scoped worktrees with auto-detected 3-segment branch naming (service/prefix/task)

🔧 Automation

• Shared dependencies — auto-detect lockfiles and clone dependency directories using copy-on-write
• Post-create hooks — run shell commands after worktree creation (e.g. ./gradlew build)
• Auto-cleanup hook — post-merge Git hook that cleans merged worktrees after git pull
• Stale cleanup — prune stale references or auto-detect and remove merged worktrees

🖥️ Developer Experience

• Status dashboard — colored tabular view with dirty state, ahead/behind counts, and filtering
• Pre-execution hints — shows available flags before long-running commands, auto-filtered and suppressible
• Worktree navigation — open worktrees or run commands inside them via open
• Shell completions — bash, zsh, fish, and PowerShell
• Cross-platform — Linux, macOS, and Windows (amd64/arm64)

Installation

Quick install (Linux/macOS)

curl -sSfL https://raw.githubusercontent.com/lugassawan/rimba/main/scripts/install.sh | bash

By default the binary is installed to $HOME/.local/bin. Set INSTALL_DIR to install elsewhere:

curl -sSfL https://raw.githubusercontent.com/lugassawan/rimba/main/scripts/install.sh | INSTALL_DIR=/usr/local/bin bash

Go install

go install github.com/lugassawan/rimba@latest

Build from source

git clone https://github.com/lugassawan/rimba.git
cd rimba
make build
# Binary is at ./bin/rimba

Verifying releases

Each release publishes a checksums.txt signed with cosign keyless signing (Sigstore OIDC via GitHub Actions). To verify a downloaded checksum file:

cosign verify-blob \
  --certificate checksums.txt.pem \
  --signature checksums.txt.sig \
  --certificate-identity-regexp 'https://github.com/lugassawan/rimba/.github/workflows/release.yml@refs/tags/v.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  checksums.txt

Each release archive also ships a companion *.sbom.json (SPDX format) on the GitHub Release page.

Quick Start

# Initialize rimba in your repo
rimba init

# Create a worktree for a task
rimba add my-feature

# List all worktrees with status (colored output)
rimba list

# Remove a worktree and its branch when done
rimba remove my-feature

Commands

Command	Description
rimba init	Initialize rimba in the current repo; with --agents also installs team agent files, --agents --local for personal agent files, -g/--global for user-level installation, all registering the MCP server
rimba add <task>	Create a new worktree with auto-prefixed branch (service/task for monorepos), or pr:<num> to create one from a GitHub PR
rimba remove <task>	Remove a worktree and delete its branch
rimba rename <old> <new>	Rename a worktree's task, branch, and directory
rimba duplicate <task>	Create a copy of an existing worktree
rimba archive <task>	Archive a worktree (remove directory, keep branch)
rimba restore <task>	Restore an archived worktree from its preserved branch
rimba list	List worktrees (compact by default; --full for all columns)
rimba status	Show worktree dashboard; --detail adds disk size, 7-day commit velocity, and disk-footprint summary
rimba log	Show last commit from each worktree, sorted by recency
rimba open <task>	Open a worktree or run a command inside it
rimba merge <task>	Merge a worktree branch into main or another worktree
rimba sync <task>	Rebase or merge a worktree onto the latest main
rimba merge-plan	Recommend optimal merge order to minimize conflicts
rimba conflict-check	Detect file overlaps between worktree branches
rimba exec <command>	Run a shell command across worktrees
rimba hook install	Install post-merge and pre-commit hooks
rimba hook uninstall	Remove the rimba hooks
rimba hook status	Show whether the rimba hooks are installed
rimba deps status	Show detected dependency modules for all worktrees
rimba deps install <task>	Detect and install dependencies for a worktree
rimba clean	Prune stale references or remove merged/stale worktrees
rimba doctor	Diagnose and remove stale git index.lock files left by killed worktree operations; --fix deletes them
rimba update	Check for updates and replace the binary in place; reminds you to refresh agent files after a successful update
rimba version	Print version, commit, build date, and platform info (os/arch/go)
rimba mcp	Start MCP server for AI tool integration
rimba completion	Generate shell completion scripts (bash, zsh, fish, powershell)

See docs/commands.md for the full reference with all flags, examples, and notes.

Configuration

rimba init creates a .rimba/ directory with team-shared and personal config files. copy_files is auto-detected from gitignored local files present in the repo (falling back to a default set when none are found); example team config:

copy_files = ['.env', '.env.local', '.envrc', '.tool-versions', '.vscode']
post_create = ['./gradlew build']

[open]
ide = 'code .'
agent = 'claude'

See docs/configuration.md for the full field reference, dependency management, and environment variables.

Running rimba init --agents or rimba init -g additionally creates or patches MCP server config files in client tools (.mcp.json, .cursor/mcp.json, ~/.claude.json, and others). See docs/configuration.md#mcp-server-registration for the full list of patched files and entry format.

Trust model

.rimba/settings.toml is committed and team-shared. The following fields execute shell commands verbatim via sh -c:

• post_create — runs after a worktree is created (e.g. rimba add, rimba duplicate, rimba restore)
• post_rename — runs after a worktree is renamed (rimba rename)
• deps.modules[].install — runs when installing dependencies into a worktree

Consent gate

rimba will not execute committed shell commands until you have explicitly approved them. On the first run in a new clone (or whenever the command set changes), rimba prints the commands and prompts for consent:

This repo's .rimba/settings.toml will run shell commands that have not been approved:
  pnpm install
  ./scripts/setup.sh

Run these commands? [y/N]

Approval is stored locally in .rimba/trust.local.toml (covered by the .rimba/*.local.toml gitignore glob — each user consents independently). The approval is keyed by a hash of the command set; changing any command re-arms the gate.

Pre-approve without prompting (e.g. for rimba trust after reviewing settings, or in CI):

rimba trust           # review and approve interactively
rimba trust --yes     # approve without prompt (non-interactive)
rimba trust --show    # inspect commands and current approval status

CI / non-interactive environments: pass --yes or set RIMBA_TRUST_YES=1:

RIMBA_TRUST_YES=1 rimba add my-task
rimba add my-task --yes

As a defense-in-depth measure, the copy_files entries and deps.modules[].lockfile paths are validated to stay within the worktree directory — paths that escape via .. are rejected with an error. Note that worktree_dir is intentionally not subject to this constraint, because its default value (../<repo>-worktrees) is itself a ../-relative path.

Global flags

Flag	Description
--json	Output in JSON (where supported: list, status, deps status, conflict-check, exec)
--no-color	Disable colored output (also respects NO_COLOR)
--debug	Log git commands and timings to stderr (also respects RIMBA_DEBUG=1)

Troubleshooting

Hit an error? rimba prints an actionable To fix: hint with most failures. Common errors — trust-gate prompts, exec scope, dirty-worktree sync blocks, init/config issues — are documented with cause and fix in the troubleshooting guide.

See docs/troubleshooting.md for the full troubleshooting reference.

Pass --debug to any command (or set RIMBA_DEBUG=1) to log git commands and their timings to stderr:

rimba list --debug

License

MIT