bonsai
Skill22 starsChanged 2 months agoMITView on GitHub
Manage git worktrees with the bonsai CLI - create isolated per-branch worktrees outside the repo, jump between them, and clean up merged ones. Use when starting commit, push, or pull-request work, isolating a branch, parallelizing tasks across worktrees, or tidying up worktrees and branches.
- Reads credentials
- Commits and pushes
In this repository9 other files it gives its agents.
- .agents/AGENTS.mdAGENTS.md
- AGENTS.mdAGENTS.md
- blueprintSkill
- commitSkill
- handoutSkill
- pullrequestSkill
- pushSkill
- squashSkill
- typesafe-aiSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Run bonsai from anywhere inside the repo — the main checkout or any worktree — it always operates on the repository as a whole.
- Distinctive: line 49
Before leaving the source checkout, record its absolute path, branch, HEAD, upstream and remotes, staged and unstaged changes, and intended …
- Distinctive: line 58
Verify the destination matches the intended source changes before staging.
- Very specific: line 77
Never pass --force without explicit authorization to discard the affected work.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
bonsai — centralized git worktrees
Mental model
- Worktrees live outside the repository at
<root>/<repo-id>/<branch>(default root~/.bonsai). Branch names nest:feat/x→feat/x/. - Run bonsai from anywhere inside the repo — the main checkout or any worktree — it always operates on the repository as a whole.
addslugifies branch inputs segment-by-segment while preserving/as a nested branch/path delimiter, creates branches automatically, and fetches the remote default branch first. Missing arguments open fuzzy pickers on a real terminal only; in non-interactive use, always pass arguments or the command exits with an error.
Core workflow
path=$(bonsai add <branch>) # create or reuse; prints absolute path; idempotent
cd "$path" # then work inside the worktree
bonsai add <branch> --base HEAD # stack on the checkout you run it from
bonsai list --json # this repo's worktrees, machine-readable
bonsai remove <branch> [-d] # drop the worktree (keep branch unless -d)
bonsai clean --dry-run --json # inspect merged/squash-merged/gone branches
bonsai clean --yes # then executeInvariants you would otherwise get wrong
--baseresolves against the directory bonsai runs from, not the main checkout:--base HEADinside a worktree stacks on that worktree.- New branches carry no upstream (
--no-track) until first push. - A fresh worktree with zero commits already counts as "merged", so
cleanwill list it — read the plan before executing. - Untracked local config (
.env*,.envrc,.mcp.json,CLAUDE.local.md, ...) is copied into new worktrees automatically. - Dependencies are installed automatically in new worktrees when a lockfile
is present (pnpm/npm/yarn/bun/cargo/uv, lockfile-frozen); a missing tool is
skipped and an install failure never aborts
add— check stderr before assuming deps are in place. Follow any linked package-manager configuration warning to enable its worktree-optimized shared store.
Existing-work handoff
- Before leaving the source checkout, record its absolute path, branch, HEAD, upstream and remotes, staged and unstaged changes, and intended untracked files. Resolve an existing pull request against this source branch.
- Reuse a bonsai worktree only when it contains the intended branch and work.
For a new task branch, use
bonsai add ab/<slug> --base <source-head>; the default branch is not a substitute for the captured source HEAD. - For commit or pull-request work, copy the intended tracked changes and untracked files into the destination without changing the source files or index. Preserve binary contents, deletions, symlinks, and executable bits. Verify the destination matches the intended source changes before staging; do not overwrite concurrent or unrelated destination work.
- For push-only work, leave pending source changes in place. Carry the source branch's synchronization upstream and separately resolved Git push destination across the handoff; these may differ in a fork workflow. A temporary task branch must not silently become the branch being published.
- Recheck the source HEAD and pending changes before publishing. If they changed concurrently, stop and reconcile the intended work before continuing. Report the source and destination paths; never silently clear the original checkout.
Destructive-command policy
- Inspect first, then act:
bonsai clean --dry-run --json, review, thenbonsai clean --yes. Same forprune(--yesskips confirmation). Check that every target is within the requested cleanup; retain unfinished work even when bonsai labels it merged. - An explicit request to clean up the reviewed targets authorizes
--yes; the user need not name the flag or repeat prior authorization. If the plan includes other targets, narrow the operation or ask about those targets. - Never pass
--forcewithout explicit authorization to discard the affected work.cleannever touches dirty worktrees;removerefuses them without--force.
Flags drift; this file does not. Trust bonsai <cmd> --help for the exact
current interface.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

