This guide explains the essential concepts and terminology used in Phantom.

A Git worktree is a feature that allows you to have multiple working directories attached to a single Git repository. Each worktree has its own working directory and can have a different branch checked out.

Main Repository (.git)
├── main worktree (default)
├── feature-a worktree
├── bugfix-b worktree
└── review-c worktree

1. Parallel Development: Work on multiple branches simultaneously
2. Context Preservation: No need to stash or commit WIP
3. Fast Switching: Instant context switches between tasks
4. Isolation: Changes in one worktree don't affect others
5. Shared Repository: All worktrees share the same Git history

A "phantom" is Phantom's user-friendly term for a Git worktree. It represents an isolated working directory where you can:

• Work on a specific feature or bug fix
• Review pull requests
• Test different versions
• Run multiple development servers

graph LR
    A[Create Phantom] --> B[Work in Phantom]
    B --> C[Commit Changes]
    C --> D[Push to Remote]
    D --> E[Delete Phantom]
    
    B --> F[Execute Commands]
    B --> G[Enter Shell]
    
    style A fill:#9f9,stroke:#333
    style E fill:#f99,stroke:#333

By default, phantoms are stored in:

• macOS/Linux: /tmp/phantom/<repo-name>/<phantom-name>
• Custom: Configurable via environment variables (future feature)

Source: src/core/paths.ts#L19-L26

Creates a new phantom (Git worktree):

phantom create <name> [branch]

• name: Unique identifier for the phantom
• branch: Optional branch to base the phantom on
  • If omitted, uses current branch
  • Can be local or remote branch

Removes a phantom and its working directory:

phantom delete <name>

• Only removes the worktree, not the branch
• Cleans up disk space
• Cannot delete if there are uncommitted changes

Shows all phantoms in the current repository:

phantom list

Displays:

• Phantom name
• Associated branch
• File system path

Executes a command inside a phantom:

phantom exec <name> <command>

• Runs in the phantom's working directory
• Inherits current environment
• Returns command exit code

Opens an interactive shell in a phantom:

phantom shell <name>

• Changes to phantom directory
• Starts user's default shell
• Full interactive environment

Gets the file system path of a phantom:

phantom where <name>

• Returns absolute path
• Useful for scripting
• Can be used with other tools

Source: src/core/types/result.ts

Phantom uses a functional error handling pattern:

type Result<T, E = Error> = 
  | { ok: true; value: T }
  | { ok: false; error: E }

Benefits:

• Explicit error handling
• Type-safe error propagation
• No unexpected exceptions
• Clear success/failure paths

1. CLI Layer: User interface and command parsing
2. Core Layer: Business logic and operations
3. Git Layer: Git command execution
4. System Layer: File system and process management

Each module has a single responsibility:

• worktree/: Phantom lifecycle management
• git/: Git operations wrapper
• process/: Command execution
• paths/: Path resolution and management

1. Validation Errors: Invalid phantom names or arguments
2. Git Errors: Git operation failures
3. System Errors: File system or permission issues
4. Process Errors: Command execution failures

• Phantoms are stateless - can be recreated if needed
• Git operations are atomic
• Failed operations don't corrupt repository state

Use descriptive, consistent names:

# Good phantom names
phantom create feature-user-auth
phantom create bugfix-memory-leak
phantom create review-pr-123
phantom create experiment-new-api

# Avoid generic names
phantom create test     # Too generic
phantom create temp     # Not descriptive
phantom create foo      # Meaningless

1. Regular Cleanup: Delete phantoms when done
2. Commit Often: Don't leave uncommitted work
3. Use Branches: Create feature branches in phantoms
4. Document Purpose: Use clear naming

# Create phantom for feature
phantom create feature-xyz

# Work in phantom
phantom shell feature-xyz
git checkout -b feature/xyz
# ... make changes ...
git commit -m "Add feature XYZ"
git push origin feature/xyz
exit

# Clean up after PR merge
phantom delete feature-xyz

# Create phantom from production
phantom create hotfix origin/production

# Fix and test
phantom exec hotfix "git checkout -b hotfix/1.2.1"
phantom exec hotfix "npm test"

# Deploy from phantom
phantom exec hotfix "npm run deploy"

# Clean up
phantom delete hotfix

Run commands in multiple phantoms simultaneously:

# Background execution
phantom exec feat-a "npm test" &
phantom exec feat-b "npm test" &
wait

# Parallel builds
for p in $(phantom list | tail -n +2 | cut -f1); do
    phantom exec "$p" "npm run build" &
done
wait

#!/bin/bash
# Script to test all phantoms

phantom list | tail -n +2 | while read name branch path; do
    echo "Testing phantom: $name"
    if phantom exec "$name" "npm test"; then
        echo "✓ $name passed"
    else
        echo "✗ $name failed"
    fi
done

Each phantom is isolated:

• Separate node_modules
• Independent build artifacts
• Isolated Git index
• Separate branch state

This enables:

• Testing different dependency versions
• Running multiple dev servers
• Parallel CI/CD pipelines
• Safe experimentation

# Test against multiple Node versions
phantom create test-node-20
phantom create test-node-22

phantom exec test-node-20 "nvm use 20 && npm test"
phantom exec test-node-22 "nvm use 22 && npm test"

# Create isolated environments for AI coding
phantom create ai-session-1
phantom create ai-session-2

# Each AI agent works independently
# No conflicts between parallel sessions

# Review multiple PRs simultaneously
for pr in 123 124 125; do
    phantom create "review-pr-$pr" "origin/pr/$pr"
done

# Check each PR
phantom exec review-pr-123 "npm run lint"
phantom shell review-pr-124  # Interactive review

Phantom simplifies Git worktree management by:

1. Providing intuitive commands
2. Abstracting complex Git operations
3. Enabling parallel workflows
4. Maintaining repository integrity
5. Supporting modern development practices

Understanding these core concepts helps you leverage Phantom effectively for enhanced development productivity.