Using nool code effectively

Write a goal the check can verify

nool code finishes when Nool's completion check passes, not when the model says it is done. Write each goal so that check has something to test: name the outcome, where it lives, and how you would know it works. Keep one goal per session; a second goal in the same session muddies the scope and the evidence.

• Weak: "improve the importer". Strong: "CSV import rejects rows with a missing email and reports the line number; add a test"
• Name the files or module when you know them, so the declared scope and the lease stay small
• Say what must not change ("keep the public API") when it matters

Put acceptance criteria in a task

For work that matters, create a Nool task with acceptance criteria and pass it with `--task`. The criteria join the completion check, an independent review judges the evidence against them, and the task is finished with the knot that lands. The criteria outlive the session, so a resumed session or a teammate checks against the same list.

nool code --task 9f9d6f04 "implement the task"

Pick the mode for the job

`--mode` sets how much the agent may do without asking. Start strict on code you do not know yet and loosen it as you trust the scope. `/mode` changes it mid-session.

• suggest: every edit and command waits for you; use it on unfamiliar or sensitive code
• auto-edit: edits go ahead, risky commands ask; a good default for day-to-day work
• full-auto: nothing asks; the default for --exec, and best with a budget and a tight permission list

Start from a playbook

A playbook turns a goal into a plan and adds its checks to the completion check. Five are built in, and `/playbook` lists them in a session.

• bug-fix: reproduce first, fix the root cause, re-run the repro
• feature: name the data shape, change callers, tests and fixtures together
• refactor: pin behaviour with tests, move in small green steps, delete what is orphaned
• perf: measure a baseline, change one thing, report before and after
• investigation: read-only; answers with path:line citations

nool code --playbook refactor "split billing/invoice.ts into parsing and rendering"

Tell the check what done means in your repo

Commands in `[code] checks` run in every completion check, for single sessions and for every fleet child. Add your linter, type checker or build so a session cannot land work that breaks them. A repository playbook with the same name as a built-in one replaces it. Land the nool.toml change on its own, with `--justification`.

Set a budget and a round limit

`--budget` caps spend in US dollars and `--max-rounds` caps how many rounds a goal may take before the session pauses. The side panel shows spend against the budget; at 80% the session tells the model to stop exploring and finish. Repeating the same write, edit or command three times in a row pauses the session as a doom loop instead of burning money.

• Set defaults once in [code] budget_usd and max_rounds, then override per run
• [code] reasoning_effort = "low-first" starts cheap and raises effort only after a failed check

nool code "add pagination to /api/orders" --budget 3 --max-rounds 20

Choose models per job

Set a default model once, and a different one per repository with `--repo` when a codebase needs it. Run the goal review on a different model with `[code] review_model`, so the model that wrote the change is not the one judging it. `/model` switches models without ending the session.

nool code provider add anthropic
nool code model set anthropic:claude-sonnet-5
nool code model set ollama:qwen3-coder --repo

Keep permissions tight

Allow the commands your work needs and deny the ones it never should run. A shell rule is a prefix (`cargo test`) or, with `=`, an exact command. `--repo` writes the rule to this repository's nool.toml for the whole team; an untrusted repository's allow rules never apply.

• Commands run in a jail that can write the worktree and temp dirs, with the outside network off
• [sandbox] network = "allowlist" in ~/.nool/code.toml lets package registries through and nothing else
• Secrets in tool output are redacted before the model sees them; the side panel counts them

nool code permissions add allow "npm test" --repo
nool code permissions add deny "=rm -rf node_modules"
nool code permissions list

Read the side panel, not only the chat

The model's last message is its opinion. The Nool panel is the record: the branch, the declared scope, knots proposed, the check result, spend, context use and what landed. If the chat says done and the panel says `check failed`, the panel is right. `/changes` (Ctrl+G) opens every file the session touched with its diff and checkpoint.

When a session blocks or pauses

A blocked session says why: a failing test, a reviewer objection, a lease another agent holds, or work that has nothing left to checkpoint. Fix the cause, then continue the same session rather than starting over, so the spend, conversation and branch come back.

• /undo restores the files the agent edited since your last message
• --fork <session-id> --at <turn> starts a new session from an earlier point to try another approach
• Exit code 3 means another agent holds a lease on the files; wait or ask the holder, do not force it

nool code --list
nool code --continue
nool code --resume <session-id>

Run it in CI

`--exec` runs headless and its exit code is the outcome, so a pipeline can trust it: 0 verified and landed, 1 paused or failed, 2 blocked, 3 lease conflict or awaiting approval. `--output-format json` prints one final object with the outcome, cost and summary for the job log.

nool code --exec "fix the failing parser test" --budget 2 --output-format json

Split big goals into a fleet

When a goal spans several modules, run it as a fleet. A coordinator plans tasks with separate scopes, each runs as its own session in its own worktree, and they land in dependency order behind one integrated check. Give the tasks yourself with `--fleet-task` when you already know the split.

nool code --fleet "add search to the docs site" --reviewer openai:gpt-5.5

Learn from your sessions

`nool code metrics` reports verified goals per week, one-shot rate, interventions, and cost and time per verified goal, so you can see whether a change in model, mode or playbook helped. `nool code policy suggestions` turns recurring failures into proposed checks or policies you can accept in one command. `nool code notify` pings you on desktop, Slack, Teams or a webhook when a long session finishes.

nool code metrics --days 30
nool code policy scan
nool code policy suggestions
nool code notify add desktop