wiz

README

wiz

Magical git branch contexts. Work on multiple branches simultaneously across terminal windows with zero confusion.

wiz create feat-auth
wiz create bugfix-login
wiz spawn feat-auth       # opens new terminal tab
wiz spawn bugfix-login    # opens another tab
# Each tab shows: 🧙 feat-auth — myapp
# Run Claude Code in parallel on different branches

Why

If you use Claude Code, Codex, or any AI coding agent, you've probably wanted to run multiple sessions on different branches at the same time. Without wiz, that means manually cloning repos, juggling directories, and losing track of which terminal is on which branch.

Wiz wraps git worktrees so each branch gets its own isolated working directory — instantly, with zero disk overhead. You create a context, spawn a terminal tab, and you're working. Your prompt tells you where you are. When you're done, wiz finish pushes, creates a PR, and cleans up.

Install

Requires Go 1.25+

go install github.com/buck3000/wiz@latest

Or build from source:

git clone https://github.com/buck3000/wiz.git
cd wiz
go build -o wiz .
sudo mv wiz /usr/local/bin/   # or anywhere on your PATH

Verify it works:

wiz doctor

Shell Setup

Add to your shell rc file so wiz enter works and you get prompt/title enhancements:

zsh (~/.zshrc):

eval "$(wiz init zsh)"

bash (~/.bashrc):

eval "$(wiz init bash)"

fish (~/.config/fish/config.fish):

wiz init fish | source

Restart your shell (or source the file), then run wiz doctor to confirm everything is wired up.

This gives you:

• A wiz shell function that handles wiz enter properly
• Automatic prompt prefix: 🧙 feat-auth* (with dirty indicator)
• Terminal title: 🧙 feat-auth — myapp
• iTerm2 badge support (automatic when detected)

Quick Start

Everything below assumes you're inside a git repo with at least one commit.

1. Create a context

wiz create feat-auth
# Creates an isolated worktree on a new branch "feat-auth"

Options:

• --base main — branch off a specific base branch
• --task "Add OAuth login" — attach a task description (used by agents and wiz finish)
• --agent claude — associate an agent for wiz spawn

2. Work in it

Option A — Enter in your current terminal:

wiz enter feat-auth
# cd's into the worktree and sets up the environment

Option B — Open a new terminal tab:

wiz spawn feat-auth
# Opens a new iTerm2/Kitty/WezTerm/tmux tab, cd'd into the context

Option C — Launch an AI agent directly:

wiz spawn feat-auth --agent claude --prompt "Add OAuth login with Google"
# Opens a new tab and starts Claude Code with the prompt

3. Run multiple contexts in parallel

wiz create feat-auth --task "Add OAuth login"
wiz create fix-payments --task "Fix Stripe webhook retry logic"
wiz create refactor-db --task "Migrate to sqlc"

wiz spawn feat-auth --agent claude
wiz spawn fix-payments --agent claude
wiz spawn refactor-db --agent claude
# Three terminal tabs, three branches, three Claude sessions

4. Check on progress

wiz list                       # List all contexts
wiz status                     # Current context status
wiz diff feat-auth --stat      # What changed vs base branch
wiz diff --all                 # Diff summary for every context
wiz log feat-auth              # Git log for a context

5. Run commands without entering

wiz run feat-auth -- make test
wiz run feat-auth -- git log --oneline -5

6. Finish up

wiz finish feat-auth
# Pushes the branch, creates a PR (via gh), and deletes the context

wiz finish feat-auth --merge
# Same, but also merges the PR

Options:

• --title "Add OAuth" — custom PR title (default: context name)
• --body "..." — custom PR body (default: task description)

Requires GitHub CLI (gh) to be installed and authenticated.

Orchestra

Define a multi-task plan in YAML and run them all at once:

# plan.yaml
tasks:
  - name: auth
    prompt: "Add OAuth login with Google"
    agent: claude
  - name: tests
    prompt: "Write integration tests for the auth module"
    agent: claude
    depends_on: [auth]

wiz orchestra plan.yaml
# Creates contexts, spawns agents, respects dependency order

Tasks with depends_on wait for their dependencies to be spawned first.

Templates

Save and reuse context configurations:

wiz template save my-template --base main --strategy worktree --agent claude
wiz template list
wiz create feat-x --template my-template

Commands

Command	Description
wiz	Launch interactive TUI picker
wiz create <name>	Create a new context
wiz list [--json]	List all contexts
wiz enter <name>	Activate context in current shell
wiz spawn <name> [--agent <name>] [--prompt <text>]	Open new terminal tab in context
wiz run <name> -- <cmd...>	Run command inside context
wiz diff <name> [--stat] [--all]	Show diff vs base branch
wiz log <name> [-n N] [--all]	Show git log for a context
wiz finish <name> [--merge]	Push, create PR, clean up
wiz orchestra <file.yaml>	Run multi-task plan
wiz path <name>	Print context filesystem path
wiz rename <old> <new>	Rename a context
wiz delete <name> [--force]	Delete a context
wiz status [--porcelain] [--json]	Show current context status
wiz template save|list|delete	Manage context templates
wiz init <bash|zsh|fish>	Print shell integration script
wiz doctor	Check environment and show active enhancements

How It Works

Under the hood, wiz uses git worktrees to create isolated working directories that share the same object store. This means:

• Contexts are instant to create (no cloning)
• All contexts share git objects (disk efficient)
• Each context has its own working tree, index, and HEAD
• Multiple terminals can operate on different branches without conflicts

State is stored in <repo>/.git/wiz/:

• state.json — context registry
• wiz.lock — file lock for concurrent safety
• trees/ — worktree directories

A clone strategy is available as a fallback (--strategy clone) for edge cases where worktrees aren't suitable. It uses git clone --shared for object sharing.

Terminal Enhancements

wiz doctor shows which enhancements are active:

 ✓ Git: git version 2.43.0
 ✓ Terminal: iTerm2 (features: title, badge, tab-color)
 ✓ Shell integration: Active (WIZ_CTX set)
 ✓ Active context: feat-auth

Terminal	Title	Badge	Tab Color
iTerm2	Yes	Yes	Yes
Kitty	Yes	—	—
WezTerm	Yes	—	—
tmux	Yes	—	—
VS Code	Yes	—	—

Environment Variables

When inside a context, these are exported:

Variable	Description
WIZ_CTX	Context name
WIZ_REPO	Repository name
WIZ_DIR	Context directory path
WIZ_BRANCH	Git branch name
WIZ_PROMPT	Formatted prompt string (set by hook)

Support

Wiz is free to use with up to 10 concurrent contexts. If you find it useful, consider sponsoring the project to unlock unlimited contexts and support development:

Sponsor on GitHub

Testing

go test ./... -race

License

MIT