Multi-repo worktree isolation for Claude Code.
your-project/
├── app/ ← Claude Code isolates this with /worktree ✅
├── sdk/ ← Still shared. Your changes leak out ❌
└── common/ ← Still shared. Your changes leak out ❌
Claude Code's worktree only isolates the main repo. Associated repos stay on the original branch — edits bleed into everyone's workspace.
cl add ../sdk ../commonyour-project/
├── app--feat-avatar/ ← Your isolated workspace
├── sdk--claude-feat-avatar/ ← ✅ Auto-created
└── common--claude-feat-avatar/ ← ✅ Auto-created
Original sdk/ and common/ are untouched. Run cl clean when you're done.
curl -fsSL https://raw.githubusercontent.com/kevinaimonster/claude-forest/main/install.sh | bash
source ~/.zshrc # or source ~/.bashrcRequires Bash 4.0+ and Git 2.20+. macOS users:
brew install bashfirst.
# Step 1: Start a Claude Code worktree (via /worktree or claude --worktree)
# Step 2: Isolate associated repos
cl add ../sdk
# Step 3: Clean up when done
cl cleancl add auto-stashes dirty state, picks the base branch, creates the worktree, and copies the /add-dir command to your clipboard.
Use slash commands without leaving the session:
/forest-add ../sdk
/forest-list
/forest-clean
| Action | Terminal | In Session |
|---|---|---|
| Create isolated worktree | cl add ../sdk |
/forest-add ../sdk |
| Batch create | cl add ../sdk ../common |
— |
| Specify base branch | cl add ../sdk -b develop |
/forest-add ../sdk --branch develop |
| List all worktrees | cl list |
/forest-list |
| Clean up | cl clean |
/forest-clean |
| Clean stale (14 days) | cl clean --stale |
— |
| Undo last add | cl undo |
— |
| Dry run | cl add ../sdk --dry-run |
— |
| Health check | cl doctor |
— |
| Disk usage | cl df |
— |
| Audit log | cl log |
— |
Full reference: cl --help or man claude-forest.
What happens when you run cl add ../sdk:
- Detects if you're inside a worktree (if not, falls back to
/add-dir) - Auto-stashes any dirty state in the target repo
- Prompts for the base branch (auto-selects default branch in CI)
- Runs
git worktree addto create the isolated worktree - Detects and handles submodules, git-lfs, and pre-commit hooks
- Silently restores the target repo's original state
- Copies the
/add-dircommand to your clipboard
Every step is transactional — if anything fails or you hit Ctrl+C, all intermediate state is rolled back automatically.
1. Transaction Safety
Signal-safe rollback on failure or interruption. Failed rollbacks are persisted to pending-cleanup and auto-retried on the next run.
2. Batch Mode
cl add ../repo1 ../repo2 ../repo3 — isolate multiple repos in one command with [N/M] progress tracking.
3. CI Integration
Tag worktrees with --tag ci_job=$RUN_ID, then clean by tag. Auto-detects CI environments (GitHub Actions, GitLab CI, Jenkins).
4. Hook System
Pre/post hooks for add and clean operations. Place scripts in .claude-forest/hooks/. 30s timeout, skippable with --no-hooks.
5. Audit & Recovery
JSON audit log with filtering (--action, --since, --stats). cl doctor diagnoses issues, cl repair fixes them automatically.
6. Dry-Run & Verbose
Preview any destructive operation with --dry-run. Debug internals with --verbose.
| Variable | Default | Description |
|---|---|---|
CF_MIN_DISK_MB |
100 |
Minimum free disk space (MB) before creating worktrees |
CLAUDE_FOREST_ALIAS |
cl |
Custom shell function name |
CLAUDE_FOREST_HOME |
$HOME |
Data directory (registry, audit log, hooks) |
CLAUDE_FOREST_SKIP_PERMISSIONS |
— | Skip Claude Code permission prompts |
| File | Location | Purpose |
|---|---|---|
claude-forest |
~/.local/bin/ |
Main executable |
forest-*.md |
~/.claude/commands/ |
Slash commands for Claude Code |
cl function |
~/.zshrc / ~/.bashrc |
Shell shortcut |
claude-forest.1 |
~/.local/share/man/man1/ |
Man page |
| Shell completions | ~/.local/share/claude-forest/ |
Tab completion |
Uninstall: claude-forest uninstall
# Run tests (requires bats-core)
brew install bats-core # macOS
bats test/claude-forest.bats
# Local install for testing
bash install.sh --local ./claude-forestMIT