Phantom is a powerful CLI tool that dramatically boosts your development productivity by making Git worktrees simple and intuitive. Run multiple tasks in isolated environments simultaneously and achieve true multitask development. Built for the next generation of parallel development workflows, including AI-powered coding with multiple agents.

• 🚀 Simple worktree management - Create and manage Git worktrees with intuitive commands
• 🔄 True multitasking - Create separate working directories per branch and run multiple tasks simultaneously
• 🎯 Execute commands from anywhere - Run commands in any worktree with phantom exec <worktree> <command>
• 🪟 Built-in tmux integration - Open worktrees in new panes or windows
• 🔍 Interactive selection with fzf - Use built-in fzf option for worktree selection
• 🎮 Shell completion - Full autocomplete support for Fish, Zsh, and Bash
• 🧭 Configurable defaults - Set editor, AI commands, and worktree location once via phantom preferences (stored in global git config)
• 🐙 GitHub Integration - Create worktrees directly from GitHub PRs and issues
• 🤖 MCP Integration - AI autonomously manages worktrees for parallel development
• ⚡ Fast and lightweight - Minimal external dependencies

brew install phantom

Note: Shell completions for Fish and Zsh are installed automatically with Homebrew. For Bash completion, see the Shell Completion section below.

npm install -g @aku11i/phantom

Git worktrees are powerful but require manual management of paths and branches. Also, navigating between multiple worktrees is cumbersome. Phantom eliminates these problems:

# Without Phantom
git worktree add -b feature-awesome ../project-feature-awesome origin/main
cd ../project-feature-awesome

# With Phantom
phantom create feature-awesome --shell

When you run phantom create feature-awesome, a new Git worktree named feature-awesome is created in .git/phantom/worktrees/. All worktrees created with phantom are centrally managed in this location.

your-project/    # Git repository
├── .git/
│   └── phantom/
│       └── worktrees/        # Phantom-managed directory
│           ├── feature-awesome/  # branch name = worktree name
│           ├── bugfix-login/     # another worktree
│           └── hotfix-critical/  # yet another worktree
└── ...

You can also customize the worktree location with phantom preferences set worktreesDirectory <path-from-git-root> (default: .git/phantom/worktrees).

This convention means you never need to remember worktree paths - just use the branch name for easy worktree operations.

Phantom provides perfect functionality as a command-line tool. Developers feel the trust and comfort of flying first class.

Phantom supports full shell completion for Fish, Zsh, and Bash. Use tab key to complete commands and worktree names.

When installed via Homebrew, completions for Fish and Zsh are installed automatically. For Bash, you need to manually set up the completion:

# Prerequisites: bash-completion v2 must be installed

# For Bash (add to your .bashrc or .bash_profile)
eval "$(phantom completion bash)"

When creating worktrees, you can use tmux to open them in new windows or panes. This allows you to manage multiple work environments simultaneously.

# Create and open worktree in new window
phantom create feature-x --tmux
# Create with split panes
phantom create feature-y --tmux-vertical
phantom create feature-z --tmux-horizontal

# Open existing worktrees in tmux
phantom shell feature-x --tmux
phantom shell feature-y --tmux-v

# Result: Multiple worktrees displayed simultaneously, each allowing independent work

Phantom works seamlessly with editors like VS Code and Cursor. Configure your preferred editor once with phantom preferences set editor <command> (stored as phantom.editor), and phantom edit will use it before falling back to $EDITOR.

# Set your preferred editor once (stored in git config --global)
phantom preferences set editor "code --reuse-window"

# Open with your preferred editor (falls back to $EDITOR)
phantom edit feature

# Open a specific file
phantom edit feature README.md

# Launch VS Code right after creating
phantom create feature --exec "code ."

# Use Cursor explicitly
phantom exec feature cursor .

Configure your preferred AI coding tool once and launch it directly in any worktree.

# Configure your assistant command (examples)
phantom preferences set ai claude
phantom preferences set ai "codex --full-auto"

# Inspect or clear the preference
phantom preferences get ai
phantom preferences remove ai

# Start the assistant in a worktree
phantom ai feature-auth

Store your defaults in global git config and manage them with phantom preferences (including a per-user worktreesDirectory relative to the Git repo root; default: .git/phantom/worktrees).

# Inspect current defaults
phantom preferences get editor
phantom preferences get ai
phantom preferences get worktreesDirectory

# Update them
phantom preferences set editor "code --reuse-window"
phantom preferences set ai claude
phantom preferences set worktreesDirectory ../phantom-worktrees

# Remove to fall back to $EDITOR or reconfigure AI
phantom preferences remove editor
phantom preferences remove ai
phantom preferences remove worktreesDirectory

Interactive search with fzf allows quick worktree selection.

# Open shell with fzf selection
phantom shell --fzf

# Delete with fzf selection
phantom delete --fzf

Phantom provides a Model Context Protocol (MCP) server. AI coding assistants can autonomously create and manage worktrees to develop multiple features in parallel.

After completing the MCP server setup, try giving your AI agent a prompt like this. The AI agent will create two worktrees and implement Express and Hono apps in each.

Create 2 variations of a simple hello world app using Express and Hono, each in their own worktree. Make sure each can be started with npm start and served on a different URL.

See MCP Integration Guide for detailed setup and usage.

phantom create feature-awesome

phantom list

phantom shell feature-awesome

# Start development work

# Exit the shell when done
exit

phantom exec feature-awesome {command to run}
# Example: phantom exec feature-awesome npm run build

phantom edit feature-awesome
phantom edit feature-awesome README.md

Uses the phantom.editor preference when set (falls back to $EDITOR).

phantom ai feature-awesome

Configure it first with phantom preferences set ai <command>.

phantom delete feature-awesome
phantom delete feature-a feature-b  # delete multiple at once

• Getting Started - Common workflows and tips
• Commands Reference - All commands and options
• Configuration - Set up automatic file copying and post-create commands
• GitHub Integration - Work with GitHub pull requests and issues
• MCP Integration - AI-powered parallel development with Model Context Protocol

• Officially supported: Linux and macOS
• Windows: not yet verified. It should run reliably when used from a Linux environment on WSL, but native Windows behavior is not guaranteed. The maintainers do not regularly test on Windows.
• Pull requests to improve Windows compatibility are welcome.

Contributions are welcome! See our Contributing Guide for:

• Development setup
• Code style guidelines
• Testing requirements
• Pull request process

MIT License - see LICENSE

Built with 👻 by @aku11i, @codex, and Claude