This document provides a high-level overview of Phantom's system architecture and design principles.

graph TB
    subgraph "User Interface"
        CLI[CLI Commands]
    end
    
    subgraph "CLI Layer"
        Handlers[Command Handlers]
        Output[Output Formatter]
        Errors[Error Handler]
    end
    
    subgraph "Core Business Logic"
        Worktree[Worktree Operations]
        Git[Git Operations]
        Process[Process Execution]
        Paths[Path Management]
        Types[Type System]
    end
    
    subgraph "External Systems"
        FS[File System]
        GitCLI[Git CLI]
        Shell[System Shell]
    end
    
    CLI --> Handlers
    Handlers --> Output
    Handlers --> Errors
    Handlers --> Worktree
    Handlers --> Process
    
    Worktree --> Git
    Worktree --> Paths
    Worktree --> Types
    
    Process --> Types
    
    Git --> GitCLI
    Paths --> FS
    Process --> Shell

Source: CLAUDE.md#L26-L31

The architecture follows a clean layered approach:

• CLI Layer: Handles user interaction, command parsing, and output formatting
• Core Layer: Contains business logic, independent of CLI framework
• External Layer: Interfaces with system resources (Git, file system, shell)

Each module has a single, well-defined responsibility:

• Command Handlers: Orchestrate operations, no business logic
• Core Modules: Business logic, no CLI dependencies
• Git Operations: Centralized Git command execution
• Process Execution: Unified process spawning and management

Source: src/core/types/result.ts

Uses a Result<T, E> type pattern for explicit error handling:

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

This enables:

• Explicit error states
• Type-safe error handling
• No exceptions for expected errors
• Composable error handling

Located in src/cli/:

• handlers/: Command implementations

  • Each command has its own handler file
  • Handlers orchestrate core operations
  • Minimal business logic

• output.ts: Centralized console output

  • Consistent formatting
  • Table rendering for lists
  • Error message formatting

• errors.ts: CLI error handling

  • Exit codes management
  • User-friendly error messages

Located in src/core/:

Manages Git worktree operations:

• create.ts: Creates new worktrees
• delete.ts: Removes worktrees
• list.ts: Lists existing worktrees
• where.ts: Locates worktree paths
• validate.ts: Validates worktree names and states

Source: src/core/git/

Centralizes Git operations:

• executor.ts: Main Git command executor
• libs/: Specific Git operation wrappers
  • add-worktree.ts: Worktree creation
  • get-current-branch.ts: Branch detection
  • get-git-root.ts: Repository root finding

Handles external process execution:

• spawn.ts: Core process spawning logic
• exec.ts: Command execution in worktrees
• shell.ts: Interactive shell sessions

• paths.ts: Centralized path management
• version.ts: Version information
• types/: Shared type definitions

sequenceDiagram
    participant User
    participant CLI
    participant Handler
    participant Core
    participant Git
    participant FS
    
    User->>CLI: phantom create feature
    CLI->>Handler: ParsedCommand
    Handler->>Core: validateWorktreeName()
    Core-->>Handler: Result<void>
    
    Handler->>Core: createWorktree()
    Core->>Git: getBranch()
    Git-->>Core: currentBranch
    
    Core->>Git: addWorktree()
    Git->>FS: git worktree add
    FS-->>Git: success
    
    Git-->>Core: Result<WorktreeInfo>
    Core-->>Handler: Result<WorktreeInfo>
    Handler->>CLI: Format output
    CLI->>User: Success message

graph LR
    A[Operation] --> B{Success?}
    B -->|Yes| C[Return Result.ok]
    B -->|No| D[Create Error]
    D --> E[Return Result.error]
    E --> F[Handler checks result]
    F --> G[Format error message]
    G --> H[Exit with code]

Source: package.json#L50

• No external runtime dependencies
• Faster installation and execution
• Reduced security surface area
• Simplified deployment

• Modern ES modules throughout
• Type safety at compile time
• Better IDE support
• Tree-shaking capable

• Uses Node.js built-in test runner
• Native module mocking for tests
• Built-in child process handling
• No external test frameworks

• Delegates to Git CLI for operations
• No Git library dependencies
• Ensures compatibility with Git versions
• Leverages Git's battle-tested code

graph TD
    CLI[CLI Layer]
    Core[Core Layer]
    Git[Git Operations]
    Process[Process Utils]
    Types[Type Definitions]
    
    CLI --> Core
    CLI --> Types
    Core --> Git
    Core --> Process
    Core --> Types
    Git --> Types
    Process --> Types
    
    style CLI fill:#f9f,stroke:#333,stroke-width:2px
    style Core fill:#9ff,stroke:#333,stroke-width:2px
    style Git fill:#ff9,stroke:#333,stroke-width:2px

Key rules:

• CLI depends on Core (never reverse)
• Core modules are independent of CLI
• Shared types in types/ module
• No circular dependencies

• All user inputs are validated
• Worktree names are sanitized
• Path traversal prevention
• Command injection protection

• Commands are properly escaped
• Shell execution is explicit
• Environment variables are controlled
• No eval or dynamic code execution

• Minimal dependencies = fast startup
• Direct execution without runtime overhead
• Bundled with esbuild for optimization

• Lightweight process footprint
• No persistent daemons
• Garbage collected after execution

• Stateless operation
• Can manage many worktrees
• Parallel operation support
• Linear complexity for most operations

The architecture is designed to support:

1. Plugin System: Modular extensions
2. Configuration: User preferences
3. Remote Operations: Network worktree support
4. Performance Monitoring: Metrics collection
5. Advanced Git Features: Submodules, sparse checkout

The clean separation of concerns and modular design make these enhancements possible without major refactoring.