Interactive CLI for managing git worktrees and configs
npm install yggtree
Yggdrasil Worktree (invoked as yggtree) is an interactive CLI designed to turn Git worktrees into a first‑class workflow.
Like the mythical world tree connecting realms, Yggdrasil lets you grow isolated, parallel environments where ideas can evolve independently without colliding.
---
Run without installing:
``bash`
npx yggtree
Or install globally:
`bash`
npm install -g yggtree
Run with no arguments to open the interactive menu:
`bash`
yggtree
Or use commands directly:
`bash`
yggtree wt create
yggtree wt list
yggtree wt enter my-feature
---
Yggdrasil is built around a few core ideas:
* Branches are ideas
* Worktrees are realities
* Each task deserves its own realm
Instead of constantly switching branches in one working directory, Yggdrasil creates isolated worktrees, each mapped to a branch, living outside your main repo.
All managed worktrees live under:
`
~/.yggtree/
This keeps your main repository clean while enabling true parallelism.
---
Git worktrees are powerful, but once you start doing parallel work, they become tedious to manage manually.
Modern development looks like this:
* Fixing a bug
* Reviewing a PR
* Prototyping a feature
* Letting AI agents explore refactors
* Running tests in isolation
All at the same time.
Yggdrasil exists to solve three problems together:
1. Parallel work without context collision
2. Fast, repeatable environment setup
3. Agent‑friendly isolation for AI workflows
Each worktree becomes its own small realm, safe to explore and easy to discard.
---
🌳 First-class worktree workflow
Create, manage, and navigate Git worktrees as a primary workflow, not an afterthought.
🧠 Parallel development by default
Work on multiple branches at the same time, each in its own isolated environment.
🧪 Sandbox worktrees for experimentation
Prototyping something risky? Create a sandbox with a random name, try different strategies, and apply the winner back to your origin branch.
🤖 AI-friendly isolation
One worktree per agent, per experiment, per idea. No shared state, no collisions.
⚡ Automatic bootstrapping
Run installs, submodules, and setup scripts automatically for each worktree.
🚪 Enter, exec, and exit with ease
Enter worktrees, execute commands, or run tasks without changing directories.
📍 Predictable structure
All managed worktrees live under ~/.yggtree, keeping your repository clean.
🧭 Interactive or scriptable
Use the interactive UI or drive everything through commands and flags.
---
`bash`
yggtree wt create feat/eng-2581-state-selection
yggtree wt create fix/eng-2610-validation
yggtree wt create chore/cleanup-api
Each command creates:
* A clean folder
* A dedicated branch
* A bootstrapped environment
No stash juggling.
No branch confusion.
No shared state accidents.
---
Yggdrasil shines when paired with AI agents.
Instead of running agents against the same directory, you can assign one worktree per agent.
`bash`
yggtree wt create feat/ai-refactor-a --exec "cursor ."
yggtree wt create feat/ai-refactor-b --exec "codex"
Each agent operates in its own realm:
* Model A refactors architecture
* Model B focuses on tests
* Model C explores performance
All in parallel. All reviewable. All isolated.
---
Sometimes you don't want to "commit to a branch" yet. You just want to try something out—or perhaps try three different ways of solving the same problem.
Sandboxes are temporary, local-only worktrees designed for this:
1. Create: yggtree wt create-sandbox (creates branch_qes2).yggtree wt apply
2. Experiment: Change files, run tests, try that risky refactor.
3. Apply: to "push" those file changes back to your origin directory.yggtree wt unapply
4. Unapply: Don't like it? restores your origin to exactly how it was before.
Sandboxes are not pushed to remote and their names are randomly generated because they are meant to be temporary playgrounds.
---
Yggdrasil automatically prepares each worktree.
Resolution order:
1. yggtree-worktree.json inside the worktreeyggtree-worktree.json
2. in the repo root.cursor/worktrees.json
3.
4. Fallback: + submodules
`json`
{
"setup-worktree": [
"npm install",
"git submodule sync --recursive",
"git submodule update --init --recursive",
"echo \"🌳 Realm ready\""
]
}
---
Open the interactive menu.
---
Create a worktree from a branch.
Options:
* --base
*
*
*
*
Example
`bash`
yggtree wt create feat/new-ui --base main --exec "cursor ."
---
Create a temporary sandbox from your current local branch.
Options:
* --carry / --no-carry: Bring uncommitted changes (staged/unstaged/untracked) with you.--no-bootstrap
*
*
*
---
Apply changes from the current sandbox back to the origin repository.
* Backs up origin files before overwriting.
* Offers to delete the sandbox after applying.
---
Undo a previous apply operation.
* Restores origin files from the sandbox's backup.
Note: Only works if the sandbox worktree still exists.*
---
Create multiple worktrees at once.
Example
`bash`
yggtree wt create-multi --base main
---
List all worktrees with state.
Columns:
* TYPE (MAIN / MANAGED)
* STATE (clean / dirty)
* BRANCH
* PATH
---
Enter a worktree using a sub‑shell.
* Uses your default shell
* Type exit to return
Optional:
* --exec "
Example
`bash`
yggtree wt enter feat/new-ui --exec "npm test"
---
Run a command inside a worktree without entering.
Example
`bash`
yggtree wt exec feat/new-ui -- npm test
---
Print a cd command for a worktree.
Useful for scripting and shell aliases.
---
Re‑run bootstrap commands for a worktree.
---
Interactively delete managed worktrees.
---
Clean up stale git worktree metadata.
---
Yggdrasil is ideal when:
* You work on multiple tasks in parallel
* You use AI agents for exploration
* You want isolation without duplication
* You value scripted, repeatable setups
* git checkout no longer scales
---
Create a worktree and enter it immediately
Command:
`
yggtree wt create feat/login-flow
What happens:
* Creates a new branch if it doesn’t exist
* Creates a dedicated worktree
* Runs bootstrap if enabled
* Drops you into a sub-shell inside the worktree
---
Create a worktree without bootstrap and without entering
Command:
`
yggtree wt create feat/cleanup-api --no-bootstrap --no-enter
When to use:
* You just want the folder ready
* You’ll enter it later
* You don’t want installs running automatically
---
Create a worktree and open it in your IDE
Command:
`
yggtree wt create feat/ui-refactor --exec "cursor ."
Works with:
* cursor .
*
*
* Any custom command available in your shell
---
Execute a command inside an existing worktree (no shell)
Command:
`
yggtree wt exec test -- npm test
What this does:
* Runs the command inside the selected worktree
* Does not enter a sub-shell
* Ideal for CI-like checks, scripts, or quick validations
---
Enter a worktree and run a command before entering
Command:
`
yggtree wt enter test --exec "codex"
What happens:
* Executes the command inside the worktree
* Then drops you into a sub-shell
* Type exit to return to your original directory
---
Get the path to a worktree
Command:
`
yggtree wt path test
Output:
`
cd ~/.yggtree/your-repo-name/test
Useful when you want to manually navigate or copy the path into scripts.
---
Try a risky refactor in a Sandbox
Command:
`bash`
yggtree wt create-sandbox --carry
Scenario:
1. You have 5 files changed in your main repo but aren't sure about the direction.
2. Run create-sandbox --carry to move those changes into an isolated current-branch_a1b2 folder.yggtree wt apply
3. Experiment freely.
4. If it works: .unapply`.
5. If it fails: Just delete the sandbox or
---
Branches are ideas.
Worktrees are realities.
Yggdrasil helps you grow many worlds and decide later which ones deserve to merge.
---
MIT License.