Pilot v0.21 is out — autopilot CI loop, model routing, epic decomposition. Read the changelog →
Getting Started
Quick Start

Quick Start: Your First PR in 15 Minutes

This guide walks you through installing Pilot, configuring it for your repository, and getting your first automatically-generated pull request.

Prerequisites: A GitHub repository, a GitHub personal access token, and an Anthropic API key. Optionally, a Telegram bot token for the chat interface.

Install

brew tap alekspetrov/pilot
brew install pilot

Verify the installation:

pilot --version
# pilot version v0.21.2

Configure

Run the setup wizard

pilot init

This creates ~/.pilot/config.yaml with your project settings. The wizard walks you through selecting your ticket source, notification channels, and project paths.

Set environment variables

# Required
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export GITHUB_TOKEN="your-github-personal-access-token"
 
# Optional: Telegram bot
export TELEGRAM_BOT_TOKEN="your-telegram-bot-token"
⚠️

Your GitHub token needs repo scope for reading issues and creating PRs. Create one at github.com/settings/tokens (opens in a new tab).

Start Pilot

# GitHub polling with dashboard
pilot start --github --dashboard
 
# Or with Telegram + autopilot
pilot start --github --telegram --autopilot=stage --dashboard

You should see the dashboard appear:

┌─ PILOT ─────────────────────────────────────────┐
│  Status: Running    Mode: GitHub Polling          │
│  Queue: 0 tasks     Uptime: 12s                  │
│                                                   │
│  Waiting for issues labeled "pilot"...            │
└───────────────────────────────────────────────────┘

Create Your First Ticket

Open a new terminal and create a GitHub issue:

gh issue create \
  --title "Add health check endpoint" \
  --label pilot \
  --body "Create a GET /health endpoint that returns JSON with status ok and the current server timestamp. Add a test."

No gh CLI? Create the issue directly on GitHub. The key is the pilot label — that's what triggers Pilot to pick it up.

Within 30 seconds, Pilot detects the issue and starts working. The dashboard updates in real-time:

⏳ Processing: Add health check endpoint

   Implementing   [████████████░░░░░░░░] 60%  GH-12  32s

   [14:35:15] Started Navigator session
   [14:35:18] Analyzing codebase patterns...
   [14:35:25] Creating health endpoint
   [14:35:40] Adding route
   [14:35:55] Writing tests...

✅ PR created: github.com/you/your-repo/pull/13

Review and Merge

Pilot creates a PR with:

  • Implementation following your codebase patterns
  • Tests matching your existing test structure
  • A clear PR description linking back to the issue

Review it like any team member's code:

gh pr view 13
gh pr diff 13

If it looks good, merge it:

gh pr merge 13

If you're running with --autopilot=stage, Pilot monitors CI automatically and merges once tests pass — no manual merge needed.

Suggested Starter Tickets

These are well-scoped tasks that work reliably as first tickets:

TicketWhy it works
"Add health check endpoint"Simple, bounded, easy to verify
"Write tests for UserService"Clear scope, follows existing test patterns
"Add loading spinner to Button component"Small UI change with clear output
"Update README with setup instructions"Documentation, low risk
"Add input validation to create endpoint"Well-defined rules, testable
⚠️

Avoid for first tickets: Architecture changes, multi-service refactors, or tasks that require decisions about tradeoffs. Start with bounded, well-defined work to build confidence in the output quality.

Troubleshooting

Pilot doesn't pick up my issue

  • Check the issue has the pilot label (exact match, case-sensitive)
  • Verify GITHUB_TOKEN is set and has repo scope
  • Confirm the repository matches your config.yaml project path
  • Check logs: pilot start --github --dashboard shows polling activity

PR quality is low

  • Initialize Navigator in your project: claude /nav-init (inside Claude Code)
  • Add a CLAUDE.md file with your code standards
  • Write more detailed ticket descriptions — treat them like you're briefing a junior developer

Token costs seem high

  • Navigator reduces token usage by 92% — make sure it's initialized
  • Check complexity routing: trivial tasks should use Haiku, not Opus
  • Set budget limits in config.yaml under executor.budget

Next Steps

InstallationConfiguration