/docs/MIGRATING.md

# Migrating to Reasonix 1.0 (the Go rewrite)

Reasonix 1.0 is a **ground-up rewrite in Go**. It is a new codebase, not an
incremental upgrade of the `0.x` TypeScript releases. This guide explains what
changed and how to move over.

## TL;DR

| | Legacy (v1) | Reasonix 1.0+ (v2) |
|---|---|---|
| Language | TypeScript / Node | Go |
| Branch | [`v1`](https://github.com/esengine/DeepSeek-Reasonix/tree/v1) (maintenance only) | `main-v2` (default, active) |
| Versions | `0.x` (up to v0.54.x) | `1.0.0`+ |
| Install | `npm i -g reasonix@0.53.2` (pin a `0.x` version) | `npm i -g reasonix` — `latest` points at the current `1.x` stable; or a release archive / `go build` |
| Code intelligence | embedding semantic search + tree-sitter symbols | LSP-assisted code reading plus grep/read_file/glob; semantic index is not yet ported |

"v1" and "v2" are **codebase generations**, not semver: the v1 line never reached
1.0, so the Go rewrite takes the `1.x` major.

## Installing 1.0

`npm` stays the primary channel — the package wraps the prebuilt Go binary (the
same way esbuild/biome ship native binaries via npm). The binary itself is a
standalone Go executable; npm is only the installer, not a runtime dependency.

**`npm i -g reasonix` installs the current `1.x` stable.** npm's `latest` tag
moved to the Go line with `1.17.5` — the earlier "`latest` stays pinned to
`0.x`" migration guard silently downgraded `npm update -g` users once 1.x went
stable (#5822), so it was retired. Release candidates still ship under the
`next` tag; `0.x` stays installable by pinning:

```sh
npm i -g reasonix          # current 1.x stable
npm i -g reasonix@next     # release candidate, when one is ahead of stable
npm i -g reasonix@0.53.2   # pin the legacy TS build
```

Prebuilt archives (`reasonix-<os>-<arch>.tar.gz` / `.zip`) and the desktop
installer are attached to each GitHub release. These are a **separate channel**
from npm: the installer drops a standalone desktop/binary build and does not
touch a CLI you installed with `npm i -g`, so the two coexist — an npm `0.53` in
your shell alongside a `1.x` desktop app is expected, not a conflict. Or build
from source:

```sh
git clone https://github.com/esengine/DeepSeek-Reasonix   # default: main-v2 (Go)
cd DeepSeek-Reasonix && make build                        # -> bin/reasonix(.exe)
```

## Configuration

| Legacy | Reasonix 1.0 |
|---|---|
| TS config files | `reasonix.toml` (project) / `config.toml` in Reasonix home (`~/.reasonix/` on macOS/Linux; `%AppData%\reasonix\` on Windows) from v1.8.1 — see `reasonix.example.toml` and [Configuration paths](./CONFIG_PATHS.md) |
| env / API keys | Provider config keeps `api_key_env`; saved key values live in Reasonix home `.env` (`DEEPSEEK_API_KEY`, `MIMO_API_KEY`, …) |
| project memory | `REASONIX.md` (+ auto-memory), Claude-Code-compatible |
| MCP servers | `[[plugins]]` in `reasonix.toml`, or a Claude-Code `.mcp.json` (read as-is) |

On first launch, v1.8.1+ runs a one-time, **non-destructive** import: it reads
legacy config from `~/Library/Application Support/reasonix/config.toml`,
`~/.config/reasonix/config.toml`, `~/.reasonix/reasonix.toml`, or v0.x
`~/.reasonix/config.json` (API key, base URL, language, MCP servers), migrates
legacy credentials into `<Reasonix home>/.env` when a key is missing there, and
imports past sessions from legacy session directories. Old files are left
untouched, and Reasonix prints a boot notice when it imports data. Each session lands in the
workspace it belonged to (read from its v0.x sidecar meta, summary carried over
as the title), so the desktop sidebar lists it under the right project; sessions
whose workspace no longer exists land in the global session dir. Imported
sessions resume with `--resume` or the history panel. The config import only
runs when no v1.8.1+ config exists yet — if v1.8.1+ wrote its config before your
legacy data was in place nothing is overwritten, so copy any missing values
across by hand.

If the automatic pass missed data because you opened a v1.8.1+ CLI/desktop build
before the old paths were available, run `/migrate` from an interactive session.
The command is available only in Go-based Reasonix builds that include it; if you
see `unknown command`, upgrade first. It prints progress while it checks legacy
config and credentials, scans legacy memory and session directories, imports
memory files and sessions that were not previously imported, and summarizes the
result. `/migrate` keeps the same safety rules as startup migration: it does not
overwrite an existing `config.toml` or memory file, it respects session import
markers, and it is not available in the legacy 0.x TypeScript line. If the old
v0.x sessions are in a custom Windows install/data directory, use
`/migrate --from "D:\OldReasonix"` to import sessions from that explicit source.
See
[Configuration paths](./CONFIG_PATHS.md) for the full path list and limitations.

## What's the same

The agent core carries over: the loop, tools (read/write/edit/glob/grep/bash/…),
subagents (`task`, explore/research/review), skills, hooks, plan mode, MCP client,
and DeepSeek prefix-cache–oriented design.

## What's different

- **Code intelligence**: the Go rewrite uses LSP-assisted code reading plus
  `grep` / `read_file` / `glob` for local understanding. The legacy v1 semantic
  search + tree-sitter symbol index is not bundled in v2 yet, and CodeGraph is no
  longer shipped as an internal MCP server.
- **Plan mode** + `complete_step` (evidence-backed step sign-off).
- **Plan-mode tool overrides are narrower, and plan mode is fail-closed for
  external tools**: `[agent].plan_mode_allowed_tools` now only declares extra
  read-only custom/external tools. It no longer unlocks known blocked plan-mode
  tools such as `bash`, `task`, writers, installers, or memory mutation tools, and
  unsafe bash commands still remain blocked. To migrate old
  `plan_mode_allowed_tools = ["bash", ...]` configs, move concrete read-only
  shell prefixes such as `gh issue view` or internal query CLIs to
  `[agent].plan_mode_read_only_commands`; do not declare shell interpreters or
  writer-capable commands there. Interactive plan-mode runs can also ask you to
  trust a concrete unknown query prefix once, and the persistent choice writes
  the same `plan_mode_read_only_commands` entry. Auto/YOLO tool approval does
  not answer this bash trust prompt. Use `read_only_task` / `read_only_skill`
  instead of trying to unlock `task` / `run_skill` while planning. An MCP/plugin tool
  whose read-only status comes from the server's untrusted `readOnlyHint` is
  confirmed the first time an interactive plan-mode run needs it; choose the
  persistent option to write the plugin-level `trusted_read_only_tools` raw-name
  list. Auto/YOLO tool approval does not answer this trust prompt, although a
  session or persistent trust choice prevents repeat prompts for the same MCP
  tool. Non-interactive runs still fail closed, so pre-seed
  `trusted_read_only_tools` or declare a concrete `mcp__<server>__<tool>` when no
  user can approve. In the desktop MCP
  panel, expand a server and use **Pre-trust read-only** for currently listed
  `readOnlyHint` tools, per-tool **Pre-trust** for audited readers, or
  **Untrust** to remove a tool; those actions write the same
  `trusted_read_only_tools` list. First-party `ReadOnlyToolNames` overrides and
  built-ins stay trusted.
- **Read-only subagent research**: use `read_only_task` for generic isolated
  research in plan mode, or `read_only_skill` when the work should follow an
  existing skill. Both expose only read-only tools and safe foreground bash, do
  not write resumable transcripts, and keep writer-capable `task` / `run_skill`
  blocked until after plan approval.
- **No web dashboard** — the v2 line is terminal + desktop (Wails), by design.
- Some granular v1 tools are intentionally consolidated (e.g. file-management ops
  go through `bash`); a few v1 tools are not yet ported (tracked on Discussions).

## File encoding

Reasonix 1.0 supports reading and editing files in UTF-8, UTF-8 BOM, UTF-16
LE/BE, and GB18030 (a superset of GBK). This matches v1's behavior.

- `read_file` decodes any supported encoding to UTF-8 for the model.
- `edit_file` and `multi_edit` preserve the file's original encoding — if you
  edit a GB18030 file, it stays GB18030 on disk.
- `write_file` always writes UTF-8 (the model's output encoding).
- `grep` decodes before matching, so regex patterns work on non-UTF-8 files.

## Reporting issues

Issues and PRs are labelled by line: **`v1`** (legacy TypeScript) and **`v2`**
(Go). File new reports against the line you're using. The legacy `v1` line is in
maintenance mode — bug fixes only, no new features.

Questions? Open a [Discussion](https://github.com/esengine/DeepSeek-Reasonix/discussions).