🌳 Yggdrasil Worktree (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.

For guided workflows, command examples, and safety notes, read the full docs: yggtree.logbookfordevs.com/docs.

🚀 Quick Start

Installation

Install globally:

npm install -g yggtree

Or try it without installing:

npx yggtree

Agent Skills

An agent skill is now available for your favorite agents.

yggtree ships one consolidated skill that helps agents choose the right worktree workflow first, then load the smallest reference they need:

• Create a task worktree: start a brand-new branch-backed task in parallel.
• Branch off without stashing: jump into another branch without disturbing the work already in progress.
• Bootstrap and use a realm: prepare a worktree, open it in your IDE, or run commands inside it.
• Run sandbox experiments: try alternative approaches locally and apply/unapply the winner safely.

This skill is especially useful with agents like Claude Code, Codex, Cursor, Gemini CLI, and other tools that support the open Skills ecosystem.

Install it with the Skills CLI:

npx skills add logbookfordevs/yggdrasil-worktree

Install it globally for your user:

npx skills add logbookfordevs/yggdrasil-worktree --global

Install only the consolidated yggtree skill:

npx skills add logbookfordevs/yggdrasil-worktree --skill yggtree

If your agent supports targeted installs, you can also point the install to a specific agent runtime, for example:

npx skills add logbookfordevs/yggdrasil-worktree --agent codex

Basic Usage

Run with no arguments to open the interactive menu:

yggtree

Or use commands directly:

yggtree create
yggtree list
yggtree wc --ref my-feature
yggtree -v

The older yggtree wt ... form still works for compatibility, but direct commands are the preferred shape.

🧠 Mental Model

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/<repo-name>/<worktree-slug>

This keeps your main repository clean while enabling true parallelism.

🤔 Why Yggdrasil Worktree?

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.

✨ Key Features

🌳 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, try different strategies, and apply the winner back to your origin branch.

🤝 Handoff current work Started in your main checkout? Carry staged, unstaged, and untracked work into a named sandbox worktree and continue there.

🤖 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.

🧠 Parallel Development, Done Right

yggtree create feat/city-selection
yggtree create fix/validation
yggtree 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.

🤖 Built for AI‑Assisted Workflows

Yggdrasil shines when paired with AI agents.

Instead of running agents against the same directory, you can assign one worktree per agent.

yggtree create feat/ai-refactor-a --exec "cursor ."
yggtree 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.

🧪 Sandbox Worktrees

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 create-sandbox (creates something like sandbox-a3f2_feature-branch).
2. Experiment: Change files, run tests, try that risky refactor.
3. Apply: yggtree apply to "push" those file changes back to your origin directory.
4. Unapply: Don't like it? yggtree unapply restores your origin to exactly how it was before.

Sandboxes are not pushed to remote. Omit the name for a generated temporary sandbox, or provide one when the work needs to be easy to find later.

Use handoff when you started in the origin checkout and want to continue that dirty work in a sandbox:

yggtree handoff --name auth-refactor

⚡ Bootstrapping & Configuration

Yggdrasil automatically prepares each worktree.

Resolution order:

1. .yggtree/worktree-setup.json in the repo root
2. yggtree-worktree.json in the repo root (legacy fallback)
3. .cursor/worktrees.json in the repo root (legacy fallback)
4. .yggtree/worktree-setup.json inside the worktree (per-worktree fallback)
5. yggtree-worktree.json inside the worktree (legacy fallback)
6. .cursor/worktrees.json inside the worktree (legacy fallback)
7. Fallback: npm install + submodules

Example configuration

{
  "setup-worktree": [
    "npm install",
    "git submodule sync --recursive",
    "git submodule update --init --recursive",
    "echo \"🌳 Realm ready\""
  ]
}

🛠️ Command Reference

yggtree

Open the interactive menu.

yggtree create [branch]

Create a worktree from a branch.

Options:

• -b, --branch <name>
• --base <ref>
• --source local|remote
• --no-bootstrap
• --open / --no-open
• --enter / --no-enter
• --exec "<command>"

Interactive flow:

• Instead of asking for a free-form exec command, yggtree now asks if you want to open an editor after creation.
• After creation, yggtree enters the new worktree shell unless you pass --no-enter.
• --exec remains available as an advanced explicit override.

yggtree create feat/new-ui --base main --exec "cursor ."

yggtree worktree-checkout [name] [ref]

Create a checkout-style worktree from an existing branch.

Behavior:

• Prompts a searchable branch picker (type to filter in real time).
• Attaches the new worktree directly to the selected branch (checkout-style).
• If a branch exists both locally and on origin, the picker shows both branch (local) and origin/branch (remote tip, detached) as explicit choices.
• If you select a remote-only branch (origin/*), yggtree creates the local branch in the new worktree automatically.
• If that branch already has an active worktree, yggtree falls back to using that worktree instead of creating a duplicate.
• By default, yggtree ends the flow inside the worktree shell.
• yggtree wc is a short alias for the same flow.

Options:

• -n, --name <slug>
• -r, --ref <ref>: skip picker and use a specific branch (feature/x or origin/feature/x)
• --no-bootstrap
• --open / --no-open: choose whether to open editors or run a startup command before the worktree shell starts
• --tool <command>: open a specific editor, app, or terminal target and skip the open prompt (cursor, code, codex-app, cmux, tmux)
• --no-enter: finish after create/open and return to the caller
• --exec "<command>"

Interactive flow:

• Yggtree asks what to open before starting the worktree shell.
• Shell-entry flows use a single action picker, so pressing Enter on Cmux or Tmux chooses that terminal target directly.
• Plain yggtree open flows use the same single action picker and return after opening the selected target.
• Use --tool to skip the open prompt and launch one editor/app or terminal target directly.
• Cmux, Tmux, and Other command... are mutually exclusive because the open picker accepts one action.
• Other command... runs a command in the Yggtree shell first, then leaves you there.
• Use --no-enter when you only want the worktree created/opened and the command to return.
• --exec remains available as an advanced explicit override.

yggtree worktree-checkout -n hotfix-auth -r main --no-open
yggtree wc hotfix-auth main --open
yggtree wc hotfix-auth main --tool codex-app
yggtree wc hotfix-auth main --open --no-enter

yggtree create-sandbox

Create a temporary sandbox from your current local branch.

Options:

• -n, --name <name>: Optional sandbox name (auto-generated if omitted).
• --carry / --no-carry: Bring uncommitted changes (staged/unstaged/untracked) with you.
• --no-bootstrap
• --open / --no-open
• --exec "<command>"

Interactive flow:

• Prompts for an optional sandbox name (leave empty to auto-generate one from current branch).
• Instead of asking for a free-form exec command, yggtree now asks if you want to open an editor after creation.
• --exec remains available as an advanced explicit override.

yggtree handoff

Carry uncommitted work from the current checkout into a sandbox worktree.

Options:

• -n, --name <name>: Optional handoff name (prompted when omitted).
• --no-bootstrap
• --open / --no-open
• --exec "<command>"

This is the continuation-focused version of create-sandbox --carry: it keeps sandbox metadata and apply/unapply behavior, but defaults to carrying staged, unstaged, and untracked files.

yggtree apply

Apply changes from the current sandbox back to the origin repository.

• Backs up origin files before overwriting.
• Offers to delete the sandbox after applying.

yggtree unapply

Undo a previous apply operation.

• Restores origin files from the sandbox's backup.
• Note: Only works if the sandbox worktree still exists.

yggtree create-multi

Create multiple worktrees at once.

Options:

• --base <ref>
• --source local|remote
• --no-bootstrap

yggtree create-multi --base main

yggtree list

List all repo-linked worktrees with state.

Columns:

• TYPE (MAIN, MANAGED, LINKED, SANDBOX)
• STATE (clean / dirty)
• LAST ACTIVE
• PR (optional — requires GitHub CLI)
• BRANCH

Notes:

• Entries are grouped by TYPE.
• SANDBOX and MANAGED are worktrees inside ~/.yggtree.
• External worktrees are labeled LINKED.
• Use --open to switch this flow into "pick and open in tool" mode.
• The PR column shows the pull request status for each branch (e.g. OPEN, IN REVIEW, APPROVED, MERGED, DRAFT, CHANGES). It only appears when gh CLI is installed and authenticated — otherwise it's silently omitted.

yggtree open [worktree]

Open a worktree in an editor, supported desktop app, or terminal target.

Behavior:

• If [worktree] is omitted, you can pick from the worktree list with type-to-filter search.
• Detects available editor commands in your PATH (for example: cursor, code, zed, webstorm).
• Detects Codex App on macOS and launches it with open -b com.openai.codex.
• Detects Cmux and Tmux when their CLI commands are available.
• Lets you choose one editor, app, or terminal target interactively, or pass --tool.
• Keeps Cmux, Tmux, and Other command... mutually exclusive by using a single action picker.
• By default, open launches the selected target and returns, except foreground terminal targets such as Tmux.
• Use wc --open when you want to open a worktree and continue in its shell.

Options:

• --tool <command> (for example: cursor, code, codex, codex-app, cmux, or tmux)

yggtree open
yggtree open feat/new-ui --tool cursor
yggtree open feat/new-ui --tool codex-app
yggtree open feat/new-ui --tool tmux
yggtree list --open

yggtree exec [worktree] -- <command>

Run a command inside a worktree without changing your current terminal.

yggtree exec feat/new-ui -- npm test

yggtree path [worktree]

Print a cd command for a worktree.

Useful for scripting and shell aliases.

yggtree bootstrap

Re‑run bootstrap commands for a worktree.

yggtree delete

Interactively delete worktrees.

Behavior:

• Default flow targets managed worktrees.
• In interactive mode, yggtree asks whether to include external linked worktrees.
• In direct CLI usage, --all includes external linked worktrees (main/current are still excluded for safety).
• The delete selector shows 6 items per page.

Optional:

• --all includes linked worktrees outside ~/.yggtree (main/current worktree is excluded for safety)

yggtree prune

Clean up stale git worktree metadata.

🌱 When Should You Use Yggdrasil?

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

📝 Practical Examples

Command:

yggtree create feat/login-flow

What happens:

• Creates a new branch if it doesn’t exist (without inheriting base tracking), then publishes it to origin when possible
• Creates a dedicated worktree
• Runs bootstrap if enabled
• Lets you choose whether to open an editor after creation

Command:

yggtree create feat/cleanup-api --no-bootstrap --no-open --no-enter

When to use:

• You just want the folder ready
• You’ll open it or move into its shell later if needed
• You don’t want installs running automatically

Command:

yggtree create feat/ui-refactor --exec "cursor ."

Works with:

• cursor .
• code .
• Any custom command available in your shell

Command:

yggtree exec test -- npm test

What this does:

• Runs the command inside the selected worktree
• Keeps your current terminal where it is
• Ideal for CI-like checks, scripts, or quick validations

Command:

yggtree wc --ref test --open

What happens:

• Checks out or reuses the branch worktree
• Lets you choose an editor, supported app, or Other command...
• Starts a worktree shell unless you pass --no-enter
• Type exit to return to your original directory

Command:

yggtree path test

Output:

cd ~/.yggtree/your-repo-name/test

Useful when you want to manually navigate or copy the path into scripts.

Command:

yggtree create-sandbox --carry

Scenario:

1. You have 5 files changed in your main repo but aren't sure about the direction.
2. Run handoff --name risky-refactor to carry those changes into an isolated sandbox-risky-refactor folder.
3. Experiment freely.
4. If it works: yggtree apply.
5. If it fails: Just delete the sandbox or unapply.

🌍 Philosophy

Branches are ideas. Worktrees are realities.

Yggdrasil helps you grow many worlds and decide later which ones deserve to merge.

📄 License

MIT License.