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

$npm install -g yggtree

Install the CLI globally once.

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.

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.

Target Codex directly

Terminal

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

Useful for Codex setups that support agent-specific skill installation.

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.

Create and return without setup or editor launch

Terminal

$yggtree create feat/docs-pass --no-bootstrap --no-open --no-enter

Useful for automation or when you want to inspect the worktree path before installing dependencies.

Run an explicit startup command

Terminal

$yggtree create feat/ui-polish --exec "code ."

`--exec` is the advanced escape hatch when the normal editor picker is not specific enough.

Checkout and move between worktrees

wc is the fastest path from "I need that branch" to "I am in the right shell." It is designed to avoid stashing, preserve the current checkout, and reuse existing branch worktrees when possible.

Pick from searchable branches

Terminal

$yggtree wc

The picker shows local branches, remote branches, and duplicate local/origin choices explicitly.

Checkout a known ref non-interactively

Terminal

$yggtree wc hotfix-auth main --no-open --no-enter

Good for scripts: create or reuse the checkout, skip tools, and return to the caller.

Open a terminal target after checkout

Terminal

$yggtree wc hotfix-auth main --tool tmux

`--tool` accepts editors, apps, and terminal targets such as `codex-app`, `cmux`, or `tmux`, then enters the worktree shell unless `--no-enter` is set.

Open one target but stay in the current shell

Terminal

$yggtree wc hotfix-auth main --open --no-enter

Use this when the command should prepare a worktree, run one open action, and return. The picker is single-select, so Enter chooses the highlighted editor, app, terminal target, or `Other command...`.

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 a terminal target directly

Terminal

$yggtree open feat/new-ui --tool cmux

`--tool cmux` or `--tool tmux` opens the worktree in that terminal target without showing the picker.

Open tools 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.

Open from the worktree list

Terminal

$yggtree list --open

Switches the list command into the same pick-and-open flow without printing the table first.

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.

Undo an apply while the sandbox still exists

Terminal

$yggtree unapply

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

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.

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.

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.

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 `.yggtree/worktree-setup.json` when present, then falls back to default setup behavior.

yggtree delete

Delete managed worktrees interactively.

-a, --allInclude linked worktrees outside the configured managed root, excluding main and current safety cases.

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.

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.

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

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. `codex` sets both the worktree root and Codex-style path layout; `default` and `yggtree` reset to the normal Yggtree layout.

PresetsAvailable presets: `default`, `yggtree`, and `codex`.

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 either Yggtree or Codex-style nesting.

Layouts`yggtree` uses `<root>/<repo>/<slug>`; `codex` uses `<root>/<slug>/<repo>`.

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 two kinds of configuration: repository setup commands, which prepare each new worktree, and global path settings, which decide where managed worktrees are created. Keep setup close to the repo. Use global path settings when you want Yggtree to 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`. When local env files such as `.env` or `.env.local` exist, interactive creation flows offer to copy them. Example and template env files are skipped, and CI or other non-interactive runs skip the prompt entirely.

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

`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 config reset

Claude and Cursor presets are intentionally not listed until their native worktree directory pattern is confirmed. Use `set-worktrees-root` for those tools 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.