This document provides a high-level introduction to Phantom, explaining what it is, its core concepts, and its architectural structure. For detailed installation and usage instructions, see Getting Started. For comprehensive command documentation, see Command Reference. For architecture deep-dives, see Architecture.
Phantom is a CLI tool that simplifies Git worktree management for parallel development workflows. It provides intuitive commands for creating, managing, and working with Git worktrees, eliminating the manual path and branch management typically required. Phantom supports both human developers through a command-line interface and AI assistants through a Model Context Protocol (MCP) server.
Sources: README.md1-34 README.md18-34
Git worktrees allow multiple working directories from a single repository. Phantom manages these worktrees in a centralized location (.git/phantom/worktrees/ by default) and uses branch names as worktree identifiers, eliminating the need to remember file paths.
your-project/
├── .git/
│ └── phantom/
│ └── worktrees/
│ ├── feature-awesome/
│ ├── bugfix-login/
│ └── hotfix-critical/
Sources: README.md64-83
Phantom uses a three-tier configuration system:
git config --global phantom.*phantom.config.jsonThis allows personal defaults (editor, AI commands, worktree location) while supporting team-wide standards through project config.
Sources: docs/configuration.md1-216 docs/commands.md336-393
Phantom is organized as a monorepo with seven internal packages following a layered architecture:
Monorepo Package Organization
Package Responsibilities:
| Package | Purpose | Key Dependencies |
|---|---|---|
@phantompane/cli | Command-line interface, handlers, shell completions | core, github, git, process, shared |
@phantompane/mcp | Model Context Protocol server for AI integration | core, github, git, process, shared |
@phantompane/core | Worktree lifecycle, validation, configuration | git, process, shared |
@phantompane/github | GitHub PR/issue checkout integration | core, git, process, shared |
@phantompane/git | Git command execution wrapper | process, shared |
@phantompane/process | Subprocess spawning, tmux integration | shared |
@phantompane/shared | Result types, type guards, utilities | None |
Sources: package.json1-40 packages/cli/package.json1-29 packages/core/package.json1-21 packages/mcp/package.json1-27 packages/github/package.json1-22 packages/git/package.json1-18 packages/process/package.json1-17 packages/shared/package.json1-14
CLI and MCP Entry Points to Core Operations
Sources: packages/cli/package.json7 packages/mcp/package.json13 docs/commands.md1-526
Worktree Lifecycle Management
Sources: docs/commands.md31-75 docs/commands.md163-192 docs/configuration.md144-189 docs/configuration.md190-216 packages/core/package.json14-20
The CLI provides human developers with commands for worktree management, integrated with shell completions, tmux, fzf, and editor/AI tools. The main entry point is packages/cli/src/bin/phantom.ts, which dispatches to command handlers.
Key CLI Commands:
| Command | Purpose | Handler Package |
|---|---|---|
phantom create | Create new worktree with branch | @phantompane/core |
phantom attach | Attach existing branch as worktree | @phantompane/core |
phantom list | List all worktrees | @phantompane/core |
phantom delete | Remove worktree and branch | @phantompane/core |
phantom shell | Open interactive shell in worktree | @phantompane/process |
phantom exec | Execute command in worktree | @phantompane/process |
phantom github checkout | Create worktree from PR/issue | @phantompane/github |
phantom preferences | Manage global preferences | @phantompane/git |
phantom completion | Generate shell completions | @phantompane/cli |
Sources: docs/commands.md1-526 packages/cli/package.json1-29
The MCP (Model Context Protocol) server at packages/mcp/src/index.ts enables AI assistants to autonomously manage worktrees. Started with phantom mcp serve, it exposes worktree operations as MCP tools that AI coding assistants can invoke.
MCP Tool Mapping:
Sources: packages/mcp/package.json1-27 docs/commands.md450-471 README.md197-207
@phantompane/git)Wraps Git commands with a type-safe Result<T, E> pattern. Executes operations like git worktree add, git worktree remove, git branch, and git config access.
Sources: packages/git/package.json1-18
@phantompane/process)Handles subprocess spawning, shell execution, and tmux integration. Provides spawnShell() for interactive shells and tmux window/pane management through --tmux, --tmux-vertical, and --tmux-horizontal flags.
Sources: packages/process/package.json1-17 docs/commands.md197-243
@phantompane/github)Integrates with GitHub CLI (gh) and GitHub API to create worktrees from pull requests and issues. Handles same-repository PRs, fork PRs, and issue branches.
Sources: packages/github/package.json1-22 docs/commands.md395-446
@phantompane/core)Merges configuration from three sources with precedence: CLI flags > global preferences (git config --global phantom.*) > project config (phantom.config.json). Supports worktreesDirectory, directoryNameSeparator, postCreate, and preDelete settings.
Sources: docs/configuration.md1-216 docs/commands.md336-393
@phantompane/shared)Foundation package providing Result<T, E> type for error handling and type guards. Has zero internal dependencies and is used by all other packages.
Sources: packages/shared/package.json1-14
Phantom uses a modern TypeScript monorepo with:
Sources: package.json1-40 package.json7-23
For detailed usage instructions, see Getting Started. For comprehensive command documentation, see Command Reference. For architectural deep-dives, see Architecture.
Refresh this wiki