Skip to Content
Getting StartedQuick Start

Quick Start: First PR in 10 Minutes

This guide takes you from zero to your first AI-generated pull request.

Before you start: Complete the Prerequisites — Claude Code installed and authenticated, Git hosting token set.

Install Pilot

curl -fsSL https://raw.githubusercontent.com/alekspetrov/pilot/main/install.sh | bash
brew tap alekspetrov/pilot && brew install pilot
git clone https://github.com/alekspetrov/pilot
cd pilot && make build
cp ./bin/pilot ~/.local/bin/pilot

Verify:

pilot --version
# pilot version v2.56.0

Run the Setup Wizard

pilot setup

The wizard walks you through:

  • Selecting your default project path
  • Configuring Telegram bot (optional)
  • Setting up notification preferences

This creates ~/.pilot/config.yaml. You can edit it manually later — see Configuration for all options.

Configure Your Repository

Add your GitHub repository to ~/.pilot/config.yaml:

adapters:
  github:
    enabled: true
    token: ${GITHUB_TOKEN}
    repo: "your-username/your-repo"
    project_path: "~/Projects/your-repo"
    pilot_label: "pilot"
    polling:
      enabled: true
      interval: 30s

Make sure your token is set:

export GITHUB_TOKEN="your-github-pat"

Add your GitLab repository to ~/.pilot/config.yaml:

adapters:
  gitlab:
    enabled: true
    token: ${GITLAB_TOKEN}
    base_url: "https://gitlab.com"       # or your self-hosted URL
    project: "your-namespace/your-repo"
    project_path: "~/Projects/your-repo"
    pilot_label: "pilot"
    polling:
      enabled: true
      interval: 30s

Make sure your token is set:

export GITLAB_TOKEN="your-gitlab-pat"

Start Pilot

pilot start --github --dashboard
pilot start --gitlab --dashboard

The dashboard appears, showing Pilot is polling for issues:

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

Create Your First Issue

Open a new terminal and create an issue with the pilot label:

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."

Go to your repository → Issues → New Issue. Set Title to Add health check endpoint, add the pilot label (create it first if it doesn’t exist), and set Body to: Create a GET /health endpoint that returns JSON with status: ok and the current server timestamp. Add a test.

Go to your project → Issues → New Issue. Set Title to Add health check endpoint, add the pilot label (create it first if it doesn’t exist), and set Description to: Create a GET /health endpoint that returns JSON with status: ok and the current server timestamp. Add a test.

Or use the GitLab API:

curl --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"title": "Add health check endpoint", "labels": "pilot", "description": "Create a GET /health endpoint..."}' \
  "https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/issues"

Watch Pilot Work

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

⏳ Processing: Add health check endpoint

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

   [14:35:15] Started context 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 existing codebase patterns
  • Tests matching your test structure
  • A PR description linking back to the issue
# Review the PR
gh pr view 13
gh pr diff 13
 
# Merge when satisfied
gh pr merge 13

Review the merge request in the GitLab UI, or:

# Using glab CLI
glab mr view 13
glab mr merge 13

With --autopilot=stage, Pilot monitors CI automatically and merges once tests pass — no manual merge needed. See Autopilot.

Starter Tickets

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 requiring design decisions. Start with bounded, well-defined work.

What Just Happened?

Here’s the execution flow Pilot followed:

  1. Polling — Pilot detected the new issue with the pilot label
  2. Branching — Created a working branch (pilot/GH-12 or pilot/add-health-check)
  3. Context intelligence — Loaded your project context from .agent/ (if initialized) for pattern awareness
  4. Execution — Claude Code analyzed your codebase and implemented the change
  5. Quality Gates — Ran build/test/lint checks (auto-detected or configured)
  6. Self-Review — Claude Code reviewed its own changes for quality
  7. PR — Pushed the branch and created a pull request

Production Setup

For production environments, enable webhooks via tunnel for instant issue detection:

# Set up a public tunnel (free via Cloudflare)
pilot tunnel setup
 
# Start with webhook-based detection
pilot start --tunnel --github --autopilot=stage

Tunnels provide instant webhook delivery with zero API polling. See the Tunnel Setup Guide for detailed configuration including GitHub, Linear, and Jira webhook URLs.

Deploy with Docker

Run Pilot in a container instead of installing the binary directly:

# Pull the official image
docker pull ghcr.io/anthropics/pilot:latest
 
# Start with Docker Compose (recommended)
cp configs/pilot.example.yaml config.yaml
# Edit config.yaml with your repo and settings
 
export GITHUB_TOKEN="ghp_..."
export ANTHROPIC_API_KEY="sk-ant-..."
 
docker compose up -d
docker compose logs -f pilot

For Helm on Kubernetes:

helm install pilot ./helm/pilot \
  --set secrets.githubToken="ghp_..." \
  --set secrets.anthropicApiKey="sk-ant-..." \
  --set config.adapters.github.repo="your-org/your-repo"

See the Docker & Helm deployment guide for full configuration, persistence setup, ingress for webhooks, monitoring, and security hardening.

Desktop App

Prefer a graphical interface? The Pilot desktop app provides the same dashboard panels in a native macOS window:

# Build from source (requires Wails CLI)
make desktop-build
 
# Open alongside your running Pilot daemon
open desktop/build/bin/Pilot.app

See the Desktop App guide for prerequisites and full setup.

Next Steps

InstallationConfiguration