Air traffic control for AI coding

nool code

Nool's coding agent works in an isolated try worktree under its own lease and lands a goal only when Nool's completion check passes.

  • Interactive TUI or headless --exec with outcome exit codes.
  • Completion check: checkpoint, affected tests, declared checks, review.
  • Ten model providers, from Anthropic and OpenAI to Bedrock and Ollama.
nool code "fix the failing parser test"

What it does

nool code is Nool's own coding agent. It takes a goal, works in an isolated try worktree under its own lease, and keeps going until Nool's completion check passes. It cannot land unverified work: the check, not the model, decides when the goal is done.

Start a session

In a terminal, nool code opens the TUI: a transcript, a plan, approvals and a fleet strip. Without a goal, the first Enter starts one. --mode picks how much it may do without asking: suggest, auto-edit or full-auto.

nool code "add rate limiting to the webhook handler" --mode auto-edit

Run it headless

--exec runs one goal with no human attached, for scripts and CI. The exit code is the outcome, so a pipeline can branch on it.

  • 0: verified, the work landed
  • 2: blocked, with the reason
  • 3: another agent holds a lease on the files
  • 1: paused or failed
nool code --exec "fix the failing parser test" --budget 2 --json

How a goal is checked

When the agent says it is done, Nool runs a completion check: a full-mode checkpoint of the change, the tests that can see it (in a jail), the commands in `[code] checks`, the acceptance criteria of the task you passed with --task, and a releasable check (`nool doctor --strict` on the worktree). A pass is graded `verified`, `self_checked` (only checks the session wrote passed) or `unverified`; `[code] min_verdict = "verified"` refuses the weaker ones. An independent review judges the evidence against the goal's requirements.

  • --task <id> joins a Nool task's acceptance criteria to the check and finishes the task when it lands
  • [code] review_model runs the review on a different model than the agent's; review = "always" runs it in interactive sessions too
  • [code] review_rubric = "REVIEW.md" gives the reviewer your repository's own rules
  • Each objection is confirmed by a read-only checker before it costs a round; a defect the change did not introduce is recorded as pre-existing and never blocks

Configure the completion check

`[code.completion]` in nool.toml makes the check stricter. `red_green`, `oracle` and `mutation` take `required`, `advisory` or `off`; `[[code.completion.steps]]` adds command steps and review steps with a lens. A `workspace.toml` above your repositories can set a floor that each repository may tighten but never weaken. Changes to nool.toml land alone, with a justification.

Pick a model and provider

nool code works with ten providers: Anthropic, OpenAI, Google (Gemini), Azure OpenAI, xAI, Amazon Bedrock, Mistral, Cloudflare Workers AI, OpenRouter and Ollama. Store a key once, set a default model, and switch per run with --model provider:model. `--repo` sets a default for one repository. If the running session server was started with different provider credentials than your shell has now, `nool code provider list` and `nool code doctor` warn and name the variable, never its value.

nool code provider add anthropic
nool code model set anthropic:claude-sonnet-5
nool code provider test anthropic

Inside a session

Five screens sit along the top: Chat (Alt+1), Board (Alt+2) for tasks, Agents (Alt+3) for every session and fleet, Changes (Alt+4, Ctrl+G) for each file's diff, and UML (Alt+5) for how the work will land. The UML screen also flags an agent that has stopped making progress: no new files, no change in tests, several quiet turns in a row. Slash commands steer the session: /model switches models, /undo restores the files the agent edited since your last message, /rewind goes back further, /cost shows spend, and /fleet <goal> hands a goal to a fleet of subagents. !command runs a shell command as you, through the session's gate.

Export a session as a diagram

`nool code uml` rebuilds a session's UML from its event log, as the UML screen draws it: the component view's Mermaid by default, the sequence view with `--sequence`, or a standalone web page with `--html`. Use it to attach how an agent's work will land to a pull request or a review. `nool code --list` shows session ids.

nool code uml <session-id>
nool code uml <session-id> --sequence
nool code uml <session-id> --html session.html

Land on a branch and open a pull request

By default verified work lands on the branch your checkout is on. With `land_target = "branch"` each landing goes to its own git branch and the pull request opens with the landing packet (testing, risk areas, how to revert) as its body; your checkout never moves.

Playbooks and checks

A playbook is a plan template: the steps a session plans with and the commands its completion check runs. `bug-fix`, `feature`, `refactor`, `perf` and `investigation` are built in; `[code.playbooks.<name>]` adds one, or replaces a built-in of the same name. `[code] checks` lists commands every completion check runs, whatever the playbook, including a fleet's integrated check. Both run commands, so a repository's own entries load only after `nool code trust`. Start one with `nool code --playbook <name>` or `/playbook <name>` in the TUI.

[code]
checks = ["cargo clippy -- -D warnings"]

[code.playbooks.release]
description = "Cut a release"
steps = ["Bump the version", "Update the changelog", "Run the release checks"]
checks = ["cargo test --workspace"]

Customise the TUI

A repository ships its TUI in `nool.toml` under `[code.tui]`; each developer keeps personal settings in `~/.nool/code.toml` under `[tui]`. The user's settings win key by key, and tabs from both are added, the repository's first. Theme, sidebar, header, footer, key bindings and file tabs load from any repository; a command tab, a URL tab and a `statusline` run commands, so they load only after `nool code trust`. `nool code doctor` lists what loaded, what trust held back, and any unknown key, so a typo does not silently do nothing.

  • `/tab add <name> <command|file|url>` adds a tab for this run; `--save` keeps it in `~/.nool/code.toml`.
  • Before trust, doctor reports `skipped … repository not trusted (nool code trust)` for the command tab and statusline.
[code.tui]
theme = "mono"                  # auto | dark | light | mono
statusline = "git describe"     # trusted repository only

[code.tui.sidebar]
position = "left"
width = 30

[code.tui.keybindings]
toggle_panel = "ctrl+p"

[[code.tui.tabs]]                # tabs 6-9; 1-5 are Chat, Board, Agents, Changes, UML
name = "Logs"
command = "nool log --compact"  # trusted repository only

[[code.tui.tabs]]
name = "Runbook"
file = "docs/RUNBOOK.md"

Bring your setup

Sessions import MCP servers, skills, hooks and Claude Code-format plugins. nool code doctor shows what a session imports and why anything was skipped; a repository's own servers and hooks load only after nool code trust.

nool code doctor
nool code trust