For AI agents: the complete documentation index is available at https://jig.md/llms.txt, the full documentation bundle is available at https://jig.md/llms-full.txt, and this page is available as Markdown at https://jig.md/guide/configuration.md.
Jig
DocumentationGuidePrerelease

#Settings and configuration

View Markdown

Use this reference to adjust Jig for your terminal, host, and application. The defaults work for the first Flow; change these settings when you need a different operating preference.

#Shell completion

Load completion for your shell:

# Bash
source <(jig completion bash)
# Zsh (after compinit)
source <(jig completion zsh)
# Fish
jig completion fish | source

Put the matching command in your shell startup file to keep it enabled. Target suggestions read the current directory's last approval, never execute jig.ts, install dependencies, or contact an Agent. Review newly added targets before they appear. Unsupported or unreadable approval produces no suggestions.

#Where settings belong

What you want to configureWhere to set it
Startup verification--verification on run, review, or inspect; JIG_VERIFICATION for a shell default
Terminal appearanceJIG_THEME, NO_COLOR, and your terminal environment
Agent client, model, and credentialsThe review chooser or exported operator environment; see Agent settings
Flows, Bindings, and application settingsjig.ts; see Project settings
Input, deadline, and output for one RunCommand arguments; see Per-command options
Bubblewrap executableAbsolute JIG_BWRAP_PATH; see Host configuration

Operator preferences are separate from reviewed project policy. Jig does not automatically load project .env files. Export environment variables in your shell or supply them through your process launcher.

#Startup verification

Jig defaults to cached verification to avoid repeatedly hashing large installed tools. It reuses hashes while file identity and metadata match, and rehashes when they change. Use --verification cached|strict|fast to choose the policy for a command.

ModeInstallation checkTradeoff
cached (default)Reuse hashes while file identity, permissions, size and modification/change times matchDetects ordinary tool updates; relies on filesystem metadata between hashes
strictHash current tool bytes at every verification pointStronger byte verification, with more startup work
fastReuse stored hashes without checking freshnessChanged tool bytes at the same path can go undetected

Choose a mode explicitly:

jig run flow:flows/hello --input '"Ada"' --verification fast
jig review --verification strict
jig inspect --verification cached

The argument takes precedence over JIG_VERIFICATION. For a persistent shell or CI preference, use export JIG_VERIFICATION=cached (or strict or fast). When neither is supplied, Jig uses cached. Missing, invalid or repeated --verification values are usage errors.

Fast mode suits operators who prioritize startup performance and trust their installation to remain suitable. All modes hash files on a cache miss, so the first use of a tool can take longer. Most savings come from avoiding repeated hashing; fast's extra benefit over cached depends on the installation and host.

The setting applies to review, Run and inspection. It is an operator preference, separate from project configuration. Flow approval, retained package verification, sandbox requirements, permissions, resource limits, cancellation and cleanup still apply. Tool and runtime compromise remains outside Jig's threat model.

The private installation cache lives at $XDG_CACHE_HOME/jig/installation-verification, or $HOME/.cache/jig/installation-verification by default. It contains tool paths, metadata and hashes, never credentials or project approvals. You can remove this directory to force fresh hashes next time. Unsafe or unusable caches fall back to full hashing. Strict bypasses the cache entirely; inspection never writes it. See the exact policy for the guarantees and limits.

#Terminal appearance

SettingValues and behavior
JIG_THEMEone-dark (default), one-light, or macchiato; unknown values use One Dark
NO_COLORAny present value, including an empty value, disables colors and animation
TERM=dumbSelects plain output without animation
COLORTERMtruecolor or 24bit enables truecolor accents; otherwise Jig uses 256-color accents when TERM contains 256color, or basic terminal colors

Choose the palette that fits your terminal background:

export JIG_THEME=one-light

Themes color structured terminal output without changing its values. Plain output ignores the theme. Redirected streams contain no terminal colors or animation. Use --json on jig run when you need machine-readable output in a terminal. See the CLI experience contract.

#Agent settings

jig review can remember an available client for the current project. For explicit selection or automation, use the exported settings below.

SettingPurpose
JIG_AGENT_CLIENTcodex, claude, pi, or api; overrides the remembered client choice
OPENROUTER_API_KEY, OPENROUTER_MODELOpenRouter credentials and model, using its Chat Completions endpoint
OPENAI_API_KEY, OPENAI_MODELDirect OpenAI or compatible API credentials and model
OPENAI_BASE_URL, OPENAI_APICompatible HTTPS endpoint and wire format: responses (default) or chat-completions
CODEX_PATH, CLAUDE_PATH, PI_PATHAbsolute native-client executable override; otherwise Jig searches the operator’s eligible PATH entries
CODEX_HOMECodex’s file-backed login directory; defaults to ~/.codex

Jig supplies no default API model. Select one API variable family at a time; supplying both OpenRouter and OpenAI configuration is ambiguous. Credentials alone do not select a client. Keep credentials outside jig.ts, Flow input, and reviewed application settings.

Client, endpoint, model, or executable changes require a new review; rotating only a credential does not. The Agent guide owns setup examples, client requirements, login support, and switching instructions.

#Project settings

jig.ts declares the project’s Flows and Bindings. A Binding configures an invocation with application settings, selected child slots, and any supported command policy. These values are reviewed before they can execute. They do not select the operator’s credentials, terminal theme, or startup verification preference.

See project authoring for the supported fields and examples, and execution policy for enforced limits.

#Per-command options

OptionCommandPurpose
--input JSON or --input @FILErunSupply JSON input; omitted input is {}
--timeout 2mrunSet the Run deadline within the supported limits
--receive CHANNELrunReceive a declared output channel; see live progress
--jsonrunEmit machine-readable JSON or NDJSON even in a terminal; redirected stdout already uses this format
--detailsreviewInclude unchanged policy as context in the review diff
--yesreviewApprove the displayed revision without an interactive prompt; does not select an Agent or grant resolution-network permission
--allow-resolution-networkreviewPermit dependency-selected network requests before graph validation for this review only; grants no Run network access

Run jig <command> --help for the complete arguments for a command. See dependency review for resolution effects and retained preparation, and results and recovery for output handling.

#Host configuration

The supported-host requirements describe the execution prerequisites. Set JIG_BWRAP_PATH to an absolute path when Bubblewrap is outside Jig’s normal host-tool locations. An invalid explicit selection fails rather than falling back. This setting selects Jig’s outer containment tool, not a native Agent’s nested sandbox.

XDG_CACHE_HOME relocates the installation verification cache described above. XDG_STATE_HOME relocates remembered Agent choices, normally stored at ~/.local/state/jig/agent-choices, separately for each canonical project directory. Neither location transfers project approval.