Reference
Configuration
The two-tier settings layout, the real precedence chain, and the task config keys the harness and runtime read.
Settings are TOML in two tiers: one global file per machine, and up to two files per project. Every file is optional — with none of them present, built-in defaults apply and flags still work.
Where settings live
| Tier | Path |
|---|---|
| Global (Windows) | %APPDATA%\neo\settings.toml |
| Global (POSIX) | ~/.config/neo/settings.toml, honouring XDG_CONFIG_HOME |
| Global override | The file named by $NEO_CONFIG always wins for this tier |
| Project | <repo>/.neo/settings.toml — meant to be committed |
| Project-local | <repo>/.neo/settings.local.toml — personal, added to the repo's .gitignore when neo creates it |
| Legacy | ~/.neo/config.toml — read only when the global file is missing |
The project tier is found by walking up from the working directory for a `.neo/` directory. `neo config path` shows the resolved locations on this machine, and `neo config list` shows effective values with the tier each came from.
Precedence
- Explicit CLI flags, and the interactive session's own state
- Environment: NEO_MODEL, NEO_PROVIDER, NEO_BASE_URL, NEO_API_BASE, NEO_API_KEY
- Project `.neo/settings.local.toml`
- Project `.neo/settings.toml`
- The global settings.toml
- The legacy ~/.neo/config.toml, only when the global file is absent
- Built-in defaults
Task configuration keys
These are read per task by the harness and the runtime. Unknown keys pass through the settings layer untouched, so a key one module owns can still be set in any tier.
| Key | What it does | Default |
|---|---|---|
| max_retries | Full attempts at the whole task, inside run_task | 3 |
| budget_cap_usd | Hard cap on model spend per task | 2.0 |
| adaptive_routing | Enable the per-call difficulty router | false |
| model_tiers | Per-tier {provider, model, api_key?, api_base?} the router targets | Built-in tiers |
| crash_retries | Scheduler attempts after a worker crash or kill — not max_retries | 1 |
| resume | Continue from a checkpoint when one exists | true |
| approval | "require" parks the worker at the diff-approval gate | Unset |
| approval_timeout_s | How long that gate may block; unset blocks forever | Unset |
| hang_heartbeat_stale_s | Heartbeat age the scheduler treats as a hang | 30.0 |
| log_root | Where task logs and sessions are written | ./logs |
| plan_with_memory | Query decision memory before planning | true |
| lint_gate | Static pass over changed files before a verify cycle | true |
| docs_lookup_enabled | Allow a step session's DOCS lookups | true |
| coordination_detect | Detect multi-file fan-out at planning time | true |