qf-studio/pilot: an AI agent that turns labelled tickets into pull requests

The backlog problem Pilot is built around

The README opens with a number: 47 tickets in the backlog. That is the target scenario. Pilot is for teams whose issue tracker has become a queue of small, describable tasks that nobody has time to pick up, and who are willing to let a machine produce the first draft of the change. The workflow it assumes is narrow on purpose. A human writes a ticket, a human reviews a pull request, and the agent occupies the space in between.

It is not a pair-programming assistant and it is not a chat interface bolted onto a repository. The unit of work is a ticket, and the deliverable is a branch plus a PR. That framing matters because it determines what you need in place before Pilot is useful: an issue tracker Pilot can read, a repository it can clone and push to, and a CI pipeline whose result it can wait on. If your work does not arrive as tickets, Pilot has nothing to pick up.

From label to pull request: the execution loop

The README documents the sequence explicitly. You label an issue pilot. Pilot claims it by adding a pilot/in-progress label, creates a branch named pilot/GH-{number}, plans an approach by analysing the codebase, implements it with Claude Code, runs quality gates (test, lint, build validation), and opens a PR that links back to the issue and carries a pilot/done label. The human step is the merge.

Around that core loop sit several mechanisms worth knowing before you trust it. Model routing sends trivial work to Haiku and standard or complex work to Opus 4.6, detected automatically, and effort routing maps task complexity onto Claude thinking depth. Research subagents run parallel codebase exploration on Haiku. Epic decomposition splits a complex task into sequential subtasks through the Haiku API. Self-review runs a code review before the PR is pushed. Sequential execution waits for a PR to merge before starting the next issue, which the README frames as conflict prevention.

The architecture is a single Go binary (module github.com/qf-studio/pilot, Go 1.25.0) with a Bubble Tea terminal dashboard, a Wails desktop app, and SQLite through modernc.org/sqlite for persistent metrics. The Dockerfile is telling: the runtime image is Ubuntu 22.04 rather than Alpine, and the comment states this is because Pilot executes the Claude Code CLI, which needs Node.js, git and the gh CLI at runtime. Pilot orchestrates an external agent; it does not embed one.

Installing Pilot and getting one ticket through it

The README lists Homebrew as the recommended path, with Go install and a source build as alternatives. The Homebrew route taps qf-studio/pilot and installs the pilot formula.

brew tap qf-studio/pilot
brew install pilot

If you prefer Go, the module path is the install target. Note that the README states Go 1.22+ for building, while go.mod declares go 1.25.0, so use a 1.25 toolchain and expect the stated requirement to be the looser of the two.

go install github.com/qf-studio/pilot/cmd/pilot@latest

Before anything runs, check the runtime requirement: the Claude Code CLI at version 2.1.17 or higher. An OpenAI API key is listed as optional and only for voice transcription. Then initialise the config and start the poller. The README's quick start uses exactly these three steps.

pilot init
pilot start --github

With that running, create a GitHub issue carrying the pilot label. According to the README, Pilot picks it up, marks it pilot/in-progress, and works through to a PR. For a container instead, docker-compose.yml builds the image, publishes port 9090, mounts a config file at /home/pilot/.pilot/config.yaml, reads ANTHROPIC_API_KEY and GITHUB_TOKEN from the environment, and runs start --github --autopilot=dev. The healthcheck curls http://localhost:9090/health.

Autopilot modes decide how much rope you give it

The autonomy setting is a flag, and the three documented values differ in a way that matters more than the naming suggests. The README gives these examples directly.

pilot start --env=dev --github
pilot start --env=stage --github
pilot start --env=prod --github

In dev, Pilot skips CI and auto-merges. In stage it waits for CI and then auto-merges. In prod it waits for CI plus human approval. Read that list again with the ordering in mind: the default posture implied by the docker-compose command is dev, which means a container started from the supplied compose file will merge without waiting for CI and without a human. That is a deliberate fast-iteration mode, but it is the wrong starting point for a repository with branch protection, required checks, or anything resembling a release process. The prod mode is the one that preserves the review step the README describes as the human's job.

Cost controls are listed as budget limits with hard enforcement, and alerting covers task failures, cost thresholds and stuck detection, so runaway spend is at least a named concern in the feature table. What the README does not specify is what happens to an in-flight task when the budget limit is hit, or whether the hard enforcement stops the current Claude Code invocation or only blocks the next one.

Where Pilot is the wrong tool

The dependency on the Claude Code CLI is the sharpest constraint. Pilot is not self-contained: it shells out to an external agent that needs Node.js, git and gh present at runtime, which is why the Docker image is Ubuntu and not Alpine. If your build environment forbids Node.js, or you want a single static binary with no external agent, this project does not fit that shape.

Sequential execution is the second limit, and it is a design choice rather than a bug. Waiting for a PR to merge before starting the next issue prevents conflicts, but it means throughput is bounded by your review latency, not by the agent. A team that lets PRs sit for two days gets roughly one ticket per two days out of Pilot regardless of how many issues carry the label. Parallelism is not offered as a documented mode.

Third, the ticket must be small enough for the pipeline to plan and implement in one pass. Epic decomposition exists precisely because larger tasks exceed that, and the README describes it as splitting work into sequential subtasks, which compounds the serialisation. A vague ticket that a human would spend a day clarifying is not a good candidate; it is a candidate for producing a plausible-looking PR that misses the point.

The licence is also worth flagging. The README badge says BSL 1.1, while the repository metadata reports NOASSERTION. Those disagree, and the LICENSE file is the authority. Read it before you build a commercial workflow on top.

How Pilot differs from a CI-driven agent runner

The obvious comparison is a general-purpose agent runner that you point at a repository and a prompt, such as the Claude Code CLI on its own. The difference is where the state lives. Running the CLI directly gives you a session: you supply context, you watch it work, you decide what to do with the result. Pilot externalises that state into the issue tracker and the git host. Labels carry the status (pilot, pilot/in-progress, pilot/done), branches follow a naming convention, and the PR is the artifact. That means the work is visible to people who never open a terminal, and it survives the process restarting.

It also means you inherit the tracker's limitations. Pilot can only pick up what the tracker exposes, and the polling adapters for GitHub, GitLab and Azure DevOps are described separately from the webhook and sync integrations for Linear, Jira and Asana. If your team's real backlog lives in a document rather than an issue tracker, a direct agent session is the better fit, because there is no label for Pilot to poll.

The second difference is the quality gate. A raw agent session ends when the model stops. Pilot's loop includes test, lint and build validation with auto-retry before the PR is opened, plus a self-review pass. Whether those gates are worth the added moving parts depends on how much you trust the repository's own test suite to catch what the agent gets wrong.

Maintenance, upgrades and what the licence leaves open

The release cadence is fast. Three releases are listed in the days before the last push on 2026-09-15: v2.276.1 on 2026-09-14, v2.276.0 on 2026-09-13 and v2.275.0 on 2026-09-10. The version numbering and the frequency suggest continuous delivery rather than periodic milestones, and the repository is not archived. Anyone pinning a version should expect to move it often, and should read CHANGELOG.md rather than assuming patch releases are inert.

Upgrades are handled in-band. The feature table lists hot upgrade via pilot upgrade, or the u key in the dashboard, and the Makefile notes that the binary inside the release tarball is named pilot rather than pilot-darwin-arm64 specifically to match the upgrade code. That is a small detail with a practical consequence: if you repackage the binary under a different name, the self-update path may not find what it expects.

On the licence, the README badge states BSL 1.1 while the repository metadata reports NOASSERTION. BSL variants typically carry usage restrictions that differ from a permissive licence, and the terms here are not something this article can resolve. Read LICENSE and, if the intended use is commercial, get your own legal reading. What can be said from the available sources is only that the two disagree.

Editorial conclusion

Adopt Pilot if your team already files small, well-scoped tickets in GitHub, GitLab, Linear, Jira or Asana and you want a PR waiting for review rather than a chat transcript. Do not adopt it if you cannot install the Claude Code CLI 2.1.17 or newer on the machine that runs it, or if your tickets are large and ambiguous: the epic decomposition step splits work into sequential subtasks, and sequential execution waits for a merge before starting the next one, which serialises your throughput. Before rolling it out, run pilot init and inspect the generated config.yaml, then start with pilot start --env=prod --github so CI and human approval gate every merge instead of the dev mode that skips CI.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. qf-studio/pilot on GitHub
4. README
5. Releases