jig init writes .ai/config.yaml with sensible values, and any
setting that is missing takes the default built into Jig. This page lists every setting, so you can
tell your agent what to change — or change it yourself.
The file uses a flat subset of YAML: section.key: value, lists written inline, no nesting.
Where project knowledge, task workspaces and runtime files live is fixed and cannot be configured.
Project settings — .ai/config.yaml
The project’s file is committed: everyone who clones the project gets the same settings.
Runtimes and stacks
After changing either list, run
jig upgrade (or ask your agent to): it installs what is newly
selected.
Git and branches
Tracker issues
The pattern is a regular expression that must match from the id’s first character up to its end or
to a
-, _ or .: with [0-9]+, 123-fix-login names issue 123, while release-0-25-1 and
123abc-fix name none. Pick one that only your issues match — [0-9]+ also reads 2026 from a
task called 2026-10-notes.
Gate hooks
Paths are relative to the project. These keys are read only from
.ai/config.yaml, never from your
own config.local.yaml: a hook is a team rule. A person sets one refusal aside for one task with
jig task waive, with a reason. See
your own checks at the finish.
Housekeeping
Working in one checkout
Knowledge
Verification
verify.full_run: ci
Set it only when your CI runs every check on every pull request. Jig takes your word for it; it
does not check.
With ci, a plain jig verify — the one the agent runs before declaring work done — checks only
what changed since the branch left its base: committed, staged, unstaged and untracked changes. The
base is the one the task in this checkout was cut from — an epic for a task of an epic — and
git.base_branch when there is no task, when several tasks on the branch were cut from different
bases, or when the task’s base cannot be found in this clone. --base <ref> names another. It
prints why:
- in CI — whenever the
CIenvironment variable is set, which every CI service does, so the same command runs everything there; - on request —
jig verify --full.
routes/ or composer.json in Laravel, a lock file, a test helper — or a file no
test is named after, the profile runs the tests it can name and leaves the full set to CI, and the
check’s line says so:
phpstan,
pint, ruff, mypy, eslint, rubocop, shellcheck, go vet, cargo clippy, dart analyze)
checks only the changed ones. When the whole tree would be checked — the tool’s own configuration
changed, or it cannot narrow (tsc and swift build never do) — the check is left to CI and says so:
What your file does not say
Every key not in.ai/config.yaml takes its default, and that is by design — the file is short
because it only has to hold what you changed. But it is also the only place you ever see which
settings exist, and Jig never edits it: it is yours, committed and reviewed like code. So after
jig upgrade brings a newer Jig, your file goes on describing the version it was written for,
and a setting added since is one nobody told you about.
Two commands close that gap.
.ai/config.yaml says nothing about. A commented-out line counts as
saying something: the file is documentation as much as configuration.
A program reads the same list with jig config keys --json, which adds each setting’s current value,
where it comes from, its kind and a description (Reading Jig as data).
jig doctor prints the same thing in one line, and only when there is something to say:
.ai/config.yaml that sets a key Jig does not read at all — a misspelling,
or a setting a later version dropped.
Personal settings are left out of both: Jig never reads agent.git, autopilot.git, agent.git_staging, agent.ci_timeout,
autopilot.unattended, autopilot.parallel, route.depth, release.merge, github.account, run.exec, run.path,
claude.implement_model, claude.review_model, codex.implement_model,
codex.review_model, or any executor.* key from the project’s file, so naming them there
would only invite you to write a line that does nothing.
Personal settings — .ai/config.local.yaml
Some settings are a matter of personal taste rather than project policy. Put them in
.ai/config.local.yaml — the same format, one file per clone, ignored by Git (jig init adds it to
.gitignore). It overrides the project’s file only for:
housekeeping.cadence,housekeeping.fetch,housekeeping.trash_ttl,housekeeping.abandoned_ttl,housekeeping.stale_after;checkout.busy_ttl,verify.busy_ttl;git.worktree_root,git.delete_merged_branches;agent.git— how far the agent takes a finished task, a specification’s epic, and an edit made from a page:none(the default: you commit, and such edits are refused),commit,push,prormerge. This one is read only from your local file; in.ai/config.yamlit is ignored, so it can never switch on for everyone. See Letting the agent ship.autopilot.git— the same levels, for what an autopilot run ships: a task shipped while its run is going, and, whenautopilot.unattendedistrue, a specification’s epic. Not set (the default), a run ships at youragent.git, exactly as before. Set it to give a run more than the work you watch —agent.git: prwithautopilot.git: merge: the tasks you take step by step end in a pull request you merge, and a run merges its own once CI passed — or less. Local only, likeagent.git. See Letting the agent ship.agent.git_staging— the same levels, for a task whose pull request goes into the staging branch: its ship and its landing. Not set (the default),agent.gitanswers there too. Set it to let your agent land on the staging branch without letting it merge anything into your main branch —agent.git: prwithagent.git_staging: merge. Local only, likeagent.git. See Staging flow.agent.ci_timeout— minutes themergelevel waits for the pull request’s checks (default 30); local only, likeagent.git.autopilot.unattended—truelets an autopilot run go on without asking you anything; local only. See Autopilot: without stops.autopilot.parallel— how many tasks autopilot builds at the same time: a roadmap phase’s wave, or a run over a set of tasks (default 2, at most 16); a run stopped for a person holds no slot; local only. See Autopilot: running a whole phase.route.depth— how much process your tasks get:full(the default) runs each class’s whole route;leantrims what does not change the risk assessment — a short analysis for T1, the plan folded into the analysis for T2, and no second review round when the review found nothing blocking. Tests on the files you changed, CI before a merge, consolidation, and the design approval and architecture review of T3/T4 are never trimmed. Local only: it is your time you are trading. One task can differ:jig task new <id> --lean, orjig task set <id> route_depth full. See A lighter route.github.account— which of your GitHub accounts this clone works as, whenghholds more than one. You rarely need it: Jig finds the one account that may push to the repository and uses it for every pull request, check, merge and push over HTTPS, whichever accountghhas active. Set it when several of your accounts may push here. See Two GitHub accounts.release.merge— who merges a release in an unattended run atagent.git: merge:agent(the default) merges it once CI passed,humanopens the pull request and leaves the merge to you. A release is a pull request whose change raises the version into the default branch (VERSION, or theversionofpackage.json,composer.json,pyproject.tomlorCargo.tomlat the repository’s root): a release’s notes task, or a release epic’s final pull request. Outside an unattended run a release is always yours to merge, and amajorone always is. Other task pull requests are not affected; local only.run.exec— where this machine runs the project’s checks:auto(the default: Jig finds out),host, or the command that reaches the project’s container. Local only: the place is a property of your machine, not of the project. See Where checks run.run.path— a folder put first onPATHfor the checks when they run on this machine (a PHP that is not first there, such as Laravel Herd’s);auto(the default) uses what Jig detected. Local only.claude.implement_model,claude.review_model— in Claude Code, the model your agent hands writing the code, and reviewing it, to: a helper agent (a subagent) on that model does the stage, and your agent checks what it reports. Write the name the way Claude Code understands it —sonnet,opus,haikuor a full model id; Jig passes it on as written and never checks it. The review key covers every review of a route, the architecture review of a risky task included. Not set (the default), your agent writes the code itself, and every review still goes to a helper on your session’s model. Local only: which model is worth its cost depends on your plan and your budget. See Autopilot: helpers on another model.codex.implement_model,codex.review_model— in Codex, the model of the subagent that runs implementation or any review stage. Set either withjig config set <key> <model> --local. Jig passes the model name to Codex without checking a model list. With no value, the current session writes the code itself and a review goes to a subagent on the session’s model. If a chosen Codex subagent cannot start, the stage stops with the reason; it is not silently completed by the current session. The reviewer starts with a fresh context. Local only. See Autopilot: helpers on another model.executor.implement_runtime,executor.review_runtime— chooseclaudeorcodexfor implementation or any review. An empty setting keeps the current session; choosing its own runtime also keeps that session and its subagent model choice. Choosing the other runtime starts its CLI in the task worktree with limited permissions. If it cannot start or finish, the stage stops with the reason. Set one withjig config set executor.review_runtime codex --local. Local only.executor.implement_model,executor.review_model— optional model names for the selected external runtime. These are distinct fromclaude.*_modelandcodex.*_model, which choose subagents inside the current runtime. With no external runtime selected, these values have no effect. Local only.
jig task start <id>:
executor.* settings above. Each overrides only
its matching local value; the others still inherit. jig task route <id> names the
effective value and whether it came from task state or local config. Use inherit
as the value to remove an override before start. At start Jig saves all four
effective values and their sources, including empty choices. Later edits to the
shared local config cannot switch a running task’s executor or model. Jig also
refuses changes to the task’s choices after start.
notify.telegram.token,notify.telegram.chat_id— where an autopilot run’s messages go: your Telegram bot’s token and your chat id. Nothing is sent until both are set. Set both withjig notify setupin your own terminal, or write the token into the file yourself —jig config setrefuses it, and Jig shows it only as********.jig notify testsends a test message. Local only. See Autopilot: messages in Telegram.notify.autopilot—falsepauses those messages and keeps the settings (defaulttrue); local only.notify.interactive—truealso sends the message when an ordinary session waits for your permission or your answer (defaultfalse). It needs your runtime’s notification hook, which Jig never adds itself; local only. See Autopilot: when an ordinary session waits for you.
jig config show --local prints the file and names the keys nothing reads, and jig config unset
removes them (below). jig status shows what your local file changes,
and warns if Git does not ignore it.
Let the agent ask you
You do not need to know the keys. Say “set up Jig for me” (or name the skill:/jig-setup in
Claude Code, $jig-setup in Codex). The agent asks one question at a time, in plain words, each with
its recommendation: how far it may take a finished task, whether it may merge, how far autopilot may go, whether it may
go on without asking you, how long to wait for CI, how much process your tasks get, which model its helpers use, how long to keep finished work, and where your project’s checks run. It explains
merging and running without questions before it asks about them, and never switches either on
without your clear yes. Then it shows you the whole file it is about to write, and writes it only
after you agree. jig init offers this at the end of its output. When origin has a stage or
staging branch and the team has named no git.flow, it also asks which flow the team uses — the
team’s answer, not yours — and puts it in .ai/config.yaml after your yes, through a task and a
pull request of its own, as any change to that file.
Or set a value yourself
jig config set writes only .ai/config.local.yaml — in a task’s worktree, the one in the main
checkout that every worktree reads. It creates the file when it is missing, replaces a setting that
is already there and adds one that is not. It accepts only the personal settings listed above, and
only values Jig reads the way you mean them: whole days for housekeeping.cadence, a duration such
as 7d or 12h for the other housekeeping settings, true or false, a level for agent.git, autopilot.git and agent.git_staging,
whole minutes for agent.ci_timeout, a count from 1 to 16 for autopilot.parallel, full or
lean for route.depth, any name for the four claude.*_model and codex.*_model settings, auto,
host or a command of plain words — no quotes, $ or backslashes — for run.exec, auto or a
folder for run.path. Anything else is refused and nothing is written, not even the
other settings of the same command. --dry-run prints the file it would write. It refuses to work
without --local: .ai/config.yaml is the team’s file, changed by hand and reviewed like code.
jig config unset takes the other direction — it removes a setting, so the default applies again,
which is how you give back a right you granted:
config set refuses too, so a key left over from an older version or a typo can be
cleared rather than living in the file forever; removing a key that is not there is reported and is
not an error. jig config show --local prints the file and, under it, one line per key nothing
reads:
Verification profiles
A profile knows how to check one stack. Jig runs the tools your project already uses, from the project’s own environment —vendor/bin, node_modules/.bin, .venv, bundle exec — never a global
copy with another version. The stack’s own toolchain (go, cargo, dotnet, composer, your
package manager) comes from PATH. Jig installs nothing: a missing tool is reported as a skip, and a
skip is never a pass.
When only part of a project changed, every profile except
generic and swift narrows its checks:
a linter gets the changed files, and tests are narrowed where the stack ties a source file to its
tests (foo.py → test_foo.py, a Go package and its importers, a Rust crate). Anything it cannot
narrow runs in full, with the reason printed.
Checks of your own belong in the project’s installed profile under .ai/profiles/; jig upgrade
keeps a profile you edited.
A profile of your own can also replace one check of a stock profile, without editing it. Say it
runs your test suite its own way: declare that in its profile.yaml, and the stock profile’s
tests stand down when both run.
laravel does the same for php (covers: [php:tests]), so a Laravel project runs its suite
once, in php artisan test. The check is named by its role, tests; php, laravel, node and
python name theirs so far, and a cover of a check a profile does not name prints a warning and
leaves the check running. A cover holds only where the covering profile applies — its detect
matches, is always, or is absent. In a run narrowed to changed files, the covered profile’s
.ai/verify/<profile>.map goes with its tests, read after the covering profile’s own map, so the
covering profile declares scope: [changed, map] (as the example’s would). One that narrows
without reading maps does not take tests whose map would be dropped: Jig warns, and the stock
profile keeps them.
Where checks run
A project that lives in a container — Laravel Sail, adocker compose service — must be checked
there, not with whatever php or node this machine happens to have: another version, and a
database host such as mysql that only resolves inside Docker, give a verdict about the wrong
thing. Before any check runs, jig verify decides where the project’s commands go, and says so:
- Your setting,
run.execin.ai/config.local.yaml:hostruns everything on this machine; any other value is the command put in front of each check —docker exec -i -w /shared/httpd/app/htdocs php, say. Nobody has to write it by hand: thejig-setupskill shows what Jig found and writes it after you agree. - A detector, while
run.execisauto(the default). Laravel Sail —vendor/bin/sailand the service Sail runs in (laravel.test, orAPP_SERVICEfrom.env) mounting the project — runs checks as Sail’s own user. docker compose — exactly one service incompose.yamlordocker-compose.ymlmounting the project directory (.:/app) — runs them in that service, in the directory it is mounted at. DDEV (.ddev/config.yaml) runs them withddev exec; Lando (.lando.yml) and a devcontainer (.devcontainer/devcontainer.json) run them in the container that mounts the project — for a devcontainer through thedevcontainerCLI when it is installed. They are tried in that order, the tool with a file of its own before a bare compose service. A shell that is already inside one of these environments (a Codespace, DDEV’s web container) just runs on the spot. When the project names no environment of its own, two more follow. Devilbox — its PHP container (the compose servicephp, with Devilbox’s data folder mounted at/shared/httpd) mounting the project’s folder or a folder above it, wherever your data folder lives — runs checks in that container, at the project’s place under/shared/httpd, as Devilbox’s own user. Laravel Herd — the project is one of Herd’s sites (in a folder Herd serves, or linked) — runs them on this machine with Herd’sbinfolder first onPATH, so Herd’s PHP answers rather than another one installed beside it. - The host, when nothing suggests a container.
PATH and that Jig does not recognise is named with run.path, a
folder put first on PATH whenever the checks run on this machine; blanks in it are fine:
DB_HOST in .env naming a compose service, a .devcontainer/ or .ddev/ folder without its
manifest — Jig
refuses rather than running the checks on this machine, exits 3, and names what it saw. A
database in a container beside an app on the host is not such a sign. Run the jig-setup skill, or
set the command yourself:
./vendor/bin/sail up -d, docker compose up -d, ddev start, lando start, devcontainer up;
for Devilbox, docker compose up -d in its folder). In a task’s worktree, a container that mounts
the main checkout instead would check other code, and that is a refusal too: start an environment
for the worktree, or verify in the checkout the container mounts.
In CI (CI is set) nothing is detected and nothing is refused: the pipeline describes its own
environment, and the checks run where it runs them.
Every built-in profile runs through the environment. For Python, a virtualenv made on your machine
is of no use inside a container, so there the tools come from a .venv/ or venv/ that runs in
the environment, and otherwise from the environment’s own PATH. A profile that is not adapted
(your own, until you do it) is not run on the host when an environment is in use: its result
is a skip that says why, and when nothing else passed, the run is not a pass. Your own profile opts in by adding
environment to its scope and running its commands through jp_run, jp_version and jp_have
(schemas/profile.md in the Jig source).
A verification map for your project
A profile only knows rules that are true for every project of its stack. When your project has its own — “changes underdocs/ affect no test”, “anything in src/Billing/ runs the billing
tests” — write them into .ai/verify/<profile>.map. The file is yours: jig init and
jig upgrade never create or touch it.
- (affects no check), ALL (run everything), or a
filter the profile understands — a test file for PHP, Python, Ruby, Dart and Node, a package for Go,
a crate for Rust, a test project for .NET, a module for Gradle and Maven, a test-name filter for
shell. The first matching line wins; a path no line matches is left to the profile’s own rules. A
broken line fails that profile with the file and line named, rather than narrowing the wrong way.
When housekeeping runs
Housekeeping — noticing merged tasks and cleaning up workspaces — needs a trigger. Jig does not run a scheduler of its own. Pick one, or both; running it twice is harmless.- Claude Code session hook. At the start of each session it starts housekeeping in the
background, only when the last run is older than
housekeeping.cadence.jig init --session-hookcreates.claude/settings.jsonwith the hook when the file does not exist yet; an existing file is never edited —jig initprints the lines to add by hand. The Windows installer turns the hook on unless you pass-NoSessionHook. - A scheduler. Codex has no session hook. Examples for cron, macOS launchd and Linux systemd are
in
.ai/templates/scheduler/; use the project’s absolute path in them.
jig status reports whether the session hook is installed.