Skip to main content
Jig works without configuration: 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.
You do not have to edit a settings file to get started. Say “set up Jig for me” and the agent explains the personal choices one at a time. Jump to guided setup.
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:
The full set still runs whenever it should:
  • in CI — whenever the CI environment variable is set, which every CI service does, so the same command runs everything there;
  • on request — jig verify --full.
A narrowed run never starts the full set on its own. When a change touches something that can affect any test — 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:
Linters and static analysis follow the same rule. A tool that takes files or packages (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:
This saves the agent from running the whole suite after every small change, while CI still proves everything before a merge. A red CI run sends the task back to verification.

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.
lists every setting this version reads, its default, and which of the two files answers for it — and marks the ones your .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:
Nothing is wrong when you see it — every one of those settings is working on its default. It is an invitation to look, and the reply is yours to write, or not. Doctor also warns the other way round, about a line in .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, pr or merge. This one is read only from your local file; in .ai/config.yaml it 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, when autopilot.unattended is true, a specification’s epic. Not set (the default), a run ships at your agent.git, exactly as before. Set it to give a run more than the work you watch — agent.git: pr with autopilot.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, like agent.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.git answers there too. Set it to let your agent land on the staging branch without letting it merge anything into your main branch — agent.git: pr with agent.git_staging: merge. Local only, like agent.git. See Staging flow.
  • agent.ci_timeout — minutes the merge level waits for the pull request’s checks (default 30); local only, like agent.git.
  • autopilot.unattended — true lets 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; lean trims 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, or jig task set <id> route_depth full. See A lighter route.
  • github.account — which of your GitHub accounts this clone works as, when gh holds 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 account gh has 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 at agent.git: merge: agent (the default) merges it once CI passed, human opens 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 the version of package.json, composer.json, pyproject.toml or Cargo.toml at 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 a major one 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 on PATH for 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, haiku or 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 with jig 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 — choose claude or codex for 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 with jig 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 from claude.*_model and codex.*_model, which choose subagents inside the current runtime. With no external runtime selected, these values have no effect. Local only.
For different executors in the same roadmap wave, set a task’s own values before jig task start <id>:
The four task keys match the four 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 with jig notify setup in your own terminal, or write the token into the file yourself — jig config set refuses it, and Jig shows it only as ********. jig notify test sends a test message. Local only. See Autopilot: messages in Telegram.
  • notify.autopilot — false pauses those messages and keeps the settings (default true); local only.
  • notify.interactive — true also sends the message when an ordinary session waits for your permission or your answer (default false). It needs your runtime’s notification hook, which Jig never adds itself; local only. See Autopilot: when an ordinary session waits for you.
Any other key in it is ignored — no reader answers from it — but it is not silently lost: 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:
It accepts keys 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, a docker 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:
It decides in this order:
  1. Your setting, run.exec in .ai/config.local.yaml: host runs 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: the jig-setup skill shows what Jig found and writes it after you agree.
  2. A detector, while run.exec is auto (the default). Laravel Sail — vendor/bin/sail and the service Sail runs in (laravel.test, or APP_SERVICE from .env) mounting the project — runs checks as Sail’s own user. docker compose — exactly one service in compose.yaml or docker-compose.yml mounting the project directory (.:/app) — runs them in that service, in the directory it is mounted at. DDEV (.ddev/config.yaml) runs them with ddev exec; Lando (.lando.yml) and a devcontainer (.devcontainer/devcontainer.json) run them in the container that mounts the project — for a devcontainer through the devcontainer CLI 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 service php, 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’s bin folder first on PATH, so Herd’s PHP answers rather than another one installed beside it.
  3. The host, when nothing suggests a container.
A PHP that is not first on 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:
When something does suggest one and no detector recognised it — two services mounting the project, 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:
Before the first check, Jig asks the environment for one thing: is it running, and does it see this checkout? A container that is stopped is a refusal with the command that starts it (./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 under docs/ 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.
Each line is a path pattern and a decision: - (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-hook creates .claude/settings.json with the hook when the file does not exist yet; an existing file is never edited — jig init prints 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.

Environment variables

Settings live in the files above; this variable is read from the environment.