Skip to content

Home

Jump to bottom
Shuhei Akutagawa edited this page Jun 23, 2025 · 7 revisions

Phantom Wiki

日本語 | English

Technical Overview

Phantom is a powerful CLI tool for managing Git worktrees with an elegant, developer-friendly interface. Built with TypeScript and modern Node.js, it provides a streamlined workflow for parallel development, making it easy to work on multiple features, bug fixes, and code reviews simultaneously.

Key Technical Features

  • Minimal Runtime Dependencies - Core packages have zero dependencies, integration packages use minimal essential dependencies
  • TypeScript - Type-safe codebase with modern ES modules
  • Monorepo Architecture - Modular packages for better maintainability
  • AI Integration - MCP (Model Context Protocol) support for AI assistants
  • GitHub Integration - Direct checkout of PRs and issues
  • Configuration Support - Customizable via phantom.config.json
  • Clean Architecture - Separation of concerns with CLI, Core, and Git layers
  • Comprehensive Testing - Unit tests with native Node.js test runner
  • Modern Tooling - esbuild for fast builds, Biome for code quality

Documentation

🚀 Getting Started

Getting Started - Complete guide from installation to advanced usage

  • Installation and setup
  • Core concepts and terminology
  • Basic commands and workflows
  • Real-world examples
  • Development setup for contributors

⚙️ Configuration

Configuration - Customize phantom behavior with phantom.config.json

  • Worktree directory configuration
  • Automatic file copying
  • Post-create and pre-delete hooks
  • Project-specific workflows

🐙 GitHub Integration

GitHub Integration - Work seamlessly with GitHub PRs and issues

  • Direct PR/issue checkout
  • GitHub CLI integration
  • Review workflows
  • Team collaboration

🤖 AI Integration

AI Integration - Enhance development with AI assistants

  • MCP (Model Context Protocol) setup
  • Claude Desktop and Cursor integration
  • AI-powered phantom management
  • Automated development workflows

🏗️ Architecture

Architecture - Technical overview and design principles

  • Technology stack and dependencies
  • Monorepo structure (7 packages)
  • Module relationships
  • Performance characteristics

Developer Resources

Technical Requirements

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

Quick Command Reference

# Install globally
npm install -g @aku11i/phantom

# Create a new phantom (worktree)
phantom create <name> [branch]

# Attach to existing branch
phantom attach <name> <branch>

# List all phantoms
phantom list

# Execute command in phantom
phantom exec <name> <command>

# Enter phantom shell
phantom shell <name>

# Delete phantom
phantom delete <name>

# GitHub integration
phantom github checkout <pr-or-issue-number>  # Checkout PR/issue

# MCP server management
phantom mcp start  # Start MCP server for AI assistants

For detailed documentation, explore the sections above or start with the Getting Started Guide.

Clone this wiki locally