Settings

Launching

ait settings

The Settings TUI requires the shared Python virtual environment (installed by ait setup) with the textual and pyyaml packages.

Understanding the Layout

The Settings TUI organizes configuration into tabs, each accessible via a keyboard shortcut displayed in the footer.

Agent Defaults (a)

×

Shows the default agent/model for each operation (task-pick, explain, batch-review, raw). These defaults are used when launching tasks from the Board TUI and running explain from the Code Browser TUI. Each entry displays:

• The current value (e.g., claudecode/opus4_6)
• A layer badge: [PROJECT] (green) for project-level defaults or [USER] (amber) for per-user overrides
• Verified score context – score, run count, and recency (e.g., [96 (9 runs, 2 this mo)])
• When the same underlying LLM has scores from multiple providers, an all providers summary appears below (e.g., all providers: 96 (12 runs, 3 this mo))
• A description of what the operation does

Press Enter on any operation to change its agent/model through the model picker.

The picker opens with a Top Verified list showing the highest-scoring models for the selected operation across all providers. Select a model directly or choose Browse all models to use the full agent/model browser.

Press d or Delete on an entry to remove a user override and revert to the project default.

Superseded models

When an entry’s model has been superseded by a newer registered model of the same agent (the same record ait codeagent check-superseded reads), a note appears directly under that entry: ⚠ superseded by claudecode/opus5_5. The note is per layer – a [USER] entry that inherits the project value carries no note of its own. If you declined that same switch when ait codeagent check-superseded offered it, the note is dimmed and says (kept via check-superseded); the Settings TUI shows that choice but never changes it.

To switch a marked entry to the newer model:

• press o on the entry, or
• press Enter on it and choose Switch to … (Choose another model… opens the normal model picker).

A switch changes only the selected entry’s layer. A project switch is saved to codeagent_config.json and committed; a user switch is saved to codeagent_config.local.json and never committed. The current value is re-read from disk first: if the entry or the offered model changed since the tab was drawn, nothing is switched and the tab refreshes. If you have already bound o to another Settings action, that binding keeps the key and Enter remains the way to switch.

Board (b)

Displays board configuration in two sections:

• Columns (read-only) – Lists each board column’s ID, title, and color
• User Settings (editable) – Auto-refresh (min) (cycle through 0, 1, 2, 5, 10, 15, 30 where 0 = disabled) and Sync on refresh (toggle whether push/pull runs on each auto-refresh)

Press Save Board Settings to persist changes.

Project Config (c)

Edit shared values from aitasks/metadata/project_config.yaml directly in the TUI. The initial editable keys are:

• codeagent_coauthor_domain – Shared email domain used for custom code-agent Co-authored-by trailers
• verify_build – Build verification command or YAML list of commands run after implementation

Press Enter on a row to edit the value, then use Save Project Config to persist it.

Project Groups (g)

Edit per-user project-group membership for registered projects. The tab reads and writes through ait projects group ..., so the registry stays consistent with the CLI.

The table lists each registered project, its effective group, and its registry status. Press Enter on a row to assign or change its group, or select a row and use:

• h — assign or change the selected project’s group. Pick an existing group or type a new valid slug.
• u — clear the selected project’s group, making it explicitly ungrouped.
• n — rename a group across every registered member. If the new group already exists, memberships merge.
• y — sync missing registry groups from each repo’s project.project_group.
• f — refresh the table from the registry.

Artifacts (k)

Choose where ait artifact stores blobs. The tab edits the artifacts: block of aitasks/metadata/project_config.yaml:

• default_backend — cycle through the available backends (local, dir, gitbranch) with ← / →. Selecting gitbranch while no branch is set fills in aitask-artifacts.
• gitbranch branch — press Enter to edit the branch the gitbranch backend uses. The name is checked before the dialog closes, so a reserved or malformed name is refused there.

Press Save Artifact Settings to validate the whole block with the artifact registry and commit it; nothing is written if the registry refuses it. local as the default is saved by removing the key. A dir backend has no row here — write its absolute path in the YAML first, and then dir can be saved as the default. Changing the branch once a store exists also needs ait artifact gitbranch-migrate --from <old> --to <new>; the tab shows that command when the branch changes. Saving with a gitbranch branch also updates the routine-fetch exclusion, so git fetch and ait sync skip the store branch; if that update fails, a warning names the command to re-run. Saving rewrites project_config.yaml without its comments.

Models (m)

Read-only display of all available models organized by agent (claudecode, codex, opencode). For each model, shows:

• Name – Internal identifier used in agent strings
• CLI ID – Exact model ID passed to the CLI
• Notes – Description of the model
• Verified stats – Per-operation score with run count and recency (e.g., pick: 96 (9 runs, 2 this month))
• All providers – When the same LLM is available through multiple providers, a cross-provider aggregate line appears below the model row

Model definitions are managed by editing aitasks/metadata/models_<agent>.json files directly or using the /aitask-refresh-code-models skill.

Profiles (p)

Browse and edit execution profiles – YAML files that pre-answer workflow questions to reduce interactive prompts. Each profile contains settings organized into groups:

• Identity – name, description
• Task Selection – skip_task_confirmation, default_email
• Branch & Worktree – create_worktree, base_branch, output_branch
• Planning – plan_preference, plan_preference_child, post_plan_action
• Feedback – enableFeedbackQuestions
• Exploration – explore_auto_continue
• QA – qa_mode, qa_run_tests, qa_tier
• Shadow Review – shadow_impl_review_tier
• Lock Management – force_unlock_stale
• Remote Workflow – done_task_action, orphan_parent_action, complexity_action, review_action, issue_action, abort_plan_action, abort_revert_status

Fields use type-appropriate controls: boolean keys toggle between true/false/(unset), enum keys cycle through their options, and string keys open an edit dialog. Setting a value to (unset) removes it from the profile so the question is asked interactively at runtime.

Shortcuts (s)

Browse and edit the keyboard shortcuts of every TUI in one place — not just Settings. The tab lists all bindings in a single table:

Press Enter on a row to open the in-place editor for that scope, where you rebind (Enter), revert an unsaved edit (r), reset to default (d), and save (s). Rebinds apply the next time you launch the affected TUI.

Two buttons act on the table:

• (D) Reset scope — clears every override for the selected row’s scope (after a confirmation).
• (L)int coherence — reports actions that should share a key across TUIs but have drifted apart.

Exporting and importing shortcuts is part of the general settings Export (e) and Import (i) flow rather than a dedicated button: tick the Shortcuts category. Export writes only the shortcuts: subtree into the .aitcfg.json bundle (your email and other local settings are never included). Import deep-merges those keys into aitasks/metadata/userconfig.yaml, preserving the rest of the file.

Navigating

Next: How-To Guides — common tasks like editing agents, creating profiles, exporting bundles. Or jump to the Reference for the full tab/field/profile schemas.