Getting Started with Phantom

This comprehensive guide covers everything you need to know to get started with Phantom, from installation to advanced usage patterns.

Quick Start
Installation
Core Concepts
Basic Usage
Command Reference
Real-World Examples
Development Setup
Configuration
Best Practices
Troubleshooting

Quick Start

Get Phantom running in 5 minutes:

# Install globally
npm install -g @aku11i/phantom

# Navigate to your Git repository
cd your-git-repo

# Create your first phantom
phantom create my-feature

# Work in the phantom
phantom shell my-feature

Installation

Homebrew Installation (Recommended)

# Using Homebrew (macOS/Linux)
brew install aku11i/tap/phantom

# Verify installation
phantom --version

Alternative: Global Installation

# Using npm
npm install -g @aku11i/phantom

# Using pnpm
pnpm add -g @aku11i/phantom

# Verify installation
phantom --version

Requirements

Node.js: v22.0.0 or higher
Git: Modern version with worktree support (2.5.0+)
Package Manager: npm or pnpm

Core Concepts

What is a Git Worktree?

A Git worktree 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

What is a Phantom?

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

Work on specific features or bug fixes
Review pull requests
Test different versions
Run multiple development servers

Phantom Storage

By default, phantoms are stored in:

Default: .git/phantom/worktrees/<phantom-name>
Custom: Configurable via phantom.config.json

Basic Usage

Creating Phantoms

# Create phantom from current branch
phantom create my-feature

# Create phantom from specific branch
phantom create bugfix-123 origin/production

# Attach to existing branch
phantom attach review-pr origin/feature/new-ui

Working with Phantoms

# List all phantoms
phantom list

# Execute commands in phantom
phantom exec my-feature npm test
phantom exec my-feature "npm install && npm run build"

# Enter interactive shell
phantom shell my-feature

# Get phantom location
phantom where my-feature

# Delete phantom
phantom delete my-feature

GitHub Integration

# Checkout GitHub PR or issue directly
phantom github checkout 123

# This creates phantoms with names like:
# - pulls/123 (for PRs)
# - issues/456 (for issues)

AI Integration

# Start MCP server for AI assistants
phantom mcp start

# AI assistants (Claude Desktop, Cursor) can then:
# - Create and manage phantoms
# - Execute commands in phantoms
# - Integrate with your development workflow

Command Reference

Command	Description	Example
`create`	Create new phantom	`phantom create <name> [branch]`
`attach`	Attach to existing branch	`phantom attach <name> <branch>`
`delete`	Remove phantom	`phantom delete <name>`
`list`	List all phantoms	`phantom list`
`exec`	Run command in phantom	`phantom exec <name> <command>`
`shell`	Enter phantom shell	`phantom shell <name>`
`where`	Get phantom path	`phantom where <name>`
`github checkout`	Checkout PR/issue	`phantom github checkout <number>`
`mcp start`	Start MCP server	`phantom mcp start`

Real-World Examples

Feature Development

# Create phantom for new feature
phantom create new-dashboard

# Enter phantom and start development
phantom shell new-dashboard

# Inside phantom:
git checkout -b feature/dashboard
npm install
npm run dev
# Make changes, test, commit...
exit

# Continue other work in main repository

Code Review

# Review GitHub PR directly
phantom github checkout 42

# Or manually create review phantom
phantom create review-pr-42 origin/feature/new-api

# Run tests and check code
phantom exec review-pr-42 npm test
phantom exec review-pr-42 npm run lint

# Interactive review
phantom shell review-pr-42

Parallel Development

# Work on multiple features simultaneously
phantom create feature-a
phantom create feature-b
phantom create feature-c

# Run tests in parallel
phantom exec feature-a npm test &
phantom exec feature-b npm test &
phantom exec feature-c npm test &
wait

# Run multiple dev servers
phantom exec frontend "npm run dev -- --port 3001" &
phantom exec backend "npm run dev -- --port 3002" &
phantom exec mobile "npm run dev -- --port 3003" &

Hotfix Workflow

# Create phantom from production
phantom create hotfix origin/production

# Make fix and test
phantom exec hotfix "git checkout -b hotfix/security-patch"
phantom exec hotfix "npm test"

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

# Clean up
phantom delete hotfix

Development Setup

Contributing to Phantom

If you want to contribute to Phantom itself:

# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/phantom.git
cd phantom

# Install dependencies (requires pnpm)
pnpm install

# Run from source
pnpm phantom

# Run tests
pnpm test

# Before committing
pnpm ready  # Runs lint, typecheck, and tests

Project Structure

phantom/
├── packages/           # Monorepo packages
│   ├── cli/           # CLI interface
│   ├── core/          # Core business logic
│   ├── git/           # Git operations
│   ├── github/        # GitHub integration
│   ├── mcp/           # MCP server
│   ├── process/       # Process utilities
│   └── shared/        # Shared utilities
├── package.json       # Root configuration
├── pnpm-workspace.yaml # Workspace configuration
└── pnpm-lock.yaml     # Dependency lock file

Configuration

Basic Configuration

Create phantom.config.json in your repository root:

{
  "worktreesDirectory": "../phantom-worktrees",
  "postCreate": {
    "copyFiles": [".env", ".env.local"],
    "commands": ["npm install", "npm run build"]
  },
  "preDelete": {
    "commands": ["docker-compose down"]
  }
}

Configuration Options

worktreesDirectory: Custom location for phantoms
postCreate.copyFiles: Files to copy to new phantoms
postCreate.commands: Commands to run after creating phantom
preDelete.commands: Commands to run before deleting phantom

Best Practices

Naming Conventions

# 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 Hygiene

Regular Cleanup: Delete completed phantoms
Frequent Commits: Don't leave uncommitted work
Use Branches: Create feature branches within phantoms
Document Purpose: Use clear, descriptive naming

Git Workflow Integration

# Feature branch workflow
phantom create feature-xyz
phantom shell feature-xyz
git checkout -b feature/xyz
# ... develop, test, commit
git push origin feature/xyz
exit
phantom delete feature-xyz

# Review workflow
phantom github checkout 123  # Checkout PR #123
phantom exec pulls/123 "npm test && npm run lint"
phantom shell pulls/123      # Interactive review

Troubleshooting

Common Issues

Installation Problems

# Check Node.js version (needs v22+)
node --version

# Reinstall if needed
npm uninstall -g @aku11i/phantom
npm install -g @aku11i/phantom

# Verify installation
phantom --version

Phantom Creation Fails

Ensure you're in a Git repository: git status
Check branch exists: git branch -a
Verify worktree support: git worktree list

Permission Errors

Check write permissions in phantom directory
Verify disk space: df -h
Try custom directory in config: "worktreesDirectory": "/path/with/permissions"

GitHub Integration Issues

# Install and authenticate GitHub CLI
brew install gh  # or platform equivalent
gh auth login

# Verify authentication
gh auth status

# Test repository access
gh repo view

Getting Help

Documentation: Check other wiki pages for detailed guides
Issues: Report bugs at GitHub Issues
CLI Help: Run phantom --help or phantom <command> --help

Next Steps

Now that you understand the basics:

Explore Integration: Check out GitHub Integration for PR workflows
AI Assistance: Set up AI Integration for enhanced development
Advanced Config: Learn more in Configuration Guide
Architecture: Understand the system in Architecture

Start with simple use cases and gradually incorporate more advanced features as you become comfortable with the phantom workflow!