| 1 | # Reasonix CLI Reference |
| 2 | |
| 3 | <a href="../README.md">README</a> |
| 4 | · |
| 5 | <a href="./CLI.zh-CN.md">简体中文</a> |
| 6 | · |
| 7 | <a href="./GUIDE.md">Guide</a> |
| 8 | |
| 9 | This reference covers interactive sessions, one-shot automation, session |
| 10 | resume, permission flags, and the most useful in-session commands. For provider |
| 11 | configuration, plugins, and sandbox policy, see the [Guide](./GUIDE.md). |
| 12 | |
| 13 | ## Start a session |
| 14 | |
| 15 | ```sh |
| 16 | reasonix |
| 17 | reasonix --model deepseek-pro |
| 18 | reasonix --profile delivery --effort high |
| 19 | reasonix --dir /path/to/project |
| 20 | ``` |
| 21 | |
| 22 | Running `reasonix` without a subcommand starts the interactive terminal UI. Use |
| 23 | `reasonix setup` first when no provider is configured. |
| 24 | |
| 25 | | Flag | Purpose | |
| 26 | | --- | --- | |
| 27 | | `--model NAME` | Select a configured provider or `provider/model` reference. | |
| 28 | | `--profile economy\|balanced\|delivery` | Select the runtime work profile. | |
| 29 | | `--effort LEVEL` | Override reasoning effort for this session. | |
| 30 | | `--max-steps N` | Set a one-off maximum tool-call round budget; `0` uses automatic execution. | |
| 31 | | `--dir PATH` | Change the workspace root before loading config and tools. | |
| 32 | | `--add-dir PATH` | Add another writable tool directory; repeat for multiple directories. | |
| 33 | | `-c`, `--continue` | Resume the most recent session. | |
| 34 | | `-r`, `--resume [QUERY]` | Open the session picker, or resume a matching session. | |
| 35 | | `--copy` | Continue in a writable copy of the resumed session. | |
| 36 | | `--allowed-tools RULES` | Add session-only permission allow rules. Repeatable; `--allowedTools` is an alias. | |
| 37 | | `--permission-mode MODE` | Start with a specific permission posture. | |
| 38 | | `--yolo` | Start in YOLO mode; alias for `--dangerously-skip-permissions`. | |
| 39 | |
| 40 | Flags may appear before or after the prompt where applicable. |
| 41 | |
| 42 | ## Update the native CLI |
| 43 | |
| 44 | ```sh |
| 45 | reasonix upgrade # install the latest official release |
| 46 | reasonix upgrade --check # report the target without installing |
| 47 | reasonix upgrade --force # reinstall the current official release |
| 48 | ``` |
| 49 | |
| 50 | The updater selects only strict `vX.Y.Z` non-prerelease GitHub Releases. During |
| 51 | the 1.x compatibility period, old channel arguments and `--channel` are still |
| 52 | accepted, but resolve to the same official release and print a deprecation |
| 53 | notice. Legacy `[cli].update_channel` values are ignored and removed the next |
| 54 | time Reasonix saves the configuration. The `reasonix update` alias behaves the |
| 55 | same way. |
| 56 | |
| 57 | ## Configure providers |
| 58 | |
| 59 | ```sh |
| 60 | reasonix setup # manage the user-global config |
| 61 | reasonix setup --local # manage ./reasonix.toml |
| 62 | reasonix setup /path/to/config.toml |
| 63 | ``` |
| 64 | |
| 65 | In an interactive terminal, `reasonix setup` is a staged provider manager. It |
| 66 | lists configured providers and lets you: |
| 67 | |
| 68 | - add OpenAI-compatible or Anthropic-compatible providers; |
| 69 | - edit endpoints and model lists; |
| 70 | - update API keys or test the connection and refresh models; |
| 71 | - choose the default model; and |
| 72 | - remove providers. |
| 73 | |
| 74 | Choose **Save and exit** to review and confirm the pending operations. Canceling |
| 75 | discards them. Setup reloads the latest config while saving: unrelated desktop |
| 76 | or CLI changes are retained, while an overlapping change is reported as a |
| 77 | conflict instead of being overwritten. |
| 78 | |
| 79 | Provider definitions contain only the `api_key_env` variable name. Key values |
| 80 | are stored in the shared Reasonix home `.env`, even with `--local`. When a |
| 81 | variable name is already used by another provider, setup asks whether to share |
| 82 | that credential; choose a different variable name when the providers use |
| 83 | different keys. Providers added or removed through setup are also added to or |
| 84 | removed from desktop provider access, so the same models are available in the |
| 85 | desktop app. |
| 86 | |
| 87 | ### Configure regional pricing currency |
| 88 | |
| 89 | Use the user-global currency command to inspect or select the official DeepSeek |
| 90 | regional price table: |
| 91 | |
| 92 | ```sh |
| 93 | reasonix config currency # show the saved and resolved currency |
| 94 | reasonix config currency auto # follow the resolved locale |
| 95 | reasonix config currency CNY |
| 96 | reasonix config currency USD |
| 97 | ``` |
| 98 | |
| 99 | `auto` resolves Simplified or Traditional Chinese locales to CNY and English or |
| 100 | other locales to USD. An explicit `CNY` or `USD` selection remains independent |
| 101 | from the UI language. This preference is stored in the user config and cannot |
| 102 | be overridden by project `reasonix.toml`; `--local` is therefore not supported. |
| 103 | Custom provider prices are preserved. |
| 104 | |
| 105 | In an interactive session, `/currency` shows the saved and resolved values, and |
| 106 | `/currency auto|CNY|USD` changes the preference and refreshes the current |
| 107 | runtime without discarding the conversation. |
| 108 | |
| 109 | ### Configure automatic compaction |
| 110 | |
| 111 | The desktop app and CLI share the user-global automatic compaction threshold. |
| 112 | Inspect the effective percentage and its source, set the global default, or add |
| 113 | a project override: |
| 114 | |
| 115 | ```sh |
| 116 | reasonix config compact-ratio # show effective value and source |
| 117 | reasonix config compact-ratio 75 # set the user-global default |
| 118 | reasonix config compact-ratio --local 75 # override in ./reasonix.toml |
| 119 | ``` |
| 120 | |
| 121 | The editable range is 65–85%, with 80% as the built-in default. Lower values |
| 122 | compact earlier and may reduce prompt-prefix cache reuse; higher values retain |
| 123 | more context before compaction. Project `reasonix.toml` takes precedence over |
| 124 | the user config. Changes apply to new CLI sessions; an already-running session |
| 125 | keeps the threshold it loaded at startup. |
| 126 | |
| 127 | ## One-shot and automation |
| 128 | |
| 129 | Use `-p` / `--print` when a script needs only the final answer: |
| 130 | |
| 131 | ```sh |
| 132 | reasonix -p "summarize this repository" |
| 133 | reasonix -p "summarize this repository" --output-format json |
| 134 | reasonix run "implement the TODOs in main.go" |
| 135 | reasonix run --auto "implement the TODOs in main.go" |
| 136 | echo "explain this code" | reasonix run |
| 137 | ``` |
| 138 | |
| 139 | `reasonix run` keeps the normal streamed terminal presentation unless `-p` or a |
| 140 | structured output format is selected. It also accepts `--model`, `--profile`, |
| 141 | `--max-steps`, `--effort`, `--dir`, `--add-dir`, `--continue`, `--resume QUERY`, |
| 142 | `--copy`, `--allowed-tools`, `--permission-mode`, and `--auto` / `-y` (an alias |
| 143 | for `--permission-mode auto`). |
| 144 | |
| 145 | ### Benchmark arms |
| 146 | |
| 147 | `--ablate` switches whole subsystems off so a benchmark can attribute a change |
| 148 | in success rate to one of them. It accepts a comma-separated list of `evidence`, |
| 149 | `planner`, `subagent`, `retrieval` and `compaction`, plus `none` (the default, |
| 150 | everything on) and `all`. Sub-agents inherit the parent's arm, and the arm name |
| 151 | is written to the `--metrics` file so a recorded run is self-describing. |
| 152 | |
| 153 | ```sh |
| 154 | reasonix run --ablate evidence,planner --metrics run.json "fix the failing test" |
| 155 | ``` |
| 156 | |
| 157 | This is a measurement tool, not a tuning knob: switching a subsystem off makes |
| 158 | Reasonix worse at the work it was added for. |
| 159 | |
| 160 | ### Output formats |
| 161 | |
| 162 | | Format | Behavior | |
| 163 | | --- | --- | |
| 164 | | `text` | Human-readable text. With `-p`, prints only the final answer. | |
| 165 | | `json` | Emits one final result object. | |
| 166 | | `stream-json` | Emits one shared `eventwire` JSON object per line, followed by the final result object. | |
| 167 | |
| 168 | ```sh |
| 169 | reasonix -p "list the risky changes" --output-format text |
| 170 | reasonix -p "summarize the diff" --output-format json |
| 171 | reasonix run "run the tests" --output-format stream-json |
| 172 | ``` |
| 173 | |
| 174 | The final structured object has this shape: |
| 175 | |
| 176 | ```json |
| 177 | { |
| 178 | "type": "result", |
| 179 | "subtype": "success", |
| 180 | "is_error": false, |
| 181 | "duration_ms": 123, |
| 182 | "num_turns": 1, |
| 183 | "result": "...", |
| 184 | "session_id": "...", |
| 185 | "total_cost": 0, |
| 186 | "currency": "USD", |
| 187 | "total_cost_usd": 0, |
| 188 | "usage": { |
| 189 | "input_tokens": 0, |
| 190 | "output_tokens": 0, |
| 191 | "cache_read_input_tokens": 0, |
| 192 | "cache_creation_input_tokens": 0 |
| 193 | } |
| 194 | } |
| 195 | ``` |
| 196 | |
| 197 | `total_cost` is denominated in the ISO currency code from `currency`, currently |
| 198 | `CNY` or `USD` for official DeepSeek pricing. `total_cost_usd` remains as a |
| 199 | numeric compatibility alias and mirrors `total_cost`; despite its legacy name, |
| 200 | it is not converted to USD when `currency` is `CNY`. New consumers must use |
| 201 | `total_cost` together with `currency`. A structured run fails instead of |
| 202 | reporting a misleading total if usage contains mixed currencies. |
| 203 | |
| 204 | Execution failures use `subtype: "error_during_execution"` and |
| 205 | `is_error: true`. Structured modes keep runtime errors in JSON instead of also |
| 206 | printing a duplicate human-readable error. |
| 207 | |
| 208 | ### Redacted machine interfaces |
| 209 | |
| 210 | Use the dedicated event flag when an automation needs lifecycle telemetry but |
| 211 | must not receive prompts, reasoning, tool arguments, tool output, or approval |
| 212 | text: |
| 213 | |
| 214 | ```sh |
| 215 | reasonix run --events-jsonl "run the focused tests" |
| 216 | ``` |
| 217 | |
| 218 | Every line has `schema_version`, `sequence`, and `kind`; the final line is |
| 219 | `kind: "run_done"`. `--events-jsonl` is intentionally separate from the richer |
| 220 | `--output-format stream-json` contract and cannot be combined with |
| 221 | `--output-format`. |
| 222 | |
| 223 | The following read-only commands expose persisted state without transcript, |
| 224 | label, command, output, path, PID, or host-name content. Here, read-only means |
| 225 | the commands do not mutate transcript, runtime, recovery, or query state. The |
| 226 | first redacted-machine invocation may initialize a private identity key in the |
| 227 | Reasonix user-state directory: |
| 228 | |
| 229 | ```sh |
| 230 | reasonix session list --json [--dir SESSION_DIR | --project-root PATH] |
| 231 | reasonix session show <machine-session-id> --json [--dir SESSION_DIR | --project-root PATH] |
| 232 | reasonix session status <machine-session-id> --json [--dir SESSION_DIR | --project-root PATH] |
| 233 | reasonix session recovery [<machine-session-id>] --json [--dir SESSION_DIR | --project-root PATH] |
| 234 | reasonix task list --json [--dir SESSION_DIR | --project-root PATH] [--session MACHINE_SESSION_ID] |
| 235 | reasonix task show <task-id> --json [--dir SESSION_DIR | --project-root PATH] [--session MACHINE_SESSION_ID] |
| 236 | reasonix task monitor list --json [--dir PROJECT_DIR] |
| 237 | reasonix task monitor status <task-id> --json [--dir PROJECT_DIR] |
| 238 | reasonix task monitor events <task-id> --json|--jsonl [--dir PROJECT_DIR] [--after N] [--follow] |
| 239 | reasonix hook list --json [--project-root PATH] [--home-dir PATH] |
| 240 | reasonix hook status --json [--project-root PATH] [--home-dir PATH] |
| 241 | ``` |
| 242 | |
| 243 | For `session` and `task`, `--dir` explicitly selects the session storage |
| 244 | directory, while `--project-root` resolves the selected project's session |
| 245 | store. The two options cannot be combined. Without either option, Reasonix |
| 246 | selects the current project's session store. |
| 247 | For `hook`, `--dir` is an alias for `--project-root`. |
| 248 | `hook list` reports `active` or `invalid`; `invalid` means the |
| 249 | configured event cannot execute because its event, command/context source, or |
| 250 | tool-event matcher is unusable. Matchers on non-tool events are ignored. |
| 251 | |
| 252 | Machine session IDs are keyed opaque hashes, not transcript file names. They |
| 253 | remain stable for the same session and Reasonix user-state directory, while a |
| 254 | different installation key produces unrelated IDs and prevents offline guesses |
| 255 | from timestamps or model labels. Preserve the private identity key when moving |
| 256 | the Reasonix state directory if automation depends on existing machine IDs. |
| 257 | Task `finished_at` is empty while a task is running, and |
| 258 | `artifact_complete=true` is emitted only for a terminal task whose persisted |
| 259 | artifact exists. A `running` record without a live session lease is reported as |
| 260 | `interrupted`; opening that session also repairs the persisted lifecycle state. |
| 261 | |
| 262 | Schema compatibility rules for version 1: |
| 263 | |
| 264 | - consumers must ignore unknown fields; |
| 265 | - fields are not removed or retyped within the same schema version; |
| 266 | - empty collections are encoded as `[]`; |
| 267 | - argument errors exit with status `2`, state/query errors with status `1`; |
| 268 | - machine-command errors are JSON objects with a stable `error.code`. |
| 269 | |
| 270 | ## Resume sessions |
| 271 | |
| 272 | ```sh |
| 273 | reasonix --continue |
| 274 | reasonix --resume |
| 275 | reasonix --resume provider-config |
| 276 | reasonix --resume <session-id> |
| 277 | reasonix --resume provider-config --copy |
| 278 | ``` |
| 279 | |
| 280 | - `--continue` resumes the newest saved session immediately. |
| 281 | - Bare `--resume` opens the searchable picker in an interactive terminal. |
| 282 | - `--resume QUERY` accepts an exact session ID or path, or a unique title or |
| 283 | preview substring. Missing and ambiguous matches fail with a descriptive |
| 284 | error. |
| 285 | - `--resume=true` and `--resume=false` remain accepted for compatibility. |
| 286 | - `--copy` leaves the original transcript untouched and continues in a new |
| 287 | writable session. Use it when another Reasonix process owns the original. |
| 288 | |
| 289 | For one-shot runs, `reasonix run --resume QUERY "task"` accepts a session file |
| 290 | path, a session ID, or an opaque machine session ID from `--events-jsonl` / |
| 291 | `reasonix session show --json`. Session leases prevent the desktop app and CLI |
| 292 | from writing the same transcript concurrently. |
| 293 | |
| 294 | ## Permissions |
| 295 | |
| 296 | ```sh |
| 297 | reasonix --permission-mode plan |
| 298 | reasonix --permission-mode acceptEdits |
| 299 | reasonix run -y "apply the requested changes" |
| 300 | reasonix -p "run the focused tests" --allowed-tools "Bash(go test ./...)" |
| 301 | reasonix --allowed-tools "Bash(git *) Edit" |
| 302 | reasonix --allowed-tools "Bash(go test ./...)" --allowed-tools read_file |
| 303 | ``` |
| 304 | |
| 305 | | Mode | Behavior | |
| 306 | | --- | --- | |
| 307 | | `manual`, `ask` | Ask for ordinary approval decisions. | |
| 308 | | `auto` | Automatically approve normal fallback operations while preserving explicit ask and deny rules. | |
| 309 | | `acceptEdits` | Allow file-editing tools; this is not full Auto mode. | |
| 310 | | `dontAsk` | Deny unapproved requests without opening an approval prompt. | |
| 311 | | `plan` | Start the plan-first workflow; tool calls still use the active permissions and sandbox. | |
| 312 | | `bypassPermissions` | Bypass approval prompts; equivalent to YOLO. | |
| 313 | |
| 314 | For unattended execution with ordinary writer fallback enabled, use |
| 315 | `reasonix run --auto ...` (or `-y`). The alias cannot be combined with an |
| 316 | explicit `--permission-mode` value. |
| 317 | |
| 318 | `[permissions] allow_dynamic_bash = true` is an advanced opt-in that lets an |
| 319 | Allow fallback, including Auto, cover command/process substitution, dynamic |
| 320 | command names, shell `-c`, and other nested/indirect Bash forms. The default is |
| 321 | `false`; explicit `ask` and `deny` rules still take precedence. |
| 322 | |
| 323 | `--allowed-tools` is a session permission override, not a provider tool-schema |
| 324 | filter. Rules may be comma- or space-separated, and the flag is repeatable. |
| 325 | Configured deny rules always win over command-line allow rules. |
| 326 | |
| 327 | In non-interactive runs (`reasonix run` / `-p`) there is no prompt to answer, so |
| 328 | approval modes resolve without blocking. The default `ask` / `manual` posture |
| 329 | fails closed for explicit Ask decisions and ordinary writer fallback; readers |
| 330 | still run. `acceptEdits` allows its named file-edit tools, while other Ask |
| 331 | decisions fail closed. `auto` allows ordinary writer fallback but still denies |
| 332 | an explicit ask rule; select it with `--permission-mode auto`, `--auto`, or |
| 333 | `-y`. `dontAsk` denies unapproved writers. |
| 334 | `bypassPermissions` runs ordinary calls despite ask rules and writer fallback, |
| 335 | but configured deny rules, the sandbox, and tools that require fresh human |
| 336 | approval (memory, plan, sandbox escape, managed config write) still apply. In |
| 337 | every mode, the owning top-level controller may still create a bounded, |
| 338 | non-sensitive, create-only project or reference memory; all other memory |
| 339 | mutations remain denied without a human. |
| 340 | |
| 341 | ## Additional directories |
| 342 | |
| 343 | ```sh |
| 344 | reasonix --add-dir ../shared |
| 345 | reasonix -p "update both projects" \ |
| 346 | --add-dir ../frontend \ |
| 347 | --add-dir ../backend |
| 348 | ``` |
| 349 | |
| 350 | Relative paths resolve from the workspace root and must already exist as |
| 351 | directories. Reasonix resolves symlinks, removes duplicates, and extends the |
| 352 | file-writer and sandboxed Bash write boundaries for the session. These additions |
| 353 | are runtime-only and are not written to configuration. |
| 354 | |
| 355 | ## Interactive controls |
| 356 | |
| 357 | The `/model`, `/provider`, and `/resume` commands use searchable pickers. |
| 358 | Approval prompts use the same row-selection behavior while retaining their |
| 359 | single-key shortcuts. |
| 360 | |
| 361 | | Key | Action | |
| 362 | | --- | --- | |
| 363 | | `Up` / `Down`, `Ctrl+P` / `Ctrl+N` | Move through picker or approval rows. | |
| 364 | | `j` / `k` | Move while the search is empty; after search input starts, enter `j` / `k` as query text. | |
| 365 | | Type | Filter a searchable picker. | |
| 366 | | `Enter` | Select the highlighted row. | |
| 367 | | `Esc` | Cancel the current picker or approval. | |
| 368 | | `y` / `a` / `p` / `n`, number keys | Use the matching approval action. | |
| 369 | | `Shift+Tab` | Cycle `Ask → Auto → Plan → Ask`. | |
| 370 | | `Ctrl+Y` | Toggle YOLO independently of the composer-mode cycle. | |
| 371 | |
| 372 | The responsive footer keeps interaction state on the left and, when space |
| 373 | allows, places model, effort, and work mode on the right. Its second row shows |
| 374 | available repository and session telemetry such as cache hit rate, context use, |
| 375 | compaction headroom, background jobs, and balance. `ready` means the composer is |
| 376 | idle; that slot changes when a picker, approval, image paste, shell mode, or |
| 377 | other interaction needs attention. Narrow terminals move or compact complete |
| 378 | groups instead of cutting labels in half. Visible labels and work-mode values |
| 379 | follow `/language`. |
| 380 | |
| 381 | Use `/theme auto|light|dark` to select the terminal background mode, or choose a |
| 382 | named accent from `/theme`. Both composer borders, the insertion cursor, |
| 383 | selection, scrollbar, and footer use the active CLI theme. See |
| 384 | [Keyboard shortcuts](./GUIDE.md#keyboard-shortcuts) for transcript navigation, |
| 385 | multiline input, rewind, and clipboard controls. |
| 386 | |
| 387 | Clipboard actions are deliberately split by content type. Local transcript |
| 388 | and composer selections use the native system clipboard and report success only |
| 389 | after that write completes; SSH falls back to an explicitly labelled OSC 52 |
| 390 | request. Text paste remains the terminal's bracketed-paste action (`Cmd+V` on |
| 391 | macOS and the terminal's configured shortcut elsewhere). While Reasonix owns the |
| 392 | mouse in a local session, right-click with no selection reads clipboard text |
| 393 | through the same paste path; right-click with a selection copies it. Over SSH, |
| 394 | use the terminal paste shortcut because the remote process cannot read the local |
| 395 | clipboard; `/mouse` restores the terminal's native right-click menu. Image paste |
| 396 | is application-owned: use `Ctrl+V` on macOS/Linux, `Alt+V` on Windows, or |
| 397 | `/paste-image`; the footer shows `Pasting image…` until the attachment token is |
| 398 | ready. |
| 399 | |
| 400 | ## In-session commands |
| 401 | |
| 402 | Type `/help` in an interactive session for the complete command list. Slash |
| 403 | completion, help, dispatch, and aliases are generated from the same registry, so |
| 404 | the displayed list matches the commands the TUI accepts. |
| 405 | |
| 406 | | Command | Purpose | |
| 407 | | --- | --- | |
| 408 | | `/model` | Search configured models and switch the active model. | |
| 409 | | `/provider` | Choose a provider, then choose one of its configured models. | |
| 410 | | `/resume` | Search recent sessions and switch to one. | |
| 411 | | `/status` | Show model, effort, cache, Git, background jobs, and profile or balance details. | |
| 412 | | `/work-mode [economy\|balanced\|delivery]` | View or change the runtime profile; `/profile` is an alias. | |
| 413 | | `/theme [auto\|light\|dark\|style]` | View or change the CLI background mode and accent palette. | |
| 414 | | `/currency [auto\|CNY\|USD]` | View or change the user-global official pricing currency and refresh the runtime. | |
| 415 | | `/paste-image` | Read a clipboard image and insert an editable attachment token. | |
| 416 | | `/mouse` | Toggle in-app mouse selection, scrollbar, and wheel handling. | |
| 417 | | `/effort` | View or change reasoning effort. | |
| 418 | | `/output-style` | Select an answer style. | |
| 419 | | `/verbose` | Toggle expanded reasoning display. | |
| 420 | | `/sandbox` | Inspect sandbox status. | |
| 421 | | `/goal [objective]` | Start a long-running goal, or inspect the current goal and its budget runtime. | |
| 422 | | `/goal status` | Show the active goal plus the turn/token/no-progress budget summary and the last continuation/evaluator reason. | |
| 423 | | `/goal pause` | Pause the running goal (keeps todos, Delivery checkpoint, and budget). | |
| 424 | | `/goal resume` | Resume a paused or blocked goal (budget pauses add one more budget slice). | |
| 425 | | `/goal clear` | End goal mode permanently. | |
| 426 | | `/docs [question]` | Show the embedded corpus identity, or search it locally and ask the configured AI to answer from version-matched evidence. | |
| 427 | | `/reasonix:docs [question]` | Preferred built-in fallback when an existing custom command or compatible plugin/skill alias owns `/docs`; if this spelling is also owned, the menu selects the next free `reasonix:`-qualified name without displacing it. | |
| 428 | | `/mcp`, `/skills`, `/hooks` | Inspect and manage extensions. | |
| 429 | | `/remember <note>` | Append a standing note to the project instruction document; `# <note>` is a shortcut. | |
| 430 | | `/memory [subcommand]` | Inspect instructions, memory provenance, recall, revisions, and recovery. | |
| 431 | | `/rewind` | Restore conversation and/or code to an earlier turn. | |
| 432 | | `/tree`, `/branch`, `/switch` | Inspect or navigate conversation branches. | |
| 433 | | `/reload` | Reload the agent runtime (extensions, tools, skills, commands, hooks, providers) while keeping the session. Queued once while a turn runs, then fail-atomic: a failed rebuild keeps the current runtime. | |
| 434 | |
| 435 | Switching model, effort, or work mode rebuilds the runtime while preserving the |
| 436 | active conversation, session-scoped permission overrides, additional directory |
| 437 | access, and session ownership. `/reload` uses the same fail-atomic rebuild. |
| 438 | |
| 439 | ### Memory diagnostics and recovery |
| 440 | |
| 441 | Bare `/memory` shows all active project/global facts without hiding same-name |
| 442 | entries. Facts include their stable ID, revision, scope, type, freshness, and |
| 443 | description. Slash completion offers the available subcommands, active IDs and |
| 444 | names, and owned archive paths. |
| 445 | |
| 446 | | Command | Purpose | |
| 447 | | --- | --- | |
| 448 | | `/memory instructions` | Show resolved instruction precedence, directories, imports, and diagnostics. | |
| 449 | | `/memory recall` | Explain the latest automatic recall query, hits, scores, reasons, freshness, and budget. | |
| 450 | | `/memory revisions <id-or-name>` | Show the active revision and immutable history. | |
| 451 | | `/memory restore <id-or-name> <revision>` | Restore old content as a new monotonic revision. | |
| 452 | | `/memory archived` | List archived facts and their owned paths. | |
| 453 | | `/memory recover <archive-path>` | Recover an archive as a new revision without overwriting active data. | |
| 454 | |
| 455 | These commands run against the active session controller. When the session |
| 456 | lives on a remote host (`reasonix remote connect` / a desktop remote web |
| 457 | window), they use the remote memory catalog and never fall back to local |
| 458 | desktop memory. See [Context Engine v2](./SESSION_MEMORY_RETRIEVAL.md) for |
| 459 | authority, automatic recall, write confirmation, and migration behavior. |
| 460 |