Requirements

Before you start, make sure you have:

• Git - Your project must be a git repository
• Node.js (v18+)
• Claude CLI - Install from https://claude.ai/code

Installation

Via npm (Recommended)

# Install globally
npm install -g pilot-ai-cli

# Verify installation
pilot --version

From Source

# Clone the repo
git clone https://github.com/i-am-anshul/pilot.git
cd pilot

# Install dependencies
npm install

# Build
npm run build

# Link globally
npm link

Quick Start

# Navigate to your project
cd your-project

# 1. Initialize pilot
pilot init

# 2. Let AI create your PRD (fills gaps in context files and generates tasks)
pilot create-prd

# 3. Run build to execute tasks
pilot build

Commands

pilot init

Sets up pilot in your project:

• Creates .pilot/ directory with context file templates
• Creates PRD.md task file template
• Runs pre-flight checks (git, Claude CLI, Node.js)

pilot init

pilot create-prd

Uses Claude to autonomously:

1. Read all spec files in .pilot/
2. Identify gaps (blanks, "TBD", "no preference")
3. Make decisions for each gap
4. Update .pilot/ files with decisions
5. Generate PRD.md with atomic, testable features

pilot create-prd

This is the bridge between init and build - it transforms rough project context into actionable tasks.

pilot build

Runs the main build loop:

1. Parses tasks from PRD.md
2. Validates each task against project context
3. Creates isolated git worktrees for parallel execution
4. Runs up to 3 Claude agents simultaneously
5. Merges completed work back to main
6. Runs tests and auto-fixes failures
7. Pushes to remote

pilot build

pilot cleanup

Cleans up stale worktrees, branches, and state from failed or interrupted runs:

• Removes all .pilot-worktrees/ directories
• Deletes all pilot/* branches
• Clears running tasks state
• Removes failed-summary.md

pilot cleanup

Use this before pilot build if you hit errors about existing worktrees or branches.

pilot fix

Interactively describe a bug and let AI investigate and fix it:

1. Asks what problem you're facing
2. Optionally accepts error logs (multi-line)
3. Optionally accepts additional context (steps to reproduce, expected behavior)
4. Uses Claude to investigate and fix the issue
5. If fix doesn't work, asks for detailed feedback with new logs

pilot fix

Use this when you encounter bugs in code that pilot built (or any code in your project).

Iterative Fix Loop

When a fix doesn't work, pilot asks for:

• Detailed feedback (multi-line) - Describe what's still broken
• New error logs (optional) - Paste updated crash logs or errors
• Additional context (optional) - Any new observations

This information is passed to the next attempt. The AI is forced to:

• Reset assumptions - Previous understanding was wrong
• Re-investigate from scratch - No incremental tweaks
• Blacklist failed approaches - Can't try variations of what failed
• Meet confidence threshold - Must be ≥7/10 confident before implementing

Mandatory Test Writing

Every fix attempt MUST include a test that:

1. Reproduces the bug (fails without the fix)
2. Verifies the fix works (passes with the fix)

"N/A" or skipping tests is not acceptable.

Deep Analysis Mode

For complex bugs, use --deep to enable brainstorming mode:

pilot fix --deep

Deep mode differences:

• Brainstorms 4 solutions - Generates 4 different approaches (including one "out of the box")
• Decision tree visualization - Shows all solutions with confidence scores
• Confidence threshold - Only implements solutions with ≥7/10 confidence
• Never gives up - Uses WebSearch to research if all solutions are below threshold
• Analysis table - Compares pros, cons, and risk levels for each approach

pilot add

Interactively add a new feature to your PRD:

1. Describe the feature you want to add
2. Optionally provide additional context (requirements, constraints)
3. AI breaks down the feature into atomic tasks with story points
4. Preview generated tasks before adding
5. Tasks are appended to PRD.md

pilot add

Use this to incrementally add features to an existing project. Works even without .pilot/ context - it will analyze your codebase directly.

Workflow

pilot init          # Create .pilot/ and PRD.md templates
     │
     ▼
Fill .pilot/ files  # Describe your project, tech stack, architecture
     │
     ▼
pilot create-prd    # AI fills gaps and generates atomic tasks
     │
     ▼
pilot build         # AI agents execute tasks in parallel
     │
     ├──▶ (if worktree/branch errors) ──▶ pilot cleanup
     │
     ├──▶ (if bugs in built code) ──▶ pilot fix (or pilot fix --deep)
     │
     └──▶ (to add more features) ──▶ pilot add ──▶ pilot build

Project Structure

After initialization, your project will have:

your-project/
├── .pilot/
│   ├── project-context.md    # REQUIRED - What is this project?
│   ├── tech-stack.md         # REQUIRED - Languages, frameworks, commands
│   ├── system-design.md      # REQUIRED - Architecture and patterns
│   ├── design-spec.md        # OPTIONAL - UI/UX patterns
│   ├── boundaries.md         # OPTIONAL - Files to never modify
│   ├── state.json            # AUTO - Crash recovery state
│   └── logs/                 # AUTO - Per-task execution logs
│       ├── task-slug.md      # Individual task logs
│       └── failed-summary.md # Quick summary of all failed tasks
├── PRD.md                    # Tasks for agents to complete
└── ... your code

Context Files

project-context.md

Describe what your project is:

# Project Context

## What is this project?
A task management app for remote teams

## Domain
Productivity, Collaboration

## Key Concepts
- Workspace: A team's shared space
- Task: A unit of work with assignee and due date

## What this project is NOT
- Not a chat app
- Not a file storage system

tech-stack.md

Define your technical constraints:

# Tech Stack

## Language
TypeScript

## Framework
Next.js 14, React

## Database
PostgreSQL with Prisma

## Testing
- Test command: `npm test`
- Lint command: `npm run lint`

## Build
- Build command: `npm run build`
- Dev command: `npm run dev`

system-design.md

Document your architecture:

# System Design

## Architecture Overview
Monorepo with Next.js app router

## Directory Structure
- /app - Next.js app router pages
- /components - React components
- /lib - Shared utilities
- /prisma - Database schema

## Key Patterns
- Server components by default
- Client components only when needed
- Zod for validation

PRD.md Format

Tasks use markdown checkboxes:

# PRD

## Tasks

- [ ] Create user authentication API [3pt]
- [ ] Build login page [2pt] <!-- depends: create-user-authentication-api -->
- [ ] Add password reset [2pt] <!-- depends: create-user-authentication-api -->

Story Points (Optional)

Tasks can include story point estimates using [Xpt] notation. Points represent implementation token consumption:

| Points | Token Budget | When to Use | |--------|--------------|-------------| | [1pt] | ~16K | Simple change, single file, mostly boilerplate | | [2pt] | ~32K | New component with basic logic | | [3pt] | ~48K | Feature touching 2-3 files | | [5pt] | ~80K | Complex feature, multiple files, some exploration | | [8pt] | ~128K | Large feature, many files, significant research |

Story points are optional but help estimate effort. Both pilot create-prd and pilot add automatically add them.

Task Status Markers

| Marker | Meaning | |--------|---------| | [ ] | Pending - ready to be worked on | | [x] | Completed - merged successfully | | [!] | Blocked - validation failed or agent stuck | | [?] | Needs attention - merge conflict unresolved |

Dependencies

Use HTML comments to specify task dependencies:

- [ ] Build API
- [ ] Build frontend <!-- depends: build-api -->

The task slug is the title in lowercase with special characters as hyphens (Build API → build-api).

Dependency matching is flexible:

• Underscores and hyphens are treated the same (content_hash matches content-hash)
• Double hyphens become single (react--typescript matches react-typescript)
• Multiple dependencies supported: <!-- depends: task-a, task-b -->

If a dependency doesn't match any task, you'll see a warning during build.

Features

• Project Context Awareness - Agents understand your domain, tech stack, and architecture
• Task Validation - AI validates each task fits the project before execution
• Parallel Execution - Runs up to 3 agents simultaneously using git worktrees
• Dependency Support - Tasks can depend on other tasks with flexible ID matching
• AI Conflict Resolution - Automatically resolves merge conflicts
• Auto-fix Tests - Attempts to fix failing tests after merge
• Crash Recovery - Resumes from where it left off if interrupted
• Failed Task Summary - Quick overview of all failures in failed-summary.md
• Easy Cleanup - pilot cleanup removes stale worktrees and branches
• Incremental Feature Addition - pilot add breaks down new features into tasks with story points
• Deep Bug Analysis - pilot fix --deep brainstorms multiple solutions with confidence scoring

Browser Automation (Optional)

If you have agent-browser CLI installed, agents can test web UIs:

# Install from https://agent-browser.dev
agent-browser open http://localhost:3000
agent-browser snapshot
agent-browser click @e1
agent-browser type @e2 "hello"

How It Works

1. Validation - Each task is validated against project context using Claude
2. Worktrees - Creates isolated git worktrees in .pilot-worktrees/
3. Execution - Claude agents work in parallel on their assigned tasks
4. Merge - Completed branches are merged to main with --no-ff
5. Conflict Resolution - AI attempts to resolve conflicts automatically
6. Testing - Runs tests after merge, attempts auto-fix on failure
7. Push - Pushes completed work to remote

Troubleshooting

"Claude CLI not found"

• Install from https://claude.ai/code
• Make sure claude is in your PATH

"Not a git repository"

• Run git init in your project directory

"Branch is already used by worktree"

• Run pilot cleanup to remove stale worktrees and branches
• Then run pilot build again

Claude rate limit errors (Exit code: 1)

• Wait for your rate limit to reset
• Check .pilot/logs/failed-summary.md for affected tasks
• Run pilot cleanup then pilot build to retry

Tasks marked as blocked

• Check .pilot/logs/ for the task log
• The task may not fit the project context

Tasks stuck even after dependencies complete

• Check if dependency IDs match (underscores vs hyphens)
• Look for warnings about "unknown dependency" in build output
• Verify the dependency task slug matches exactly

Many tasks failed - how to see why?

• Check .pilot/logs/failed-summary.md for a quick overview
• Each entry shows: task name, status, 1-line reason, and log file path

Merge conflicts unresolved

• Check the branch in .pilot-worktrees/
• Resolve manually and run pilot build again

License

MIT