YGGDRASIL

Grow your worlds. Manifest your ideas.

Peaceful Village by Arthur Vyncke | arthurvost
Music promoted by free-stock-music.com
Creative Commons Attribution-ShareAlike 3.0 Unported

Yggdrasil
Worktree

Grow many worlds. Merge what matters.

Like the mythical world tree connecting realms, Yggdrasil lets you grow isolated, parallel environments where ideas can evolve independently without colliding.

Changelog

npx yggtree

Read the docs→

Mental Model

Yggdrasil is built around a few core ideas that transform how you think about parallel development.

Branches are ideas

Each branch represents a concept, a possibility, a direction your code could take.

Worktrees are realms

Each worktree is a complete, isolated reality where that idea can fully manifest.

Each task deserves its own world

No more context switching. No more stashing. Each task lives in its own space.

Quick Start

Install once, then open the guided workflow from any Git repository.

Installation

Install the latest release:

Terminal

$curl -fsSL https://yggtree.logbookfordevs.com/install.sh | bash

Prefer npm globals? npm install -g yggtree still works.

Or try it without installing:

Terminal

$npx yggtree

Basic Usage

yggtree

Key Features

Everything you need for modern parallel development workflows.

True Parallel Tasks

Run completely independent tasks at the same time — implement a new page while fixing a bug in a totally different flow. No stashing, no conflicts.

First-class Worktree Workflow

Create, manage, and navigate Git worktrees as a primary workflow, not an afterthought.

AI-Friendly Isolation

Assign each AI agent its own worktree — every task gets a dedicated, isolated environment.

Automatic Bootstrapping

Run installs, submodules, and setup scripts automatically for each worktree.

Open Tools and Shells

Launch editors, Codex App, Cmux panels, or Tmux sessions from the same worktree picker.

Interactive or Scriptable

Use the interactive UI or drive everything through commands and flags.

The Core

Run Independent Tasks in Parallel

This is the heart of Yggdrasil. Each worktree is a completely independent task — with its own branch, its own remote, its own environment. Implement a new page while fixing an unrelated bug in a different flow. Simultaneously.

Multiple Tasks, Zero Conflicts

Terminal

$yggtree create feat/new-dashboard --exec 'cursor .'

Terminal

$yggtree create fix/auth-bug --exec 'code .'

Terminal

$yggtree create chore/update-deps --exec 'aider'

Task 1

feat/new-dashboard

Building the new analytics page

Task 2

fix/auth-bug

Fixing a login edge case

Task 3

chore/update-deps

Upgrading outdated dependencies

Three unrelated tasks. Three isolated environments. All running at the same time.

🤖 Even Better with AI Agents

Assign each agent its own worktree. Different tasks, different agents, all in parallel — no collisions.

Terminal

$yggtree create feat/ai-refactor --exec 'cursor .'

Terminal

$yggtree create feat/ai-tests --exec 'codex'

Terminal

$yggtree create fix/ai-perf --exec 'aider'

Agent A · Cursor

Refactors architecture

Agent B · Codex

Writes test suite

Agent C · Aider

Optimizes performance

All in parallel. All reviewable. All isolated.

Extra Mode

🧪 Sandbox Mode

Not every worktree needs to be a live task with its own remote branch. Sometimes you just need a local playground — a temporary, disposable space to experiment freely and bring back only what works.

When to Use Sandbox

The core workflow creates real, managed worktrees — each with its own branch and remote, perfect for independent tasks. But sometimes you don't need all that. You just want a quick, local-only space to try something without any Git footprint. That's where Sandbox comes in.

🔬 A/B Testing Approaches

Create 3 sandboxes. Try 3 completely different architectures for the same problem. Keep the winner, discard the rest. No branches left behind.

🚀 Risky Refactors

That massive refactor you're not sure about? Do it in a sandbox. If it breaks everything, just delete it — your main code is untouched.

🤖 Multi-Agent Experiments

Give the same task to different AI agents — Cursor in one sandbox, Codex in another, Aider in a third. Compare the results side by side. Pick the best one.

📝 Multi-Prompt Testing

Same agent, different prompts. Spin up sandboxes to test how different instructions produce different outcomes for the very same task. Iterate faster.

The Workflow

Terminal

$yggtree handoff --name risky-refactor

Creates a named, local-only sandbox and carries your staged, unstaged, and untracked changes. Never pushes to remote.

Terminal

$yggtree apply

Liked the result? Copy changed sandbox files back to your origin directory with backups.

Terminal

$yggtree unapply

Didn't work out? Restore the backed-up origin files before deleting the sandbox.

Choose the right realm

The full docs now carry the command reference. Here are the three choices that matter most.

Official task

yggtree create feat/new-flow

Create a branch-backed worktree for real implementation work.

Existing branch

yggtree wc hotfix-auth main --tool tmux

Review or fix another branch in a terminal target without stashing your current work.

Disposable experiment

yggtree create-sandbox

Try a local-only approach and copy it back only if it wins.

Read the guided docs and full command reference

Configuration

Customize how Yggdrasil bootstraps each worktree with automatic setup scripts.

.yggtree/worktree-setup.json

Create a .yggtree folder in your repo root with a worktree-setup.json file to define custom bootstrap commands:

.yggtree/worktree-setup.json

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

Resolution order: