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 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.
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. Setclaude.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
Setexecutor.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: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: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: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:
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 runjig 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:
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:
.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:
🔔 <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:
(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: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.
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: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 itjig task startrefuses, and the reason is shown byjig status.
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:--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:
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.