Skip to main content
Jig has two kinds of parts: instructions the AI follows and commands that maintain project state. This page explains the boundary, the files involved, and the effects on your machine. For commands you can try, start with Manual control.
Scripts never call an AI model. Your coding app runs the agent and controls its access to files, commands, and services. Jig’s rules complement those permissions; they do not replace them.

Two layers

Jig splits the work in two:
  • Skills are instructions in Markdown. The agent reads them and makes every judgement: what a change touches, how risky it is, what the design should be, what the project should remember.
  • Scripts are POSIX shell (bash 3.2+) in .ai/scripts/, with Git as the only requirement. They keep records straight: task state, which knowledge applies, running checks, installing and cleaning up. No script calls an AI model, and nothing is sent to any service run by Jig — there is none, and there is no telemetry.
The agent runs the scripts through its normal shell tool, so everything it does is visible in your runtime and subject to your runtime’s permission settings. A typical exchange:
The script answers from file metadata alone; the agent then reads the listed files itself. When the task is in the queue, the queue: lines say where it stands, what it waits for and why, and a pause asked of it that it has not honoured yet.

What lives where

What each part does to your machine

Installers

  • install.sh (macOS, Linux): clones Jig into ~/.local/share/jig at the newest release tag, links ~/.local/bin/jig, and adds one marked PATH line to your shell startup file only when that folder is not already on PATH. No sudo. It never touches the directory you run it from. On a failed run it removes only the install directory it created in that same run and the link it created. It refuses to overwrite anything it did not create.
  • install.ps1 (Windows) additionally, and says so before doing it:
    • installs Git for Windows when missing — through winget, which it runs with the source and package agreements accepted for you, or by downloading the official installer. The download is not checked against a hash or signature.
    • sets user.name and user.email globally when Git has none (with -Yes, the e-mail defaults to <username>@example.com);
    • in a folder it turned into a repository, makes one first commit of everything in it — including files that were already there (it lists the first few);
    • runs jig init --session-hook unless you pass -NoSessionHook; from an unreleased Jig (-Ref main) it adds --unreleased only after you typed yes to its question.
    It deletes only the Git installer it downloaded in that run. -Uninstall removes the PATH entry, the jig link only when it points into the install folder, and the install folder only when it is a Jig checkout with no local changes.
  • jig self-update moves the Jig on your machine to the newest release tag, never backwards, and refuses a checkout with local changes. Release tags are not signature-verified. It changes no project.

In a project

  • jig init creates what it needs and never overwrites existing knowledge, configuration or a file you changed. It appends missing lines to .gitignore (.ai/workspace, .ai/runtime, .ai/config.local.yaml, *.log, .claude/worktrees/) and .gitattributes — the first two deliberately without a trailing slash, so that a checkout sharing another one’s workspace through a directory link still ignores it. With --session-hook it creates .claude/settings.json only when that file does not exist; an existing one is never edited. It asks nothing and commits nothing.
  • jig upgrade fetches nothing: it copies from the Jig on your machine, and only when that is a release (a checkout at its version’s tag, with no local changes); otherwise it refuses unless given --unreleased. It replaces framework files you have not edited, keeps and reports the ones you have, and deletes a file the new version no longer ships only when you have not edited it — this can be outside .ai/, for example an old skill under .claude/skills/. It never touches knowledge, specifications or configuration. Of AGENTS.md it writes one thing: the section between <!-- jig:begin --> and <!-- jig:end -->, and only while that section is still exactly what Jig last put there. Change a word inside it and Jig keeps your version from then on, saying keep-modified AGENTS.md (Jig section); delete the markers and nothing comes back. Each run ends with a summary line, and a run with nothing to place and nothing to record leaves .ai/manifest alone — a project only starts using another checkout of Jig once an upgrade has really installed from it.
  • jig verify runs your project’s own tools — test scripts, linters, php artisan test, Gradle or Maven wrappers. That is running your project’s code, with whatever that code does; some toolchains download dependencies by themselves. Jig installs nothing. A missing tool is a skip, never a pass; when every check is skipped, the run still exits successfully, and the report says what was skipped. - jig task start --worktree, and jig task bootstrap, which repeats it, carry into the worktree whatever your project’s checks need that Git does not track — vendor/, node_modules, .env — as declared by the active profiles’ carry and the project’s own worktree.carry in .ai/config.yaml. A folder named in worktree.share is not copied: the worktree gets a real folder of that name whose entries are links to this checkout’s, and jig task bootstrap links in entries added since. Only a path the worktree does not already have is touched; a path under .ai/ is always refused. Never fatal: a carry that fails partway leaves the worktree and its branch exactly as they are, for jig task bootstrap to try again. A task started with --share <dir> gets that folder the same way, for itself alone. - worktree.setup, when your project sets it, is run by both after the share and the carry: sh -c in the worktree, on this machine, with nothing on its input. That is running your project’s code too — the command your .ai/config.yaml names. It is stopped, with every process it started, after worktree.setup_timeout (10 minutes by default). Never fatal, and nothing it leaves is taken back: Jig names what Git can see afterwards and keeps a failure on the task until a jig task bootstrap succeeds.

Git

No script commits or pushes on its own — apart from the Windows installer’s first commit in a repository it created, the only ones that do are jig task ship, jig spec ship and the writes from a program (jig spec item, jig knowledge accept|reject|reviewed --json, jig writes ship), and on the staging flow jig task land (a merge into the staging branch, pushed there) and jig task promote (it pushes the task branch and opens the pull request into the main branch), and only as far as agent.git in your .ai/config.local.yaml allows (none by default: they do nothing). jig task land, jig task promote, jig task request-review and jig task merge-pr with --by human are your own decision, made in a terminal or by a dashboard, and do not read agent.git; they still never force, never use an administrator’s override and never wait for CI. On a CI runner, which has no agent.git, jig task promote follows the flow alone. They commit what is staged, push without --force, never skip hooks, and open a pull request with gh or glab. With nothing staged, jig task ship stages the changes to tracked files itself and lists them, and refuses while a new file is neither staged nor ignored — a new file is never staged for you. jig spec ship refuses an empty index while tracked files still hold changes. Nothing reaches your forge — no push, no pull request — until the branch is known to carry a commit your main branch does not. At agent.git: merge, shipping can also merge after the required checks pass; see the merge level for its conditions. Starting a task refuses when tracked files have uncommitted changes (untracked files do not block it), so one task’s work cannot become another’s first commit; shipping one reads the working tree by the same test, for the same reason.

Network

Project Git operations use your Git remote. Shipping and housekeeping also use your forge’s command-line tool: with forge: auto and gh or glab installed and signed in, housekeeping lists pull requests to learn whether a task was merged — also during a dry run, which otherwise skips git fetch. Outside a dry run it lists the open ones’ checks too (one more call on GitHub), and keeps what it heard in .ai/runtime/forge-cache, which jig task list --json and jig status read instead of asking the forge; jig upgrade adds the pull request it has just opened there, so the upgrade waiting for its merge shows before housekeeping next runs. jig upgrade --land asks the forge itself, once, before it changes anything. The commands a person presses a button for ask the forge themselves, once, when run: jig task request-review (adds reviewers), jig task merge-pr and jig task land --by human (read the pull request’s checks and review, then merge it), and jig task pr-status --json (reads checks, review, mergeability and branch protection, and writes nothing). forge: none turns forge lookup off. Installation and self-update also access the framework source and releases; the Windows installer can download Git, as described above. Carrying state into a worktree touches no network either: a profile’s install command is printed for you to run, never executed, even when there is nothing to carry because the owning checkout is not installed itself.

Deletion

Everything a script deletes, it first proves is its own:
  • Workspaces are never deleted directly. Housekeeping moves one to .ai/runtime/trash/ when its task is closed after a confirmed merge, or closed without ever having been started (no branch, no fork point, nothing at its branch name, no pull request from that name at the forge — a forge that does not answer keeps it — no commit message in its workspace, no unchecked roadmap item naming it, and no link to a spec whose roadmap cannot be read here; a branch template without {id} keeps it too, and a findings task also waits for its source task), and trash entries are deleted after housekeeping.trash_ttl (7 days). A task nobody finished is not deleted at all: once it was abandoned more than housekeeping.abandoned_ttl (14 days) ago — whatever its remote state — or has gone untouched for housekeeping.stale_after (60 days), housekeeping archives it. Its status becomes archived, the workspace stays where it was with no time limit, and jig task unarchive returns it. A task whose remote state cannot be determined is otherwise always kept. Age alone never removes a task.
  • Idea drafts are never removed by housekeeping or by age. One goes to .ai/runtime/trash/ only when jig spec ship has committed the specification of the same id, or when you run jig spec draft drop <id>.
  • Paths are deleted only after being checked to lie inside .ai/ and to look like a workspace or a trash entry. Task, spec, profile, adapter and domain names are validated before any path is built from them.
  • Worktrees are removed by Git, never by a script, under the conditions above; on Windows, leftover links and empty folders inside that path are then removed, never followed. Jig’s own tree under the git directory goes the same way: Git removes it, and once Git no longer knows the path, only the links and empty folders left there are removed; anything else stays, and the next write is refused tree-in-the-way.
  • Specifications removed, closed or finished go to the trash, not straight to deletion.
  • Branches are deleted only as the table above says: the branch a failed worktree start just created, and Jig’s own branches once their work has landed (git.delete_merged_branches, on by default; false keeps every branch). A branch you made is never deleted, nor one with a commit that is not merged.
The session hook, when you installed it, starts jig housekeeping — the real one, not a dry run — in the background at most once per housekeeping.cadence.

Knowledge and what an agent reads

  • Proposed knowledge reaches no agent. Documents an agent inferred — a domain map, a linked or copied document — are created as proposed and are left out of every answer jig context gives until they are accepted.
  • Acceptance is the skill’s discipline, not a script’s check. jig knowledge accept cannot tell who ran it. The jig-accept skill requires a human’s yes to each document; nothing technical stops an agent from running the command itself. Review knowledge changes in pull requests.
  • Knowledge written at the end of a task is active immediately, like any file the agent edits: its check is your review of the pull request.
  • Linked documents (.ai/knowledge/sources/) must be regular files Git tracks, inside the repository, not symlinks. The check is repeated every time one is resolved, because a file can be swapped after it was accepted. Changes after acceptance are reported until a human reviews them.
  • Copied rule files are scanned for obvious secrets before the copy; a hit names the line and the kind, never the value, and the copy waits for explicit confirmation. The scan catches the obvious only.
  • Reading is recorded, not proven. The agent records which documents it has read per task, so a changed document becomes unread again. That record says the agent claimed to read it — nothing more.
  • A task can link a neighbouring repository’s task or spec with a Linked: line in its task.md. Jig only reads that repository — the listed documents, nothing else — and never writes to it. Its documents are recorded like knowledge, so an edit there becomes unread here.

Measurement

jig measure derives everything it reports when you run it, from knowledge metadata, local task state, Git history and the housekeeping log (where housekeeping records a task’s class and dates when it cleans the workspace up). Nothing is sent anywhere.

More

jig help lists every command; jig doctor checks the machine and the project and prints a fix for each problem. The accepted design decisions behind all of the above are in the repository’s .ai/knowledge/adr/.