Skip to content

GUIDE.md

Latest commit

 

History

History
1747 lines (1478 loc) · 102 KB

GUIDE.md

File metadata and controls

1747 lines (1478 loc) · 102 KB
Raw

Reasonix Guide

README  ·  简体中文  ·  Spec

Day-to-day configuration and usage. For the engineering contract and internals (data types, registries, package layout, roadmap), see the Spec.

Contents

Configuration

Resolution order: flag > ./reasonix.toml > the user config file > built-in defaults. Starting with Reasonix v1.8.1, the user config lives at ~/.reasonix/config.toml on macOS/Linux and %AppData%\reasonix\config.toml on Windows; see Configuration paths for migration and related data paths. Fields marked user/global only are not overridden by ./reasonix.toml. Provider entries name secrets with api_key_env, while the secret values live in Reasonix's global <Reasonix home>/.env, shared by CLI and desktop. Project .env, home .env, inherited shell environment variables, legacy credentials, and the OS keyring are not provider-key runtime fallbacks; legacy credentials are only migration sources. Project .env still feeds workspace-scoped, non-provider ${VAR} expansion for MCP/plugin settings without importing provider keys or Reasonix control variables. See Configuration paths for the full config.toml and .env structure.

For the desktop and CLI usage of visible reasoning language, see Reasoning language.

default_model = "deepseek-flash"   # executor; set [agent].planner_model to add a planner
# language    = "zh"               # ui language; empty = auto-detect from $LANG / $REASONIX_LANG

[ui]
# shortcut_layout = "desktop"      # classic|desktop; compatibility setting
# cursor_shape = "bar"             # block|underline|bar; CLI/TUI text cursor
show_turn_usage = false             # hide per-request token/cost receipts in the TUI; default true

[agent]
reasoning_language = "auto"      # visible reasoning text: auto|zh|en
# plan_mode_read_only_commands = ["gh issue view"]   # legacy compatibility only; Plan bash now uses Permissions
# planner_model = "deepseek-pro"      # optional low-frequency planner
# subagent_model = "deepseek-pro"     # optional default for runAs=subagent skills
# subagent_models = { review = "deepseek-pro", security_review = "deepseek-pro" }
# max_subagent_depth = 2              # nested delegation depth; set 1 for the old single-layer boundary
# max_subagent_concurrency = 6        # session-wide sub-agent concurrency (task/fleet/skills)
# max_parallel_writers = 3            # concurrent writers with non-overlapping write_paths
# compact_ratio = 0.85             # sole auto trigger; presets 0.70 / 0.80 / 0.85
# max_output_tokens = 0            # recommended: automatic (DeepSeek default high → ~64K; not unlimited)
# max_output_tokens = 32768        # ordinary coding / cost control
# max_output_tokens = 65536        # heavy reasoning / long tool loops
# max_output_tokens = 131072       # only after repeated finish_reason=length
# max_output_tokens never changes compact_ratio; only the final send-time clip does

[[providers]]
name        = "deepseek-flash"
kind        = "anthropic"
base_url    = "https://api.deepseek.com/anthropic"
model       = "deepseek-flash"
api_key_env = "DEEPSEEK_API_KEY"
web_search  = true
# also preset: deepseek-pro

[tools]
enabled = []   # omit/empty = all built-ins
bash_timeout_seconds = 120   # foreground safety cap; set 0 for no tool-local cap
protect_changed_files = true   # refuse a whole-file write over a change made since the agent last read or wrote the file
browser_tools = true   # built-in browser tools; the browser starts on first use
mcp_startup_timeout_seconds = 30   # background initialize + tools/list safety cap
mcp_call_timeout_seconds = 300   # default MCP call safety cap; per-plugin/tool overrides may raise it

[tools.system_one]
api_key_env = "TYPESAFE_API_KEY" # optional TypeSafe AI System One decision protocol
model = "jev-latest"
# base_url = "https://api.typesafe.ai"

[tools.system_one.laya]
local = false                      # true: run the official Python SDK locally (`pip install laya`)
python = "python"                  # interpreter containing the laya package
model = "auto"                     # auto|english|multilingual|typed-decisions
# http_base_url = "http://127.0.0.1:8080" # self-hosted POST /v1/systemone gateway
# http_api_key_env = "LAYA_API_KEY"       # optional gateway Bearer token

[environment]
enabled = true   # inject a stable startup summary of OS, shell, and common tools
offline = false  # set true when outbound network access is unavailable; prevents futile retries
# [environment.tools]
# go = "/opt/homebrew/bin/go"   # optional explicit trusted path; workspace-local paths are not auto-executed

[skills]
# paths = ["~/my-skills", "../shared/skills"]   # extra custom skill roots
# excluded_paths = ["~/.agents/skills"]         # hide convention roots without deleting folders
# disabled_skills = ["review"]                  # hide skills until /skill enable <name>
# suppress_warnings = true                      # quiet non-fatal skill loading warnings; doctor still reports issues

[permissions]
mode  = "ask"                                # writer fallback when no rule matches: ask|allow|deny
deny  = ["Bash(rm -rf*)", "Bash(git push*)"] # hard-blocked in every mode
allow = ["Bash(go test:*)"]                  # never prompted

[sandbox]
# workspace_root = ""          # file-writers confined here; empty = current dir
# allow_write    = ["/tmp"]    # extra dirs write_file/edit_file/multi_edit/move_file may touch
# forbid_read    = ["${HOME}/.ssh"]   # paths the agent must not read or list

[serve]
# auth_mode = "token"          # token (default)|password|none; none still requires the launch token for changes
# token = ""                   # optional fixed token; empty token mode generates one at startup
# password_hash = ""           # bcrypt hash generated with reasonix serve --hash-password --password '...'
# behind_proxy = false         # true only behind a trusted reverse proxy

[[plugins]]
name    = "example"
command = "reasonix-plugin-example"
startup_timeout_seconds = 60   # optional initialize + tools/list cap
call_timeout_seconds = 600   # optional per-server MCP call timeout
tool_timeout_seconds = { "generate_video" = 1800 }   # optional raw MCP tool names

For the full schema and every field's contract, see SPEC.md §5.

Installed and project-configured MCP servers need no per-tool trust list. The dedicated two-model Planner may use every non-destructive MCP tool, even when the server omits readOnlyHint; strict read-only sub-agents still require readOnlyHint: true and no destructiveHint.

[agent].plan_mode_read_only_commands is also retained for config round trips, but the main Plan workflow no longer has a separate bash allowlist or trust prompt. Bash classification and approval use the same Permissions rules in Plan and Standard mode; the Sandbox remains the filesystem, process, and network boundary. Dedicated planner and read-only subagent runners keep their own strict read-only tool registry and foreground-command classifier.

Environment variables

Most day-to-day settings belong in config.toml or the global Reasonix .env described above. The variables below are process-level advanced switches; set them before launching Reasonix. Project .env files are not a runtime source for Reasonix control variables.

To hand extra variables to every command the bash tool runs, set the user-global [tools.shell.env] table in config.toml (for example BASH_ENV). It is applied over the inherited environment; a project reasonix.toml cannot set it, so a cloned repository cannot inject variables into your commands.

A preset is not scoped to a command you asked for: BASH_ENV is sourced before every bash command, including the ones the host classifies as read-only and the ones it runs as verification.

So keep it side-effect free and outside the workspace's writable roots: anything it writes can invalidate what a verification just proved. The table reaches the local bash tool only — a remote workspace and reasonix review build their own sandbox and do not carry it.

CLI telemetry

The CLI can send a once-per-day anonymous active-install ping and bounded, content-free event counters to https://crash.reasonix.io. Configure the user-global policy with:

reasonix config telemetry          # print the effective mode
reasonix config telemetry auto     # default: local interactive TTY only
reasonix config telemetry on       # also allow local headless `reasonix run`
reasonix config telemetry off      # disable and delete pending counter files

On the first eligible release-build interactive session, Reasonix explains the exact data boundary and asks once before any telemetry request. The prompt is [Y/n]: pressing Enter, y, or yes stores auto; n or no stores off and deletes pending counters. After the choice is saved, enabled reporting is silent and the prompt is not shown again. If the preference cannot be saved, nothing is uploaded.

Reporting is always disabled in CI, development builds, and when DO_NOT_TRACK is set or REASONIX_TELEMETRY=0. Under auto, redirected/piped or otherwise non-interactive sessions do not report. When no choice has been saved yet, these ineligible sessions neither prompt nor report. Network failures after consent are silent and never change stdout, stderr, or the process exit code; unsent counters stay in a bounded local queue for a later invocation.

The ping contains a dedicated random 128-bit CLI install ID, CLI version, OS, architecture, and the cli surface marker. Counter batches use that same ID for daily active-install deduplication and contain only fixed buckets such as CLI mode/profile, permission/session mode, turn latency, finish reason, cache-hit range, generic Provider/tool error class, compaction, recovery counters, and normalized UI language. This ID is separate from the desktop install ID and is not an account, hardware, repository, or session identifier.

Reasonix never uploads prompts, answers, reasoning, tool names/arguments/output, paths, repositories/branches, session IDs, exact token or cost values, Provider/model names, base URLs, or environment variables.

CLI crash reports

An unhandled Go panic that reaches the CLI entrypoint is saved locally as a sanitized report under <Reasonix home>/cli-crash-reports. Reasonix keeps at most 10 files with owner-only permissions. The panic value is never serialized. Absolute source paths become <path>/<file>.go:<line>, function arguments are removed, and the same secret, token, email, and long-identifier scrubbers run both when saving and immediately before sending.

Crash reports are never uploaded automatically. Review and manage them with:

reasonix report                 # preview newest; prompt before sending on a TTY
reasonix report list            # list local reports
reasonix report show [ID]       # preview without sending
reasonix report send [ID]       # explicit send; delete locally only after success
reasonix report delete [ID]     # delete without sending

Piped or redirected reasonix report calls only preview and never prompt or send. The CLI telemetry setting does not auto-send or auto-delete these separately reviewed reports. Runtime fatal throws, operating-system kills, and panics in unwrapped background goroutines cannot be recovered by Go and do not produce this local report.

Web frontend

For local use, reasonix web starts the browser UI and opens it in your default browser. Inside an interactive CLI session, /web snapshots the current session, restores the terminal, and opens an explicit /sessions/<id>#token=... deep link. Even a never-used session keeps its reserved ID without forcing an empty transcript onto disk, so the first Web turn continues the same session identity.

cd your-project
reasonix web

Use reasonix web --no-open when you want to start the foreground Web server and print its URL without opening a browser tab. The lower-level reasonix serve command starts the same engine without opening a browser by default. It remains the right entry point for remote development boxes, supervisors, tunnels, reverse proxies, and shareable authenticated sessions.

reasonix web starts at 127.0.0.1:8787, automatically tries 8788, 8789, and so on when a port is busy (up to 100 retries), and defaults to a newly generated token even when [serve].auth_mode is none. Each live process registers a single-writer heartbeat file under <Reasonix home>/server/instances/; clean shutdown removes its own file, while later instances lazily remove records whose owner process is confirmed dead. Multiple Web instances can therefore share one Reasonix home without overwriting registry state. The process stays attached to the terminal; stop it with Ctrl-C.

reasonix serve also defaults to a freshly generated per-launch token unless [serve].auth_mode or --auth says otherwise.

  • --auth none (or auth_mode = "none") is an explicit opt-out for a Serve fronted by its own authentication. Reads are open to whoever reaches a loopback or bound address; other Host names get 421 serve.host_rejected.
  • Every state-changing request, approvals included, still needs the launch token: Authorization: Bearer <token>, or the cookie the printed approvals: link sets. Without it the answer is 403 auth.launch_token_required.
  • Serve writes the token to a 0600 file under <Reasonix home>/remote/ and prints only its path; append #token=<file contents> to the printed link. A managed launch with --token-file names that file instead. The phone QR code a terminal shows in token mode still carries the token.
  • Prefer --token-file over --token: argv is visible to other processes, sandboxed ones included. A plaintext [serve].token in the global config is readable from inside the sandbox; keep the secret in a file.
  • On macOS and Linux the OS sandbox denies the remote state directory and every token file. Windows has no bash sandbox, so there only the read tools refuse.
  • [serve] is read from the user config only; a project reasonix.toml cannot set it.

Choose the mode explicitly when binding outside loopback:

reasonix serve --auth token
reasonix serve --addr 0.0.0.0:8787 --auth token
reasonix serve --auth password --password 'temporary-password'

Token mode prints a share URL with #token=...; the Web page exchanges the fragment for an HttpOnly cookie before starting API or SSE requests, keeping the token out of request URLs, browser history, referrers, and access logs. Pass --token or set [serve].token to reuse a stable token. Password mode requires either --password at startup or a stored bcrypt hash:

reasonix serve --hash-password --password 'strong-password'

# <Reasonix home>/config.toml
[serve]
auth_mode = "password" # none|token|password
password_hash = "$2a$12$..."
behind_proxy = true    # only behind a trusted reverse proxy

The web UI exposes chat, tool approvals, session history, rewind/fork/summarize, model and reasoning-effort controls, Goal, a live todo panel fed by the todo_write tool, extension status/card/form/notification surfaces, and provider balance when configured. Extension-hosted providers appear in the model picker. Run /reload while idle to fail-atomically reload extension sidecars and the runtime generation without restarting Serve. Use --model, --max-steps, or --resume for one-off launches; otherwise serve uses the user-global default_model.

If the selected Provider has no saved API key, a loopback-bound Serve still starts and shows a Provider setup page instead of failing before the browser can connect. After authentication, enter the key there; Reasonix writes it to this host's global credential file with restricted permissions, rebuilds the active controller in the same process, and opens the normal UI. The credential-writing endpoint is disabled for non-loopback listeners. For a remote SSH window, "this host" means the remote host reached through the SSH tunnel; the key is not copied from the desktop machine.

Editor integrations over ACP

reasonix acp exposes Reasonix as an ACP v1 stdio agent for editors and other host clients. The dedicated ACP editor integration guide covers startup, capability negotiation, session lifecycle, independent model/work/ collaboration/approval controls, client filesystem and terminal capabilities, MCP servers, permission requests, and the Reasonix mid-turn steering extension.

Remote SSH

The remote module runs Reasonix on a remote host and reaches it over your own SSH connection — VS Code Remote-SSH style. It bootstraps a persistent headless reasonix serve on the remote host, forwards a local loopback port to it, and opens the existing serve web client through that tunnel. The agent, its tools, and its files all live on the remote host at full fidelity; nothing runs through a lossy file proxy.

Linux, macOS and Windows remote hosts are supported. A Windows host needs PowerShell and OpenSSH, whichever login shell (cmd, PowerShell or Git Bash) its DefaultShell names.

Hosts live in a user-global [remote] section of config.toml. Like [secrets], a project reasonix.toml cannot inject or override remote hosts — a cloned repo can never steer where Reasonix opens SSH connections. Credentials follow the provider idiom: the host names an env var (passphrase_env, password_env) whose value lives in Reasonix's global .env; key material itself is never stored — identity_file is a path.

[remote]
[[remote.hosts]]
name          = "gpu-box"
host          = "203.0.113.7"
user          = "dev"
identity_file = "~/.ssh/id_ed25519"
workspace     = "~/projects/app"
serve_install = "auto"            # Remote CLI: auto | npm | upload | never
provider      = "local"           # Model credentials: local (this machine, over the tunnel) | remote (that host's own)

[[remote.hosts.forwards]]
type   = "local"                  # local (-L) | remote (-R)
bind   = "127.0.0.1:5432"
target = "127.0.0.1:5432"

CLI:

reasonix remote add gpu-box dev@203.0.113.7 --workspace '~/projects/app'
reasonix remote import --all              # import aliases; ssh -G resolves Include/Match rules when connecting
reasonix remote test gpu-box              # dial + auth + host-key confirmation
reasonix remote connect gpu-box --open    # bootstrap serve, tunnel, open the URL
reasonix remote serve status gpu-box
reasonix remote fs ls gpu-box:'~/projects/app'

Hosts with use_ssh_config enabled resolve the final effective configuration through the local OpenSSH ssh -G, including Include, wildcard Host, Match (including Match exec), repeated IdentityFile, ProxyJump, and IdentitiesOnly. Import stores the original alias instead of a stale snapshot.

connect is a foreground supervisor (like ssh -N plus the serve bootstrap): it keeps the tunnel and configured forwards alive, auto-reconnects with exponential backoff if the link drops, and re-attaches forwards on reconnect. Ctrl-C disconnects the local side only — the remote serve keeps running, so the next connect reuses it. There is no background daemon in V1.

Host keys are verified against your OpenSSH ~/.ssh/known_hosts (read-only) plus a Reasonix-managed ~/.reasonix/remote/known_hosts. A first-seen key prompts for trust-on-first-use and is recorded in the managed file; a key that contradicts a recorded one is a hard error that names the offending line and is never auto-accepted.

Remote-side state lives under the remote host's ~/.reasonix/remote/: serve-<workspace-slug>.json (pid, bound loopback address, workspace), serve-<slug>.token (0600; the auth token, passed to serve via --token-file so it never appears in ps), serve-<slug>.broker (0600; the provider broker token, see below), and serve-<slug>.log.

Getting the kernel there

The remote runs a reasonix serve. The binary is a static Go build — no runtime, no Node, no glibc — so putting it there is a file transfer, not an install. serve_install = "auto" tries, in order:

  1. The remote fetches its own release. Reasonix reads SHA256SUMS here and hands that host the archive URL and the digest; the host downloads over its own connection and keeps the archive only if it matches. Nothing but the command crosses the SSH link, and a machine in a datacenter pulls the ~21MB archive far faster than a laptop can push it.
  2. Upload this machine's binary, when the platforms match.
  3. Download here and push over SFTP, for a host with no route to the release.
  4. npm, last. npm i -g reasonix installs the same static binary but needs Node ≥18 over there to do it; it stays because a network that mirrors npm while throttling GitHub is a real one.

Set serve_install to npm, upload or never to take exactly one route. reasonix remote test <name> reports which routes are open on a host before you connect, and names what closes each one that is not.

Model credentials

A remote session resolves its models on your machine by default. The connection carries a reverse (-R) forward back to a provider broker Reasonix runs on loopback here; the remote kernel calls that instead of a model endpoint, and the request is issued from this machine with this machine's key.

So a remote host needs no API key of its own and no egress to the model API — a locked-down build machine works. The key is never written to the remote disk: only a per-connection broker token is, and only as a 0600 file. The remote also never sees the endpoint, headers, or proxy settings behind a provider; it sees the same catalog you do and nothing else.

Set provider = "remote" on a host to leave it resolving providers from its own config instead, for a machine whose providers are deliberately not yours. reasonix remote serve start never uses a broker: that serve is meant to outlive the command that started it, and a broker published from a command that has exited is a port nobody holds.

Two costs are worth knowing. Model traffic now leaves through your own uplink rather than the remote's, which is a downgrade when the remote sits on a much fatter pipe. And the models available to a remote pane are the ones configured here, so a provider only that host had configured no longer appears unless you switch it to provider = "remote".

In the desktop app, manage hosts under Settings -> Remote SSH, then use the status-bar chip or the host row's Remote explorer button to browse and edit files over SFTP, manage port forwards, and start/open the remote workspace. Opening a workspace creates a separate native Reasonix window, similar to a VS Code Remote SSH window. The primary window owns the SSH tunnel; the remote window is an isolated, lightweight shell and does not restore or acquire local conversation sessions. The remote window uses this machine's providers through the broker described above, so opening a workspace on a host that has never held an API key just works. On a host set to provider = "remote" the old path applies: the window shows the authenticated setup page first, saves the key only in the remote Reasonix credential file, and activates the Provider without restarting the remote Serve process. A transient SSH outage keeps the remote window open; the desktop reconnects in the background, re-attaches its loopback forward, and reloads the window against the recovered Serve. An authentication or host-key failure is terminal and closes the unusable remote window instead.

Custom OpenAI-compatible providers

In the desktop app, open Settings -> Model -> Access -> Add model service -> Custom provider for proxies, aggregators, or self-hosted services that speak the OpenAI-compatible chat API or Anthropic-compatible Messages API.

For common providers, choose Add model service -> Recommended preset instead. New official DeepSeek entries use the Anthropic-compatible Messages endpoint by default and enable provider-side web_search; the same DEEPSEEK_API_KEY works for both protocols. On startup, Reasonix upgrades unmodified legacy deepseek-flash / deepseek-pro entries that still use the official endpoint and standard key/model settings. Customized official Chat Completions entries stay unchanged and show an Upgrade protocol action in Settings. Proxy endpoints, custom headers, model lists, and capability overrides are never migrated automatically. Existing separately named deepseek-anthropic entries remain compatible, but that redundant preset is no longer offered for new access. Reasonix can prefill editable custom-provider entries for Kimi CN, Kimi Global, Kimi Coding Plan, MiMo API, MiMo Anthropic, MiMo Token Plan CN/SGP/AMS and their Anthropic-compatible variants, MiniMax CN/Global API, MiniMax CN/Global Anthropic, GLM CN, Z.AI Global, GLM/Z.AI Coding Plan OpenAI-compatible and Anthropic-compatible endpoints, OpenCode Go, OpenCode Go Anthropic, OpenCode Go DeepSeek Anthropic, OpenCode Go DeepSeek Responses, OpenCode Zen Anthropic, Qwen/DashScope CN/Global, Qwen Coding Plan CN/Global OpenAI-compatible and Anthropic-compatible endpoints, StepFun OpenAI-compatible and Anthropic-compatible endpoints, NovitaAI, GMI Cloud, Vercel AI Gateway, HuggingFace Router, NVIDIA NIM, KiloCode, and Ollama Cloud. Plan names describe the access/payment route; they include CN/Global only when the provider exposes distinct regional endpoints. Kimi Coding Plan is therefore a dedicated plan endpoint, while Kimi direct API is split into CN and Global. The preset path usually needs only the provider API key: the key value is stored in Reasonix home .env, while config.toml stores the endpoint, model list, key environment-variable name, context window, vision model metadata, proxy bypass for China-only endpoints, MiniMax reasoning_split, GLM/MiniMax thinking heuristics, Anthropic-compatible Bearer auth where needed, Ollama Cloud max-effort support, and OpenCode Go per-model reasoning overrides. The dedicated OpenCode Go DeepSeek Anthropic and DeepSeek Responses presets expose the verified Flash routes and enable provider-side web_search by default; the Responses variant uses stateless context replay. The existing mixed OpenCode Go Anthropic preset remains scoped to Qwen and MiniMax so server tools are not sent to unverified models. DeepSeek Pro remains on the Chat Completions preset because live Anthropic and Responses requests currently fail in the OpenCode Go upstream conversion. The OpenCode Go preset includes its native kimi-k3 subscription route with image input, high/max reasoning effort, and a 1,048,576-token context window. Existing untouched OpenCode Go preset installs are upgraded automatically; edited model catalogs are preserved. The Kimi CN and Kimi Global direct-API presets also include kimi-k3 with image input, a 1,048,576-token context window, and the official low/high/max effort scale (default max). For the official K3 endpoints, Reasonix preserves complete assistant messages across turns, sends output limits as max_completion_tokens, and omits K3's fixed sampling parameters. Untouched legacy Kimi direct-API catalogs are upgraded automatically without changing the default model; custom catalogs and endpoints are preserved. After adding a preset, open its provider card if you need to change models, headers, endpoint, or compatibility settings.

Fill API address with the provider endpoint that should receive the standard chat path. In this mode Reasonix previews and sends chat requests to:

<API address>/chat/completions

Enable Full URL when the service gives you a complete request URL, for example https://gateway.example.com/v1/chat/completions. Reasonix then sends chat requests directly to that URL and does not append /chat/completions. The preview under the field shows the exact request URL that will be used.

Model discovery uses the API address to try likely model-list URLs such as /models and /v1/models. If the gateway requires a separate model-list endpoint, open Compatibility settings and set models_url, for example https://gateway.example.com/v1/models. If discovery is not available, fill the model list manually.

Full URL still uses the OpenAI-compatible chat request body. It does not switch the request schema to the OpenAI Responses API.

Compatibility settings

The Compatibility settings (usually leave unchanged) section is for gateways whose authentication, model-list endpoint, or reasoning/thinking request shape differs from the normal OpenAI-compatible defaults. Leave these fields at their defaults unless the provider documentation or a proxy error tells you otherwise. For Anthropic-compatible services, such as some coding-plan endpoints, choose Anthropic-compatible as the connection protocol before saving.

Field What it controls When to change it
api_key_env The environment-variable name used for this provider's API key. Desktop-saved key values are stored in Reasonix home .env under this name; the TOML config stores only the name. Change it when several providers need distinct keys, or leave it blank for a service that does not require an API key.
models_url The URL used only for model discovery. Chat requests still use the API address or Full URL above. Set it when /models or /v1/models is not where the gateway exposes its model list.
Extra request headers Static HTTP headers, one Header: value per line. Use for gateways such as OpenRouter that require HTTP-Referer, X-Title, or similar site headers. Keep bearer/API keys in the key field instead of duplicating them here.
Extra request body A JSON object merged into the top-level chat request body. Use only for provider-specific flags such as {"enable_thinking": true}. Reasonix still owns core fields such as model, messages, tools, stream, and thinking, and null values are rejected.
Authorization: Bearer For Anthropic-compatible providers, sends the saved API key as Authorization: Bearer <key> instead of x-api-key. Enable it only when the gateway documents Bearer auth, such as MiniMax Global or Vercel AI Gateway.
Model capability mode Which reasoning request protocol Reasonix should use for this provider. Keep Auto-detect unless the gateway is misdetected or the model docs require a specific reasoning format.
Thinking override Provider-specific override for thinking.type. Keep Auto unless the backend documents enabled, disabled, or adaptive. Unsupported values can make some OpenAI-compatible gateways reject the request.
Balance URL Optional endpoint for wallet/balance lookup. Set it when the provider exposes a balance endpoint and you want the desktop status bar to show it.
Context window The provider-wide token budget Reasonix uses for automatic context cleanup. 0 disables automatic compaction. Set it to the provider's model context limit; use a per-model override below when selected models differ.

Each selected model also has an optional Context window input. Leave it blank to inherit the provider-wide value, or enter a positive token count to override that value for this model. This avoids premature compaction for long-context models and provider errors for shorter-context models sharing the same endpoint. Use the context-window limit from the model documentation, not the maximum output tokens. For example, 128K commonly means 128000; if the provider documents 131072, use that exact value. Values below 16384 show a non-blocking warning because they can trigger frequent compaction and reduce cache hit rates.

Model capability mode options:

Option Effect
Auto-detect (recommended) Reasonix chooses the request shape from model capability metadata and endpoint detection.
DeepSeek thinking Uses DeepSeek-style thinking control, including thinking.type and DeepSeek-supported reasoning depth.
OpenAI reasoning Uses the standard OpenAI-compatible reasoning_effort levels.
Plain chat Sends no reasoning or thinking control fields. Use this for text-only proxies that reject reasoning parameters.

Thinking override options:

Option Effect
Auto (provider default) Does not write an explicit provider-level thinking override. Reasonix uses the provider/model default behavior.
Enabled Sends thinking.type = "enabled" for compatible providers.
Disabled Sends thinking.type = "disabled" for compatible providers. On DeepSeek-style providers this also avoids sending a reasoning depth hint.
Adaptive (self-adjusting) Sends or preserves thinking.type = "adaptive" only for providers that document adaptive thinking, such as MiniMax-M3-style endpoints.

Some OpenAI-compatible gateways require non-standard top-level request body fields. Add them with extra_body on the provider entry:

[[providers]]
name        = "spark"
kind        = "openai"
base_url    = "https://maas-coding-api.cn-huabei-1.xf-yun.com/v2"
models      = ["xopglm52"]
api_key_env = "SPARK_API_KEY"
extra_body  = { enable_thinking = true }

extra_body is merged into the chat JSON request body. Reasonix keeps core fields such as model, messages, tools, stream, and thinking under its own control.

Desktop hooks

Desktop hooks run local commands at lifecycle events such as SessionStart, UserPromptSubmit, PreToolUse, and PreCompact. A successful SessionStart hook may write plain text to stdout, or return JSON with hookSpecificOutput.additionalContext; Reasonix injects that text once into the next real user turn as <hook-context event="SessionStart">...</hook-context>. This is intended for plugin or workflow bootstrap context, including Superpowers-style startup instructions, without baking that workflow into Reasonix's system prompt.

Plugin packages can provide this startup context through hooks/session-start-codex or a plugin-root CLAUDE.md. Claude-style .claude/settings.json command hooks are also mapped to matching Reasonix hook events.

The injected hook context is dynamic current-turn context. It does not change the stable system prompt, memory prefix, or tool schema, though dynamic content can still reduce cache reuse for that turn.

Tool hooks (PreToolUse, PostToolUse, PermissionRequest), PostLLMCall and PreCompact fire in every agent a session runs. Each fires under a session_id derived from the parent session's id at the moment the hook runs:

Agent Hook session_id
Executor <session>
Planner <session>:planner
Guardian <session>:guardian
task, read_only_task, parallel_tasks, fleet, run_skill, read_only_skill children <session>:subagent:<call>
reasonix review a fresh id per run

/new or a branch switch moves every child to the new id along with the parent.

SubagentStart and SubagentStop:

  • bracket a foreground task call only; read_only_task, parallel_tasks, fleet, skill children and background tasks fire neither;
  • carry the call's id as callId, so a consumer can pair them;
  • SubagentStop fires on every end: answer, failure, cancel or refusal;
  • neither can block: exit 2 only warns.

Keyboard shortcuts

Shortcuts are documented by client because users usually look for the keys that work in the surface they are using. Desktop keeps its Plan toggle, while the CLI cycles Ask, Auto, and Plan with Shift+Tab. Desktop uses Cmd+Y on macOS or Ctrl+Y elsewhere for YOLO by default. If YOLO is rebound on Windows/Linux, Ctrl+Y becomes the standard composer redo fallback. Desktop paste stays on the platform paste key; in the CLI, terminal-native text paste and application-owned image paste use separate shortcuts.

[ui].shortcut_layout is still accepted for old configs, but the shortcut behavior below is unified across layouts.

For CLI/TUI text input, [ui].cursor_shape accepts underline, block, or bar. The default is bar: it remains easy to locate without covering double-width CJK characters in mixed-language input. Set it to block for a traditional terminal cursor or underline for a lower-profile cursor. This setting does not change desktop or web text fields.

Desktop GUI

Desktop shortcuts are managed from Settings → Shortcuts. Pick a configurable row, press a new key combination, and Reasonix saves it for the desktop app. Standard editing shortcuts such as Undo and Redo are shown as locked rows because the WebView's native text history uses those platform chords. Conflicting bindings are rejected so one shortcut never triggers two actions. Press ? or use the help button in the topic bar to open the shortcuts sheet; it is generated from the same shortcut registry, so it reflects any custom bindings.

Global shortcuts:

Key or control What it does Notes
Cmd+K on macOS, Ctrl+K on Windows/Linux Toggles the command palette The palette focuses search when it opens; Esc closes it.
Cmd+, on macOS, Ctrl+, on Windows/Linux Opens Settings Use Shortcuts in Settings to customize desktop bindings.
Cmd+W on macOS, Ctrl+W on Windows/Linux Closes the active top tab The last tab is kept by the normal close-tab guard.
Cmd+B / Ctrl+B Shows or hides the left sidebar Same action as clicking the sidebar toggle.
Cmd+Shift+B / Ctrl+Shift+B Expands or collapses the most recent shell output Same action as clicking the collapsed shell-output hint.
Cmd+1-Cmd+9 on macOS, Ctrl+1-Ctrl+9 elsewhere Jumps to the matching visible chat in the sidebar Hold Cmd/Ctrl briefly to reveal the numbered badges. Existing custom shortcuts that already use the same key take precedence.
Cmd++, Cmd+-, Cmd+0 on macOS; Ctrl++, Ctrl+-, Ctrl+0 elsewhere Increases, decreases, or resets text size = is accepted for the plus key on keyboards that report it that way.
? Opens the keyboard shortcuts sheet The sheet shows the current effective desktop bindings.

Composer shortcuts:

Key or control What it does Notes
Enter Sends the current message IME composition confirmation is left alone.
Shift+Enter Inserts a newline The composer keeps focus.
Shift+Tab Toggles Plan on/off Plan changes the workflow instruction; built-in writers keep the active Ask/Auto/YOLO and Sandbox boundary, while MCP writer/destructive targets stay hard-blocked for the whole planning phase.
Cmd+Z on macOS, Ctrl+Z on Windows/Linux Undoes the latest composer edit Native typing stays in the WebView history; Reasonix-managed paste, cut, folded blocks, and structured tokens are restored as complete transactions.
Cmd+Shift+Z on macOS, Ctrl+Shift+Z on Windows/Linux Redoes the latest composer edit On Windows/Linux, Ctrl+Y is also accepted after the YOLO shortcut has been rebound.
Cmd+Y / Ctrl+Y (default) Toggles YOLO on/off Turning YOLO off restores the previous Ask/Auto base when known. The current binding is shown in Settings → Shortcuts.
Cmd+V on macOS, Ctrl+V on Windows/Linux Pastes clipboard content Clipboard images are attached. Dropping into the composer takes any file or folder and references it where it lives — the desktop app copies nothing, so the turn works on that file itself. Only sources with no path to offer, the clipboard and the add-image button, store bytes in the workspace.
Plain Up / Down at the prompt boundary Recalls older or newer submitted prompts Modified arrows and native text navigation stay with the textarea.
Esc while a turn is running Cancels the running turn If the turn has not produced a response yet, the draft is restored.

Menus and controls:

Key or control What it does Notes
Up / Down in slash, @, or past-chat menus Moves the highlighted item Past-chat search uses the same navigation keys.
Enter / Tab in those menus Accepts the highlighted item Directory-like entries can keep the menu open for the next level.
Esc in those menus Closes the current menu or returns from past-chat search Regular typing continues after the menu closes.
Ask / Auto / YOLO approval controls Picks the tool approval posture directly Clicking these controls is unchanged by keyboard shortcuts.
Tool approval card Left / Right, Enter, 1-4, Esc Move the highlighted action, confirm it, pick a numbered action, or deny. The default highlighted action is Allow once.
Plan approval card Left / Right, Enter, 1-3, Esc Move between Revise plan, Start execution, and Exit plan. The default highlighted action is Start execution.
Plan control Toggles Plan on/off Same mode as Shift+Tab.
Goal item in the collaboration menu Starts, views, or clears Goal Goal is not in any keyboard cycle.

CLI / TUI

The composer uses theme-coloured top and bottom borders and a slim bar cursor by default. Long drafts grow to the available maximum height; once they overflow, wheel events inside the composer scroll the draft without moving the insertion cursor, while wheel events in the transcript keep scrolling the conversation. Use /theme auto|light|dark to select the background mode, or /theme <style> to select one of the named accent palettes shown by bare /theme.

The responsive footer keeps the active Ask/Auto/Plan or YOLO posture and current interaction state on the left. On wider terminals, model, effort, and work mode stay together on the right; a second row shows available Git identity, cache hit rate, context use, compaction headroom, jobs, and balance. ready is the idle composer state, not a model-health check. Pickers, approvals, image paste, shell mode, and other active interactions replace it. Narrow terminals move, wrap, or compact whole groups; labels and displayed work-mode values follow /language, while /work-mode command arguments remain the stable English identifiers.

Chat and transcript shortcuts:

Key or command What it does Notes
Enter Sends the current message While a turn is running, non-empty input is durably queued as a follow-up before the composer clears.
Ctrl+Enter or /steer <text> Adds guidance to the active turn The guidance is persisted first; if the turn cannot accept it, it remains a normal follow-up.
Shift+Enter, Alt+Enter, or Ctrl+J Inserts a newline Plain Enter is reserved for send/confirm.
Plain Up / Down while idle Recalls older or newer submitted prompts In a running turn, the same keys navigate queued follow-up feedback.
PageUp / PageDown Scrolls the transcript Works regardless of the current chat state.
Ctrl+Home / Ctrl+End Jumps to the top or bottom of the transcript Useful after long tool output.
Ctrl+L or /cls Clears only the visible transcript The LLM context, session file, tools, memory, and plugins stay loaded. Use /clear when you want to discard the conversation context.
Esc Backs out of the current action It un-sends a just-submitted turn before any reply, cancels a running turn, or clears non-empty input.
Double Esc on an empty idle composer Opens the rewind picker Same entry point as /rewind.
Transcript text selection Copies transcript text Releasing an in-app drag writes through the verified native clipboard path in a local session (pbcopy on macOS, the available Wayland/X11 tool on Linux, or the Windows clipboard). SSH falls back to OSC 52 and labels the fallback instead of claiming native success. Ctrl+C/Super+C/Meta+C or right-clicking the active selection copies it again.
Composer text selection Selects, copies, or replaces draft text Releasing an in-app drag copies the selection through the same verified clipboard path as transcript text. Typing or pasting replaces the selection; arrow keys collapse it.
Right-click with no active selection Pastes clipboard text locally In a local session with in-app mouse capture on, Reasonix reads text only and routes it through the normal bracketed-paste handling. Over SSH, use the terminal paste shortcut because the remote process cannot read the local clipboard; /mouse restores the terminal's native right-click menu. Right-click with an active selection still copies that selection.
/mouse Toggles in-app mouse capture Off hands the mouse back to your terminal, restoring its native click-drag selection and right-click context menu, at the cost of in-app drag-select, the transcript scrollbar, and wheel-scroll. Set REASONIX_DISABLE_MOUSE=1 to start every session with it off. Remote (SSH) sessions start with capture off so native selection works out of the box; REASONIX_DISABLE_MOUSE=0 forces capture on everywhere.
Ctrl+C Copies, cancels, clears, or quits Copies an active transcript or composer selection first. Otherwise it cancels a running turn, clears non-empty input, or quits on a second empty-composer press.
Ctrl+D Quits the TUI Immediate quit.
Your terminal's text-paste shortcut Pastes text Text stays on the terminal's bracketed-paste path (Cmd+V on macOS, commonly Ctrl+Shift+V on Linux, and the terminal's configured shortcut elsewhere). Reasonix consumes the resulting paste event and never probes for an image first.
Ctrl+V on macOS/Linux; Alt+V on Windows Pastes a clipboard image Image paste is a separate application action. The footer shows Pasting image… while the clipboard is read, then inserts an editable [image #N] token at the cursor.
/paste-image Pastes a clipboard image Command form of the same image-only action.
A line starting with ! Runs a shell command directly The command runs locally without asking the model.

/queue list shows bounded previews without loading full bodies. Use /queue show|edit|delete|move, /queue pause|resume, and /queue retry|refresh to inspect or manage pending work. After crash recovery the inbox is paused, so review it and run /queue resume before dispatch continues. Each item is limited to 4 MiB; a session accepts at most 64 items and 64 MiB total.

Mode and display shortcuts:

Key or command What it does Notes
Shift+Tab Cycles Ask → Auto → Plan → Ask YOLO remains outside this composer-mode cycle; the footer shows the active mode.
Ctrl+Y Toggles YOLO on/off Turning YOLO off restores the previous Ask/Auto base when known. Terminals that forward Command/Super may also send Cmd+Y, but Ctrl+Y is the reliable terminal shortcut.
--yolo, --dangerously-skip-permissions Starts chat in YOLO Same runtime mode as Ctrl+Y.
[ui].commandmode = "vi" Opts the composer into a vi command mode User/global only; a project reasonix.toml cannot set it, so a cloned repo never rebinds the user's keys. Esc enters command mode, a running turn or not; only Ctrl+C interrupts. Ctrl+C with a non-empty prompt clears it and leaves shell mode, in vi mode and out; in vi mode it first saves the trimmed draft to the prompt history, so Up recalls it. Unset or "" keeps the default, where Esc stops a running turn. The footer names the current input mode, NORMAL in command mode and INSERT otherwise.
`/preset [balanced delivery]` Shows or switches the current session's execution setting (执行设定)
`/theme [auto light dark
Ctrl+O Toggles verbose reasoning display Also available through /verbose.
Ctrl+B Expands or collapses long shell output Long shell-output hint lines can also be clicked in the transcript; text selection is handled in-app while the full-screen TUI has mouse reporting enabled.
/goal <objective>, /goal status, /goal pause, /goal resume, /goal clear Starts, checks, pauses, resumes, or clears Goal A Goal is unbounded unless [agent].goal_token_budget is set.
/migrate, /migrate --from <legacy-dir> Retries legacy migration or imports sessions from a chosen v0.x source Use --from for custom Windows v0.52 install/data directories; it imports sessions only. See Configuration paths.

Picker and approval shortcuts:

Context Keys What they do
Slash or @ completion Up / Down, Ctrl+P / Ctrl+N, Tab / Enter, Esc Move, accept, or close the completion menu.
Tool approval prompt y/1, a/2, p/3, n/4, Enter, Esc, Ctrl+C Allow once, allow for session, persist allow, deny, accept default allow once, deny, or cancel the turn.
Ask question card Up/Down or j/k, Left/Right or h/l, Space, Enter, 1-9, Esc, Ctrl+C Navigate answers/tabs, toggle multi-select answers, submit/activate, pick numbered options, dismiss, or cancel the turn.
Rewind picker Up/Down or j/k, Enter, b, c, d, f, s, u, Esc Choose a turn, apply both/conversation/code/fork/summarize actions, or go back/close.
Model, provider, or resume picker Up/Down or Ctrl+P/Ctrl+N; j/k while search is empty; type to filter; Enter; Esc Search, select an item, or close the picker. Once search input starts, j/k become query text. /provider opens that provider's model list.
MCP import picker Up/Down or j/k, Space, Enter, Esc / Ctrl+C Move, select servers, import selected servers, or cancel.
MCP manager Up/Down or j/k, Enter, Left/Right or h/l, r, number keys, q / Ctrl+C Navigate server lists/details, refresh, choose actions, or close.
/clear confirmation Arrow keys or j/k / Tab, Enter, y, n, Esc / Ctrl+C Toggle Clear/Cancel, confirm clear, or cancel.

Mode meanings:

Mode Meaning
Ask Prompts for fallback writer approvals.
Auto Auto-allows fallback approvals; explicit ask / deny rules still apply.
YOLO Skips ordinary tool approval prompts; deny, user ask questions, and plan approval prompts still wait.
Plan Directs the model to plan first — a plan-first workflow, not an all-tools read-only mode. Built-in writers still follow the active Ask/Auto/YOLO rules and Sandbox; installed MCP writers, destructive targets, and readers from unauthorized servers are hard-blocked for the whole planning phase (approval cannot release them; they return once Plan exits), and explicit phase-only tools such as complete_step wait until approval.
Goal Pursues a saved objective until complete, blocked, or cleared.

Permissions & sandbox

Permissions gate each tool call: deny > ask > allow > fallback. Bash and file mutation tools require approval by default; read-only tools generally do not. Approvals are stored and matched as permission rules, not button labels: for example Bash(npm run build), Bash(npm run test:*), and Edit(docs/**). reasonix can grant Bash as an exact command or as a conservative command prefix (for example Bash(go test:*)), while file-editing tools share session edit grants and persist path-scoped rules such as Edit(src/app.go). Parameter/arithmetic expansions, assignments, heredocs, file redirects, and globs cannot reuse a bare Bash, prefix, or glob allow; a user-approved reusable choice saves the whole command as Bash=<literal>. They still follow normal fallback, so Auto executes them without an extra prompt. Command/process substitution, a dynamic command name, eval, source, shell -c, inline runtime code, and unparseable forms require a human in interactive Ask/Auto. Headless Ask/Auto/DontAsk reject that nested/indirect class unless an exact literal exists; YOLO may bypass it. Advanced users can set [permissions] allow_dynamic_bash = true to let an Allow fallback, including Auto, cover that class; explicit ask and deny rules still take precedence. Because a headless run has no approval UI, the default Ask posture also fails closed on ordinary writer fallback and explicit ask rules. Use reasonix run --auto ..., -y, or --permission-mode auto when unattended automation should allow ordinary writer fallback; configured ask and deny rules always remain authoritative.

Ask is not read-only: after approval, a writer can still run. Permissions decide whether to allow or prompt; the Sandbox is the enforced capability boundary. The sandbox remains a second boundary after authorization; confinement cannot make ambiguous command parsing safe to authorize automatically.

Permissions are policy (which calls to allow / prompt). The sandbox is enforcement: the file-writers (write_file / edit_file / multi_edit / move_file) refuse any path outside [sandbox] workspace_root (default: the current dir, so edits stay in the project), resolving symlinks and .. so a link can't tunnel out. forbid_read optionally hides sensitive files or directories from the agent's read/list/search tools; use absolute paths or ${HOME} / ${VAR} references, not ~, because config expansion is environment-variable based. bash is itself jailed by default when an OS sandbox is available ([sandbox] bash, Seatbelt on macOS and bubblewrap on Linux): commands may write only those same roots plus platform-specific command temp/cache roots, cannot read configured forbid_read roots while the OS sandbox is active, and reach the network only when [sandbox] network is set. Reasonix always removes saved provider and bot credential variables from tool subprocess environments and automatically adds its global credential .env to the runtime read-deny boundary. Project .env files keep their existing workspace-scoped behavior.

Git metadata is host-protected. Inside the bash sandbox, the Git configuration and hooks of the workspace repository stay read-only, because the host's own git reads them.

The repository is the one git itself discovers from each writable root. A .git file is followed to the gitdir it names the way git resolves it, relative to the file with symlinks followed, so the protection lands on what git will read. Protected:

  • .git itself, the gitdir, the common dir and every symlink on the way to them: none can be removed, renamed or replaced by a symlink.
  • config, config.worktree, commondir and hooks/ of the gitdir and of the common dir.
  • config, config.worktree and commondir of each existing worktrees/* entry, and config and config.worktree of entries created later.
  • config, config.worktree, commondir and hooks/ of each submodule gitdir under modules/, existing or created later.

Everything else under .git (objects, refs, index, logs, lock files) stays writable, so add, commit, branch, checkout, merge, rebase, stash, tag and worktree creation keep working. These operations change:

Operation In the sandbox
git config without --global, git remote add / set-url, git branch -m, git submodule init, git submodule update --init, git sparse-checkout init, git maintenance register, git init in an existing repository Fails
Installing a hook into .git/hooks Fails
git worktree remove / prune of a linked worktree that existed before the command Fails; one added in the same command can be removed
Cloning a new submodule (git submodule add, git submodule update for one not yet cloned) Fails on macOS; on Linux the clone lands but its config entry does not
git branch --set-upstream-to, git checkout --track, git push -u Reports the refused write but exits 0; no upstream is recorded

To add or initialise submodules, run it outside the sandbox, in a terminal; updating submodules that are already cloned works inside it.

When a command's output names one of these paths, the bash result says so with sandbox.git_metadata_protected, also when git exited 0.

A protected file that already has another hard link refuses every confined command with sandbox.git_metadata_linked, because a write through the other name would reach it; the user removes that link outside the sandbox.

Limits:

  • On Linux, bubblewrap can only mount over paths that exist and cannot pin a symlink. Creating an absent commondir, config.worktree or hooks directory, or swapping a symlink on the gitdir: path, is not stopped there.
  • Closing that on Linux is the host's side: its own git has to pin its git and common directories instead of rediscovering them.
  • Existing worktree and submodule gitdirs get exact rules, up to 128 each on macOS and 512 on Linux.
  • On macOS, patterns cover the rest and gitdirs created later. They skip refs/ and logs/, so a branch or tag named config or hooks stays writable, but a new submodule named hooks is protected whole.
  • On macOS with more than 128 worktrees, git worktree add fails; past 128 submodules each command starts about 0.1 s slower.
  • On Linux, past 512 gitdirs the whole worktrees/ or modules/ directory is mounted read-only, and a command can cause that by planting HEAD files. A command can likewise plant a submodule gitdir with a hard-linked config, after which every confined command is refused until the user removes it.
  • A repository created by a sandboxed command is protected from the next command on.
  • A .git made unrecognisable to git (for example a corrupted HEAD) sends git's discovery further up.
  • A repository nested in the workspace that is not a submodule gitdir under modules/ is not protected, including one a command creates and records as a gitlink.
  • The host can run such a repository's configuration through its gitlink unless the host's own git excludes it.
  • Hooks that core.hooksPath points outside .git, and files include.path names, are ordinary workspace files.
  • Windows has no Bash sandbox, so none of this is enforced there.

Session-private temporary directory. Within one logical chat session, Bash commands share a private temporary directory so consecutive calls can exchange files through $TMPDIR (and, on Linux under bubblewrap, through literal /tmp). No user setup is required: Reasonix automatically exports TMPDIR, TMP, and TEMP for Bash and client-owned ACP terminals. The directory is created lazily, is never the host public temporary root, and is rotated on /new, /clear, resume of another session, and branch switches. Model/settings hot rebuilds keep the same directory. Temporary files are not durable storage: resume across process restarts does not restore them, and scripts that need long-lived data should write into the workspace or a user-specified path.

Reasonix-generated and project scripts should use the standard temporary environment variables rather than hard-coding /tmp; users should not set these variables themselves. For example:

tmp_file="${TMPDIR:?}/result.json"
$tmpFile = Join-Path $env:TEMP "result.json"
Platform $TMPDIR / $TMP / $TEMP Literal /tmp
Linux + bubblewrap Virtual /tmp (bound to the private dir) Shared for the session (not a fresh empty tmpfs each call)
macOS Seatbelt Host path of the private dir (allowed by policy) Host macOS temporary directory; scripts should use $TMPDIR
Windows (no OS Bash sandbox) Host path of the private dir Not promised to match (e.g. Git Bash /tmp)

Independent sandboxes such as MCP servers keep their own isolation and do not inherit the chat session's temporary directory. An approved sandbox-escape command still receives the private temp environment variables, but on Linux its literal /tmp is no longer mapped by bubblewrap.

Windows note: Reasonix does not ship an OS-level Bash sandbox on Windows. The effective mode is fixed to off; even an older config containing bash = "enforce" resolves to off, reasonix doctor flags the ignored value, and the desktop selector is read-only. Bash commands therefore run unconfined, while the dedicated file tools still enforce workspace_root, allow_write, and forbid_read in process. Saved credential variables are still removed from the child environment, but an approved unconfined shell runs as the user and is not a security boundary for other user-readable files.

When no OS sandbox backend is available, bash = "enforce" refuses bash execution instead of running unconfined. Install the platform sandbox backend (bubblewrap/bwrap on Linux, sandbox-exec on macOS) or set [sandbox] bash = "off" to explicitly restore the pre-1.16 unconfined shell behavior. On Windows the compatible value is always off.

For coding-quality reports, run reasonix doctor quality <branch-id-or-path> (add --json for structured output). This reads the selected session but emits only content-free counts and profile categories: model family, runtime profile, collaboration / approval modes, message and tool-call counts, verification and persisted compaction-summary counts, plus desktop token/cache telemetry when available. It omits transcript text, paths, session identifiers, tool arguments and output, endpoints, and custom model names, so the result is suitable for a public issue or Discussion. This differs from reasonix doctor session, whose support zip contains the complete unredacted transcript and must remain in a trusted support channel.

Capability diagnostics

Use this when a skill, slash command, hook, plugin package, MCP server, or AGENTS.md is missing, shadowed, disabled, or fails to start. Full flag reference, JSON schema, and issue codes: Capability diagnostics.

# Static (default): no network, no MCP child processes
reasonix doctor capabilities

# Machine-readable (stdout is pure JSON)
reasonix doctor capabilities --json

# Another workspace root
reasonix doctor capabilities --root /path/to/project

# Live MCP probe — only when you explicitly allow starting third-party servers
reasonix doctor capabilities --live --timeout 5s
Surface How
CLI reasonix doctor capabilities (above)
Desktop Settings → Diagnostics — refresh, copy redacted JSON, optional “include current session runtime” (reads the active tab Host only; does not start MCP)
Agent /reasonix-guide (built-in inline skill) or ask naturally; it prefers static doctor JSON before --live

Exit code 0 allows warnings/info; 1 means at least one error (or a live start failure); 2 is bad flags. This is separate from reasonix doctor (providers/sandbox) and reasonix plugin doctor <name> (one package).

Plugins (MCP)

Reasonix is an MCP client. A [[plugins]] entry's type selects the transport: stdio (default) launches a local subprocess (command/args/env); http (Streamable HTTP) connects to a remote url with optional static headers (${VAR} / ${VAR:-default} expanded from the environment, so tokens stay out of the file); sse connects to servers that still use the legacy persistent GET + announced POST endpoint transport.

${REASONIX_WORKSPACE_ROOT} (or ${CLAUDE_PROJECT_DIR}) expands to the current workspace's absolute path, so one global entry can name the project:

headers = { IJ_MCP_SERVER_PROJECT_PATH = "${REASONIX_WORKSPACE_ROOT}" }

For a remote HTTP server without a static Authorization header, an authentication challenge is shown as Sign in. Run reasonix mcp auth <name> in the CLI, or click Sign in for that server in the Desktop MCP panel. Reasonix performs OAuth metadata discovery, dynamic client registration, PKCE S256 authorization, and refresh-token rotation. Discovery and token requests use the same Reasonix network-proxy settings as the MCP connection.

OAuth client and token state is kept outside the workspace in the server's private Reasonix state directory, written with mode 0600, and bound to the full configured resource URL. An explicit static Authorization header always takes precedence. Clear authentication removes only Reasonix's local OAuth state; it does not sign out the third-party browser session. Reasonix opens the browser only after an explicit sign-in action, never automatically from a background tool-call failure. Removing the MCP server also removes its local OAuth state unless a lower-priority declaration for the same resource becomes effective.

Browse the official MCP Registry from Settings → MCP servers → Browse registry, or use reasonix mcp browse [query] and reasonix mcp install <registry-name>. Registry access is explicit and never runs during startup. Entries that need secrets or required arguments are shown as manual setup instead of being installed with an incomplete configuration; query-specific cached results remain available during a registry outage.

The normal setup path is intentionally one step. Use Desktop's Add and connect, /mcp add, or ask Reasonix to install a package or URL. These explicit installs are saved to the user-global config.toml and are also authorization: the server connects in the current session, and no second trust step appears now or on the next startup. Servers declared by the current project's reasonix.toml or .mcp.json remain in that project and are trusted without a separate launch confirmation. Explicit deny rules still win. The server's calls run directly, including tools that declare destructiveHint. The dedicated Planner still refuses destructive tools, and strict read-only sub-agents still expose only hinted non-destructive readers.

MCP names are resolved once per workspace. Project declarations override same-name global installs; inside a project, reasonix.toml overrides .mcp.json. Editing updates the effective declaration in its original file, and removing a higher-priority declaration reveals the next one instead of deleting every same-name entry.

stdio servers keep one process for initialize, reads, and writes, so stateful servers such as browsers retain sessions and open pages. Because an OS sandbox is fixed when a process starts, this shared process uses the server's normal process sandbox for every call; readOnlyHint and read-only sub-agent filtering are dispatch policy, not a second per-call process sandbox.

Tools surface to the model as mcp__<server>__<tool>. A tool declaring MCP's readOnlyHint: true joins parallel dispatch and the strict read-only tool surfaces. Installing a server or declaring it in project configuration authorizes the dedicated Planner to use all of its non-destructive tools without another per-tool setting; strict read-only research sub-agents receive only hinted non-destructive readers. Tools without the hint remain write-capable for scheduling and mutation accounting. While planning, built-in writers keep the ordinary permission posture. The dedicated Planner permits authorized non-destructive MCP (including opaque writers) but hard-blocks destructive or unauthorized targets; a single-model Plan without that dedicated Planner keeps the older writer/destructive block until Plan exits.

Installing an MCP server is the authorization decision. After installation, all of its tools run directly without a second server-level, per-tool, writer, or destructive approval setting. Explicit global deny rules still win. The host keeps readOnlyHint and destructiveHint internally for parallel scheduling, Plan restrictions, strict read-only sub-agents, and cached-to-live safety reclassification; these hints do not add user configuration. Reasonix deliberately trusts an installed server to describe those hints honestly. Planner/read-only filtering is therefore a workflow boundary for trusted servers, not containment against a malicious MCP server; explicit deny rules and the process sandbox remain host-controlled boundaries.

The retired trusted_read_only_tools, default_tools_approval_mode, tools.<raw>.approval_mode, and approvals_reviewer fields are ignored when loading older files and removed the next time Reasonix saves that MCP entry.

A server's prompts surface as /mcp__<server>__<prompt> slash commands (positional args after the command); its resources are pulled in by writing @<server>:<uri> in a message; /mcp lists connected servers and what each exposes. make build also produces bin/reasonix-plugin-example — a runnable reference stdio server (echo, wordcount, a review prompt, a style-guide resource) you can copy.

[[plugins]]                       # local stdio server
name    = "example"
command = "reasonix-plugin-example"
# startup_timeout_seconds = 60    # optional initialize + tools/list cap
# call_timeout_seconds = 600       # optional per-server MCP call timeout
# tool_timeout_seconds = { "generate_video" = 1800 }   # optional raw MCP tool names

[[plugins]]                       # remote server over Streamable HTTP
name    = "stripe"
type    = "http"
url     = "https://mcp.stripe.com"
headers = { Authorization = "Bearer ${STRIPE_KEY}" }

Enabled MCP servers start connecting automatically in the background after a session begins, so chat stays usable while tools come online. Use /mcp or the desktop MCP panel to refresh status, reconnect a server, inspect failures, or disable a server for the current session. For a read-only config/runtime health report across skills, hooks, packages, and MCP (without changing settings), see Capability diagnostics (reasonix doctor capabilities or Settings → Diagnostics).

An interactive caller waits only briefly for a cold server. If that wait ends, the shared startup continues in the background rather than being killed and restarted; retry the tool after it comes online. mcp_startup_timeout_seconds (default 30) bounds the full launch, authorization, initialize, and tools/list sequence. mcp_call_timeout_seconds applies only after the server is connected. Either value can be overridden per server.

Already have an .mcp.json? Drop it in the project root and Reasonix reads it as-is — the mcpServers spec (command/args/env, type/url/ headers, ${VAR} expansion) maps field-for-field onto [[plugins]]. Both sources are merged; on a name collision reasonix.toml wins.

{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"] },
    "stripe": { "type": "http", "url": "https://mcp.stripe.com", "headers": { "Authorization": "Bearer ${STRIPE_KEY}" } }
  }
}

Upgrading from 0.x? Your old ~/.reasonix/config.json is still read for its mcpServers (honouring mcpDisabled) as a lowest-priority source, so MCP servers keep working — move them into reasonix.toml's [[plugins]] or a .mcp.json when convenient.

Slash commands

In an interactive reasonix session, built-in commands (/compact, /context, /new, /clear, /rewind, /tree, /branch, /switch, /todo, /model, /work-mode, /mcp, /skills, /hooks, /memory, /goal, /output-style, /sandbox, /language, /reasoning-language, /help, /version) run locally — /help lists them all. Built-in skills such as /init, /explore, /test, and /reasonix-guide also appear in the slash menu and via run_skill (bodies load on demand; only the index line is cache-stable). Use /reasonix-guide when you need config or capability troubleshooting; it points at reasonix doctor capabilities (see Capability diagnostics). /new starts a new session while saving the previous transcript for history/resume; /clear asks for confirmation, then discards the current context without saving it. /tree shows saved conversation branches, /branch [name] branches from the current conversation tip, and /switch <id|name> loads another branch. Custom commands are Markdown files under .reasonix/commands/ (project) or ~/.reasonix/commands/ (user) — review.md becomes /review, a subdirectory namespaces it (git/commit.md → /git:commit). The body is a prompt template; invoking the command sends it as a turn.

Subagent profiles

Subagent profiles are manual Skills with runAs: subagent and invocation: manual. They are stored in the same project/global Skill roots as the desktop settings page, so profiles created on either surface are immediately available to the other after the session refreshes. In interactive chat, invoke one with /<name> <task>; Reasonix runs an isolated child loop and keeps only the task and final answer in the parent conversation.

The headless CLI provides explicit management and execution commands without changing the ordinary reasonix run task semantics:

reasonix subagent list
reasonix subagent create reviewer --description "Review changes" --prompt-file reviewer.md --tools read_file,grep,bash
reasonix subagent edit reviewer --effort high --model deepseek-pro
reasonix subagent try reviewer "review the current diff"   # always read-only
reasonix subagent run reviewer "review and fix the current diff"
reasonix subagent delete reviewer --yes

create defaults to project scope when a workspace is available and to global scope otherwise; pass --scope project|global to choose explicitly. edit changes only explicitly supplied fields, and an empty value such as --model= or --tools= clears that field. The profile editors deliberately refuse custom-path or richer hand-authored Skills so they cannot discard frontmatter, references, or scripts; manage those files through the Skills workflow instead. Built-in profiles have no editable file, so edit accepts only --model and --effort for them and stores the same per-name overrides as the desktop settings page.

See Subagent profiles for the complete CLI reference, Skill file format, model precedence, safety behavior, and troubleshooting.

Context Engine v2 separates two intentionally different layers:

  • Standing instructions come from hierarchical REASONIX.md, AGENTS.md, and CLAUDE.md files. Put rules here when they must be present on every relevant turn. User-global files load first, then workspace and deeper target directories; within one directory, .local.md variants win.
  • Background memory stores one durable fact per Markdown file. Each fact has an immutable ID, monotonic revision, timestamps, independent type (user, feedback, project, reference) and scope (project, global), plus freshness metadata. Facts may be stale, so they never outrank the current request or standing instructions.

Before a turn that changed files may finish, Reasonix asks whether a check ran after the last write. It recognises the common runners on its own — go test, pytest, npm test, make check, cargo test, tsc --noEmit and the like — but it deliberately cannot tell python deploy.py from python run_tests.py. A project that runs its checks through its own scripts needs no setup for this: the agent names which command was the check when it signs the step off (complete_step evidence with kind: verification and the command as run), and the host proves from its own receipts that the command ran after the write and passed. The agent decides only which of the commands it ran was the check; whether it ran, exited zero, and did so after the write are never its to claim.

When a command ran that the host could not read as a check, it says so as a warning and lets the turn end: the miss is its own blind spot, not evidence the work went unverified. A turn that changed files and ran nothing at all is a different case and still fails.

Declaring checks is the stronger, optional form. Name them in any standing-instruction file, under exactly this heading:

## Reasonix host checks

- verify: python -m pytest tests/
- verify: python scripts/screening.py --self-check

Every declared check must then have run since the latest write for the turn to end, and the built-in classifier stops having a say — the project has defined what verification means there. Entries are - verify: <command> (or * verify:); ordinary instructions elsewhere in the file stay guidance and never become gates.

The same section names the paths whose changes deserve the hardest review:

## Reasonix host checks

- sensitive: src/auth/**
- sensitive: infra/network.tf

A change under a declared path requires review plus security_review before the turn can end; everything else is scored by structure alone (an opaque write the host cannot name a path for, or ten or more paths at once). Sensitivity is declared rather than inferred, because a path's spelling cannot tell internal/auth from session_write_authority.go.

Reasonix automatically recalls a small set of relevant facts before each real user turn. It searches the raw user message, suppresses generic requests such as "continue", prefers project facts over equivalent global fallbacks, down-ranks stale facts, and appends at most four facts / 2,400 characters to the user turn. This dynamic suffix does not rewrite the cache-stable system prompt or tool schemas. Use /memory recall to see the selected IDs, scores, reasons, freshness, budget, and suppression decision.

New, bounded, non-sensitive project/reference facts can be created automatically with no setup or approval click. Global facts, user preferences, feedback, updates, duplicates, sensitive/oversized content, and every forget still require explicit confirmation. The storage layer makes the automatic grant create-only, so it cannot overwrite a fact that appears concurrently. A top-level headless controller may use the same one-shot low-risk create path; sub-agents and headless surfaces without the owning scoped controller fail closed.

forget archives rather than permanently deletes. Every update snapshots the previous revision; restore and archive recovery always create a higher revision instead of overwriting history:

/memory instructions
/memory recall
/memory revisions <id-or-name>
/memory restore <id-or-name> <revision>
/memory archived
/memory recover <archive-path>

The desktop Context Center shows the same provenance, conflicts, revision history, recall trace, and recovery actions. Opening its Suggestions tab scans recent local user turns automatically; candidates are deduplicated against both memory scopes and instruction bodies, but nothing is saved until the user accepts it. Remote workspaces never fall back to local desktop memory or sessions.

Legacy facts are upgraded in place with deterministic IDs and revision 1; missing scope is inferred from the containing directory. Migration is idempotent, old clients retain safe routing, and legacy Memory v5 transcripts remain readable. For the complete behavior and privacy/cache contract, see Context Engine v2.

---
description: Review the staged diff
argument-hint: [focus-area]
---
Review the staged diff. Focus on $ARGUMENTS, list bugs with file:line.

$ARGUMENTS expands to all space-separated args, $1…$N to positional ones. MCP prompts also appear here as /mcp__<server>__<prompt>.

Embedded documentation retrieval

Reasonix bundles the Markdown files from docs/ into each CLI and Desktop build. The read-only docs tool searches that exact offline corpus with local BM25 retrieval and can read a complete matching section with source provenance. The agent should use the tool before web search or assumptions when a question concerns Reasonix configuration, CLI/Desktop behavior, permissions, MCP, memory, recovery, providers, or maintainer workflows.

No setup, network connection, vector database, or embedding service is needed. Search results prefer the query language while retaining explicit en, zh-CN, audience, and catalog filters. Balanced and Delivery profiles expose the tool directly; Economy connects the docs source on demand. Every result reports the product version, immutable source revision, and corpus SHA-256 digest. The embedded manifest is bound to the candidate's docs/*.md and build identity, so an online page cannot silently replace version-matched local guidance.

Use /docs to inspect the bundled corpus identity and usage examples without calling a model. Use /docs <question> (for example, /docs how to configure an MCP server) to make Reasonix search the corpus locally first and then pass the matched sections to the currently configured AI for a sourced answer. This command path does not depend on the model deciding to call the docs tool, while ordinary natural-language questions may still use the tool automatically. Existing custom commands and compatible plugin or skill aliases keep ownership of /docs; when that happens, CLI and Desktop normally expose the built-in corpus as /reasonix:docs instead. If that qualified name is also already owned, Reasonix selects the next free reasonix:-qualified fallback without displacing it. A remote Desktop uses the host's resolved command catalog, so the displayed entry always matches what that host will execute.

Pull requests that change user-visible CLI, Desktop, configuration, provider, permission, or tool behavior must declare whether embedded documentation was updated. When no documentation change is needed, the declaration must explain why the existing version-matched guidance remains correct.

Goal

Goal is the unified runtime for long-running objectives. Reasonix keeps working until the goal is complete, blocked, paused, or cleared. Ordinary chat never changes collaboration mode implicitly; choose Goal in the composer or use /goal to start a long-running objective.

Goal has no default model-round, cross-Run turn, wall-clock, or numeric no-progress limit. It continues until completion, a genuine user/external blocker, manual stop/pause, an unrecoverable external error, or an explicit user-selected budget. To place an optional ceiling on an unattended loop, set:

[agent]
goal_token_budget = 20000000

The default is 0 (off). Reaching a positive token budget produces one summary and a resumable budget_spend pause. /goal resume grants a fresh configured slice while cumulative Goal statistics remain intact. Explicit positive max_steps, task time, and task cost budgets remain available as well. Progress is goal-scoped and novelty based: new read/search results, mutations, verification, todo/signoff changes, and reviews advance the goal; an exact tool/argument/result repeat does not. Cumulative turns, tokens, real provider requests, and active work time are tracked and shown as statistics; a token limit appears only when explicitly configured. A paused goal keeps its todos, Delivery checkpoint, and runtime history — use /goal resume to continue, or /goal pause to pause a running goal manually. /goal status shows turns, requests, tokens, and work time. Repeated host failures, zero-evidence rounds, and Todo stall thresholds inject a strategy redirect and reset their intervention epoch; they do not pause the Goal. At the end of every goal turn the model reports its disposition through the structured update_goal tool (continue/complete/blocked); when no report arrives, an independent bounded evaluator judges the turn once, and any evaluator failure pauses the goal instead of continuing silently.

For complex work, write the objective as a task contract: Context, Request, Output format, Constraints, and Pause policy. Goal mode treats those sections as the boundary for autonomous work. It keeps going with sensible defaults unless the next step requires an irreversible or externally visible operation, a scope change, or information only the user can provide.

Legacy simple/write/research classes are still inferred for sidecar and CLI compatibility, but they no longer select an execution quota. There is no separate research runtime to configure. Goal state stays in the normal session sidecar, progress comes only from novel host receipts, canonical todos, complete_step, review and the Delivery checkpoint, and completion is decided by Delivery readiness plus the bounded Goal evaluator. Legacy .reasonix/autoresearch/<task-id>/ archives are read-only: an explicit old path can be recovered as an ordinary Goal, but new runs never create or update those directories. Deprecated budget flags are accepted for compatibility but are hidden from help and completion.

@ references

Embed @ references in a message and Reasonix resolves them before sending, as tagged context blocks: @path/to/file (or @dir) injects a local file's contents (or a directory listing), and @<server>:<uri> injects an MCP resource. A local path is only treated as a reference when it actually exists, so ordinary @mentions stay literal. Typing / or @ opens an autocomplete menu — slash commands, or hierarchical file navigation (one directory level at a time, descend into folders) plus MCP resources.

Two-model collaboration

reasonix setup manages providers, model lists, credentials, connection tests, and the default model. It stages changes until Save and exit, and synchronizes provider access with the desktop app. See the CLI reference. Running two models together (executor + planner, separate cache-stable sessions) is a one-line edit afterwards — set planner_model to any other enabled provider:

[agent]
planner_model = "deepseek-pro"   # used as the low-frequency planner

The planner sees loaded REASONIX.md / AGENTS.md memory and a small read-only research tool set, so it can inspect relevant files before handing a plan to the executor. Writer and workflow tools remain executor-only.

Reasonix routes each turn deterministically without another classifier model: questions, short follow-ups, clear atomic edits, and bounded read-only actions go straight to the executor; bounded implementation work may receive a short light plan. Ambiguous, cross-surface, structured, high-risk, active-Goal, or Delivery work receives a full plan unless the request is clearly atomic or read-only. Explicit Plan Mode remains a separate host workflow and is never planned twice. An explicit plan first / 先规划 request forces planning, while just do it / 直接改 goes directly to the executor. Execution boundaries are recognized across the request, not only at its beginning, while quoted examples are ignored. Bare plan-first requests continue from the planner to the executor automatically. Requests that explicitly say to wait for confirmation pause at the host approval boundary and continue to the executor after approval. Only an explicit plan only / 不要执行 request ends the current turn with the plan persisted and no execution; a later user instruction can continue in the same session. The phase detail records a privacy-safe route, depth, and reason code for diagnosis without logging the user prompt.

Light plans contain a compact objective, at most four ordered steps, likely touchpoints, and the main verification. Full plans distinguish verified from candidate touchpoints and add relevant non-goals, risks, acceptance criteria, command-level verification, and rollback guidance when the operation is hard to reverse. These contracts are part of one stable planner system prompt; only the small per-turn depth instruction is appended to the user turn, preserving the planner's prefix cache after the one-time prompt upgrade. The host also gives light and full research different per-turn round budgets. If a planner still does not finalize after its bounded research and finalization round, ordinary plan-and-execute work continues with the executor using the original task. Plan-only and approval-gated requests remain fail-closed, and the incomplete planner turn is rolled back instead of leaving an unusable continuation tail.

Reasonix manages normal execution automatically: if an active todo produces no new completion, unique read, command, or mutation for 8 tool-call rounds, the host asks the executor to reassess. In Goal mode, the later threshold forces a smaller step, different tool/approach, focused delegation, or a real blocker report, then execution continues. Exact repeats do not count as progress; new host-observed work renews the lease. Two-level task lists keep the same single-current contract: the active level-1 sub-step is the one in_progress item while its level-0 phase stays pending; sub-steps are worked and signed off in order, and once every sub-step has completed the phase itself becomes in_progress for its own final sign-off.

Existing [agent].max_steps and planner_max_steps keys remain syntactically accepted during upgrades, but their values are ignored and removed with a one-time notice. This prevents a stale hidden limit from truncating automatic progress or inherited subagent work. Use the one-off CLI --max-steps flag when an explicit run budget is needed.

An ordinary chat task has no limit of any kind by default — not rounds, not tokens, not time, not money. It runs until the model finishes, an adaptive guard decides it stopped making progress, or you stop it.

One such guard is the perseveration guard (a model stuck echoing one block): it detects when the model emits the same short block of text or reasoning byte-for-byte.

Detection is on by default, but it only reports: a byte-identical block is sometimes legitimate output — printing a value 300 times, a run of identical table or log rows, a page of = or A — so nothing is cut and nothing reaches the model unless you opt in.

A detected loop is surfaced through the progress-watch channel as a perseveration notice, and the run goes on.

The notice is said once per loop episode: while the same loop keeps tripping the guard it stays quiet, and it is said again only after a block that does not trip the guard in between. The user's progress_watch.pause setting is what ends the run on a detected loop.

Cutting the stream and nudging a retry is opt-in with [progress_watch].perseveration_retries (a global default) or a per-provider perseveration_retries on a [[providers]] entry, which overrides the global value for that provider:

[progress_watch]
perseveration_retries = 0   # the default: report a detected loop, never cut

[[providers]]
name = "deepseek"
perseveration_retries = 1   # this provider also cuts and retries once

At 0 a detected loop is only reported, as above.

A positive value also cuts the stream, shows the user a [retrying (N) avoiding perseveration] interjection, appends a host-authored nudge through the mid-turn steer path, and retries up to that many times; once the budget is spent the run stops resumably with a perseveration pause.

Before retrying, it trims the loop from the turn back to the phrase and its last repetition, so the retry resubmits evidence of the loop rather than all of it. The trim reaches both the transcript and the stored turn, so the two never diverge.

Setting the key negative disables the guard entirely.

An optional spend gate is available when you want one. It bounds a whole task (every "continue" included, until you start unrelated work), and on crossing it the task produces one tool-free summary and pauses; the work is saved and the next message continues it.

[agent]
task_cost_budget = 5.0            # in the model's pricing currency
task_time_budget_minutes = 60     # wall clock across the whole task

Both are off unless set. In particular, task_time_budget_minutes = 0 (and legacy negative values) disables the time gate; only a positive value enables it. Neither has a default, because a stop is a judgement only you can make: no amount of money is portable across models — a budget loose enough for a cheap model would land a frontier model within a couple of answers — and a long task is as often the job you asked for as it is a runaway.

Cost applies only to a priced model. Without a price table that axis stays inactive rather than reading the task as free; use the time axis for a free or local model.

Rounds are deliberately not an axis. A turn that reaches a high round count without spending much is one whose rounds are individually cheap and fast, which is the case least worth interrupting. Use the one-off --max-steps flag when you specifically want a run bounded by rounds.

Subagent skills inherit the executor model by default. Set subagent_model to run them on another configured model, or use subagent_models to override only specific skills such as review or security_review.

Subagents may delegate one more layer by default: the root session is depth 0, first-layer subagents are depth 1, and the maximum max_subagent_depth = 2 means a depth-1 workflow can dispatch a depth-2 reviewer or implementer. Depth-2 subagents do not receive recursive agent/skill tools. Set agent.max_subagent_depth = 1 to restore the old single-layer boundary. This is intended for workflows such as Superpowers where a workflow skill may dispatch a reviewer subagent, while still avoiding unbounded recursion and background fanout.

Use read_only_task when planning needs isolated, deeper research without granting write-capable delegation. Use read_only_skill when the same need is best expressed through an existing skill. Both run ephemeral read-only subagents with only read-only research tools plus safe foreground bash, return only the final answer, and do not create resumable subagent transcripts. Read-only nested delegation may be available until max_subagent_depth is reached, but writer-capable task / run_skill remain unavailable inside these read-only child registries. Execution settings share one tool surface: call use_capability for read_only_skill and other optional tools. Subsequent writer calls still pass through Permissions/Sandbox.

Every strict read-only child is built through one shared construction pairing — RunReadOnlySubAgentWithSession / NewReadOnlyAgent — which marks the child permanently read-only and applies a final registry filter. The filter removes writers, destructive MCP targets, readers from unauthorized servers, and every host-mutating tool. User-installed and project-configured servers are authorized immediately. Eligible readers may still start on demand. These are the strict read-only entrances:

Entrance Purpose
read_only_task Isolated read-only research child from the main session
parallel_tasks (read-only) Concurrent read-only research children
fleet with read_only: true Parallel profile-aware batch (forced read-only per item)
read_only_skill The same isolation driving an existing skill
reasonix review (CLI) Read-only review of a diff or branch
Desktop preview/review subagents Read-only desktop analysis surfaces

reasonix review treats the checkout it reviews as untrusted input and runs only your own configuration:

  • The review skill is the built-in one, or one in your Reasonix home or home-directory skill folders. No project skill directory is read, so a <root>/.reasonix/skills/review never replaces it.
  • Tools and their sandbox, including [tools.search] engine and rg_path, come from <Reasonix home>/config.toml, never from the checkout's reasonix.toml.
  • Hooks are only the ones you configured under the Reasonix home: the global settings.json and installed plugins. Project hooks from the checkout (<root>/.reasonix/settings.json) never run, and the interpreter those hooks use comes from your own [tools.shell].
  • Review hooks start in the checkout root so they can inspect it, but a bare command such as python never resolves to an executable the checkout ships: the hook process runs with NoDefaultCurrentDirectoryInExePath=1, which stops cmd.exe on Windows from searching the current directory first.

The model and provider still resolve from the merged config, as in a session.

In persisted sessions, parallel_tasks and fleet return a bounded preview plus one Subagent reference per completed child instead of concatenating every full answer into a truncation-prone tool result. The parent can call read_subagent_result with that reference and page by offset_bytes; results are scoped to the current conversation lineage and workspace. Headless runs without a persisted parent session remain ephemeral and receive fair bounded previews, but cannot mint durable references.

The interactive two-model Planner uses a dedicated construction path (NewPlannerAgent): it still blocks bash, file writers, and ordinary writers, but may call authorized, non-destructive MCP through the fixed use_capability proxy without requiring readOnlyHint. Direct mcp__* schemas never enter the Planner tool list, so MCP install/connect churn does not change the Planner cache prefix after the one-time schema upgrade. Missing readOnlyHint no longer blocks the Planner; tools with destructiveHint are zero-exec and should be written into the plan for the Executor. In Balanced two-model sessions the Executor has its own frontend for the same stable proxy, so an auto_start=false or destructive capability discovered by the Planner remains callable by capability ID after handoff. Planner and Executor ledgers/audits stay isolated and only the Host connection is shared.

Ordinary task / fleet sub-agents also get the same fixed proxy (session- shared Host and connections, per-agent frontend/ledger) and may call installed or project-configured MCP without readOnlyHint. Those calls use the trusted MCP permission path (live authorization plus explicit deny only); writer and destructive calls are still serialized, recorded as mutations, and subject to Delivery evidence/lease guards rather than Planner handoff. Strict read_only_task / read_only_skill / review sub-agents share the stable proxy schema and connection reuse but keep the strict execution gate (authorized && readOnlyHint && !destructiveHint). Profile allowed-tools MCP names convert to capability-id allowlists on the proxy; children never inherit dynamic mcp__* schemas.

Inside a strict child, use_capability re-checks the resolved target before commit/permission/hooks/execution. An unconnected eligible MCP reader may start on demand from the current schema cache. Before tools/call, cached readOnlyHint/destructiveHint facts are checked against the live initialize/tools-list result; a reader-to-writer change or destructive promotion means zero executions and a normal retry through the current boundary. A schema-only change refreshes the cache for the next session without interrupting the authorized call. Runtime enablement, authorization, and the complete connection identity are checked again immediately before dispatch, so a same-name client from another project/tab cannot be reused accidentally. An unauthorized server cannot raise privileges there. This strict-child boundary is narrower than the dedicated Planner: the Planner accepts authorized opaque non-destructive MCP, while a strict child requires an explicit reader hint and never exposes writers at all.

Choose the startup execution setting with --preset balanced|delivery (for example, reasonix run --preset delivery "fix and verify this bug"). Legacy --profile economy|balanced|delivery still works (economy maps to light). All three execution settings share the same provider-visible core tool surface: direct read/bash/edit/write, background-shell lifecycle tools, ask/compress/recall when registered, and the stable use_capability proxy for optional tools (search, MCP, skills, subagents, docs, web_fetch, and so on). Calling use_capability never expands the top-level provider schema, so the prompt-cache tool prefix stays stable across execution settings.

What differs by execution setting is host policy (planning route, verification intensity, independent review floor), not the tool list:

  • Light — direct-first planning, targeted verification, independent review only on high-risk/security class work; optional capabilities stay on-demand.
  • Balanced (default) — auto light/full planning by risk, risk-tiered verification, conditional independent review on medium-risk multi-file work.
  • Delivery — full acceptance criteria, full verification, forced independent review on medium+ risk, and security review on high-risk work. Mutations and verification commands are blocked until a concrete acceptance list exists; a changed result cannot finalize until it has been reviewed, verified after the latest mutation, and signed off with complete_step.

Meta tools such as task, run_skill, and review are not counted as mutations by themselves — only real child writes are. Read-only analysis remains available without forcing a write.

Inside an interactive TUI session, use /preset to inspect the current choice or /preset balanced|delivery to switch it. /work-mode and /profile are compatibility aliases. The switch updates the execution setting in place without rebuilding the controller, preserves history, the session path, leases, and the Ask/Auto/YOLO posture, and is rejected while a turn, approval/question, background job, or another runtime switch is active. This command changes only the current session and does not persist a new global default. Because the provider-visible tool surface is unified, switching execution settings does not create a new tool-schema cache prefix.

Desktop tabs expose the same three choices (shown as Light / Balanced / Delivery) and dual-write agentPreset with legacy tokenMode (economy/full/delivery) for one compatibility version.

For interactive frontends, Plan Mode is always an explicit user choice. Select Plan in the desktop collaboration-mode control or cycle to Plan with Shift+Tab in the CLI. Reasonix first drafts a plan, then waits for approval before the workflow switches to implementation. Tool calls made while drafting still use the current Permissions and Sandbox. Legacy agent.auto_plan and agent.auto_plan_classifier values are ignored and removed from the user config during upgrade. The visible reasoning language can be changed with /reasoning-language auto|zh|en in the session, or reasonix config reasoning-language auto|zh|en in a shell/script. Pass --local to the reasoning-language shell command only when you intentionally want a project-local override.

The why behind separate sessions (keeping each model's prefix cache-stable) is in SPEC.md §3.5.