# Configuration NurCLI is configured via a TOML file and optional rule/hook files, plus environment variables. ## Config file The config file lives at `~/.nur/config.toml` and is created on first run. ```toml # Active provider id from the catalog (set by TUI /login) provider = "meta" model = "muse-spark-1.2" base_url = "https://api.meta.ai/v1" reasoning_effort = "high" # 0 = unlimited agent rounds per prompt (default). Set a number to cap. max_turns = 0 stream = true context_window = 1000000 # Tool results larger than this spill to ~/.nur/tool-results/ (0 = unlimited) tool_result_max_chars = 12000 # Optional hard stops (omit or leave unset for unlimited) # max_session_cost_usd = 5.0 # max_session_tokens = 500000 # Per-request completion ceiling and reservation used before every dispatch. # 0 restores the provider default and removes this safety reservation. request_output_reserve_tokens = 8192 # Compaction (auto under context pressure, or /compact) compact_keep_user_turns = 4 compact_tool_body_max_chars = 800 # Optional OMP-compatible remote summarizer (POST {systemPrompt,prompt} -> {summary}). # Setting remote_endpoint opts in. OpenAI /chat/completions endpoints are also supported. # On failure, nur falls back to local model summarization. # [compaction] # remote_enabled = true # remote_endpoint = "https://example.com/compact" # Prewalk: strong model plans + todos, then switch to a cheap model at # the first write/edit. Off by default. Toggle with /prewalk in the TUI. # [prewalk] # enabled = true # into = "openai-codex/gpt-5.6-luna" # Optional HelixDB graph-vector memory resident. `auto` activates when a URL is # configured here or through HELIX_URL/NUR_HELIX_URL, so an untouched default # has no network/startup cost. # Local native memory remains authoritative and failed mirrors retry from a # durable outbox. # [helix_memory] # mode = "on" # auto | on | off # url = "http://127.0.0.1:6969" # api_key_env = "HELIX_API_KEY" # env var name, never the key itself # timeout_ms = 1500 # Cost-saver prompt: skip PLUR inject + long memory (tools + skill NL/slash stay full) poor_mode = false # Background TTL pack repair on later TUI opens (first install is foreground) ecosystem_auto_ensure = true # Let ecosystem ensure install/upgrade Oh My Pi (omp); an omp on PATH is used either way # Cheap model for `agent` cost_mode=economy (and prewalk when [prewalk] into is unset) # economy_model = "" # Self-update from GitHub Releases — checked on EVERY launch (60s network floor) auto_update = true # Allow failover from a subscription route (OAuth sign-in, OpenCode Go) to a # per-token fallback. Off by default: a paid fallback is skipped, not billed. # failover_allow_paid = false # Force the wire protocol for one provider/model route, e.g. a gateway that # only speaks Chat Completions. Keys are "provider/model" (or just "provider" # for the whole provider); values: responses | chat | anthropic | gemini. # [protocols] # "opencode/kimi-k3" = "chat" # Auth behaviour. # [auth] # import_fallback = false # true restores silent vendor CLI / OMP import when # no credential is found (default is the explicit # `nur auth import --from `) ``` ### Settings reference | Key | Type | Default | Description | |-----|------|---------|-------------| | `provider` | string | `meta` | Catalog id (`meta`, `openai`, `openrouter`, `ollama`, …). Set by TUI **`/login`** with matching `base_url` + `model` | | `model` | string | `muse-spark-1.2` | Model id for the active provider | | `base_url` | string | `https://api.meta.ai/v1` | API base (no trailing path); providers use Responses or Chat Completions under this base | | `provider_privacy` | map | empty | Per-provider privacy you assert about your own account/endpoint (`{provider_id = "local" / "tee" / "zdr" / "standard"}`); set in the provider picker and overrides the built-in default | | `provider_base_urls` | map | empty | Per-provider base-URL overrides (`{provider_id = "https://…/v1"}`) so any provider - including `openai` - can point at an OpenAI-compatible endpoint (Azure, a proxy, LiteLLM, a mirror). Also honored via env `{PROVIDER}_BASE_URL` | | `fallback_providers` | array | empty | Opt-in cross-provider failover chain: catalog ids or aliases, retried in order on 5xx/429/transport. Each fallback uses its own env-var key; empty = no failover | | `failover_allow_downgrade` | bool | `false` | Allow failover to a provider whose privacy tier is weaker than the active one. `false` means an outage never silently weakens data privacy | | `failover_allow_paid` | bool | `false` | Allow failover from a subscription route (OAuth sign-in, or an OpenCode Go `/zen/go/` base URL) to a per-token provider. `false` skips the paid fallback with a status line instead of silently billing it | | `protocols` | map | empty | Force the wire protocol per route: `{"provider/model" = "responses" \| "chat" \| "anthropic" \| "gemini"}` (a bare `provider` key covers every model). Wins over the catalog's per-model routing; use it when a gateway rejects the default protocol (the 400 error names this table). Ignored for Anthropic and Gemini providers, whose protocol is not negotiable | | `auth.import_fallback` | bool | `false` | When no credential is found, silently import a signed-in vendor CLI / OMP session. `false` (default) keeps imports explicit via `nur auth import --from `, because rotating vendor refresh tokens sign out whichever tool refreshes second | | `auth.encrypt_at_rest` | bool | `true` | Seal `auth.json`, `provider_keys.json` and `provider_sessions.json` with Windows DPAPI (user scope) before writing, so a copied file is inert on another account or machine. Older plaintext files are read as-is and sealed in place on first read. Set `false` when `~/.nur` is synced between machines or Windows accounts. No effect on Unix, where mode 0600 is the protection | | `path_models` | array | empty | Per-directory model: `[[path_models]]` with `path`, `model` and optional `provider` / `effort`. See [Per-directory models](#per-directory-models) | | `advisor.model` | string | empty | A second model that reviews each turn and leaves notes (empty = off). `advisor.provider` (empty = the session's) and `advisor.every_round` (`false`). See [Advisor](#advisor) | | `stream_rules` | array | empty | `[[stream_rules]]` with `name`, `pattern`, `rule`: stop an answer that matches and send it again with the rule. See [Stream rules](#stream-rules) | | `fusion_panel` | array | empty | Opt-in `/fusion` panel: catalog ids polled alongside the active model. `/fusion ` asks each and the active model synthesizes one answer. Empty = off | | `reasoning_effort` | string | `high` | Reasoning depth: `low`, `medium`, `high`, `xhigh`, `max`, `ultracode` (also `minimal`). See [below](#reasoning-effort-levels) | | `max_turns` | integer | `0` | Max agent tool/model rounds per user prompt. **`0` = unlimited** (default). Set via config or `/budget turns` / `/turns` | | `max_session_cost_usd` | float? | unset (∞) | Optional session $ hard-stop. `/budget cost ` · `/budget clear` | | `max_session_tokens` | integer? | unset (∞) | Optional session token hard-stop. `/budget tokens ` · `/budget clear` | | `request_output_reserve_tokens` | integer | `8192` | Conservative per-request completion ceiling/reservation. Nur preflights estimated input + this reserve against context and session budgets, then sends the matching provider output-limit field where supported. `0` uses the provider default and is intentionally less safe. | | `stream` | bool | `true` | Stream API responses | | `context_window` | integer | `1000000` | Fallback context window in tokens (range: 1000–2000000). The models.dev catalog is authoritative when it knows the active provider/model; this value is used only when it does not. Auto-compaction keeps an OMP-style response/tool reserve: the larger of 15% or 16,384 tokens on large windows, with a proportional safety clamp on small windows. A local stored-context estimate is used when provider usage is absent or under-reported. | | `avoid_long_context_pricing` | bool | `true` | On OpenAI API-key GPT-5.6 Sol routes, proactively compact before the [272k input price tier](https://developers.openai.com/api/docs/models/gpt-5.6-sol). This is an estimate, not a hard limit or a billing guarantee; set it to `false` to use the full context without this price target. Subscription sessions are excluded. | | `tool_result_max_chars` | integer | `12000` | Max inline tool output chars; larger results spill to disk with a head+tail preview (`0` = unlimited) | | `shell_timeout_handoff` | bool | `true` | A `bash` command still producing output at its timeout moves to a `bg` job (the model gets a "still running" placeholder with the job id) instead of being killed. `false` restores kill-on-timeout | | `tools.worker_background_secs` | integer | `5` | Automatically hand off a child agent's shell command after this many seconds; `0` disables it. An explicit `timeout_ms` or `background` choice takes precedence | | `compact_keep_user_turns` | integer | `4` | Recent user turns kept after compaction | | `compact_tool_body_max_chars` | integer | `800` | When compacting, truncate older tool bodies to this many chars (`0` = leave intact) | | `kv_stable_compact` | bool | `true` | `true` preserves the recent working edge verbatim after a stable summary for provider prompt-cache reuse. `false` uses a classic reconstructed working-tail order. Compaction status reports the active strategy. | | `compaction.remote_enabled` | bool | `false` | Prefer remote summarizer when an endpoint is set | | `compaction.remote_endpoint` | string | unset | OMP-compatible compact URL; setting it opts in. Supports `{systemPrompt,prompt}` endpoints and OpenAI `/chat/completions`; failures fall back locally. The bounded transcript crosses this configured remote data boundary. Nur records endpoint origin, bounded input estimate, output estimate, and provider usage when returned in the session receipt. Env: `NUR_COMPACT_REMOTE_ENDPOINT` (+ `NUR_COMPACT_REMOTE=1` if only env) | | `typesafe.enabled` | bool | `true` | [TypeSafe](https://docs.typesafe.ai) (Jev) typed judgments for the harness: tool gate, result judge, Jev-scored compaction, skill checks, model routing. Needs a key (`TYPESAFE_API_KEY` or `/auth`); with none, every policy returns "no judgment" and behavior is unchanged. Full reference: [typesafe.md](./typesafe.md) | | `typesafe.model` | string | `jev-latest` | System One model that answers the questions | | `typesafe.key_env` | string | empty | Exclusive environment variable name for a selected Jev engine; never the key value | | `typesafe.credential_provider` | string | empty | Exclusive credential-store slot, set to `jev:` by `nur jev use --engine ` | | `typesafe.base_url` | string | `https://api.typesafe.ai/v1/systemone` | System One endpoint. A **loopback** URL (127.0.0.1 / localhost / `[::1]`) needs no key and runs the whole judgment layer against a local engine - see [jev-local.md](./jev-local.md) | | `typesafe.act_confidence` | float | `0.85` | Confidence at or above which a judgment may change behavior | | `typesafe.escalate_confidence` | float | `0.5` | Below this the judgment is handed to a bigger model or a human instead of being acted on | | `typesafe.api_key` | string | unset | Key inline in config. Prefer `TYPESAFE_API_KEY` or the credential store - anything here is plain text on disk | | `typesafe.timeout_ms` | integer | `20000` | Per-request timeout. Jev is fast; a long stall means something is wrong | | `typesafe.retries` | integer | `2` | Retries on 429/529/5xx with exponential backoff | | `typesafe.max_questions_per_request` | integer | `24` | Questions merged into one request before they are split and sent in parallel | | `typesafe.max_parallel` | integer | `4` | Concurrent requests when a question set is split | | `typesafe.max_request_tokens` | integer | `30000` | Estimated ceiling for one request (state + its questions). Ported from fast-jev-compaction; keeps a request under System One's ~32k limit | | `typesafe.compaction.enabled` | bool | `true` | Jev-scored compaction: drop tool calls, keep survivors verbatim | | `typesafe.compaction.replace_summary` | bool | `true` | Manual `/compact` honors configured Jev without summarizing, even at zero reduction; automatic recovery also checks `min_reduction` | | `typesafe.compaction.min_reduction` | float | `0.25` | Automatic recovery only: positive reduction required to skip summarization | | `typesafe.compaction.preserve_recent` | integer | `6` | Newest N items never touched (the first item is always kept) | | `typesafe.compaction.keep_threshold` | float | `0.5` | Minimum keep probability for a call or result to survive | | `typesafe.compaction.truncate_head_chars` | integer | `300` | Chars of a dropped result retained before its note | | `typesafe.compaction.max_state_tokens` | integer | `25000` | Estimated token ceiling for the state Jev sees | | `typesafe.compaction.goal_prompts` | integer | `3` | Recent user prompts that make up the goal shown to Jev | | `typesafe.tool_gate.enabled` | bool | `true` | Pre-execution gate + post-execution result judge at the tool boundary | | `typesafe.tool_gate.judge_results` | bool | `true` | Judge results after execution (did it work, keep it, keep it verbatim) | | `typesafe.tool_gate.skip_redundant` | bool | `true` | Answer a confident duplicate of a call whose result is still in context without re-running the tool | | `typesafe.tool_gate.skip_repeated_failures` | bool | `false` | Also skip identical repeats of a call that already failed (surfaced in the transcript, not enforced, by default) | | `typesafe.tool_gate.flag_risky` | bool | `true` | Surface risk / needs-human judgments in the UI. Never blocks anything | | `typesafe.tool_gate.preview_chars` | integer | `1200` | Chars of arguments/result shown to Jev per call | | `typesafe.tool_gate.trace_window` | integer | `16` | Most recent calls kept in the gate's state window | | `typesafe.skills.enabled` | bool | `true` | Skill layer on/off | | `typesafe.skills.rerank` | bool | `true` | Rerank skill candidates against the request when several match | | `typesafe.skills.narrow_requirements` | bool | `true` | Inject only the triggered skill's applicable rules as a checklist | | `typesafe.skills.check_usage` | bool | `true` | Check that an activated skill was actually carried out | | `typesafe.skills.max_requirements` | integer | `8` | Most rules injected from a narrowed skill | | `typesafe.routing.enabled` | bool | `true` | Run an `agent` call that names no provider/model on a cheaper reachable model when it is known-price, at least 15% cheaper and no weaker in privacy, with parent context Jev judged directly useful. The parent session never moves | | `typesafe.routing.suggest` | bool | `true` | Show routing decisions in the transcript | | `typesafe.tools.subset` | bool | `false` | Narrow the tool surface on the first round of a turn (one Noul per specialist; later rounds get the full surface). Off because tool schemas ride the prompt cache | | `typesafe.tools.keep_probability` | float | `0.75` | How confident the answer must be that a tool is *not* needed before it is dropped (keeping is the safe direction) | | `enclave.url` | string | `https://mcp.enclave.ai/` | [Enclave](./enclave.md) MCP endpoint (empty = default). https only; plain http only for a loopback host. The key comes from `ENCLAVE_MCP_API_KEY` or the credential store, never this file | | `enclave.timeout_secs` | integer | `120` | Upper bound on one Enclave MCP request | | `headroom.enabled` | bool | `true` | [Headroom](https://github.com/headroomlabs-ai/headroom) inline compression of large tool results (needs the `headroom-ai` package; missing package = no-op) | | `headroom.mode` | string | `inline` | `inline` compresses tool results before they enter model context; `off` disables (proxy mode reserved) | | `headroom.min_chars` | integer | `2000` | Skip compression below this many chars | | `headroom.model` | string | active session model | Token-counter model passed to Headroom; empty = the active session model | | `optmem.enabled` | bool | `true` | [OptMem](https://github.com/VictorTaelin/OptMem) permanent memory under upstream `~/.optmem` (wake inject + `optmem` tool; `/optmem` · `/memo`) | | `prewalk.enabled` | bool | `false` | After todos exist, first write/edit switches to `prewalk.into` | | `prewalk.into` | string | unset | Cheap model for prewalk handoff (`/prewalk into …`, or `NUR_PREWALK_MODEL`) | | `helix_memory.mode` | string | `auto` | `auto` enables only when `HELIX_URL`/`NUR_HELIX_URL` or a configured URL exists; `on` uses the configured/local endpoint; `off` disables the resident | | `helix_memory.url` | string | local endpoint when on | HelixDB gateway base URL. Nur uses `/healthz` and typed `/v2/query` requests | | `helix_memory.api_key_env` | string | `HELIX_API_KEY` | Name of the env var containing the Helix bearer token. The token is never written to config or memory | | `helix_memory.timeout_ms` | integer | `1500` | Per-request deadline. Writes queue locally first and retry from the outbox on later writes or `helix_sync` | | `native_memory` | bool | `true` | Agent-native memory + Connectome continuity: inject hierarchical memories into the system prompt and run localized maintenance on compact | | `memory_embed_mode` | string | `auto` | Embedding mode: `auto` (API, fall back to local on error), `api` (require API), or `local` (offline n-gram hash embedding only) | | `memory_embed_model` | string | provider default | Embedding model for the vector store. Empty = provider default (`text-embedding-3-small`); falls back to the local embedding when the API path is unavailable | | `memory_model_extract` | bool | `false` | Let the active model write durable first-person memories from assistant turns (one cheap low-effort call per turn). Off by default | | `message_inbound` | string | `refuse` | Inbound peer-mail policy (`~/.nur/peers`, `message` tool): `refuse` (default - off) / `ask` (you approve each letter before the model sees it) / `accept` (deliver). Unknown values fail closed as `refuse` | | `proposal_mode` | bool | `false` | Shepherd-style retained outputs: `write_file` stages under `~/.nur/proposals//` until `proposal apply` | | `quality_gate` | string | empty | Shell command run as a quality gate before accepting DONE in autonomous mode. Empty = none | | `context_register_min_chars` | integer | `8000` | Auto-register tool results larger than this into the RLM context store (`0` = disabled) | | `subagent_depth` | integer | `1` | RLM-style subagent recursion depth. `1` = children only; each extra level multiplies cost | | `poor_mode` | bool | `false` | Skip PLUR auto-inject and long memory (explicit skill activation - slash and the `skill` tool - still works) | | `theme` | string | unset | Picked theme id (`/theme`). Unset = Nur Gold until onboarding choice | | `theme_setup.accent` | hex string | unset | Personal accent color (`#rrggbb`) layered over **every** theme pick - recolors the accent ramp, highlights, and banner gradient. `theme_setup.accent_deep` / `theme_setup.accent_sky` optionally pin the ramp ends (derived automatically when absent) | | `theme_setup.protocol` | string | `auto` | Force the terminal graphics protocol for inline images: `kitty`, `sixel`, `iterm2`, `halfblocks`, or `auto` | | `theme_setup.inline_images` | bool | `true` | Pictures inline: sent attachments and successful tools' images (screenshots, `look`, generated images) drawn in the transcript as half-blocks, with kitty/sixel pixels over them where the terminal speaks one, and on stderr in `nur run`. `false` keeps compact rows. See [Vision](vision.md#inline-images) | | `theme_setup.transparent` | bool | `false` | Skip painting panel/code backgrounds so a translucent terminal shows through (`/theme transparent`) | | `theme_setup.motion` | string | `auto` | Animation. With `full`, the NUR banner shimmers whenever it is on screen, idle included; every other ambient animation (aurora rules, the input border, modal edges) moves only while an agent turn, startup or a modal is active, and holds its frame while idle. `reduced` is an accessibility setting: the banner and all ambient animation hold one still frame, and spinners tick at ~10fps. `auto` picks `reduced` only over SSH (`SSH_TTY`/`SSH_CONNECTION`), where every frame crosses a network link. `/theme motion` toggles and saves; `NUR_REDUCED_MOTION=1|0` overrides for one run | | `ecosystem_auto_ensure` | bool | `true` | Background TTL **repair** of packs on later TUI opens (first install is foreground via npx / one-liner / EXE / `nur install\); set `false` to skip repair | | `economy_model` | string | unset | Model for `agent` calls with `cost_mode: economy` that stay on this provider, and for prewalk when `[prewalk] into` is unset. Unset: an economy child runs on the cheapest tool-capable model the account lists that models.dev prices | | `skills.auto_activate` | bool | `false` | Natural-language skill activation ("think like fable" injects the skill body). Off by default; explicit `/skill-name` and the `skill` tool always work. See [natural-language skill activation](./ecosystem.md#natural-language-skill-activation) | | `tools.profile` | string | `lean` | `lean` = the editing shell and session tools up front, every ecosystem tool loaded on demand through `tool_search` (about 6.1k tool-schema tokens before the v0.61 additions; 32 tools in the default build, plus the system prompt; a loaded tool joins the end of the roster from the next request on). `full` = every tool up front. `core` = minimal editing shell (18 tools: typesafe, read/list/write/edit/multi_edit/apply_patch/hashline_edit, bash, sgrep/ast_grep/grep/glob, web_fetch/web_search, question, todo_write, submit_plan) with no ecosystem prose. Restart to change. Unknown values fall back to `lean`. Measured per-request overhead on the E2E harness (chars/4, no PLUR or OptMem installed): `full` about 3.9k system-prompt + 15.4k tool-schema tokens (54 tools), `core` about 1.8k + 2.8k (15 tools). Measured before the code-shape block (about 280 tokens, in `lean` and `full` only) and the `slop_scan` and `secscan` tools were added | | `tools.sgrep_first` | bool | `true` | Semantic search is enforced, not suggested: a `grep` whose pattern is a description is answered by `sgrep`, a `grep` past its default cap comes back reranked by `sgrep` (an explicit `max_matches` is honored), and shell searches (`grep`/`rg`/`findstr`/`Select-String` as the command) are refused. Needs sgrep installed to change anything; see [Tools](tools.md#sgrep) | | `tools.pass_provider_keys` | bool | `false` | Model-provider keys (`OPENAI_API_KEY`, `NUR_API_KEY`, and the rest of the catalog's key variables) are removed from the environment of commands that tools run, so `printenv` or an injected `curl` cannot leak them. `GITHUB_TOKEN`, `HF_TOKEN`, `CLOUDFLARE_API_TOKEN` and `AWS_BEARER_TOKEN_BEDROCK` pass through for your own tools. `true` passes every key, for scripts that call a provider themselves | | `tools.rust_builder` | string | `"cargo"` | `"blaze"` or `"auto"` runs plain `cargo build`/`check`/`test`/`run` through [blaze](https://github.com/indexable-inc/blaze), the incremental Rust compiler (`auto` only on Linux x86-64/aarch64 and macOS arm64 with blaze installed; `NUR_BLAZE_BIN` overrides the binary). `--release`, `+toolchain`, compound shell lines and flags blaze refuses stay on cargo, a blaze refusal reruns the command on cargo, and every blaze result reminds the agent to run `cargo check` once (blaze's borrow checker is partial). nur never installs blaze | | `lsp.prewarm` | bool | `true` | Start detected language servers in the background and on first edit; `false` starts them only through the `lsp` tool | | `lsp.servers` | table | built-in list | Extension → language-server command, e.g. `rs = "rust-analyzer"` or `py = "basedpyright-langserver --stdio"`. Built-ins are detected on PATH (rust-analyzer, typescript-language-server, pyright, gopls); an extension with no entry has no server, and the `lsp` tool says so instead of spawning anything | | `sandbox.enabled` | bool | `true` | Wrap `bash` commands in the OS jail: bubblewrap, Landlock and seccomp on Linux, and Seatbelt on macOS. If the requested jail is unavailable, the command fails; set `sandbox.mode = "off"` to run without it. Windows defaults to `off` | | `sandbox.mode` | string | `read-only` on Linux/macOS, `off` on Windows | `read-only` (filesystem read-only outside a private `/tmp`, network off), `workspace-write` (adds a writable workspace), or `off`. Approval still gates whether a command runs; this decides what it can reach | | `auto_update` | bool | `true` | On **every** launch (bare TUI, `nur "prompt"`, `nur run …`, gateway), check [GitHub Releases](https://github.com/nuroctane/nur-cli/releases/latest) and install a newer binary when available; it runs on a background thread so it never delays or breaks a run, and the new binary is picked up on the next launch. A 60s floor between network checks stops a script that loops `nur` from hammering the API — tune it with `NUR_AUTO_UPDATE_TTL_SECS` (`0` = check every run). Opt out with `false` or env `NUR_SKIP_AUTO_UPDATE=1`. Verify with `nur update --check`; `nur update` always runs the full update path | ### Personal accent (theme setup) Layer a personal accent color on top of any `/theme` pick: ```toml [theme] accent = "#e8b923" # your accent (any #rrggbb) # accent_deep = "#8a5a00" # optional; derived when absent # accent_sky = "#ffe08c" # optional; derived when absent ``` The accent recolors the theme's ramp (sky → accent → deep), selection highlights, and the banner gradient - so `/theme midnight` + `accent = "#ff5470"` gives you midnight with a pink spine. `/theme` switching keeps the override. ### Reasoning effort levels | Level | Behaviour | |-------|-----------| | `low` | Light reasoning | | `medium` | Balanced (alias `med`) | | `high` | Deep reasoning (default) | | `xhigh` | Deeper still (alias `extra`) | | `max` | The strongest reasoning the route takes | | `ultracode` | `max`, plus the agent splits work that splits across parallel subagents and verifies the result (alias `ultra`) | `minimal` is still accepted for OpenAI-shaped routes. Set a level with `/effort ` (saved to this file) or `--effort` for one run. Providers do not share one ladder, so nur keeps the level you chose and sends each route the nearest rung it accepts, on that route's native field: Responses `reasoning.effort`, Anthropic `output_config.effort`, the Chat Completions vendor's own field, or Gemini's `thinkingLevel`. Bare `/effort` shows what the active route receives: | Route | Receives | |-------|----------| | OpenAI GPT-5.6 | `none`, `low`, `medium`, `high`, `xhigh`, `max`; `ultracode` sends `max` | | Other Responses-API routes (`reasoning.effort`) | `minimal` … `xhigh`; `max` and `ultracode` send `xhigh` | | xAI browser login (Responses) | Grok 4.6/4.7: `low`, `medium`, `high`, `xhigh`; Grok 4.5: through `high`; legacy Grok 3 mini: `low` or `high` | | Anthropic (`output_config.effort`) | By model: Fable, Opus 4.7+ and Sonnet 5 take `low` … `max`; Opus/Sonnet 4.6 and Mythos Preview take all but `xhigh`; Opus 4.5 takes `low` … `high`; Haiku and older models get none | | Paper Instruments (Ultramarine) | Top-level `reasoning_effort`: `low`, `high`, `max` | | Morph | DeepSeek snapshots (`morph-dsv4…`): top-level `reasoning_effort` `low`, `high`, `xhigh`, `max`; GLM and Kimi models: `reasoning.effort` `low`, `medium`, `high` | | OpenRouter | `reasoning.effort` `low`, `medium`, `high` (`none` is omitted: provider default) | | Groq | GPT-OSS models: `reasoning_effort` `low`, `medium`, `high`; other reasoning models: a `none`/`default` toggle | | Mistral | Reasoning models (Magistral, Small/Medium/Large): `none`/`high`; others get nothing | | Together | GPT-OSS and most models: `low`, `medium`, `high`; DeepSeek V4 Pro: `high`/`max` | | Fireworks | `none`, `low`, `medium`, `high`, `max` | | Cohere | `none` or `high` | | Kimi / Moonshot | K3 family: `reasoning_effort` `low`, `high`, `max`; K2-era ids keep the `thinking` toggle | | DeepSeek, zhipu | `reasoning_effort` `low`, `high`, `max` | | Qwen | A `none`/`high` toggle | | Gemini (Cloud Code) | `thinkingLevel`: `minimal`→MINIMAL, `low`→LOW, `medium`→MEDIUM, `high` and above →HIGH | | vLLM and other OpenAI-compatible routes | `reasoning_effort` `minimal` … `xhigh` | | MiniMax, Meta, Ollama, llama.cpp, LM Studio | No effort control, so nothing is sent | A 400 that names the effort field (aggregators route by model id, so the model behind the route is not known in advance) retried once with the field omitted; the status line names the value that was dropped. The level is saved either way and applies again on a route that takes one. `ultracode` also turns on parallel subagent orchestration, which works on every route because it is an instruction to the agent rather than a request field. Write **`ultrathink`** as a word anywhere in a prompt to send the strongest rung the route accepts for that turn only; the saved level does not change. Inside code spans, fenced blocks, paths, flags and identifiers (`notes/ultrathink.md`, `--ultrathink`) it is just text. Provider references: [OpenAI](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.6), [xAI](https://docs.x.ai/developers/model-capabilities/text/reasoning), [Anthropic](https://platform.claude.com/docs/en/build-with-claude/effort). A missing rung rounds to the nearest one, and ties round up. A name nur does not know is forwarded as-is, so a rung a vendor ships today works today. ### Session budgets (interactive) In the TUI you can set ceilings without editing the file: ```text /budget # show ceilings + spend so far /budget cost 2.5 # hard stop at ~$2.50 this process /budget tokens 500000 /budget clear # unlimited this process /budget save # write current ceilings into config.toml ``` When a ceiling is hit, the agent **refuses new API turns** with a clear status message. Budgets are the only thing that stops a turn. With no ceilings set, nothing ends a turn on its own: context-window overflow (a preflight estimate or a provider rejection) recovers through staged compaction - promote to a larger sibling model, model-assisted compact, then a local minimal trim - and oversized pasted input is auto-registered with the `context` tool (pointer + preview) instead of being refused. Every other turn stop is an explicit budget you set. `max_turns = 0` means unlimited task completion rounds - it does **not** mean that spending is safe or capped. On the first unrestricted turn Nur warns about this distinction. Provider usage can be absent or subscription-only, so token and dollar enforcement remains estimate-based on those routes. ### Conservative budget preset For unattended or weekly-allowance-sensitive work, start with this explicit preset and adjust upward only after inspecting `/usage` and `/receipt`: ```toml # Conservative: 40 model/tool rounds, 250k total tokens, $2.00 estimated # list-price spend, and an 8k reserve before every request/failover target. max_turns = 40 max_session_tokens = 250000 max_session_cost_usd = 2.0 request_output_reserve_tokens = 8192 # Keep fusion/fan-out opt-in. Every configured panel is an additional reserved # request; set fusion_panel = [] for the conservative preset. fusion_panel = [] ``` The preflight also evaluates each failover destination for context capacity, tool capability, parallel-tool safety, output-limit support, and incremental catalog-estimated cost. Local OpenAI-compatible servers use conservative serial tool behavior because tool support depends on the selected model template. --- ## Permission rules Optional file: **`~/.nur/permissions.toml`** (and/or project **`.nur/permissions.toml`** - both are merged). A project file comes with the repository, so it can only tighten on its own: its `deny` and `ask` rules apply at once, while its `allow` rules are held until you trust that exact list with `/permissions trust` or `nur permissions trust`. An edit to the list (a `git pull`, say) holds it again, and nur tells you at startup what the project asks to auto-approve. Trust is recorded per directory in `~/.nur/trusted-permissions.json`; `/permissions untrust` withdraws it. ```toml # Patterns: "tool" or "tool:glob" (* = any sequence) # Order: deny > ask > allow > mode default # Plan mode still blocks code authoring / VCS mutation even if allow matches. deny = ["bash:rm -rf *", "bash:git push --force*"] ask = ["bash:npm publish*"] allow = ["bash:git status*", "bash:cargo test*"] ``` | Decision | Effect | |----------|--------| | **deny** | Always block (including auto mode) | | **ask** | Force an approval prompt (even in auto) | | **allow** | Skip approval in manual (plan structural blocks still win) | `bash` rules see every command in a chain. The command is split at `;`, `&`, `&&`, `|`, `||`, newlines and subshell parentheses (quoted text stays whole), so a `deny` or `ask` rule fires when **any** command in it matches: `cd . && rm -rf /` is denied by `bash:rm -rf *`, and so is `echo "$(rm -rf /)"`. An `allow` rule approves only when **every** command is allowed on its own: `bash:git *` covers `git status && git diff`, not `git status && curl … | sh`. A command substitution (`$(…)`, backticks, `<(…)`) or a redirect into a file (`> out.txt`; `2>&1` and `>/dev/null` are fine) is never approved by pattern and falls back to the mode default. Reload without restart: `/permissions reload`. `/cd` reloads them for the new directory. --- ## Tool hooks Hook **output is discarded** - exit status is the only channel (`0` allows, non-zero blocks the call in Manual/Auto and is reported to the model). stdout/stderr are not captured, so a hook that writes a lot cannot stall the call. Optional file: **`~/.nur/hooks.toml`**. ```toml pre_tool = "echo pre $NUR_TOOL" post_tool = "" timeout_ms = 5000 ``` Environment for hook commands: | Env | Meaning | |-----|---------| | `NUR_TOOL` | Tool name | | `NUR_ARGS_JSON` | Raw JSON args | | `NUR_CWD` | Workspace cwd | | `NUR_SESSION` | Session id | Non-zero **pre_tool** exit blocks the tool. Missing file = no hooks. Check status with `/hooks`. --- ## Per-directory models `[[path_models]]` picks the model by working directory. The longest `path` that contains the directory wins; outside every entry the configured model applies. `provider` and `effort` are optional. ```toml [[path_models]] path = "~/work/site" model = "claude-sonnet-5" provider = "anthropic" effort = "low" [[path_models]] path = "C:/work/engine" model = "gpt-5.5" ``` The entry applies at startup and on every `/cd`, with a note naming it. It never touches `config.toml`: saving writes the configured model back, not the directory's. An explicit choice wins for the rest of the session: `--model`, `NUR_MODEL`, `NUR_PROVIDER`, or picking a model with `/model`. --- ## Advisor `[advisor]` adds a second model that reviews the agent's work. Before a turn ends it reads the request, the turn's recent tool trace and the answer; if it sees a misread request, a skipped requirement, a bug or an unchecked claim, it writes a short note, the note joins the conversation, and the agent takes one more pass. It pushes back at most once per turn. With `every_round = true` it also reviews after each tool round; that note is read before the next step and never stops anything. ```toml [advisor] model = "gpt-5.5-mini" provider = "openai" # optional: the session's provider when empty every_round = false ``` Notes appear in the transcript (`advisor · `) and as `advice` events in `nur run --output-format stream-json`. Advisor requests are metered under their own route. A failed advisor request is a status line and the turn goes on. A provider without a saved key turns the advisor off for that turn with a note. The advisor also holds the work to the project's own rules: a `## Code Review Rules` section in any AGENTS.md of the instruction chain (up to 4,000 characters) is added to its brief, and when the turn wrote files it checks them against the code-shape indicators (implicit coupling, duplication, god files, pass-through wrappers and the rest; see the `codebase-slop` skill). --- ## Notifications `[notifications] chime = true` signals a completed turn with a terminal bell, and also sounds whenever the agent stops mid-turn to wait on the user: a question, approval, secret, or login modal in the TUI, an update modal, or an interactive approval/question prompt in headless mode. That second signal is the point: without it, an approval can wait silently while the user has no idea. Terminal and multiplexer bell settings determine whether it is audible. Set `chime = false` to disable both signals, or set `command` to a sound command to run instead of the bell. The sound fires once per pop-up, when the prompt becomes visible and actionable, not when it is merely queued behind another modal. It does not fire for ACP or gateway clients, which surface prompts in their own UI. ## Auto-continue A turn that stops on a usage limit (429, "usage limit reached", a quota with a reset) or an outage the client's own retries could not ride out (5xx, overloaded, a dropped connection) continues by itself once it lifts: the TUI shows a card with a toggle (`/autocontinue`), and `nur run` and `--continuous` wait in place (Ctrl+C stops; a waited-out step does not count against `--max-iters`). The reset comes from the provider's headers (`retry-after`, `anthropic-ratelimit-unified-reset`, `x-ratelimit-reset-*`), error body (`resets_in_seconds`, `resets_at`, `RetryInfo`) or message ("try again in 2 hours"). Billing, sign-in and bad requests never continue. ```toml [auto_continue] enabled = true # default delay_secs = 60 # after the reset the provider gave max_attempts = 8 # resumes in a row before handing back ``` ## Secrets `[secrets] catch_pasted = true` (default): a live-looking credential typed or pasted into the TUI prompt opens the secret modal instead of being sent. Saved secrets (`/secrets`, `nur secrets set NAME`) are environment variables in every shell command and are redacted from tool output; see the `secret` tool. --- ## Stream rules A stream rule sits idle until the model writes what it forbids. When the streamed answer matches a rule's pattern, the request is stopped mid-stream, the partial answer is taken back, the rule joins the conversation and the request goes out again (oh-my-pi's time-traveling stream rules). Tool-call arguments do not stream, so a finished response is checked too and a matching one is dropped before any tool runs. Each rule fires at most once per turn. ```toml [[stream_rules]] name = "box-leak" pattern = 'Box::leak' # Rust regex over the answer rule = "Do not use Box::leak; use Arc or an owned String." ``` A project can add its own in `.nur/stream-rules.toml` (`[[rule]]` entries with the same fields). Like project skills, they stay off until you trust the project with `/skills trust` (`nur skills trust`), and an edit holds them again: a cloned repo's rules can inject instructions. A rule that does not compile is skipped with a status line. In `stream-json` output a stopped answer shows as a `stream_restart` event. --- ## Environment variables ### API and model | Variable | Purpose | |----------|---------| | `NUR_API_KEY` | API key (preferred) | | `META_API_KEY` | Optional key for Meta Model API provider | | `NUR_BASE_URL` | Override API base URL (self-hosted Ollama/vLLM/LiteLLM/gateways) | | `NUR_PROVIDER` | Override the provider for this process (catalog id or alias, e.g. `opencode-go`, `chatgpt`). The provider's host and default model follow; `[provider_base_urls]` and `_BASE_URL` still apply, and `NUR_MODEL` / `--model` still pick the model. An unknown id is a config error. A value inherited from a parent `nur` session is ignored | | `NUR_MODEL` | Override model id for the active provider. A value inherited from a parent `nur` session is ignored (nur exports `NUR_MODEL` to its own children) - pass `--model` to override explicitly | | `NUR_JEV_LOCAL_URL` | Point the TypeSafe layer at a local System One engine (e.g. `http://127.0.0.1:8788`). Loopback needs no key, so `TYPESAFE_API_KEY` becomes optional. See [jev-local.md](./jev-local.md) | | `TYPESAFE_API_KEY` | TypeSafe (Jev) key for the harness boost layer. Aliases: `TYPESAFE_KEY`, `JEV_API_KEY`; also `/auth` → `TypeSafe · Jev`, or `~/.nur/typesafe.key`. It is a judgment credential, never the active chat provider | ### Provider reliability | Variable | Purpose | |----------|---------| | `TREG_TOKEN` | Token from [treg](https://treg.to/web-access) (`treg login`). Turns on treg as `web_search`'s first backend and `web_fetch`'s fallback for blocked or JavaScript-only pages; each call prefers the free vendor and is capped at $0.02. `NUR_TREG_BASE` points at a self-hosted treg. | | `EXA_API_KEY` | Enables Exa as a `web_search` backend after treg. | | `BRAVE_API_KEY` | Enables Brave as a `web_search` backend after Exa. | | `TINYFISH_API_KEY` | Key from [TinyFish](https://docs.tinyfish.ai) (free: Search 30 requests/min and 12,000/day, Fetch 150 URLs/min and 1,000/day). Enables TinyFish Search as a `web_search` backend after Brave, and TinyFish Fetch as `web_fetch`'s fallback after treg for blocked or JavaScript-only pages (each one spends a daily fetch). A rejected key, a used-up allowance or a rate limit is named in the answer. | | `NUR_SCRATCH` | Set by nur for every shell command: `/.nur/scratch`, the model's scratch folder (created on demand with a `.gitignore` of `*`). Not read from your environment. | | `NUR_PROVIDER_IDLE_TIMEOUT_SECS` | How long a provider connection may stay completely silent (no bytes, headers included) before Nur treats it as dead and reconnects (default `300`). A response that is still streaming is never cut off | | `NUR_PROVIDER_TURN_TIMEOUT_SECS` | Optional hard cap on one provider request, every transport including the Cursor Agent and Droid CLIs. Unset (the default) means no cap | ### Rendering | Variable | Purpose | |----------|---------| | `NUR_IMAGE_PROTOCOL` | Force the terminal graphics protocol for inline images (`kitty`, `sixel`, `iterm2`, `halfblocks`); overrides `theme_setup.protocol` | | `NUR_IMAGE_QUERY` | Set to `1` to run the full stdio graphics-capability probe on launch (default is the instant, non-blocking path) | | `NUR_REDUCED_MOTION` | `1` freezes ambient animation and stops idle repaints for this run, `0` forces full motion; overrides `theme_setup.motion` | | `NUR_STARTUP_TRACE` | Set to `1` for local phase timings in `$NUR_HOME/cache/startup-.jsonl`, or set a file path. Records elapsed milliseconds and stage names, without prompts or credentials. Off by default | ### Paths | Variable | Purpose | |----------|---------| | `NUR_HOME` | Override data home (default `~/.nur`). Its parent directory also becomes the `~` nur reads vendor state from (`~/.agents`, `~/.claude`, `~/.codex`, `~/.optmem`, ...), so `NUR_HOME=/.nur` is a fully contained install. Without it, `HOME` then `USERPROFILE` are honoured on every OS (Windows included), then the OS profile | | `NUR_CWD` | Default working directory | ### Status and usage Set by NurCLI for host integrations: | Variable | Purpose | |----------|---------| | `NUR_STATUS_PATH` | Path to live status file | | `NUR_USAGE_LOG_PATH` | Path to usage log | | `NUR_SESSION_ID` | Current session id | | `NUR_PROVIDER` | Provider id Nur exports to its own children (the active provider, e.g. `meta`); children ignore the inherited value, see above | ### Update control The release check runs on **every** launch (see `auto_update` above). | Variable | Purpose | |----------|---------| | `NUR_SKIP_AUTO_UPDATE` | Set to `1` to skip the launch-time release check for this shell | | `NUR_DISABLE_UPDATES` / `DISABLE_UPDATES` | Set to `1` to disable the launch-time release check | | `DISABLE_AUTOUPDATER` | Claude Code's kill switch — also honored. It is injected only inside AI-agent sessions, so nur stays on your last version there instead of swapping its own binary mid-session. Absent from an ordinary terminal, where nur still updates every run | | `NUR_AUTO_UPDATE_TTL_SECS` | Minimum seconds between network checks (default `60`; `0` = check every single run). Guards against a script looping `nur` | | `NUR_AUTO_UPDATE_BLOCKING` | Set to `1` to wait for the check to finish before continuing, instead of backgrounding it (scripts / CI that want to be on the newest build now) | ### Ecosystem | Variable | Purpose | |----------|---------| | `CLAUDE_FLOW_DB_PATH` | Ruflo database path | | `CLAUDE_FLOW_MEMORY_PATH` | Ruflo home path | | `HELIX_URL` / `NUR_HELIX_URL` | Activate the HelixDB memory resident in `auto` mode and select its gateway | | `HELIX_API_KEY` | Optional HelixDB bearer token (or use the env-var name configured by `helix_memory.api_key_env`) | | `USE_BUILTIN_RIPGREP` | Set to `0` to use system ripgrep | --- ## Data home All NurCLI state lives under `~/.nur/` by default: ``` ~/.nur/ ├── auth.json # API key ├── config.toml # Configuration ├── permissions.toml # Optional allow/deny/ask rules ├── hooks.toml # Optional pre/post tool hooks ├── nur.log # Tracing (not painted into the TUI) ├── status.json # Live token/cost status ├── usage.jsonl # Per-request usage log ├── ade.json # ADE discovery manifest ├── memory.md # Cross-session memory journal (quick-memory #notes) ├── history.jsonl # Prompt history ├── sessions/ # Session files (UUID.json + .json.bak / .precompact.bak) ├── tool-results/ # Spilled oversized tool outputs ├── browser-extension/ # Staged tmwd_cdp_bridge for browser tool ├── skills/ # Installed skill packs ├── ruflo/ # Vector memory database └── skill-packs/ # Skill pack metadata ``` Override with `NUR_HOME`. --- ## Project instructions nur reads instruction files from every directory between the git root and the working directory, root first, each time a user turn starts: | File | Purpose | |------|---------| | `AGENTS.md` | Project instructions shared with other agents (`/init` creates or audits it) | | `CLAUDE.md` | Read in a directory that has no `AGENTS.md` | | `NUR.md` | nur-only layer, loaded after the `AGENTS.md` of the same directory | - **Budget.** `[instructions] max_chars` (default `48000`) covers the whole chain. Nothing is cut silently: what does not fit is stored as a context variable (or, when it looks like a credential, left in the file) and the prompt says where it continues. `/context` lists each file with its size and anything spilled. - **Imports.** A line that is exactly `@path` (outside a code fence) is replaced by that file, relative to the file that names it, five levels deep. Project files may import only inside their repository and user files only under your home directory; credential paths (`.ssh`, `.aws`, `.env`, `*.pem`, ...) and credential-shaped content are refused with a one-line notice. - **Nested directories.** A directory below the working directory with its own `AGENTS.md` is delivered once per session, appended to the result of the first tool that reads or edits a file there (`node_modules`, `vendor`, `target`, `.git` and `third_party` are skipped). The system prompt stays the same, so provider prompt caches hold. - Hidden Unicode (tag characters and bidi controls) is removed before any of it reaches a model, and `/context` names the file. ```toml [instructions] max_chars = 48000 ``` ### User instructions Standing rules that apply in every workspace go in the nur home: `~/.nur/NUR.md`, or `~/.nur/AGENTS.md` when there is no `NUR.md` (`NUR_HOME` relocates both). The file is loaded each turn, for subagents too, ahead of the project's instructions, so project rules can refine it. Use it for machine-wide constraints such as CPU limits for builds. It can import shared rules kept elsewhere under your home, e.g. a line `@~/.agents/AGENTS.md`. ## Inspecting the effective configuration Run `nur config --dump` to print the effective configuration as JSON with credential-bearing fields redacted.