Yggdrasil Worktree

Documentation

Use worktrees without losing the plot.

Yggtree helps you move to the right Git checkout without disturbing the work already in motion. Install the CLI, then choose the workflow that matches what you need to protect.

Terminal
$curl -fsSL https://yggtree.logbookfordevs.com/install.sh | bash
Install the latest CLI release.
Terminal
$yggtree
Open the guided menu from any Git repository. If your global install is behind npm, the menu points you to the update command.

Prefer a one-off run? Use npx yggtree without installing. Prefer npm globals? npm install -g yggtree still works.

Choose what to protect.

Start with the state you need to keep safe, then jump to the deeper command section when you need flags.

Start planned work

yggtree create

You need a named branch, reviewable history, and normal setup.

Creates a managed task worktree.

Jump to a branch

yggtree wc

You were interrupted and do not want to stash current edits.

Reuses or creates the checkout, then enters the shell.

Try risky edits

yggtree create-sandbox

You want an experiment that may be discarded.

Keeps the idea local until you copy the result back.

Use Yggtree from agent workflows

The consolidated Yggtree skill helps agents choose the right worktree workflow before loading the smallest reference they need: create a task worktree, branch off without stashing, manage a realm, or run a sandbox experiment without confusing handoff, apply, and branch creation semantics.

Install the full skill pack

Terminal
$npx skills add logbookfordevs/yggdrasil-worktree

Adds the consolidated Yggtree skill plus its focused references for worktree creation, checkout, lifecycle, and sandbox workflows.

Install the Yggtree skill only

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

Use this when your agent runtime supports targeted skill installs and you want the compact Yggtree workflow guide.

Create a task worktree

create is for work you expect to keep: a named branch, a reviewable diff, and a repeatable setup path. Let the prompts guide you when you are exploring. Pass flags when the workflow is already clear.

Create from the default interactive flow

Terminal
$yggtree create

Yggtree asks for the branch, base ref, optional local env-file copy, bootstrap preference, and whether to open an editor before entering the new worktree shell.

Create a named branch from a known base

Terminal
$yggtree create feat/invoice-export --base main --source remote

Use this for reviewable task work when you already know the branch name.

Use an agent-native path once

Terminal
$yggtree create feat/agent-native --config claude

`--config` changes the path preset for this run only; it does not update the saved global config.

Open worktrees in editors, apps, and terminals

Opening targets is separate from creating or checking out a worktree. Use open when you want to launch an editor, app, Cmux panel, or Tmux session and return. Use wc --open when you want the checkout flow to offer one open action before entering the worktree shell.

Pick a worktree and open tools

Terminal
$yggtree open

Pick from a type-to-filter worktree list, then choose one detected editor, app, or terminal target. Yggtree detects common tools such as Cursor, VS Code, Zed, WebStorm, Codex App, Cmux, and Tmux.

Open Codex App directly

Terminal
$yggtree open feat/new-ui --tool codex-app

`--tool` skips the picker. Codex App can be addressed as `codex` or `codex-app`; Yggtree launches it with `codex app <path>` so the selected worktree becomes the active project.

Open and continue in the shell

Terminal
$yggtree open feat/new-ui --tool code --enter

`open` returns by default. Add `--enter` when opening should continue into the worktree shell.

Use sandboxes for risky edits

Sandboxes are local-only worktrees for experiments, refactors, and trial runs. They are useful when the idea may be thrown away, but you still want a clean path to copy the result back. Use `handoff` when the experiment starts from dirty work in your current checkout.

Start a throwaway experiment

Terminal
$yggtree create-sandbox

Creates a sandbox from the current local branch with an auto-generated name.

Continue current edits in a sandbox

Terminal
$yggtree handoff --name risky-refactor

Copies staged, unstaged, and untracked work into a named sandbox so you can continue there.

Apply sandbox changes back

Terminal
$yggtree apply

Run inside the sandbox. Yggtree copies changed files to origin and stores backups in sandbox metadata.

Command reference

Every worktree command is available directly at the top level. yggtree wt ... remains as a compatibility alias.

Create realms

yggtree create [branch]

Create a branch-backed task worktree, then enter its shell by default. Interactive creation asks whether to open an editor first, while `--exec` remains the explicit startup-command override.

  • -b, --branch <name>Branch name when not passed positionally.
  • --base <ref>Base ref such as main.
  • --source <type>Choose local or remote base source.
  • --no-bootstrapSkip setup commands.
  • --open / --no-openChoose whether to open an editor after creation.
  • --enter / --no-enterChoose whether to enter the worktree shell after creation.
  • --exec <command>Run an explicit command after creation.
  • --config <preset>Use `yggtree`, `codex`, or `claude` path settings for this run only.
yggtree worktree-checkout [name] [ref]

Create or reuse a checkout-style worktree from an existing branch or ref. The picker shows local and `origin/*` choices separately, creates local branches for remote-only refs, reuses active worktrees, and enters the shell by default.

  • -n, --name <slug>Worktree name.
  • -r, --ref <ref>Branch or ref to use without the picker.
  • --no-bootstrapSkip setup commands.
  • --open / --no-openChoose whether to open tools before entering.
  • --tool <command>Open one editor, app, or terminal target directly, such as cursor, code, codex-app, cmux, or tmux.
  • --no-enterDo not enter the worktree shell after checkout.
  • --exec <command>Run an explicit command after creation.
  • --config <preset>Use `yggtree`, `codex`, or `claude` path settings for this run only.
yggtree wc [name] [ref]

Short alias for `worktree-checkout`.

  • Same flagsAccepts the same flags as `worktree-checkout`.
yggtree create-multi

Create multiple official task worktrees when explicitly needed. This is bulk setup, not the full `create` open/enter/exec lifecycle.

  • --base <ref>Base ref.
  • --source <type>Local or remote.
  • --no-bootstrapSkip setup commands.
  • --config <preset>Use `yggtree`, `codex`, or `claude` path settings for this run only.

Move around

yggtree list

Show repo-linked worktrees grouped by `MAIN`, `MANAGED`, `LINKED`, and `SANDBOX`, with clean/dirty state, last activity, branch, and an optional PR column when GitHub CLI is available.

  • --openSwitch from list output into the open-worktree flow.
yggtree open [worktree]

Open a worktree in an editor, supported desktop app, or terminal target. Without a worktree argument, pick from a type-to-filter list. The interactive picker chooses one action; the command returns by default.

  • --tool <command>Use a specific editor, app, or terminal target such as cursor, code, zed, webstorm, codex-app, cmux, or tmux.
  • --enterEnter the worktree shell after opening.
yggtree exec [worktree] -- <command>

Run a command inside a chosen worktree without entering it.

  • Command separatorPass the command after `--`, for example `yggtree exec feat/api -- pnpm test`.
yggtree path [worktree]

Print a `cd` command for a worktree.

  • OutputUseful for shell aliases and scripts that want to resolve the selected path.

Maintain realms

yggtree bootstrap

Run the configured setup commands again in the current worktree.

  • Config sourceReads repo/worktree setup config; if none exists, setup is skipped.
yggtree delete [worktrees...]

Delete managed worktrees interactively, or delete explicit worktree names non-interactively with `--yes`. Main and current worktrees are protected.

  • -a, --allInclude external worktrees labeled `LINKED` in `yggtree list`, excluding main and current safety cases.
  • -y, --yesConfirm deletion without prompts. Required for non-interactive deletion.
  • Examples`yggtree delete my-feature --yes`; `yggtree delete external-feature --all --yes`.
yggtree prune

Clean stale Git worktree metadata.

  • When to useUse after manually deleting worktree folders or when Git reports stale entries.

Sandbox transfer

yggtree create-sandbox

Create a local-only sandbox for disposable experiments. The interactive flow can name it, ask whether to copy uncommitted edits, and ask whether to open an editor after creation.

  • -n, --name <name>Optional sandbox name.
  • --carry / --no-carryExplicitly choose whether to copy uncommitted changes. Prefer `handoff` for dirty-work continuation.
  • --no-bootstrapSkip setup commands.
  • --open / --no-openChoose whether to open an editor after creation.
  • --exec <command>Run an explicit command after creation.
  • --config <preset>Use `yggtree`, `codex`, or `claude` path settings for this run only.
yggtree handoff

Carry staged, unstaged, and untracked work from the current checkout into a named sandbox so you can continue there.

  • -n, --name <name>Optional handoff name.
  • --no-bootstrapSkip setup commands.
  • --open / --no-openChoose whether to open an editor after creation.
  • --exec <command>Run an explicit command after creation.
  • --config <preset>Use `yggtree`, `codex`, or `claude` path settings for this run only.
yggtree apply

Copy changed sandbox files back to the origin checkout, backing up overwritten files in sandbox metadata and offering to delete the sandbox afterward.

  • Run locationRun from inside the sandbox. This is file transfer, not a Git merge; review the origin diff afterward.
yggtree unapply

Restore origin files from the sandbox backup created by `apply`.

  • ConstraintOnly works while the sandbox and its backup metadata still exist.

Configure paths and setup

yggtree config get

Show the resolved global Yggtree settings, including the active managed worktree root and layout.

  • OutputPrints the resolved root, layout, config file path, and whether the config is still default.
yggtree config use <preset>

Apply a bundled path preset. `claude` uses Claude Code's repo-local worktree directory, `codex` uses Codex's global worktree root, and `default` or `yggtree` reset to the normal Yggtree layout.

  • PresetsAvailable presets: `default`, `yggtree`, `codex`, and `claude`.
yggtree config set-worktrees-root <path>

Set the managed worktree root manually while keeping the current layout, or defaulting to the Yggtree layout when no layout is set yet.

  • Example`yggtree config set-worktrees-root ~/Worktrees` keeps paths under your chosen directory.
yggtree config set-worktree-layout <layout>

Change only the path shape. Use this when you want a custom root with Yggtree, Codex, or Claude-style nesting.

  • Layouts`yggtree` uses `<root>/<repo>/<slug>`; `codex` uses `<root>/<slug>/<repo>`; `claude` uses `<root>/<slug>`.
yggtree config bootstrap

Set local bootstrap commands in `.yggtree/worktree-setup.json` under the current directory.

  • --command <command>Add a command non-interactively; repeat the flag for multiple commands.
  • --clearRemove the local setup file from the current directory.
yggtree config reset

Clear global settings and return managed worktrees to the default Yggtree layout under `~/.yggtree`.

  • EffectDoes not move or delete existing worktrees; it only changes where new managed worktrees are created.

Configuration

Yggtree has repository setup commands and global path settings. Keep setup close to the repo when a project needs its own ritual, and use path settings when Yggtree should follow a different workspace layout.

.yggtree/worktree-setup.json

{
  "setup-worktree": [
    "pnpm install",
    "git submodule sync --recursive",
    "git submodule update --init --recursive"
  ]
}

Bootstrap runs after worktree creation unless you pass `--no-bootstrap`. The same config is used by `create`, `worktree-checkout`, `wc`, `create-multi`, and `create-sandbox`. If no repo or worktree setup file exists, Yggtree skips setup. Use `yggtree config bootstrap --command "pnpm install"` to create `.yggtree/worktree-setup.json` in the current directory. The first interactive create flow in a repo offers to create that file; declining skips the offer on later runs.

Global worktree paths

Default layout

New managed worktrees normally live at `~/.yggtree/<repo-name>/<worktree-slug>`. Existing worktrees are not moved when you change this setting.

Terminal
$yggtree config get

Codex-style layout

Use the Codex preset when you want new Yggtree worktrees under Codex's worktree root: `~/.codex/worktrees/<worktree-slug>/<repo-name>`.

Terminal
$yggtree config use codex

Claude-style layout

Use the Claude preset when you want new Yggtree worktrees in Claude Code's repo-local directory: `<repo-root>/.claude/worktrees/<worktree-slug>`.

Terminal
$yggtree config use claude

`use` applies a preset bundle. `set-worktree-layout` changes only the path shape and keeps the current root.

Terminal
$yggtree config set-worktrees-root ~/Worktrees
Terminal
$yggtree config set-worktree-layout codex
Terminal
$yggtree create feat/agent-native --config claude
Terminal
$yggtree config reset

Cursor presets are intentionally not listed until their native worktree directory pattern is confirmed. Use `set-worktrees-root` when you already know the directory you want.

Safety notes

Use create for task branches. Use create-sandbox for disposable alternatives, and handoff for continuing current dirty work in a sandbox.

Run unapply before deleting a sandbox if you may need to undo files copied back to the origin with `apply`.

Prefer worktree-checkout over stash when the current checkout contains work you do not want to disturb.

Use delete --all carefully. It can include linked worktrees outside the configured managed root, while still protecting the main and current worktree.

Troubleshooting

The branch already has a worktree.

`worktree-checkout` reuses the active worktree instead of creating a duplicate. Prunable or missing paths are ignored.

You are outside a Git repo.

`wc` can fall back to a registered repo reference and ask which repo to use. Non-interactive flows stay conservative.

The worktree needs project-specific setup.

Put the setup commands in `.yggtree/worktree-setup.json` so every new realm runs the same bootstrap ritual.

You need the old `enter` or `close` command.

Those public commands were removed. Use `wc` for branch-to-shell work, `open --enter` for editor-plus-shell, and normal shell exit/delete flows when you are done.