igris.toml reference

igris.toml lives in the project root (igris init creates it). Every key is optional: a missing key takes the default below. The normative description is SPEC §12.

Unknown keys are errors, which catches typos.
Durations use Go syntax ("30s", "15m", "1h30m").
Secret keys accept "env:VAR" to read the value from an environment variable; an unset or empty variable is an error. igris.toml holds no secrets by default and is safe to commit.
igris config migrate rewrites a file written by an older release and keeps a backup under .igris/config/.

Top level

Key	Type	Default	Description
`plan`	string	`"tasks.md"`	Path to the plan file, relative to the project root.
`backend`	string	`"auto"`	Where agent sessions run (SPEC §11.3). `auto` picks herdr inside a herdr pane, else tmux inside tmux. Allowed: `auto`, `herdr`, `tmux`.
`default_mode`	string	`"auto"`	Permission mode of a run when `--mode` is not given (SPEC §7). `yolo` and `plan:yolo` always ask for confirmation. Allowed: `default`, `accept`, `auto`, `plan`, `plan:default`, `plan:accept`, `plan:auto`, `plan:yolo`, `yolo`, `manual`.
`needs_input_after`	duration	`"30s"`	How long a session may sit idle at a prompt before it counts as needing you (SPEC §6.3). Greater than zero.
`waiting_limit`	duration	`"30m"`	How long a session may wait on background work before it needs you (SPEC §6.3). Greater than zero.
`nudge`	boolean	`true`	Remind an idle agent of `igris done` once before it needs you (SPEC §6.3).
`poll_interval`	duration	`"2s"`	How often igris checks the session and refreshes the TUI tail. Greater than zero.
`models`	table	`{ fable = "fable", haiku = "haiku", opus = "opus", sonnet = "sonnet" }`	Rank alias to the `claude --model` value. Ranks used in the plan's Model column must be listed here.
`columns`	table	empty	Header aliases for the plan table: your header text to the canonical column name (for example `"Depends on" = "Deps"`).
`verify`	table	no profiles	Verify profiles: name to shell command (SPEC §6.4). Names match `[a-z0-9_-]+`, `none` is reserved, commands must not be empty.
`phases`	table	no phases	Per-phase settings under `[phases.<id>]` (SPEC §6.4); the id matches a plan phase case-insensitively. `verify` is its only key: a profile name, or `none`.

`[claude]`

Key	Type	Default	Description
`extra_args`	list of strings	`[]`	Arguments appended to every session launch. Model, mode, session, settings, tool, directory, prompt, plugin and MCP flags are rejected, and so are control characters (SPEC §7.4).

`[run]`

Key	Type	Default	Description
`verify`	string	`""`	Shell command run after a task signals done; the verify profile `default` (SPEC §6.4). Empty means no verification. Cannot be combined with `[verify] default`.
`verify_timeout`	duration	`"15m"`	Time limit for every verify profile. Greater than zero.
`verify_max_attempts`	integer	`3`	How many times a failing verify is fed back to the agent before the run stops.
`commit`	string	`"ask"`	What igris does with the changes after a verified task. Allowed: `ask`, `auto`, `never`.
`commit_message`	string	`"{{.ID}}: {{.Title}}"`	Go template for the commit message. Variables include `{{.ID}}` and `{{.Title}}`.
`prompt_template`	string	`""`	Path to a custom task prompt template. Empty uses the built-in one.
`env`	list of strings	unset	The only variables verify commands and task hooks get, besides `PATH` and `HOME`: names, or prefixes ending in `*` (SPEC §6.4). Unset passes igris's whole environment.
`worktree`	boolean	`false`	Run sessions, verify and commits in a git worktree on branch `igris/<run-id>` (SPEC §6.8).

`[hooks]`

Key	Type	Default	Description
`before_task`	list of strings	`[]`	Argv list run before every agent session, never through a shell (SPEC §6.7). A non-empty list needs a non-empty first element.
`after_task`	list of strings	`[]`	Argv list run after every agent session, never through a shell (SPEC §6.7).
`timeout`	duration	`"2m"`	Time limit for each hook. Greater than zero.

`[plan_mode]`

Key	Type	Default	Description
`then`	string	`"auto"`	The mode a plain `plan` task switches to when you approve its plan in igris (SPEC §6.3, §7.1). Never `yolo`. Allowed: `default`, `accept`, `auto`.
`approve_timeout`	duration	`"30m"`	How long a plan presented for approval waits for your answer in igris before the pane decides (SPEC §6.3). 1m to 24h; `"0"` approves plans in the pane only.

`[usage]`

Key	Type	Default	Description
`enabled`	boolean	`true`	Read the task sessions' transcripts for token usage in the run log (SPEC §6.9). `false` reads none.
`statusline`	boolean	`false`	Use igris's status line in task panes to record your subscription quota (5-hour and 7-day usage) for the header and `igris usage` (SPEC §6.3). It replaces your own status line in those panes. `false` leaves it alone and the quota is unavailable.

`[side]`

Key	Type	Default	Description
`model`	string	`"sonnet"`	The rank the side-session dialog preselects (SPEC §6.10), a `[models]` key. Unset, `sonnet`, or the first rank when there is none of that name.
`mode`	string	`"default"`	The mode the side-session dialog preselects (SPEC §6.10); during a run in the shared tree it preselects `manual` whatever this says. Never `yolo` nor a `plan:<mode>` value: side sessions never skip permissions. Allowed: `default`, `manual`, `accept`, `auto`, `plan`.

`[adapt]`

Key	Type	Default	Description
`model`	string	`"sonnet"`	Model rank `igris adapt` uses (SPEC §9). Allowed: `sonnet`, `opus`.

`[draft]`

Key	Type	Default	Description
`model`	string	`"opus"`	Model rank `igris draft` uses (SPEC §9.1). Allowed: `sonnet`, `opus`.

`[parallel]`

Key	Type	Default	Description
`max`	integer	`2`	How many tasks a phase marked `<!-- igris:parallel -->` runs at once, each in its own worktree (SPEC §5.1, §6.11). `arise`/`serve --parallel N` replaces it for one run. Allowed: `1` to `8`.
`exclusive_owner_tasks`	boolean	`true`	A `user` or `agent + user` task of a parallel phase starts only when no other task is active, and nothing starts beside it (SPEC §5.1). `false` schedules them like the others.
`serial_verify`	boolean	`false`	Run one verify at a time in a parallel phase while the sessions stay parallel (SPEC §6.11).
`on_conflict`	string	`"rerun"`	What happens to a task whose commit doesn't integrate, a rebase conflict or verify failing on the integrated tree (SPEC §6.11): `rerun` runs it again from the start once, then asks; `ask` asks at once. Allowed: `rerun`, `ask`.
`ranks`	table	`{ fable = 1 }`	At most this many active tasks of a rank, under `[parallel.ranks]` (SPEC §5.1): a `[models]` key to `1`–`8`. Merged with the default `fable = 1`; a cap above `max` changes nothing.

`[serve]`

Key	Type	Default	Description
`http`	string	unset	The address of serve's HTTP listener for the web UI and ntfy's answer buttons (SPEC §14), `ADDR:PORT`. Unset: no listener. Loopback and Tailscale addresses bind as they are; any other needs `igris serve --listen-public` and TLS. `serve --http` replaces it for one serve.
`tls_cert`	string	unset	A PEM certificate the HTTP listener serves TLS with, relative to the project root; together with `serve.tls_key` (SPEC §14).
`tls_key`	string	unset	The PEM private key of `serve.tls_cert`, relative to the project root.

`[tui]`

Key	Type	Default	Description
`mouse`	boolean	`true`	Click/tap, wheel and hover in the TUI (SPEC §15.5). `false` keeps the terminal's own text selection.
`theme`	string	`"auto"`	Which colors to use (SPEC §15.4). `auto` goes by the terminal's background. Allowed: `auto`, `dark`, `light`.
`rank_colors`	table	empty	Rank to color: `"#rrggbb"` or an ANSI color number `"0"`–`"255"` (SPEC §15.4). Ranks not listed keep the built-in colors.
`tail`	boolean	`true`	Live tail of the current session in the task card (SPEC §15.3). `false` makes no tail calls.

`[notify]`

Key	Type	Default	Description
`quiet`	string	`""` (none)	Quiet hours as `HH:MM-HH:MM`, local time, may cross midnight; held messages go out as a digest (SPEC §10). Start and end must differ.
`break_through`	list of strings	`["needs_input", "session_lost", "task_overdue"]`	Events never held in quiet hours. `[]` holds everything. Allowed: event names (see below).
`task_done_digest`	integer or string	`0`	How `task_done` messages are grouped: `0` or `1` one per task, N ≥ 2 one per N tasks (at most 1000000), `"phase"` one per phase. Allowed: integer, or `"phase"`.

`[notify.backend]`

Key	Type	Default	Description
`enabled`	boolean	`true`	The backend's own toast (herdr, tmux).

`[notify.ntfy]`

Key	Type	Default	Description
`server`	string	`"https://ntfy.sh"`	ntfy server URL.
`topic`	string	`""`	ntfy topic. The channel is off while this is empty.
`token`	string	`""`	ntfy access token, or `"env:VAR"` to read it from the environment.
`events`	list of strings	`["needs_input", "session_lost", "task_overdue", "rank_mismatch", "phase_done", "phase_stuck", "run_error", "verify_failed_limit"]`	Events sent to ntfy. A file igris writes leaves this out while it is the default list. Allowed: event names (see below).
`template`	string	`""`	Message text template (SPEC §10), at most 1000 characters. Empty uses the default text.
`actions`	boolean	`false`	Answer buttons on a pending question's message (SPEC §10): commit, skip, retry or stop, approve a plan. Needs serve's HTTP listener (`[serve] http` or `serve --http`).

`[notify.discord]`

Key	Type	Default	Description
`webhook_url`	string	`""`	Discord webhook URL (https only), or `"env:VAR"`. The channel is off while this is empty.
`events`	list of strings	`["needs_input", "session_lost", "task_overdue", "rank_mismatch", "phase_done", "phase_stuck", "run_error", "verify_failed_limit"]`	Events sent to Discord. Allowed: event names (see below).
`template`	string	`""`	Message text template (SPEC §10).

`[notify.webhook]`

Key	Type	Default	Description
`url`	string	`""`	Generic webhook URL (http or https), or `"env:VAR"`. The channel is off while url and secret are empty.
`secret`	string	`""`	Signs the body (`X-Igris-Signature`), or `"env:VAR"`. A secret without a url is an error.
`events`	list of strings	`["needs_input", "session_lost", "task_overdue", "rank_mismatch", "phase_done", "phase_stuck", "run_error", "verify_failed_limit"]`	Events sent to the webhook. Allowed: event names (see below).
`template`	string	`""`	Message text template (SPEC §10).

`[notify.slack]`

Key	Type	Default	Description
`webhook_url`	string	`""`	Slack incoming-webhook URL (https only), or `"env:VAR"`. The channel is off while this is empty.
`events`	list of strings	`["needs_input", "session_lost", "task_overdue", "rank_mismatch", "phase_done", "phase_stuck", "run_error", "verify_failed_limit"]`	Events sent to Slack. Allowed: event names (see below).
`template`	string	`""`	Message text template (SPEC §10).

`[notify.gotify]`

Key	Type	Default	Description
`server`	string	`""`	Gotify server URL, for example `https://gotify.example.org`. Needs `token` too.
`token`	string	`""`	Gotify application token, or `"env:VAR"`. Needs `server` too.
`events`	list of strings	`["needs_input", "session_lost", "task_overdue", "rank_mismatch", "phase_done", "phase_stuck", "run_error", "verify_failed_limit"]`	Events sent to Gotify. Allowed: event names (see below).
`template`	string	`""`	Message text template (SPEC §10).

Event names

events and break_through take any of: needs_input, session_lost, task_overdue, rank_mismatch, verify_failed_limit, task_done, phase_done, phase_stuck, run_error.

The default events of a channel are ["needs_input", "session_lost", "task_overdue", "rank_mismatch", "phase_done", "phase_stuck", "run_error", "verify_failed_limit"]; the default break_through is ["needs_input", "session_lost", "task_overdue"].