Skip to main content
Use these commands when you want to inspect or manage Jig yourself. Run them from your project folder. The examples use jig on your PATH; .ai/scripts/jig runs the project’s installed copy explicitly. In PowerShell, use .ai\scripts\jig.cmd for that local copy.
Commands keep the records; the agent does the work. Creating a task in the terminal does not start an AI session or write code. Return to your agent and ask it to continue the named task.

Inspect before changing anything

task list shows the tasks, and says how many are archived (jig task list --status archived lists them); task current looks for the task on this branch. When several match, choose an explicit ID. status summarizes the project and doctor checks its setup. A script can read the same task list as JSON with jig task list --json, a task’s documents with jig task artifacts <id> --json and jig task artifact read <id> <kind> --json, the specs with jig spec list --json, the queue with jig queue list --json, and what needs you with jig status --json; see Reading Jig as data. To create the browser status file without opening a browser:
Or use jig status --open to create and open it. Read about the status page.

File a task, then start it

For this example, assume a contained change already classified as T1. Use the appropriate risk class for your actual work.
Fill in .ai/workspace/tasks/booking-message/task.md: the goal, scope, and what a correct result looks like. Filing the task does not switch branches. To give the goal as you file it, pass it as one line; it becomes the paragraph under ## Goal:
To start from a brief you already wrote, pass --from <file> instead.
Start from a repository with a commit and no uncommitted tracked changes. If other work is in progress, pause its task or use a separate worktree; do not bundle it into this task’s commit.
Begin work separately:
When the queue’s advice (jig queue next, below) is another task that outranks this one, the start is refused and names that task. To start this one anyway, say why: jig task start booking-message --out-of-order --reason "<why>". The reason is kept in the task’s state and jig status shows it, so a start against the queue is never quiet. A task that is not in the queue starts as it always did. By default, this switches to a task branch from the project’s configured base. For a separate working copy, use jig task start booking-message --worktree instead, then work in the directory it prints. Tasks linked to a spec with an open epic start from that epic. Starting looks at the goal first — the same paragraph jig task list --goals shows. When ## Goal in task.md is empty or holds only the template’s comment, a T0–T2 task starts with a warning, and a T3 or T4 task is refused until the goal is written: put it in task.md with jig task artifact write booking-message task --from <file> and start again. A new worktree also gets whatever vendor/, node_modules/ or .env your project’s profiles (and worktree.carry) declare, and links to the folders worktree.share names — see carrying state into a worktree. Add --no-bootstrap to skip that for this run, or repeat it later with jig task bootstrap booking-message. Then your project’s own worktree.setup runs, if it has one. --share packages gives this one task the links to packages/ that worktree.share gives every task; jig task bootstrap booking-message --share packages adds them to a task already running. See sharing for one task.

Pause and resume

Add --stash to the pause command when you also need to put uncommitted work aside. Resume reports what changed while the task was paused. Read that report before continuing. Resume runs in any checkout, unless the pause stashed work: then run it where the task’s branch is checked out (its worktree, if it has one), because that is where the stash is applied. If the stashed work conflicts with what changed while the task was paused, resume leaves the conflicts in your files and keeps the task paused. Resolve them, git add the files (or commit them), and run jig task resume again: it remembers that the stash is already in your files, does not apply it a second time, and ends the pause. The stash entry stays in git stash list either way. When an agent is working on the task, on autopilot or in an ordinary session, ask it to pause instead:
The agent finishes the stage it is on, pauses the task instead of starting the next one, and stops. An autopilot run checks when it enters its next stage; any agent checks when the next stage reads its context with jig context resolve --task <id> --stage <stage>, the first step of every stage skill. A stage without a skill of its own, such as a plan, reads none, so the request then waits for the stage after it. The request waits until then, or until you cancel it. Resume as above, and start a new session to continue.

Archive and unarchive

An archived task leaves the lists but is not deleted: its notes stay in .ai/workspace/tasks/, and its branch, worktree and pull request are not touched. You can archive an active, ready or abandoned task. Housekeeping does the same for an abandoned task after housekeeping.abandoned_ttl and for an idle one after housekeeping.stale_after. unarchive returns the task to the status it had. If an archived task’s work is merged later anyway, housekeeping asks you to close it — but only for a task that was archived unfinished. A task that was abandoned before it was archived, or absorbed into another task, stays archived without a question: what happens to it was already decided.

Merge a task into another

When one task turns out to do another’s work, merge it. The documents of booking-message are copied, not moved, to absorbed/booking-message/ in the receiving task’s notes, and the receiver’s task.md gets a section that names them. Without --partial the absorbed task is archived (reason absorbed) and anything in the queue that waited on it waits on the receiver instead; the absorbed task itself leaves the queue. jig task unarchive brings the task back, but not its queue place or the queue waits that moved: put them back with jig queue set and jig queue depend. A merge can always be run again. With --partial the task stays open and both sides note the overlap; the queue is left alone. The receiving task must be active or ready, and a merge that would make the queue wait in a circle is refused before anything changes. Jig does not touch your tracker. When the receiving task ships, its commit and pull request name the absorbed tasks’ issues in an Absorbs: line, so the tracker’s own integration can link or close them.

Close a roadmap item for a task you gave up

jig task abandon does this by itself where it can; jig spec drop <task-id> is the same edit run by hand, where Jig said it could not. It checks the roadmap item of a spec that names the abandoned task and ends it with — dropped (<date>): <reason>, or — moved to <ref> (<date>): <reason> when the task was moved elsewhere. Read about giving a task up. The edit has to be made where the roadmap is current, so the command refuses in a checkout that is not that place:
  • lands on <base>, which is not checked out here: the spec has an open epic, or the task was started from another branch, and the roadmap there is edited in a checkout of that branch. Run the command in one.
  • the task is not abandoned: abandon it first with jig task abandon <id> --reason <text>.
  • spec/<id> does not name <task>: the spec’s own branch, left from an earlier session, lacks the item the default branch has. Jig switches back to the default branch; merge it into the spec’s branch and run the command again.
A task’s own branch never ships the roadmap, so the command refuses there too and names the checkout to run it in.

Keep an idea’s draft

While you shape an idea with the jig-idea skill, the agent keeps a draft of the conversation on disk, so a session that ends early loses one round and not the whole. You can read and manage drafts yourself:
A draft is the file .ai/workspace/ideas/<id>/draft.md. It is ignored by git: it is not a spec, has no branch, and jig task start and jig spec new do not see it. write takes --from <file>, or - to read standard input, and refuses an empty draft. list shows each draft with where it is, how long ago it was written and whether a spec of that id exists. rename is for an idea whose spec was given another id, so that jig spec ship finds the draft. drop moves it to trash. A draft stays until the specification of the same id is committed, when jig spec ship moves it to trash, or until you drop it; housekeeping never removes one, whatever its age. In a clone with no main checkout to find (made with --separate-git-dir, or the worktrees of a bare repository), drafts live under <git-common-dir>/jig/ideas/, one place for every checkout. While a draft exists, jig status prints drafts: 1 (jig spec draft list).

Order the work

The queue keeps the priority, order and dependencies of your tasks and epics, one queue for the whole project, outside git. Priority runs from 0 (most urgent) to 5, and each number means one thing, so that you and your agent set “bugs first” the same way: Your agent gives a task a priority when it files it, and writes to the queue when you ask it to set priorities; a number already there it changes only when asked. --priority none takes the priority away. A task given a priority, or a new one, takes its place after the last item with the same or a more urgent number, so the order you read follows the numbers. A move places one item before or after another, or with --top and --bottom at an end; an epic (epic:<spec-id>) is ordered beside tasks, and the tasks built on it are ordered within it. A dependency always says why. jig queue remove takes an item out, and jig queue undepend drops a dependency. A program reads the queue with jig queue list --json (Reading Jig as data). A task leaves the queue by itself when it is finished: closing, abandoning or archiving it takes its entry out, and every jig housekeeping run takes out the entries of tasks that are finished or whose workspace is gone. jig queue prune does the same on demand (--dry-run only says what would go). Whatever waited on a closed task no longer waits: that dependency is met. A dependency on a task that was abandoned or archived stays, because that work never landed: jig queue next names it broken until you drop it with jig queue undepend. A task you bring back with jig task unarchive, or by setting an abandoned task active again, is not in the queue any more: give it a priority again with jig queue set. To ask which task to take next, run jig queue next. It answers from the queue and from what Jig already knows, over the network never, and changes nothing:
resume first: names the autopilot runs that stopped for a person and were answered (jig task autopilot <id> answer): they resume on the next free slot before any new task starts, most urgent first, then the one that stopped first. A stopped run holds no slot; slots: counts autopilot.parallel against the runs that are on and not consolidated in the clone. A task that depends on one whose run is stopped waits with its autopilot run is stopped, waiting for an answer or a free slot — jig status. A task a watcher could not start now is never advised either, and is named as blocked: one whose autopilot run is stopped for a person or ended not merged (blocked by a stop of <id>), one whose task.md holds only the stub, with no goal under ## Goal yet, and a release’s notes task (release-notes-*), which raises the version and stays yours. A queue held only by such stops answers blocked, not none — the queue holds no task to take: next: none — blocked by a stop of <id> for a stopped or not-merged run, and next: none — blocked: <id> has no goal in its task.md yet or … raises the version, which stays a person's for a stub or a release. Only a task that is active, not paused and not started yet is advised: what is started is listed on the in progress: line, since the advice is what to start. One waits while anything it depends on, or the epic it is built on depends on, is not finished. A task is finished when it is closed or jig housekeeping saw its pull request merged; an epic when its branch has landed. Among the tasks that do not wait the lowest priority number goes first, with a task without one last; at the same priority the place in the queue decides, a task on an epic taking its epic’s place. When no task can be taken it says why: every queued task waits for a dependency, is taken by another session, is already in progress, is held by a stop, is paused, or there is none. A wait that can never end (broken: the task it waits for was abandoned, archived or is gone) comes with the command that drops it; one Jig cannot tell (unknown) with the one that may find out. The last line counts the active tasks that are not in the queue. jig queue next --json gives the same answer to a program (Reading Jig as data). A task another session is already working on is not advised, even before it has a branch. Every session that works a task — writes its documents, sets its state, enters a stage, starts it — leaves a note of it for the whole clone, and jig queue next passes over a task whose newest note is another session’s, naming it instead:
When that leaves nothing, the answer is next: none — every queued task left is taken by another session. jig queue list prints the same line under the task. Your own session’s tasks are advised as before, and reading, filing or ordering a task does not take it: that covers reading a task’s documents, and writing the task document of a task that has no branch yet, which is how a task’s goal is filed. Any other document before jig task start, and the task document of a task already started, still take it. A note lapses after checkout.busy_ttl (12 hours unless you set it), or at once when the runtime says the session ended: in Claude Code, the SessionEnd hook calling bash "$CLAUDE_PROJECT_DIR"/.ai/scripts/jig-session-end-hook (a new .claude/settings.json made by jig init has it; add it by hand to an existing one) marks that session’s notes ended, and the readers skip them. To take over the task of a session that is gone without it, just work on it — the newest note holds the task. This needs a runtime that names its sessions (Claude Code does); a session without a name leaves no note and treats every note as another’s. jig status shows each queued task’s place on its task line — queue=2/5 is second of five on its level (the top, or the epic it is built on), priority=1 its priority — with what it waits for, and a pause asked of it with its age, on the lines under it:
A task started against the queue’s advice with --out-of-order shows the task it went ahead of on its line and the reason under it; the status page marks it “out of order” and its “Needs you” list asks you to check the reason:
Once the project has a queue, jig status also prints the first line jig queue next gives, after the task lines, so the answer is where you already look (the status page shows it as “Next task”):
When nothing can be taken the line reads next: none — and the reason; jig queue next has the lines under it. jig status only reads that answer, it does not work it out again. jig context --task <id> gives the agent working on the task the same facts as queue: lines. Without a queue, none of this appears and the output looks as it always has. jig status reads, and never fetches, so what it says about origin is as of your last fetch. To bring the clone up, run jig refresh: it fetches origin and fast-forwards the base branch to origin’s, and nothing else moves. On a task branch your branch and files stay as they are; if you are on the base branch itself, it fast-forwards there and stops where the change would overwrite your edits. It never stashes or forces, says in a line why the base could not move, and closes the writes in Jig’s own tree that are over. How a program uses it is in Reading Jig as data. In a project on the staging flow (git.flow: staging), jig status names the flow before the task lines and says, on each task line, whether the task’s work is on the staging branch:
staging=behind means the task has commits of its own that are not on the staging branch yet, such as a fix QA asked for; bringing the base branch into the task does not count. Jig reads this from git each time, by the task’s branch, comparing it with origin’s staging branch — git fetch to see what colleagues merged. When the flow cannot work, the line says so instead (flow: staging, not usable: … (jig doctor)). jig housekeeping puts the same word in its report (on staging: …, behind staging: …), and a task waiting on the staging branch is never archived as stale. With git.staging_land: external, where your CI merges tasks into the staging branch and no pull request goes there, this is how you see what CI landed: the same words, read the same way. On the default direct flow none of this appears. A shipped task that waits at the staging branch is parked, and it leaves the task lines for one line of its own:
review waits for a review of its pull request into the staging branch — landing when its review is approved (or git.staging_review is none) and you land it yourself (agent.git below merge) — and signal waits on the staging branch for “prepare for prod”. jig task list marks it parked=signal. A parked task is not the current task, jig queue next does not offer it, and another task may start in the checkout it was landed from. jig task resume <id> takes it back for a fix: it becomes active and appears among the tasks again until its next jig task ship into the staging branch, verify included — at any agent.git, also when that ship leaves the commit or the push to you. signal is read from the staging branch as your checkout last fetched it. With git.staging_land: external, a task you shipped is listed as an ordinary task — and stays your current task — until a fetch (jig housekeeping, or git fetch) shows that CI merged it; with pull requests there is no such gap, since the open pull request keeps it parked for review until the housekeeping run that hears of the merge also fetches. A task parked for the signal stays on that line however long it waits; once it has waited git.staging_stale_after, the drift report below names it as well, since nobody promoted it.

The staging drift report

On the staging flow jig status and jig housekeeping also say where the staging branch drifts from the base branch, a staging: line each:
  • Waiting with no promotion. A task’s work has been on the staging branch for git.staging_stale_after (14 days unless you set it) and no pull request into the base branch is open or merged for it. The days count from the commit that last brought its work onto the staging branch — the landing merge — so shipping a fix QA asked for starts them again. Every task branch counts, here or on origin, so a colleague’s task is named too — with (jig task promote <id>, from any checkout, or ask its owner): a task is promoted by its id from any checkout whose agent.git allows it, or from CI, workspace or not.
  • A promotion that conflicts. A promotion this checkout opened (jig task promote) that the forge, at the last housekeeping run, called conflicting with the base branch. Running the command again names the files to resolve, and pushes the merge once you have resolved it.
  • Work no task owns. Your own commits on the staging branch that the base branch does not have, that no task branch — yours or anyone’s on origin — holds, and that you have not marked as known: something committed onto the staging branch directly, or a task whose branch was deleted before its work reached the base branch. Yours means the author’s email or name is your git user’s (the one git var GIT_AUTHOR_IDENT names); a colleague’s commits are not named anywhere, not even in jig status --json. Only what the staging branch has and the base branch does not counts, so a task whose promotion was merged with a merge commit and whose branch was deleted leaves nothing here; a squash-merged one still does (see Known issues). jig staging ack --dry-run lists exactly the commits counted, and jig staging ack marks them as known in this clone (.ai/runtime/staging-acked, by content, so a rebase or cherry-pick on the staging branch keeps the mark): from then on the line counts only new ones.
All of it is read from git and from the forge cache housekeeping keeps, never from the forge directly; without a forge the line about conflicts does not appear. The status page and jig status --json show the same facts as items. Jig takes nothing off the staging branch: what to do with work on it stays your team’s call.

Inspect the change and its review

Replace main with the task’s actual base from jig task show booking-message. The change inventory includes committed and local changes; it does not prove that every change belongs to this task. Findings and the receipt tell you what was reviewed and whether that review still matches the work. A missing receipt can be expected before review or for a task whose route does not require one. When the receipt is stale, --since-review shows what changed since the review, and whether a repeat review may read only that (narrow) or must read everything (full, with the reason). An edit to GLOSSARY.md, ARCHITECTURE.md or RULES.md alone keeps it narrow and shows that edit too; a change to a document written for the task’s files, or to which documents apply to them, makes it full.

Ask which knowledge applies

Read the required documents. The catalog lists other potentially useful documents; select those with --ids when needed. For an investigation without a task, pass explicit file selectors:
Replace README.md with the actual paths you are investigating. To record documents you have actually read, use jig context acknowledge; jig context guard checks that record and names why each document it still asks for is owed (global, paths: skills/**, domains: knowledge):
--stage records at which stage a document was read, and a passing guard reports it — a guard run for review that says none acknowledged at review passed on what the implementer read. A path may be written as the guard prints it, with a leading ./, or as an absolute path inside the project. --revoke withdraws an acknowledgement given by mistake. How context works.

Review a colleague’s pull request

The jig-pr-review skill drives this when you give it the link of a GitHub pull request or a GitLab merge request. The installer and jig self-update place it for you as well as in each project, so it works in a clone of any repository, with or without Jig. The commands are the same ones you can run yourself, in your own checkout:
fetch takes the pull request’s head and base into refs of Jig’s own and a detached worktree beside the repository, <git.worktree_root>/.pr-<n>, without touching your checkout. Read that tree; run nothing in it. Its method: and show: lines name the review method and the rule for showing a document in the Jig that ran it: the skill reads them there, not beside itself. draft checks the review against the format the skill keeps and prints it; give it a file with --from to keep a new one. comments check places the draft on the forge’s own diff and prints the review as it would be posted, with a hash. comments post posts only that version: it is refused unless --shown carries the hash check printed, so what you read is what goes out. A draft may rank its findings (from 0.44.0). A === levels block right after the summary names the four severities, P0 to P3, one to a line and in the review’s language; each === comment P<n> <position> <path> then names its level and starts with a one-line title. comments check puts the level’s colour (🔴 🟠 🟡 🟢) and a number before each comment, numbered by level with P0 first, and adds to the summary a legend and the findings by level. A comment that cannot be placed on the diff moves into the summary and keeps its number. All of it is part of the version you approve and the hash covers it. A draft without a levels block is posted as before. Posting a ranked review has not yet been checked on a live pull or merge request. After the author pushes fixes:
followup reads your earlier review back from the forge: its open threads and the head you reviewed, which it finds even after a force-push. The next draft answers each thread fixed or open, and --login names the account that reviewed when it cannot be told. list shows each fetched pull request with its head, worktree and whether a draft exists; cleanup takes the worktree, the refs and the draft of one back. The record and the draft live in .ai/workspace/pr/<n>/, ignored by git. In a project without Jig installed they live in <git-common-dir>/jig/pr/<n>/, inside the clone and out of its working tree. GitHub needs gh, and gh 2.40 or later when several accounts are signed in on the host, so that Jig can post as the one that may comment; GitLab needs glab. Posting to GitLab and the follow-up have not yet been checked on a live merge request or pull request. In Claude Code your own copy of the skill wins over a project’s, so inside a Jig project the released skill runs; jig status says so when the two differ. Codex may offer both and does not document which one it uses.

Run the project’s checks

--explain previews each check as full, filtered, skipped or conditional without running the checks or waiting for another verification. It uses the same scope choice as a plain jig verify; combine it with --changed, --full, --base or --profile to preview those choices. Conditional means a tool such as Go or Jest would have to inspect the project before the final set is known, so a full run remains possible. The preview is not verification: exit 0 means a plan was printed, exit 2 means an installed profile could not explain its plan, and exit 1 means the preview failed. --changed requests checks for the changed files. Each profile says whether it narrowed its work or ran the full check. A plain jig verify follows the project’s verify.full_run setting. Configure verification.
Skipped is not passed. Read the report even when the command exits successfully. Missing tools or dependencies can leave checks unrun.

Preview a personal setting

This example previews letting the agent commit, push, and open pull requests:
To apply it, remove --dry-run. To return to the default, use:
Personal settings live in the ignored .ai/config.local.yaml. Compare the permission levels before changing one.

Finish through the workflow

Ask the agent to verify the result and record what the project should remember before shipping it. jig task ship follows your personal permissions and checks the task’s completion records. After the change lands, confirm whether the task can close. On the staging flow, jig task land <id> lands the task’s open pull request on the staging branch when you allow merge: after an approval, on the forge, or by a direct merge when it conflicts (how a task ships). It exits 3 when you decide — no approval yet, or a push the staging branch refused — and 5 when a conflict waits in its temporary worktree for jig task land <id> --resolved --note-file <file>; --abort gives the landing up. These commands are the agent’s, so they follow agent.git. Your own decisions do not: jig task land <id> --by human lands the pull request whatever agent.git says, and so do jig task promote <id> --by human, jig task request-review <id> --reviewer <login> --by human and, on the direct flow, jig task merge-pr <id> --by human, which merges the task’s pull request on the forge. They look at CI once instead of waiting, refuse a conflict, and never override the forge’s branch protection. jig task pr-status <id> --json shows why a pull request waits: its checks, its review and whether it merges cleanly. Your agent never passes --by human.
jig help lists the full command surface. Use Skills for the agent procedures, Configuration for settings, and Under the hood for boundaries and side effects.