reasonix.example.toml

# Reasonix configuration.
# Resolution order: flag > ./reasonix.toml > <Reasonix home>/config.toml > built-in defaults.
# Fields marked user/global only are not overridden by ./reasonix.toml.
# Provider entries name secrets via api_key_env; saved key values live in
# Reasonix's global <Reasonix home>/.env. Never put API key values here.

default_model = "deepseek"   # a provider name (→ its default model) or "provider/model"
# language      = "zh"   # ui language; empty = auto-detect from $LANG / $REASONIX_LANG
# auto_submit   = true   # commit a multi-question ask once its last question is answered; user/global only

[ui]
theme = "auto"   # auto|dark|light; controls CLI colors only; REASONIX_THEME can override per run
# theme_style = "graphite"   # graphite|aurora|slate|carbon|nocturne|amber and legacy aliases
# shortcut_layout = "desktop"   # classic|desktop; compatibility setting; Shift+Tab toggles Plan, Ctrl+Y toggles YOLO
# cursor_shape = "bar"   # block|underline|bar; text input cursor shape; slim default avoids covering CJK characters
# commandmode = "vi"   # ""|vi; "vi" gives the CLI prompt a vi command mode (Esc enters command mode, ^C interrupts a stream, ^D exits)
show_turn_usage = true   # CLI/TUI: show per-request token and cost receipts in transcript scrollback

[cli]   # user/global only; ./reasonix.toml cannot override
# diff_fences = true   # render a fenced ```diff/```patch block through the colourised diff renderer instead of the plain code rail; default false
# diff_formatter = "delta --color-only --paging=never"   # optional external argv (no shell) that formats a fenced ```diff/```patch block, a writer tool's diff card, and a whole-diff shell result; the diff is piped on stdin and its stdout is re-emitted with non-SGR escapes stripped

[desktop]
# language = "auto"   # auto|en|zh; auto follows the browser/OS locale
# currency = "auto"   # legacy display currency; prefer [billing].display_currency
# theme = "auto"   # desktop only: auto|dark|light
# terminal_theme = "auto"   # integrated terminal: auto|dark|light; auto follows the desktop app
# theme_style = "graphite"   # graphite|aurora|slate|carbon|nocturne|amber and legacy aliases

[billing]
# display_currency = "auto"   # auto|CNY|USD — display only; never rewrites provider list prices
# Provider list prices use each provider's billing_currency (frozen from the
# official table or custom price). Switching display currency only re-selects
# occurrence-time valuations already recorded in the cost ledger.

[notifications]
enabled = false   # system notifications for CLI and desktop turns; default off
turn_done = true   # notify when a turn finishes
approval_request = true   # notify when a tool approval is waiting
ask_request = true   # notify when a question is waiting

# User config only: a project reasonix.toml cannot set this section. The notice
# above the composer is always on; only pausing changes what a run does.
# [progress_watch]
# pause = false         # end a run that stops producing observable effects; resumable, default off
# rounds = 20           # tool rounds without a file change, check moving, task step, new read or delegated result
# token_multiple = 8    # also when input spent since the last observable effect reaches this many context windows

# User config only. Archives conversations idle for `days`; reversible, and never touches
# pinned, running or mid-turn ones. Off by default.
# [auto_archive]
# enabled = false
# days = 30

[agent]
# system_prompt = "You are ..."   # custom persona/prompt; unset or empty = built-in default
# system_prompt_file = "prompts/system.md"   # project paths stay in <workspace>; user paths may fall back to <reasonix home>
temperature       = 0.0
# recovery_model = ""               # optional reviewer for low-risk automatic recovery; falls back to guardian_model then main model
# reasoning_language = "auto"   # visible reasoning text: auto|zh|en
# plan_mode_read_only_commands = ["gh issue view"]   # legacy compatibility only; Plan bash uses Permissions
compact_ratio       = 0.85  # sole auto trigger; presets 0.70 (active) / 0.80 (steady) / 0.85 (recommended default)
# planner_model = "deepseek-pro"   # optional: enable two-model collaboration
# subagent_model = "deepseek-pro"   # optional default for runAs=subagent skills
# subagent_models = { review = "deepseek-pro", security_review = "deepseek-pro" }   # per-skill overrides
# triage_model = "deepseek-flash"   # answers the host's small classifications (is this unrecognized
#                                   # shell command read-only?) when the static tables come up short.
#                                   # A few dozen tokens per call and the verdict is cached. Empty falls
#                                   # back to subagent_model, then the main model — set this to send the
#                                   # classifications somewhere cheaper than the model doing the work.
# max_subagent_concurrency = 6   # session-wide sub-agent concurrency (task/fleet/skills)
# max_parallel_writers = 3       # concurrent writers with non-overlapping write_paths
# output_style = "explanatory"   # persona/tone folded into the prompt: explanatory | learning | concise,
#                                  or a custom .reasonix/output-styles/<name>.md ; empty = default
# [agent.persona]                  # the agent's identity, as opposed to output_style's tone.
#                                  # prefix leads the system prompt, suffix follows the built-in guidance;
#                                  # include_runtime_context = false drops the probed environment section and
#                                  # the offline note. User-level only; applies on the next session build.
# prefix = "You are the staff engineer who owns this change end to end."
# suffix = "Close with the risk you did not verify."
# include_runtime_context = true
# embedded_diff_detection = true   # mark a shell result whose whole output is a unified diff (e.g. `git diff`)
#                                  so the transcript renders it as a diff instead of flat text; default false

# A provider is a vendor endpoint (one base_url + key) that offers one or more
# models. Use `models = [...]` to expose several under a single entry — switching
# models reuses the same connection; no need to re-declare base_url/api_key.
# In the desktop app, Settings -> Model -> Access -> Add provider includes
# recommended editable presets for Kimi CN/Global, Kimi Coding Plan, MiMo API
# and Anthropic/token-plan regions, MiniMax CN/Global API and Anthropic routes,
# GLM/Z.AI CN/Global API and coding-plan routes, OpenCode Go/Zen, Qwen/DashScope
# CN/Global API and coding-plan routes, Token Rhythm (基元律动), StepFun,
# NovitaAI, GMI, Vercel AI Gateway, HuggingFace, NVIDIA, KiloCode, and Ollama Cloud.
[[providers]]
name        = "deepseek"
kind        = "openai"
base_url    = "https://api.deepseek.com"
models      = ["deepseek-flash", "deepseek-v4-pro"]
default     = "deepseek-flash"   # optional; defaults to the first of `models`
# deepseek-flash reads images; deepseek-v4-pro takes them and answers as if it
# saw nothing, so listing it here would drop pictures silently.
vision_models = ["deepseek-flash"]
api_key_env = "DEEPSEEK_API_KEY"
context_window = 1000000
# Per-turn total output budget (does not change compact_ratio):
# max_output_tokens = 0       # recommended: automatic (DeepSeek default high → ~64K)
# 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
# Stream idle watchdog for this provider: how long a call may send nothing —
# before response headers or between stream events — before it is read as
# dropped. Per-provider only; there is no global setting. Default 300s; accepts
# 1–32767 (0 or unset keeps the default). A silent pre-header wait (prefill) is
# retried once, so the transport can hold for up to twice this value before the
# call finally fails.
# idle_timeout_seconds = 300
# Optional per-model context budgets. Omitted models inherit context_window.
# model_overrides = { "deepseek-flash" = { context_window = 1000000 } }
# Official list prices are frozen per provider (billing_currency). Display
# currency ([billing].display_currency) never rewrites these tables.
# billing_currency = "USD"   # frozen list-price currency: CNY|USD
# billing_mode = "payg"      # payg | subscription_equivalent (e.g. MiMo Token Plan)
# Set prices explicitly only when you want to pin custom rates (always protected).
# prices = { "deepseek-flash" = { cache_hit = 0.02, input = 1, output = 2, currency = "¥" }, "deepseek-v4-pro" = { cache_hit = 0.025, input = 3, output = 6, currency = "¥" } }   # per 1M tokens
# DeepSeek thinking is always on; effort: high | max. Omit for auto (provider default).
effort      = "high"

# A single-model provider still works (use `model = "..."`) — pick this form when
# a model needs its own base_url. Use model_overrides when models share an endpoint
# but need distinct context windows or capability settings.

# Custom /effort levels for a provider. When supported_efforts is set, the
# /effort command exposes these levels; default_effort is what "/effort auto"
# (or unset) resolves to. Leave both commented to keep the built-in defaults
# (DeepSeek models: high|max; Anthropic: low|medium|high|xhigh|max). DeepSeek
# models behind a proxy are detected by model name; set reasoning_protocol =
# "none" to disable that or "openai" to force ordinary reasoning_effort.
# Other OpenAI-compatible providers don't expose /effort unless you opt in here.
#
# [[providers]]
# name           = "openai-compatible-custom"
# kind           = "openai"
# base_url       = "https://api.example.com/v1"
# model          = "example-reasoning-model"
# api_key_env    = "EXAMPLE_API_KEY"
# reasoning_protocol = "openai"   # auto|deepseek|openai|none
# supported_efforts = ["low", "medium", "high"]
# default_effort    = "high"

# Anthropic (Claude) — the "anthropic" kind speaks the Messages API directly (no
# OpenAI shim). base_url is optional (defaults to https://api.anthropic.com). Note:
# this provider does not enable extended thinking and does not send temperature —
# current Claude models reject sampling params (see internal/model/anthropic).
# Some Anthropic-compatible gateways use Bearer auth instead of x-api-key; set
# auth_header = true for those (for example MiniMax Global or Vercel AI Gateway).
[[providers]]
name           = "claude"
kind           = "anthropic"
model          = "claude-opus-4-8"
api_key_env    = "ANTHROPIC_API_KEY"
context_window = 1000000
price          = { cache_hit = 0.5, input = 5, output = 25, currency = "$" }   # per 1M tokens
# Extended thinking (anthropic kind only; round-trips the signed reasoning block
# across tool calls). Omit to disable. effort: low | medium | high | xhigh | max.
thinking       = "adaptive"
effort         = "high"

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

[tools]
enabled = []   # empty = all built-in tools
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_resources = true  # user file only; a read_mcp_resource tool for resources a connected MCP server lists; asks first; default off
mcp_startup_timeout_seconds = 30   # background initialize + tools/list safety cap; per-server overrides may raise it
mcp_call_timeout_seconds = 300   # default MCP call safety cap; per-plugin/tool overrides may raise it

[tools.background_jobs]
stalled_warning_seconds = 900   # warn once per background job after this many quiet seconds; 0 disables

# Sandbox confinement bounds the blast radius of tool calls. Writers may only
# modify workspace_root (empty = current directory) plus allow_write. forbid_read
# hides sensitive directories from read/list/search tools and from sandboxed bash
# while OS-level sandboxing is active. Use absolute paths or ${HOME}; "~" is not
# expanded in config values.
# [sandbox]
# workspace_root = ""
# allow_write    = ["/tmp"]
# forbid_read    = ["${HOME}/.ssh"]
# bash           = "enforce"   # enforce (default on macOS/Linux) | off; Windows fixes this to off because it has no OS-level Bash sandbox
# network        = true

# Skills are invokable playbooks (SKILL.md / <name>.md with frontmatter), found
# under .reasonix/skills, .agents/skills, .agent/skills, .claude/skills (project)
# and the same dirs under ~ (global). Built-ins (explore/research/review/security-review/test)
# ship out of the box. The model invokes them via run_skill / explore / …; you
# invoke them via /<name>. Manage with /skill (list, show, enable, disable, new, paths).
# [skills]
# paths = ["~/my-skills", "../shared/skills"]   # extra "custom"-scope skill roots
# excluded_paths = ["~/.agents/skills"]         # hide convention roots without deleting folders
# disable_implicit_invocation = true             # keep /skill explicit; hide skill discovery and tools from the model
# disabled_skills = ["review"]                  # hide from prompt, slash invocation, and skill tools
# suppress_warnings = true                       # quiet non-fatal skill loading warnings; doctor still reports issues

# Hooks run shell commands around the loop (PreToolUse / PostToolUse /
# PermissionRequest / UserPromptSubmit / Stop). They are NOT configured here — put them in
# settings.json: <Reasonix home>/settings.json (global, always on) and
# <project>/.reasonix/settings.json (project, loaded automatically).
# Exit 0 = pass, exit 2 = block (PreToolUse / UserPromptSubmit only). Example
# <Reasonix home>/settings.json:
#   { "hooks": {
#       "PreToolUse":  [ { "match": "bash", "command": "my-guard.sh" } ],
#       "PermissionRequest": [ { "match": "bash", "command": "notify-send 'approval needed'" } ],
#       "PostToolUse": [ { "match": ".*file", "command": "gofmt -w ." } ],
#       "Stop":        [ { "command": "notify-send 'turn done'" } ] } }

# A custom status line: a command whose first stdout line replaces the built-in
# data row. It receives {"model","contextUsed","contextWindow","cwd"} as JSON on stdin.
# user/global only: set it in <Reasonix home>/config.toml; ./reasonix.toml cannot.
# [statusline]
# command = "my-statusline.sh"

# External stdio plugins (MCP-compatible); each is a standalone executable.
# [[plugins]]
# name    = "example"
# command = "reasonix-plugin-example"
# # Startup may continue in the background after the first caller stops waiting.
# # startup_timeout_seconds = 60
# # Per-server MCP call timeout; 0 keeps the global/default cap.
# # call_timeout_seconds = 600
# # Raw MCP tool names with per-tool call timeouts.
# # tool_timeout_seconds = { "generate_video" = 1800 }
# # Hide exact raw MCP tool names from the model, catalog, and tool counts.
# # disabled_tools = ["write_file", "delete_file"]
# # Enabled MCP servers connect automatically in the background after session
# # start. Use /mcp or the desktop MCP panel to refresh, reconnect, or disable.

[serve]
# Authentication for the HTTP serve frontend (reasonix serve).
# auth_mode = "token"     # token (default) | password | none (changes and approvals still need the launch token)
# token      = ""          # pre-shared token for auth_mode = "token" (auto-generated if empty)
# password_hash = ""       # bcrypt hash for auth_mode = "password". Generate with: reasonix serve --hash-password <password>
# behind_proxy = false      # set true when behind a trusted reverse proxy (nginx, Caddy, etc.) that sets X-Forwarded-* headers