Skip to main content
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:
Send to your agent
Autopilot still stops for decisions that need you by default. Running without questions is a separate, explicit setting; see Without stops.
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: The run’s level is autopilot.git when you set it, and agent.git when you did not — so with nothing extra set a run goes exactly as far as the rest of your work. Set autopilot.git to let a run go further or less far than the tasks you follow step by step; for example agent.git: pr with autopilot.git: merge merges what autopilot builds and leaves everything else to you (A different choice for autopilot). The agent names the level and where it comes from when the run starts (autopilot git: merge (autopilot.git)). 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.

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. As in every task, the review is done by a second agent that did not write the code. One thing is different:
  • 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). Autopilot does not relax any of them.

Helpers on another model

In Claude Code or Codex your agent can hand two stages to a helper on a model you choose: writing the code, and reviewing it. Set claude.implement_model and claude.review_model in Claude Code, or codex.implement_model and codex.review_model in Codex (Configuration), or by answering the question jig-setup asks. A common choice is sonnet for both while your own session runs on Opus: the helpers cost less, and the agent that classified the task, wrote the design and answers for the result stays the one you picked. The cheaper helper is safe because nothing it does is taken on its word. Its review findings go into the ledger and block the task until they are fixed, its review is pinned to what it read, and the checks still have to pass (Working with tasks). Classifying, the design and its approval, the checks, deciding what the project should remember and shipping stay with your agent. Jig never checks the name you write: the selected runtime interprets it. With nothing set — the default — no helper model is chosen, and a review still goes to a second agent on your session’s own model, with or without autopilot. For a T4 task a review model unlike the coding one is what makes its review run on another model; without one, the pull request says the review ran on the same model. Codex uses its own two settings. A requested Codex helper that cannot start stops the stage instead of silently changing the chosen executor. jig task route <task-id> prints a delegate: line for each configured runtime and stage; the session follows its own runtime’s lines.

A stage in the other runtime

Set executor.implement_runtime or executor.review_runtime to claude or codex in your local settings, or answer the question jig-setup asks when the other CLI is installed, to choose which runtime does that stage. If you are already in the chosen runtime, it follows the in-runtime helper choice above. Otherwise your agent starts the other CLI in the task worktree with limited tools. You can also set executor.implement_model or executor.review_model for that external process. The review starts in a fresh process without the implementation conversation. The current agent checks the process result, task diff, findings and review receipt, and runs Jig’s verification. A missing CLI, permission denial or interrupted run stops the stage with the reason. jig task route <task-id> shows the selected runtime.

Different executors in one roadmap wave

Before starting each task, the coordinator can set its own runtime and model:
Each value overrides the matching personal setting for that task only. jig task route <task-id> shows whether a value came from the task or your local config. An unset value inherits your local choice; inherit removes a task value before start. Jig records the effective choices when the task starts, so a later personal-settings change cannot silently switch a running agent’s executor or model. The existing phase coordinator gives each task its own worktree, checks its review and verification, and merges finished tasks one at a time.

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. After you answer, the agent continues, and it gets two fresh attempts at fixing: your answer gave the run a new direction. It carries your answer into the run’s record word for word, and the report lists it under Resumed on an answer — if you see an answer there you never gave, the agent resumed itself. In a project on the staging flow, a run ends where the task lands on the staging branch, or where its pull request into the staging branch waits for a review: the task is then parked. The run does not approve that pull request, does not land it without a review unless you said so, and never prepares it for prod. It cannot start again on a parked task: when QA asks for a fix, you take the task back with jig task resume <id> (or tell the agent to), and a new run can do the fix.

Taking a stopped run over

You can finish a stopped task yourself, or tell the agent to go on with it without autopilot. Say so to the agent, and it records your words:
The run ends, and the task stops waiting for you on the status page and in jig status (autopilot=handed-over). From then on the design approval is yours: if the design changed, the page still asks you to approve it. The task ships at your own git level. A task that was handed over never starts a new run, so it gains no new attempts at fixing. The report lists your words under Taken over by a person, and a Telegram message says it happened: if you see one you never sent, the agent took the run over by itself.

Pausing a run yourself

To stop a run that needs nothing from you — you want to look at something first, or need the machine — ask it to pause:
The agent finishes the stage it is on and, instead of starting the next one, pauses the task and ends its session. The request waits until then, however long the stage takes; jig queue cancel <task-id> pause takes it back. To continue, run jig task resume <task-id> — from any checkout, since a requested pause stashes nothing — and start a new session in the task’s worktree: the run picks up at the stage it had not started. A paused run is not a stop, so there is no question to answer.

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, the route’s depth (full or lean), and how it ended. At the pr level or above the pull request’s description is short and in English: what changed and why, the review and check results, and the report’s sections listing what the agent chose without you. You can see the whole report any time with:
When the task edited a file one of your adopted rules links to — a document in your docs/, an ADR — the report lists it under Changed linked sources — need your review, one line per rule with the size of the edit and the command that shows it, and the pull request carries the same block. The agent never approves its own edit, so the new text waits for you in jig-accept; the block does not stop the run or the merge. jig status marks a task that is running with autopilot=on, one waiting for you with autopilot=stopped, one a person answered that waits for a free slot with autopilot=answered, and one a person took over with autopilot=handed-over. Every run waiting for an answer is also listed in a waiting for you: block of jig status, each with its question word for word, so you can answer them all in one go from any session: jig task autopilot <id> answer --answer <text> (--by human for an unattended run).

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

Messages in Telegram

With several runs going at once, the status page still needs you to look. Jig can tell you instead: when a run stops, ends, or — in a run without stops — approves its own design or decides something for you, a short message reaches your Telegram within seconds:
The first line names the project and the task, the second is the task’s own short description, the third is what the agent needs, chose, or how the run ended. The mark says which: Nothing is sent when the run starts, moves to the next stage or fixes something: those need nothing from you. A whole phase sends one too, when its coordinator stops — a wave waiting for your answers, or, without stops, a draft that ended the run. It names the specification and the phase instead of a task:
⛔ there means the phase run ended and nothing waits for you; the next wave is yours to start. To set it up, make a bot with @BotFather in Telegram (/newbot gives you the bot’s token), and send your bot any message. Your chat id is the chat → id of that message, which Telegram’s https://api.telegram.org/bot<token>/getUpdates shows in a browser. Then run, in your own terminal:
It asks for the token without showing it as you type, and for the chat id; writes both into your .ai/config.local.yaml (readable by you alone on macOS and Linux); and sends a test message. It refuses to run without a terminal, and gives up after five minutes with nothing typed — so it is yours to run, never your agent’s: the token never passes through the agent. It also refuses while git does not ignore .ai/config.local.yaml (jig init fixes that). Run it again to change either value; pressing Enter keeps the one set. Then let your agent check that it can reach Telegram — the jig-setup skill does this for you:
It sends 🔔 <project> · notifications work the way autopilot sends its messages, from the agent’s own session, and waits for Telegram’s answer. When it fails, it prints that answer — a wrong token, a chat the bot has never seen — or curl’s, which usually means the agent’s sandbox keeps it off the network: then autopilot’s messages would not arrive either. You can also write the token into .ai/config.local.yaml yourself, in your editor, as one line (notify.telegram.token: 123456789:AAE...), and the chat id with jig config set notify.telegram.chat_id 987654321 --local. Jig refuses the token on a command line — a command line is kept by your shell’s history, by the list of running processes, and by your agent’s transcript — and never prints it back: jig config show --local, jig notify and jig status show ******** in its place. Never put the token in .ai/config.yaml: that file is committed, and a token in it is anyone’s once pushed. Jig ignores it there, and jig status tells you to revoke it with @BotFather. Sending never slows a run down or breaks it: the message goes in the background, and a run on a machine without curl simply sends nothing. When a message cannot be delivered — a wrong token or chat id, or an agent whose sandbox has no network — jig status says so until the next message gets through:
A phase’s message that failed is named by its specification there: (spec release-1-2, …), and a waiting session’s (below) by its task, or as (a waiting session, …) when its branch has none. To pause the autopilot’s messages without removing the settings, set notify.autopilot to false; a waiting session’s messages follow notify.interactive alone. Silence is not “still working”. A session that dies — closed, out of context, the computer asleep — records no stop, and so sends nothing.

When an ordinary session waits for you

The same message can reach you from a session that is not on autopilot, when it waits for your permission or your answer — so you can walk away from the screen and still be told. It is off by default, so that “message me about autopilot, not while I sit at the computer” stays possible; turn it on with:
The second line is there only when the branch belongs to a task; without one, the first line names the branch. The last line is Waiting for your permission or Waiting for your answer. The session decides when it waits, so Jig needs its runtime’s hook: in Claude Code, the Notification hook calling .ai/scripts/jig-notify-hook. Jig never edits your runtime’s settings; jig doctor prints the lines to add to your own .claude/settings.local.json, and jig status says notify hook (claude): connected once they are there. The jig-setup skill can add them for you after your yes. How often it writes depends on where Claude Code runs. In the terminal, Claude Code calls the hook only when you seem to be away: a permission prompt that waited about six seconds, or a minute with nothing typed after its answer. In the desktop app and in the IDE extensions a permission prompt calls it after about six seconds even while you are sitting there, so with notify.interactive on you get a message for every permission you take longer than that to give. While the branch’s task has an autopilot run going or stopped, “waiting for your answer” sends nothing — the run’s own message already said it stopped. A permission prompt is sent all the same: the run cannot report it. Codex is not supported: it has no event for a session that waits for you. Its notify program is called at the end of every turn, and its PermissionRequest hook at once on every approval, whether you are there or not.

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):
(autopilot.git: merge in place of the first line lets only autopilot runs merge, and leaves the rest of your work at agent.git.) 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: A task you work on by hand, with no autopilot run of its own, is still yours to approve: jig task gate <id> approved records your approval with questions turned off too. If you are present and answer a run that was already stopped for a decision, the agent can record your exact answer and continue without gaining more attempts to fix a failing change. A stop after the repair limit still ends in a draft, unless you take the task over. If a risky design changed while the run was stopped, the agent’s new approval remains labeled as its own in the pull request; your answer to one decision is not treated as approval of the whole design. 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 by itself: that pull request opens as a draft that says “Needs a human: major release?”. It never releases notes that miss work merged after they were written (release notes cover everything they 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:
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.

Several tasks in one run

You can hand over more than one task at once:
“Take booking-form, booking-message and the csv export on autopilot.”
Each task gets a run of its own, and the agent starts the next one as a place frees (autopilot.parallel, below). The tasks you named are not the whole queue, though: something more urgent may be filed while they run. So before every start the agent asks jig queue next which task to take:
  • When the queue names one of your tasks, or nothing more urgent than the next of them, that next task starts.
  • When it names a task outside your list with a higher priority, the agent starts neither on its own — it tells you which task the queue names and asks whether to take it or keep to your list. Without stops it decides for you, cautiously: the tasks already running finish, nothing new starts, and the decision reaches you as any other. It never takes someone else’s T3 or T4 task to approve that task’s design itself.
  • A task the queue names as taken by another session is never started, even one from your list; the agent names it when it hands back.
  • Once you have chosen, or the decision was made for you, a task the queue would not name is started with jig task start <id> --out-of-order --reason "<why>": without it jig task start refuses, and the reason is shown by jig status.
A run that stops to ask you something gives its place up: the next task starts while the question waits, and there is no limit to how many may wait. jig queue next counts the places (slots: 1 of 2 free (1 building): runs that are on and not consolidated yet, across the clone). Answer from any session with jig task autopilot <id> answer --answer <text>; the answer is recorded, and the run resumes on the next free place, before any new task: jig queue next lists answered runs under resume first:, most urgent first, then the one that stopped first. A running task is never pushed out to make room. A task that depends on a waiting one in the queue waits too (its autopilot run is stopped, waiting for an answer or a free slot). In Claude Code desktop, when you ask for it, the coordinator of a set may run each task in a session of its own, in its own worktree: the sidebar shows which ones wait, and the last message of a stopped session is its question. Answer in that session. The session runs the filed Jig task as usual; once the task is consolidated the coordinator archives the session if you asked it to. Other runtimes are unchanged, and a phase run keeps using subagents. A whole phase asks the queue the same way before starting each of its tasks.

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:
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. They are the runtime’s subagents, not sessions you open: the run goes on between your messages, and the Claude Code desktop app starts a session only on your own words. The status page shows their progress. 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 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 (the run’s level — autopilot.git, else agent.git — at pr or merge) and a specification built on an epic branch. 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:
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 — and when you set up Telegram messages, a short one reaches your phone too. The wave being worked on finishes either way; it is the next wave that waits for your answer. Without stops (above) 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.