pilot

Pilot is a Python tool that turns labeled tickets from GitHub, Linear, Jira, or Asana into reviewed pull requests: it plans the implementation, writes the code, runs tests and lint, and opens a PR linking back to the issue. It's built for developers and small teams who want their backlog worked down without handing merge control to a bot — every change still goes through human review. What sets it apart is the ticket-to-PR loop as a single process, with configurable autopilot modes (dev, stage, prod) that decide how much CI gating and auto-merge happens before you ever see the diff.

Features

Everything below is what users get out of the box. Features are grouped by area — skim the tables for the short version, or dive into the snippets for concrete usage.

Core Ticketing Loop

Execution Intelligence

• Epic decomposition — multi-step epics are split into ordered subtasks and executed sequentially
• Sequential merge mode — optionally waits for a PR to merge before starting the next ticket, eliminating rebase churn
• Quality gates with retry — test, lint, and build validation with automatic retry on transient failures
• Model routing by complexity — cheap models for trivial changes, stronger models for complex ones, selected automatically
• Effort routing — maps task complexity to reasoning depth so you don't burn tokens on a typo fix
• Parallel research subagents — explores the codebase concurrently to inform the plan before any code is written
• Cross-project memory — patterns learned in one repo are available to others sharing your configuration

Integrations

Four interaction modes keep chat from being a one-size-fits-all command line:

💬 Chat     "What do you think about using Redis?"      → discussion only
🔍 Question "What files handle authentication?"          → read-only answer
🔬 Research "Research how the caching layer works"      → deep analysis
📐 Planning "Plan how to add rate limiting"              → plan with Execute/Cancel
🚀 Task     "Add rate limiting to /api/users"           → confirms, then ships a PR

Visibility & Control

• Live dashboard — queue depth, per-task phase, token usage, cost, and recent history at a glance
• Persistent metrics — token, cost, and task counts survive restarts
• Execution replay — record runs, then play back or export them (HTML / JSON / Markdown) for post-mortems
• Budget enforcement — hard limits on spend, checked continuously rather than reported after the fact
• Alerting — fires on failures, cost thresholds, and stuck tasks through your configured channels
• Hot upgrade — self-update without dropping the running queue

Bring Your Own Model

Routing, budget, and backend selection are all configurable per project, so a monorepo with mixed requirements doesn't force a single global policy.

How it works

Pilot is a ticket-to-PR pipeline. Each stage is a discrete, observable step, so you can watch progress in the dashboard or follow it in the execution log.

Ticket labeled "pilot"
        │
        ▼
┌────────────────────┐
│  1. Pick up        │  Claims the ticket, adds an in-progress label
└─────────┬──────────┘
          ▼
┌────────────────────┐
│  2. Branch         │  Creates a working branch off the default branch
└─────────┬──────────┘
          ▼
┌────────────────────┐
│  3. Plan           │  Reads the codebase, drafts an approach
└─────────┬──────────┘
          ▼
┌────────────────────┐
│  4. Implement      │  Writes code against the plan
└─────────┬──────────┘
          ▼
┌────────────────────┐
│  5. Verify         │  Runs tests, lint, and build checks
└─────────┬──────────┘
          ▼
┌────────────────────┐
│  6. Open PR        │  Links the ticket, marks it ready for review
└─────────┬──────────┘
          ▼
      You review → merge

What each stage does

Quality gates and retries

Verification is not a single pass/fail. When a gate fails, Pilot feeds the failure back into the implementation step and tries again, up to a configured limit. If it still cannot pass, the ticket is surfaced with the failing output attached rather than opening a broken PR.

verify → pass? ──yes──▶ open PR
           │
           no
           ▼
   retry budget left? ──yes──▶ implement (with failure context) → verify
           │
           no
           ▼
   surface ticket with diagnostics

Execution order

Tasks run sequentially by default: Pilot waits for the current PR to merge (or time out) before starting the next ticket. This keeps branches from piling up and conflicting with each other. Parallel execution is available when tickets are known to touch independent areas.

Ticket sources

The pipeline is source-agnostic. The pickup and status updates are driven by an adapter, while planning, implementation, and verification are identical regardless of where the ticket originated.

• Polling adapters — scan for tickets carrying the configured trigger label on an interval.
• Webhook adapters — react immediately when a ticket is created or labeled.
• Chat-driven — a task can also be started directly, bypassing the ticketing system entirely.

Observability

Every stage emits a record you can inspect after the fact:

• Live — dashboard queue depth, current phase, elapsed time, and token spend.
• History — per-task records of phases entered, retries consumed, and gate results.
• Replay — export a run (HTML/JSON/Markdown) to reconstruct exactly what happened and why.

Requirements

Pilot runs as a CLI tool that orchestrates an AI coding backend. The table below lists the runtime prerequisites, followed by the optional integrations you may enable.

Optional Backends and Integrations

Environment

• Network access to your issue tracker and AI backend endpoints.
• A writable config directory (~/.pilot by default) for config.yaml and the local metrics database.
• On Windows, run Pilot from a shell where git and the Claude Code CLI resolve correctly (WSL is the tested path).

Refer to Configuration for the exact keys each integration expects.

Configuration

All settings live in a single YAML file at ~/.pilot/config.yaml. Run pilot init to generate a commented starter file, then edit it or override values with environment variables.

version: "1.0"

gateway:
  host: "127.0.0.1"
  port: 9090

adapters:
  github:
    enabled: true
    token: "${GITHUB_TOKEN}"
    repo: "owner/repo"
    pilot_label: "pilot"
    polling:
      enabled: true
      interval: 30s

  telegram:
    enabled: fal