> ## Documentation Index
> Fetch the complete documentation index at: https://jig.fapost.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Autopilot

> Hand a task to the agent and get it back finished — what a run does, where it stops, and what to do at each stop.

Normally the agent reports after each stage of a task and waits for you to say "go on". On
autopilot it goes from stage to stage by itself and comes back only when it is finished, or when it
needs something only you can give.

## Start a run

Say it the way you would ask for any task:

> *"Take the CSV export on autopilot."*
> *"Fix the login redirect, end to end, without me."*

The agent sizes the task as usual, says what will happen and where the run will end, and starts.
Asking for autopilot covers that one task only.

Where the run ends depends on [Letting the agent ship](/agent-ships):

| `agent.git` in your `.ai/config.local.yaml` | The run ends with                                                              |
| ------------------------------------------- | ------------------------------------------------------------------------------ |
| `merge`                                     | the pull request merged once its checks passed — or left open, with the reason |
| `pr`                                        | an open pull request for you to review and merge                               |
| `push` or `commit`                          | the task's branch pushed or committed; the rest is yours                       |
| `none` (default)                            | the change in your working tree, ready for your review and commit              |

Below `merge` the agent never merges, and the pull request is where you look at the result. If you
cannot answer the questions a run stops on, read [Without stops](#without-stops).

## What happens during a run

The same steps as without autopilot, in the same order: understanding the task, a plan or a design,
the change itself, a review, the checks, and recording what the project should remember. Two things
are different:

* **The review is done by a second agent** that did not write the code, so the author does not
  review its own work.
* **Fixing has a limit.** When the review finds a serious problem or the checks fail, the agent
  fixes it and has it looked at again — at most twice per run. A third attempt is refused by Jig
  itself, and the run stops instead of going round in circles.

The same rules that stop an ordinary task stop a run: a serious review finding that is not fixed, or
a change made after its review, keeps the task from being finished ([Working with tasks](/working-with-tasks#review-findings)).
Autopilot does not relax any of them.

## Where it stops

A run stops only where a human is needed. The agent tells you in plain words what it needs; answer
it, and it carries on from where it stopped.

| The run stops when                                                                                | What you do                                                                                                       |
| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| The task is risky enough to need your approval of its design (classes T3 and T4)                  | Read the design it shows you and approve it, ask for changes, or reject it                                        |
| A problem is still there after two attempts to fix it                                             | Suggest another approach, decide the problem can stay (a serious one only you can wave through), or drop the task |
| The task turns out bigger and now needs a design approval                                         | The same as the first row                                                                                         |
| It needs a decision nobody has made — a product choice not written down anywhere                  | Make the decision                                                                                                 |
| The next step would destroy something — force-push, delete a branch, delete data, rewrite history | Allow it, or ask for another way                                                                                  |

After you answer, the agent continues, and it gets two fresh attempts at fixing: your answer gave
the run a new direction.

## The report

At the end — or at a stop — the agent shows the run's report: which stages it went through, each
fixing attempt and why, each stop and its reason, and how it ended. With `agent.git: pr` the report
is also in the pull request's description. You can see it any time with:

```bash theme={null}
jig task autopilot <task-id> report
```

`jig status` marks a task that is running with `autopilot=on`, and one waiting for you with
`autopilot=stopped`.

## Watching a run

To follow a run without asking the agent, open the status page — the agent offers it when the run
starts, or run `jig status --open` ([Seeing where things stand](/working-with-tasks#seeing-where-things-stand)).
While the run goes on, the page shows the stage it is in, for how long, and how many of its two
fixing attempts it used. When it stops, a card at the top says so, with the agent's question and
when it was asked. The page keeps itself up to date: leave it open.

## Without stops

The stops above ask for decisions a developer makes. If you build through the agent without being
one, you may not be able to answer them — and you would rather have your change deployed. Then add
two lines to `.ai/config.local.yaml` in your project (create the file if it is not there):

```yaml theme={null}
agent.git: merge
autopilot.unattended: true
```

Or ask your agent to *"set up Jig for me"*: it explains both before asking, and writes them only
after your yes. Both are personal: they change what **your** agent does, never a colleague's, and they do nothing in
the shared `.ai/config.yaml`. The first lets the agent merge its pull request; the second lets a run
go on without asking you anything. Hand over a task as usual — *"take the CSV export on
autopilot"* — and the agent comes back when the change is merged, or with a pull request and the
reason it stayed open.

### What the agent decides for you

Where a run would stop and ask, it takes the safe choice instead and writes it down in the pull
request, in plain words:

| Where it would ask                                 | What it does instead                                                                                                     |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Approving the design of a risky task               | Approves its own design. The design is in the pull request under **Design — approved by the agent, not a human**         |
| A decision nobody has made                         | Picks the most careful option, the one easiest to undo. Listed under **Decided without you**                             |
| Something that would destroy data or history       | Never does it. It finds another way or leaves that part out, and says so under **Decided without you**                   |
| A problem still there after two attempts to fix it | Stops working and opens a **draft** pull request that starts with **Not finished** and says why. A draft is never merged |

Read these sections in the pull request, even after it merged: they are everything the agent chose
without you. The run's report (`jig task autopilot <task-id> report`) lists them too.

### When it merges

Only when all of this holds:

* your project's automatic checks (CI) ran on the pull request — at least one — and every one
  passed, within 30 minutes (change it with `agent.ci_timeout: <minutes>` in the same file);
* the review found nothing serious left, and nothing changed after the review;
* the pull request is not a draft, and it is exactly the change the agent sent.

Then the agent merges it the way your repository allows, closes the task, and your CI deploys as it
always does. A project with no CI never gets merged: checks that never ran prove nothing.

### What it never does

* It never merges past your repository's rules — no admin override, no "merge later by itself".
* It never dismisses a serious review finding, and never skips the review or the checks.
* It never force-pushes, deletes branches or data, or rewrites history.
* It never merges a draft, a pull request with a failed check, or one no check ran on.
* It never releases a **major** version of a whole feature ([an epic](/agent-ships#specs-and-epics)) by
  itself: that pull request opens as a draft that says "Needs a human: major release?".

### Why a pull request can stay open

Many repositories protect their main branch: a required human review, a required check, a list of
who may merge. The agent obeys that protection — it is the limit your team keeps over one person's
settings. When the repository refuses, the pull request stays open, and the agent tells you why:

```text theme={null}
not merged: the forge refused: At least 1 approving review is required
```

Ask someone who may approve or merge on your repository to look at it. The same line explains the
other cases — a failed check, checks that took longer than the timeout, or no checks at all.

## Which tasks of a phase may start

A specification's roadmap groups its items into waves: the items of one wave can be worked on at the
same time, and a wave starts only once everything in the waves before it has been merged. To see
where a phase stands, run:

```bash theme={null}
jig spec plan <spec-id> --phase <n>
```

It lists each wave of that phase with its items, the task each one was filed as and how far that
task is, what earlier waves are still holding it, and which tasks may start now. An entry of the
waves list that names no roadmap item, or more than one, is reported, never guessed. It changes
nothing and needs no network. `--format tsv` prints the same answer for a script to read.

## Running a whole phase

A run can take a phase of a roadmap instead of a single task:

> *"Run phase 4 of the autopilot spec on autopilot."*

The agent becomes a **coordinator**. For each wave of that phase it files the wave's tasks,
gives each one its own folder and its own agent, and those agents work at the same time. The
coordinator writes no code itself: it opens each task's pull request, keeps the merge queue,
and after every merge ticks the roadmap item off and brings the other branches of the wave up
to date. A wave finishes; then the next one starts.

The session you ask in becomes the coordinator, and it holds the epic branch for the whole run, so
ask in a checkout that is free to sit on that branch. Your main one is the natural place: the task
records of the whole phase are kept where the coordinator started them, and that is where
`jig status` and the status page read them. A [worktree](/working-with-tasks#several-agents-at-once)
of the epic works too when the main checkout is busy with other work — the phase's tasks then belong
to that worktree, so ask there for the status of the run as well.

For this it needs two things: permission to open pull requests (`agent.git: pr` or `merge`) and
a specification built on [an epic branch](/agent-ships#specs-and-epics). Without either it says
so and offers to run the phase's tasks one at a time instead.

**How many at once** is yours to choose, in `.ai/config.local.yaml`:

```yaml theme={null}
autopilot.parallel: 2
```

Two by default, at most sixteen. The number counts only the agents still *building* a task: one
whose work is finished and is waiting its turn to be merged does not hold a place, and neither
do the short-lived agents that fix a failed check or a merge conflict. `jig spec plan` prints
what is left — *"may start now: a, b (1 of 2 slots free)"* — and the status page shows the phase,
its waves and its free places while the run goes on.

**Where you answer.** A question from any task of the phase comes to you in the coordinator's
session, not the task's — the status page says so too. Questions from one wave arrive together,
in a single message. The wave being worked on finishes either way; it is the **next** wave that
waits for your answer. Without stops ([above](#without-stops)) nothing is asked: a task that
could not be finished becomes a draft pull request, and the phase run ends there with a report,
leaving the next wave to you.

**Why a change is reviewed again.** Every time another task of the wave lands, the branches
still open are brought up to date with it. When what arrived is more than the roadmap tick, the
task's review no longer covers what the branch now contains, so it is reviewed again before it
ships. That is the cost of an honest review, not a wasted step.

## What autopilot does not protect you from

Jig's scripts cannot see the commands the agent runs. The limit on fixing attempts and the rules
that keep an unfinished task from being finished are enforced by Jig; the stop before a destructive
operation is a rule the agent follows. What really prevents a command you did not allow is your
coding agent's own permission settings — keep them as strict as you are comfortable with.