esengine--deepseek-reasonix/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 (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:

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:

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
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 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.