This document provides a comprehensive overview of Phantom's architecture, including technology stack, module structure, and design principles.

• System Overview
• Technology Stack
• Monorepo Structure
• Module Dependencies
• Design Principles
• Package Details
• Performance Characteristics

Phantom is a modern CLI tool built with TypeScript and Node.js, designed for managing Git worktrees efficiently. The architecture emphasizes modularity, minimal dependencies, and clear separation of concerns.

• Monorepo Design: 7 focused packages with clear boundaries
• Minimal Dependencies: Core packages have zero runtime dependencies
• Modular Integration: Optional features via separate packages
• Type Safety: Full TypeScript coverage with strict mode
• Modern Node.js: Leverages latest Node.js features (v22+)

• Version: 5.8.3
• Target: ES2023
• Module System: ES Modules (ESM)
• Features: Strict type checking, native execution via --experimental-strip-types

• Minimum Version: v22.0.0
• Features Used:
  • Native ES modules
  • Built-in test runner
  • Native module mocking
  • Child process management

Core Packages (Zero Dependencies):

• @aku11i/phantom-cli
• @aku11i/phantom-core
• @aku11i/phantom-git
• @aku11i/phantom-process
• @aku11i/phantom-shared

Integration Packages (Minimal Dependencies):

• @aku11i/phantom-github: @octokit/rest, zod
• @aku11i/phantom-mcp: @modelcontextprotocol/sdk, zod

• Fast bundling for CLI distribution
• ES modules output targeting Node.js 22
• Source map support for debugging

• Version: 1.9.4
• Combined linting and formatting (replaces ESLint + Prettier)
• 10-20x faster than traditional tools
• Written in Rust for performance

• Version: 10.8.1+
• Monorepo workspace management
• Efficient dependency storage
• Strict dependency resolution

phantom/
├── packages/              # 7 focused packages
│   ├── cli/              # CLI interface (@aku11i/phantom-cli)
│   ├── core/             # Business logic (@aku11i/phantom-core)
│   ├── git/              # Git operations (@aku11i/phantom-git)
│   ├── github/           # GitHub integration (@aku11i/phantom-github)
│   ├── mcp/              # MCP server (@aku11i/phantom-mcp)
│   ├── process/          # Process utilities (@aku11i/phantom-process)
│   └── shared/           # Shared utilities (@aku11i/phantom-shared)
├── package.json          # Root configuration
├── pnpm-workspace.yaml   # Workspace setup
└── pnpm-lock.yaml        # Dependency lock

graph TB
    subgraph "CLI Layer"
        cli["@aku11i/phantom-cli<br/>Command Handlers"]
    end
    
    subgraph "Integration Layer"
        github["@aku11i/phantom-github<br/>GitHub API"]
        mcp["@aku11i/phantom-mcp<br/>AI Assistants"]
    end
    
    subgraph "Core Layer"
        core["@aku11i/phantom-core<br/>Business Logic"]
        git["@aku11i/phantom-git<br/>Git Operations"]
        process["@aku11i/phantom-process<br/>System Processes"]
    end
    
    subgraph "Foundation"
        shared["@aku11i/phantom-shared<br/>Common Utilities"]
    end
    
    cli --> github
    cli --> mcp
    cli --> core
    cli --> git
    cli --> process
    cli --> shared
    
    github --> core
    github --> git
    github --> process
    github --> shared
    
    mcp --> github
    mcp --> core
    mcp --> git
    mcp --> process
    mcp --> shared
    
    core --> git
    core --> process
    core --> shared
    
    git --> shared
    process --> shared
    
    classDef cli fill:#ff9,stroke:#333,stroke-width:2px
    classDef integration fill:#9ff,stroke:#333,stroke-width:2px
    classDef core fill:#9f9,stroke:#333,stroke-width:2px
    classDef foundation fill:#f9f,stroke:#333,stroke-width:2px
    
    class cli cli
    class github,mcp integration
    class core,git,process core
    class shared foundation

Each package has one clear, focused purpose:

• CLI: User interface and command routing
• Core: Phantom lifecycle and configuration
• Git: Git command abstraction
• GitHub: GitHub API integration
• MCP: AI assistant tools
• Process: System process management
• Shared: Common utilities and types

Dependencies flow from higher-level packages to lower-level ones:

• CLI packages depend on everything below
• Integration packages depend on core packages
• Core packages depend only on shared utilities
• Shared utilities have no dependencies

Core functionality maintains zero runtime dependencies:

• Faster installation
• Smaller package size
• Better security posture
• Reduced dependency conflicts

Advanced features are in separate packages:

• GitHub integration is optional
• MCP server is optional
• Core functionality works standalone

Purpose: Command-line interface and user interaction

• Entry points (bin/)
• Command handlers (handlers/)
• Help text and CLI logic
• Dependencies: All other phantom packages

Purpose: Core business logic and phantom management

• Worktree lifecycle management
• Configuration system (phantom.config.json)
• Validation and error handling
• Dependencies: git, process, shared

Purpose: Git command abstraction and execution

• Git executor with Result pattern
• Command libraries (libs/)
• Git operation wrappers
• Dependencies: shared only

Purpose: GitHub integration via REST API

• PR and issue checkout
• GitHub API client
• Authentication handling
• Dependencies: core, git, process, shared, @octokit/rest, zod

Purpose: Model Context Protocol server for AI assistants

• MCP server implementation
• Tool definitions for AI assistants
• Claude Desktop/Cursor integration
• Dependencies: All phantom packages, @modelcontextprotocol/sdk, zod

Purpose: System process management and execution

• Safe process spawning
• Command execution utilities
• Cross-platform compatibility
• Dependencies: shared only

Purpose: Common utilities and type definitions

• Result type for error handling
• Shared interfaces and types
• Utility functions
• Dependencies: None

• Cold Start: ~50ms
• Factors: Zero core dependencies, bundled executable, minimal initialization

• Base Memory: ~30MB
• Scaling: Linear with phantom count
• No Background Processes: Zero memory when idle

• Full Build: <5 seconds (esbuild + TypeScript)
• Type Check: ~2 seconds
• Test Suite: ~1 second (native Node.js runner)

• Core CLI: Minimal dependencies for fast install
• With Integrations: Additional dependencies loaded on demand
• Development: Full monorepo setup with pnpm workspaces

• Clear package boundaries prevent coupling
• Single responsibility makes reasoning easier
• Type safety prevents runtime errors
• Comprehensive test coverage

• Zero-dependency core for fast startup
• Modern build tools for quick iteration
• Native Node.js features for efficiency
• Minimal overhead design

• Monorepo structure supports new packages
• Clear interfaces for integration points
• Optional feature packages
• Plugin-ready architecture

• Native TypeScript execution in development
• Fast feedback loops with modern tooling
• Comprehensive error messages
• Self-documenting code through types

This architecture enables Phantom to remain lightweight and fast while providing powerful features through optional integrations, making it suitable for both simple and complex development workflows.