Phantom

A CLI tool for managing overlay filesystems to enable multiple AI agents to work on the same codebase in parallel without conflicts

Get Started View on GitHub

Features

Parallel Agents

Run multiple AI agents on the same codebase simultaneously without conflicts. Each agent gets its own isolated overlay.

Git Integration

Automatic branch per overlay. Commit, push, and merge changes with full git workflow support.

Chain Workflows

Run agents sequentially where each step builds on the previous one's work. Perfect for complex pipelines.

Cross-Platform

Works on Linux (native overlayfs or fuse-overlayfs) and macOS (unionfs-fuse). Auto-detects the best backend.

Post-Run Hooks

Automate linting, testing, and notifications after agent runs. Integrate with your existing toolchain.

Single Binary

No runtime dependencies beyond FUSE. Install via Homebrew or download the binary directly.

Quick Start

Install

brew install martinsuchenak/tap/phantom

Initialize

phantom init

Run an agent

phantom run ~/myproject --agent "claude --print" --task "implement auth" --name auth-feature

Apply changes

phantom apply auth-feature --cleanup

Full Installation Guide

How It Works

Base Directory (read-only lower layer)
         ↓
   ┌─────────────┐
   │  Overlay A   │  → phantom/feature-auth  → ~/.phantom/mnt/feature-auth/
   │  Overlay B   │  → phantom/feature-api   → ~/.phantom/mnt/feature-api/
   │  Overlay C   │  → phantom/feature-tests → ~/.phantom/mnt/feature-tests/
   └─────────────┘
         ↑
  Isolated upper layers (~/.phantom/overlays/<name>/upper/)

Phantom creates a writable overlay on top of your project directory. The base stays untouched — all writes go to an isolated upper layer. Each overlay gets its own mount point, git branch, and state.