Skip to main content
The agent can build a change and leave it for you to check, or also handle saving it and adding it to the project. You choose where its work ends and yours begins. By default, it changes the files on your computer and leaves the remaining steps to you. If you do not know those steps, ask the agent to explain them or help you choose a different setting.
These choices apply to your copy of the project. They do not change what a colleague’s agent may do. You can change your choice later.

Turn it on

Send this in your AI chat:
Send to your agent
The agent explains the options, asks what you want, and shows the settings before saving them. You do not need to edit a file yourself.
  1. Create .ai/config.local.yaml in your project if it does not exist, and add one line:
    The file is yours: Git ignores it, and jig init adds it to .gitignore if an older project does not ignore it yet.
  2. For pr, the agent opens the pull request with GitHub’s gh or GitLab’s glab. Install the one for your host and sign in once:
    Without a signed-in tool the agent still commits and pushes, then tells you the pull request is yours to open.
  3. Check it took effect:
Putting agent.git in the committed .ai/config.yaml does nothing: that file is shared with everyone, and a shared value would switch every contributor’s agent on. jig status and jig doctor warn when they find it there.

Choose how far it goes

Think about what you want to happen when a change is ready. These are three useful starting points; the agent can also help you choose a step in between.

Leave the result for me to check

The agent changes the files on your computer and reports what it did. This is the default. You try the result; saving a version in the project’s history and sharing it still need a separate step.

Prepare everything for review

The agent saves a version, sends it to your project’s shared storage, and opens a review page with the change and its checks. You or a developer reviews it and decides whether to add it to the main version of the project.

Add checked changes automatically

The agent also adds the change to the main version when the project’s automatic checks pass and its rules allow it. If something prevents that, it leaves the change waiting and explains why.
Not sure yet? Ask: “What would I have to do myself with each option? Show me using a task from this project.” Choose after you understand what will be left to you.
Adding a change to the project does not necessarily publish it. A website becomes public only through its publishing setup. Ask the agent whether that happens automatically in your project.
A commit saves a version in Git. A push sends it to the shared repository. A pull request is the review page for a change; merge adds it to its target branch.Up to pr, merging is your decision. The same levels apply to a specification’s epic (Specs and epics).

If you choose automatic completion

This option needs automatic checks already set up for your project. The agent waits for them; if a check fails, no checks ran, or a required approval is missing, the change stays waiting. What you do then: read the agent’s explanation. Ask it to fix a failure or explain whose approval is needed. It cannot simply ignore the project’s rules to finish.
This choice concerns adding finished work to the project. It does not by itself let the agent make every decision for you while building. Autopilot explains that separate choice.
With agent.git: merge, jig task ship opens the pull request, waits for its checks and merges it — only when at least one check ran and every check passed (it waits up to agent.ci_timeout minutes, 30 by default, set in the same file), the review left nothing serious open, the pull request is not a draft and it is exactly the commit that was shipped. It merges the way your repository allows: a merge commit, else squash, else rebase.agent.git limits only what the agent does on its own. When you merge or land a pull request yourself, with jig task merge-pr <id> --by human or jig task land <id> --by human (or the same button in a dashboard), Jig does not read it: at none you can still merge from the card. Branch protection holds for you too.It never uses an administrator’s override and never asks the host to “merge when ready” later. When your repository’s branch protection refuses — a required review, for example — the pull request stays open and ship says why:
That is not an error: protection on your main branch is the limit your team keeps over one person’s setting. The level works the same with GitLab.Once it has merged, the branch goes with its work. Shipped from your main checkout, ship switches you back to the main branch, brings it up to date and deletes the task’s branch, here and on the remote. Shipped from the task’s own worktree, the branch stays until housekeeping removes the worktree after the task is closed, and deletes the branch then (on the remote too, at push or higher). Only Jig’s own branches are ever deleted, with git branch -d — Git itself refuses one holding a commit that is nowhere else. When another tool (an IDE’s background fetch --prune) already removed the branch’s remote copy and Git refuses, the branch still goes if its last commit is exactly the one the hosting site merged, or an earlier one; a branch with anything newer stays. On the remote a branch is deleted only while it is still at the commit that was merged. Set git.delete_merged_branches: false in .ai/config.local.yaml to keep every branch. Together with autopilot.unattended: true it is how a run finishes without you (Autopilot: without stops).

What happens at the end of a task

The agent checks its work, records anything future sessions need to know, and takes the final steps you allowed. Ask it to make the result clear:
Send to your agent
You should get a result you can inspect and a clear next step. If the agent gives you a technical instruction you do not understand, ask it to explain the action and why it is needed.
When the work is finished and checked, the agent:
  1. records what the project should remember from the task — or that there is nothing;
  2. stages the task’s own changes, and only those — if other work sits in the same folder, it stays out of the commit;
  3. writes the commit message: the first line becomes the pull request’s title, the rest its description — what the task was for and how it was checked;
  4. runs jig task ship, which does the Git part as far as your level allows and reports each step:
    At a lower level it says where it stopped, for example stopped at push: the pull request is the human's.
The pull request goes into the branch the task was cut from: your main branch, or the epic branch of a specification released at once (New project). You do not have to pick it.In a project on the staging flow (git.flow: staging), a task cut from the main branch opens its pull request into the staging branch instead, and none into the main branch. At merge the ship also lands it there; below merge it stops at the pull request and you land it later with jig task land <id>. When the task has been tested, “prepare for prod” (jig task promote <id>) opens a second pull request, from the task’s branch into the main branch. A task of an epic still goes into its epic. Before shipping onto staging your agent asks you who should review, offering the people who reviewed recent pull requests there, and jig task ship <id> --reviewer <login or name> requests them on the pull request it opens; it lands only once every one of them has answered. The whole flow — setup, review, landing, conflicts, promoting from CI, auto-merge — is on Test on staging first.

A different choice for autopilot

You can trust a task the agent runs on autopilot further than the work you follow step by step, or less far. A common choice: the tasks you go through with the agent, answering its questions, end on a review page you merge yourself; the tasks you hand to autopilot are added to the project on their own once the automatic checks pass. Say so:
Send to your agent
Without this choice, autopilot goes exactly as far as everything else.
autopilot.git takes the same five levels as agent.git and is read the same way — only from .ai/config.local.yaml. It decides how far jig task ship goes for a task whose autopilot run is going (jig task autopilot <id> start until end, a phase run’s tasks included; a run stopped to ask you is yours again, and goes by agent.git), and how far jig spec ship goes when autopilot.unattended is true. Everything else — a task shipped outside a run, jig upgrade — goes by agent.git. Not set, it is agent.git.
With that, a task you ship yourself stops at an open pull request, and a run merges its own once CI passed. The other way round (agent.git: merge, autopilot.git: pr) a run stops at the pull request. release.merge: human still keeps every release’s merge yours: any pull request whose change raises the version.You can see which one decides: jig status prints autopilot.git: merge (from autopilot.git) or (from agent.git), jig task route <id> and jig task autopilot <id> start print autopilot git: <level> (<key>), and jig task ship names the key it went by: task ship: git level merge (autopilot.git).
On a project that uses the staging flow, agent.git_staging is a level of its own for a task whose pull request goes into the staging branch; see Ship and land. Not set, agent.git answers there as everywhere.

When a project takes several tasks

You may want to collect several completed parts before releasing the whole feature. Tell the agent what should be usable first and when you want other people to receive it. It will help plan that work and explain the decisions that need you. Your choice above also governs how far the agent can take that larger piece of work. You do not need to learn the branch commands to discuss the release.
The same setting covers the work of a specification released at once: the spec reaching your main branch, the epic branch, and the epic’s final pull request. The agent runs jig spec ship <id>, which works out which of four it is from where your repository stands, prints it (mode: declare, mode: epic, mode: final or mode: remove) and goes as far as your level allows:What stays yours at every level:
  • Finishing. The agent finishes an epic only when you say every phase is in.
  • The version. A feature epic’s final pull request merges the finished feature without touching the version; jig spec ship refuses one that raises it. The release comes after, made apart by the jig-release skill (below). An epic that jig-release declared as a release carries a Release: line with the level you chose, and its final pull request raises the version by it.
  • Merging. Only an unattended run at merge (autopilot.git, or agent.git when that is not set) merges an epic’s final pull request — with a merge commit, once CI passed and every roadmap item is done. On a release epic it never merges a major release, which it opens as a draft for you, and release.merge: human in .ai/config.local.yaml leaves even that merge to you.
  • A release. A pull request whose change raises the version into the default branch — VERSION, or the version of package.json, composer.json, pyproject.toml or Cargo.toml at the repository’s root — is a release, and jig task ship merges it by the same rule: only in an unattended run, only with release.merge: agent, never a major one, which it opens as a draft. It says so: task ship: this change raises the version in package.json: 1.4.0 -> 1.5.0.
  • Release notes cover everything they release. The task that writes a release’s notes records which commit of the default branch they describe (jig task set <id> notes_through <sha>), and jig task ship writes it into the commit as Release-Notes-Through: <sha>. From level pr, a release is refused before anything is sent while the default branch has commits after it — work merged after the notes were written would otherwise reach the release undescribed — and checked again right before a merge. When it is refused, describe what came in, record the new tip and ship again.
  • Protected epic branches. The epic is never pushed to after it is cut: the finish goes on a branch cut from it, finish/<id>, and the pull request into main comes from there, so a repository that protects epic/* like main needs no bypass.
jig spec ship keeps the limits of jig task ship below: it never force-pushes or skips hooks, never merges a spec reaching main or a spec’s removal, merges the epic only as above, commits only what was staged, and refuses when task notes or runtime files are staged. A spec reaching main is committed on a branch of its own, never on main itself, and may stage nothing but the spec. The epic is pushed only as a fast-forward: when someone else moved it on the server, the push is refused and the agent tells you. The final pull request is refused until the epic holds the latest main.

Try the result and ask for changes

Check the behaviour you asked for. For example, open the class schedule and try making a booking. If something is wrong, tell the agent what you did, what happened, and what you expected:
Send to your agent
If the work is waiting on a review page, you can send that feedback before it is added to the project. If you allowed automatic completion, it may already have been added; tell the agent what needs correcting and let it check the task’s current state.
Review the pull request as you would any other. When you ask for a change, the agent makes it in the same task and runs jig task ship again: it commits the fix, pushes it, and reports the pull request that is already open instead of opening a second one.After you merge, the task is not closed yet — a fix may still follow. At the start of a later session the agent names the merged task and asks whether it can be closed. Nothing is closed without your yes.

Two GitHub accounts

If you are signed in to gh with more than one account — a work one and a personal one, say — gh answers as whichever is active, on the whole machine. Jig does not depend on that. For each project it finds the one account of yours that may push to the repository and uses it for the pull request, the checks, the merge and a push over HTTPS, whichever account gh has active. It never switches accounts, so a session in another project is not disturbed, and your agent does not ask you to switch either. jig status shows the account it found:
You only need to say which account when several of yours may push to the same repository and the active one is not among them. The agent asks once and records it for you; by hand it is one line in .ai/config.local.yaml:
To ask GitHub something about the project yourself as that account, put jig in front: jig gh pr list.
  • Each gh call gets that account’s stored token for the call only (gh auth token --user, gh 2.40 or later). Nothing is written to gh’s configuration.
  • A GH_TOKEN or GITHUB_TOKEN already in the environment wins over everything, as it does for gh itself, so CI and a project .envrc keep working. It also wins when you did not mean it to: a tool started from another project’s directory inherits that directory’s GH_TOKEN. When GitHub refuses to open a pull request (“must be a collaborator”), the failure names the account Jig asked as and where it came from — github.account, the one found, or a token in the environment, with the variable to remove.
  • Pushing and fetching over HTTPS go as the same account — the one you named, the one Jig found among several, or the only one gh holds: for each of those git calls, Jig sets aside your credential helper for that host and has git ask gh for that account’s token. Nothing is stored in your helper or in git’s configuration. If your helper held another GitHub user’s credentials, the push now goes as the gh account instead; a GH_TOKEN in the environment, or an SSH origin, leaves git as it was. Over SSH your key decides the account.
  • When several accounts may push, the active one is not among them and none is named, a ship stops before its push and says how to name one; nothing is sent. Over HTTPS that holds at every agent.git level; over SSH only at pr and merge, where the pull request needs an account — at push your key decides.
  • A push that changes a file under .github/workflows needs the workflow scope on that account’s gh token. gh auth refresh -s workflow adds it to the active account only; for another one, make it active for that one command with gh auth switch --user <login>, then switch back, while no other session is working — the active account is the whole machine’s. Jig itself never switches, and your agent never asks you to.
  • jig pr fetch, which reads a colleague’s pull request, still fetches as your credential helper answers.
  • The choice is remembered in .ai/runtime/gh-account; delete the file to have Jig look again.

When the agent cannot finish

It should tell you what stopped it and what needs to happen next. That might mean fixing a failed check, getting a person’s approval, or completing a setup step.
Send to your agent
It is a script, so these limits hold whatever the agent intends:
  • it never force-pushes and never skips your Git hooks, and it merges only at merge, only on green checks and never past your repository’s protection;
  • it commits what was staged; with nothing staged it stages the changes to files Git already tracks and lists them, so the change goes out with the ship instead of staying in the folder;
  • it never stages a new file for you: with nothing staged, a new file that is neither staged nor in .gitignore is a refusal that names it — a secret or a scratch file pushed to your forge cannot be taken back. The commit message and pull request body files do not count;
  • when something is staged, that is the commit, and it names every change it left out. At merge, with no person between the commit and your main branch, it refuses instead, committing nothing, until the rest is staged or --partial says the rest is not this task’s;
  • it refuses when the branch has no commit your main branch does not, before it pushes anything or asks your forge for a pull request;
  • it refuses, changing nothing, until the task’s knowledge decision is recorded;
  • it refuses on any branch but the task’s own, and on the main branch itself;
  • it refuses when task notes (.ai/workspace/) or Jig’s runtime files (.ai/runtime/) are staged — those never leave your machine.
When it refuses, the message says why and what to run. At none it does nothing at all, and the agent tells you the change is ready for your review.

Turn it off

To return to the default, say:
Send to your agent
This changes how future shipping steps are handled. It does not undo work already saved, sent, or added to the project. If you also enabled runs without questions, ask the agent to turn that separate setting off too.
That removes the line, so the default — none — applies again; setting agent.git: none explicitly does the same thing. The next task ends in your working tree again. The same command takes back autopilot.git and autopilot.unattended, and jig config show --local prints what is left (Configuration).