| 1 | <p align="center"> |
| 2 | <img src="docs/logo-ghost-wave-effect.svg" alt="Reasonix" width="360"/> |
| 3 | </p> |
| 4 | |
| 5 | <p align="center"> |
| 6 | <strong>English</strong> |
| 7 | · |
| 8 | <a href="./README.zh-CN.md">简体中文</a> |
| 9 | · |
| 10 | <a href="./docs/GUIDE.md">Guide</a> |
| 11 | · |
| 12 | <a href="./docs/ACP.md">ACP</a> |
| 13 | · |
| 14 | <a href="./docs/EXTENSIONS.md">Extensions</a> |
| 15 | · |
| 16 | <a href="./docs/SPEC.md">Spec</a> |
| 17 | · |
| 18 | <a href="https://esengine.github.io/DeepSeek-Reasonix/">Website</a> |
| 19 | · |
| 20 | <strong><a href="https://discord.gg/XF78rEME2D">Discord</a></strong> |
| 21 | </p> |
| 22 | |
| 23 | <p align="center"> |
| 24 | <a href="https://www.npmjs.com/package/reasonix"><img src="https://img.shields.io/npm/v/reasonix.svg?style=flat-square&color=cb3837&labelColor=161b22&logo=npm&logoColor=white" alt="npm version"/></a> |
| 25 | <a href="https://github.com/esengine/DeepSeek-Reasonix/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/esengine/DeepSeek-Reasonix/ci.yml?style=flat-square&label=ci&labelColor=161b22&logo=githubactions&logoColor=white" alt="CI"/></a> |
| 26 | <a href="./LICENSE"><img src="https://img.shields.io/npm/l/reasonix.svg?style=flat-square&color=8b949e&labelColor=161b22" alt="license"/></a> |
| 27 | <a href="https://www.npmjs.com/package/reasonix"><img src="https://img.shields.io/npm/dm/reasonix.svg?style=flat-square&color=3fb950&labelColor=161b22&label=downloads" alt="downloads"/></a> |
| 28 | <a href="https://github.com/esengine/DeepSeek-Reasonix/stargazers"><img src="https://img.shields.io/github/stars/esengine/DeepSeek-Reasonix.svg?style=flat-square&color=dbab09&labelColor=161b22&logo=github&logoColor=white" alt="GitHub stars"/></a> |
| 29 | <a href="https://atomgit.com/esengine/DeepSeek-Reasonix"><img src="https://atomgit.com/esengine/DeepSeek-Reasonix/star/badge.svg" alt="AtomGit stars"/></a> |
| 30 | <a href="https://github.com/esengine/DeepSeek-Reasonix/graphs/contributors"><img src="https://img.shields.io/github/contributors/esengine/DeepSeek-Reasonix.svg?style=flat-square&color=bc8cff&labelColor=161b22&logo=github&logoColor=white" alt="contributors"/></a> |
| 31 | <a href="https://github.com/esengine/DeepSeek-Reasonix/discussions"><img src="https://img.shields.io/github/discussions/esengine/DeepSeek-Reasonix.svg?style=flat-square&color=58a6ff&labelColor=161b22&logo=github&logoColor=white" alt="Discussions"/></a> |
| 32 | <a href="https://discord.gg/XF78rEME2D"><img src="https://img.shields.io/badge/discord-join-5865F2.svg?style=flat-square&labelColor=161b22&logo=discord&logoColor=white" alt="Discord"/></a> |
| 33 | </p> |
| 34 | |
| 35 | <p align="center"> |
| 36 | <a href="https://trendshift.io/repositories/27020?utm_source=trendshift-badge&utm_medium=badge&utm_campaign=badge-trendshift-27020" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/27020/monthly?language=Go" alt="esengine/DeepSeek-Reasonix | Trendshift" width="250" height="55"/></a> |
| 37 | <a href="https://trendshift.io/repositories/27020?utm_source=repository-badge&utm_medium=badge&utm_campaign=badge-repository-27020" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/27020" alt="esengine/DeepSeek-Reasonix | Trendshift" width="250" height="55"/></a> |
| 38 | </p> |
| 39 | |
| 40 | <br/> |
| 41 | |
| 42 | <p align="center"><strong>Open source · MIT · a single Go binary</strong></p> |
| 43 | <h3 align="center">A coding agent you can leave running.</h3> |
| 44 | <p align="center">One local engine, four ways in — terminal, desktop app, browser, or your editor over ACP. Plan mode, permissions, a workspace sandbox and per-turn checkpoints keep a long autonomous run something you can still read and undo.</p> |
| 45 | |
| 46 | <div align="center"> |
| 47 | <video src="https://github.com/user-attachments/assets/ab2f3878-e224-4931-8254-060e7695cfb9" controls preload="metadata" width="560"></video> |
| 48 | </div> |
| 49 | |
| 50 | <br/> |
| 51 | |
| 52 | > [!IMPORTANT] |
| 53 | > **Community · 加入社区** — bilingual Discord for setup help (`#help` / `#求助`), workflow showcases, and feature ideas. → **<https://discord.gg/XF78rEME2D>** |
| 54 | |
| 55 | <br/> |
| 56 | |
| 57 | ## Features |
| 58 | |
| 59 | - **Config-driven.** Providers, the agent, enabled tools, and plugins are all |
| 60 | declared in `reasonix.toml`. No hardcoded models. |
| 61 | - **Multi-model & composable.** DeepSeek ships as a preset; any |
| 62 | OpenAI-compatible endpoint is a config entry, not new code. Optionally run |
| 63 | two models together (executor + planner) in separate, cache-stable sessions. |
| 64 | - **Plugin-driven.** MCP servers contribute tools, prompts, and resources; |
| 65 | Extension Protocol v1 sidecars can also intercept runtime events, contribute |
| 66 | Providers and structured UI, and ship versioned plugin packages. |
| 67 | - **Cache-aware context maintenance.** Startup injects a small stable environment |
| 68 | summary, stale tool output is snipped/pruned before summary compaction, and the |
| 69 | built-in tool schema contract is documented for regression review. |
| 70 | - **Zero-friction distribution.** `CGO_ENABLED=0` single binary; cross-compile |
| 71 | to six targets with one command. The result is a fully self-contained static |
| 72 | binary — nothing to install on the target machine beyond the binary itself. |
| 73 | |
| 74 | ## Install |
| 75 | |
| 76 | Choose the path that matches how you want to use Reasonix. The CLI/TUI, |
| 77 | desktop app, and VS Code extension all use the same local Reasonix engine. |
| 78 | |
| 79 | ### Path A: CLI / TUI |
| 80 | |
| 81 | Install the native binary through npm on any supported platform, or use |
| 82 | Homebrew on macOS: |
| 83 | |
| 84 | ```sh |
| 85 | npm i -g reasonix # any OS; pulls the prebuilt native binary |
| 86 | brew install esengine/reasonix/reasonix # macOS |
| 87 | ``` |
| 88 | |
| 89 | Prebuilt archives (`darwin|linux|windows × amd64|arm64`) and `SHA256SUMS` are on |
| 90 | every [GitHub release](https://github.com/esengine/DeepSeek-Reasonix/releases). |
| 91 | |
| 92 | ### Path B: Desktop app |
| 93 | |
| 94 | Use the [official download page](https://reasonix.io/?download=desktop#start) |
| 95 | for the latest desktop build. |
| 96 | |
| 97 | | Platform | Package | Architecture | |
| 98 | | --- | --- | --- | |
| 99 | | macOS | Universal `.dmg` or `.zip` | Apple Silicon / Intel | |
| 100 | | Windows | Installer `.exe` or portable `.zip` | x64 / ARM64 | |
| 101 | | Linux | `.deb` or `.tar.gz` | x64 | |
| 102 | |
| 103 | Windows installers are code-signed with a Certum code-signing certificate. |
| 104 | |
| 105 | ### Path C: VS Code extension |
| 106 | |
| 107 | Complete Path A first. The extension does not bundle the CLI; it starts your |
| 108 | local `reasonix acp` backend and adds native chat, editor context, tool-call |
| 109 | approvals, model selection, and workspace sessions. |
| 110 | |
| 111 | - **VS Code:** [install from Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=SivanLiu.reasonix-agent) |
| 112 | - **VSCodium / Eclipse Theia:** [install from Open VSX Registry](https://open-vsx.org/extension/SivanLiu/reasonix-agent) |
| 113 | - **Extension ID:** `SivanLiu.reasonix-agent` · [source and usage guide](https://github.com/SivanCola/reasonix-vscode) |
| 114 | |
| 115 | ### Path D: Build from source |
| 116 | |
| 117 | Clone the repository first: |
| 118 | |
| 119 | ```sh |
| 120 | git clone https://github.com/esengine/DeepSeek-Reasonix.git |
| 121 | cd DeepSeek-Reasonix |
| 122 | ``` |
| 123 | |
| 124 | #### CLI |
| 125 | |
| 126 | The CLI build requires **Go 1.26+**. The module pins a `toolchain` directive; |
| 127 | keep `GOTOOLCHAIN=auto` so Go downloads the pinned toolchain, or install it. |
| 128 | |
| 129 | ```sh |
| 130 | make build # -> bin/reasonix(.exe) |
| 131 | make cross # -> dist/ (darwin|linux|windows × amd64|arm64) |
| 132 | ``` |
| 133 | |
| 134 | #### Desktop |
| 135 | |
| 136 | The desktop build additionally requires **Node 24+ and pnpm 10** |
| 137 | (`npm install -g pnpm@10`) for the frontend and the Electron shell: |
| 138 | |
| 139 | ```sh |
| 140 | scripts/desktop-build.sh darwin/arm64 v0.0.0-dev # one platform per run |
| 141 | ``` |
| 142 | |
| 143 | No platform webview dependencies are needed — the shell ships its own |
| 144 | Chromium. See the [desktop build guide](desktop/README.md#prerequisites). |
| 145 | |
| 146 | ## Quick start |
| 147 | |
| 148 | ### CLI / TUI |
| 149 | |
| 150 | These commands are for the CLI/TUI installed through Path A: |
| 151 | |
| 152 | ```sh |
| 153 | reasonix setup # configure a provider and model |
| 154 | reasonix # start an interactive session |
| 155 | reasonix run "implement the TODOs in main.go" |
| 156 | ``` |
| 157 | |
| 158 | In an interactive session, run `/init` when you want Reasonix to create project |
| 159 | instructions. |
| 160 | |
| 161 | ### Desktop app |
| 162 | |
| 163 | Download the installer for your platform from the |
| 164 | [official download page](https://reasonix.io/?download=desktop#start), install |
| 165 | and launch Reasonix, then configure a provider and model in the app. The CLI |
| 166 | commands above are not required for the desktop app. |
| 167 | |
| 168 | For advanced CLI usage and configuration, see the **[CLI reference](./docs/CLI.md)**, |
| 169 | **[Guide](./docs/GUIDE.md)**, and |
| 170 | **[configuration paths](./docs/CONFIG_PATHS.md)**. |
| 171 | |
| 172 | ## Documentation |
| 173 | |
| 174 | - **Getting started:** [Guide](./docs/GUIDE.md) · [CLI reference](./docs/CLI.md) · |
| 175 | [Configuration paths](./docs/CONFIG_PATHS.md) · [ACP editor integration](./docs/ACP.md) |
| 176 | - **Features & troubleshooting:** [Subagent profiles](./docs/SUBAGENT_PROFILES.md) · |
| 177 | [Context Engine v2](./docs/SESSION_MEMORY_RETRIEVAL.md) · |
| 178 | [File deliverables and the `present` tool](./docs/PRESENT_TOOL.md) · |
| 179 | [Capability diagnostics](./docs/CAPABILITY_DIAGNOSTICS.md) · |
| 180 | [Recovery and updates](./docs/RECOVERY.md) · [Bot guide](./docs/BOT_GUIDE.md) · |
| 181 | [Checkpoints & rewind](./docs/CHECKPOINTS.md) |
| 182 | - **Engineering & migration:** [Spec](./docs/SPEC.md) · |
| 183 | [Task contracts & pause policy](./docs/TASK_CONTRACT.md) · |
| 184 | [Tool contract](./docs/TOOL_CONTRACT.md) · [Migrating from 0.x](./docs/MIGRATING.md) |
| 185 | - **Extension development:** [Extensions](./docs/EXTENSIONS.md) · |
| 186 | [Plugin packages and Manifest v1](./docs/PLUGIN_PACKAGES.md) · |
| 187 | [Extension Protocol](./docs/EXTENSION_PROTOCOL.md) · |
| 188 | [Go SDK and starter](./sdk/go/README.md) |
| 189 | |
| 190 | ## Star History |
| 191 | |
| 192 | <a href="https://www.star-history.com/?repos=esengine%2FDeepSeek-Reasonix&type=date&legend=top-left"> |
| 193 | <picture> |
| 194 | <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/esengine/DeepSeek-Reasonix/star-history/assets/star-history/star-history-dark.svg" /> |
| 195 | <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/esengine/DeepSeek-Reasonix/star-history/assets/star-history/star-history-light.svg" /> |
| 196 | <img alt="Star History Chart" src="https://raw.githubusercontent.com/esengine/DeepSeek-Reasonix/star-history/assets/star-history/star-history-light.svg" /> |
| 197 | </picture> |
| 198 | </a> |
| 199 | |
| 200 | <br/> |
| 201 | |
| 202 | ## Acknowledgments |
| 203 | |
| 204 | A small list of folks whose work has shaped Reasonix the most — the current top |
| 205 | 20 contributors by commit count. The full contributor graph is on |
| 206 | [GitHub](https://github.com/esengine/DeepSeek-Reasonix/graphs/contributors?all=1). |
| 207 | |
| 208 | <!-- reasonix-top-contributors:start --> |
| 209 | | Contributor | Contributor | Contributor | Contributor | |
| 210 | | --- | --- | --- | --- | |
| 211 | | [**SivanCola**](https://github.com/SivanCola) | [**esengine**](https://github.com/esengine) | [**ttmouse**](https://github.com/ttmouse) | [**lifu963**](https://github.com/lifu963) | |
| 212 | | **reasonix** | [**HUQIANTAO**](https://github.com/HUQIANTAO) | [**GTC2080**](https://github.com/GTC2080) | [**mchenziyi**](https://github.com/mchenziyi) | |
| 213 | | [**Li-Charles-One**](https://github.com/Li-Charles-One) | **merge-order-check** | [**light-front-theory**](https://github.com/light-front-theory) | **Yan Li** | |
| 214 | | [**eghrhegpe**](https://github.com/eghrhegpe) | **wufengfan** | [**Bernardxu123**](https://github.com/Bernardxu123) | [**HaoyueQin**](https://github.com/HaoyueQin) | |
| 215 | | [**CVEngineer66**](https://github.com/CVEngineer66) | [**JesonChou**](https://github.com/JesonChou) | [**SuMuxi66**](https://github.com/SuMuxi66) | [**lanshi17**](https://github.com/lanshi17) | |
| 216 | <!-- reasonix-top-contributors:end --> |
| 217 | |
| 218 | Special thanks to [**Bernardxu123**](https://github.com/Bernardxu123) for designing the project logo and intro video. |
| 219 | |
| 220 | <p align="center"> |
| 221 | <a href="https://github.com/esengine/DeepSeek-Reasonix/graphs/contributors"> |
| 222 | <img src="https://contrib.rocks/image?repo=esengine/DeepSeek-Reasonix&max=100&columns=12" alt="Contributors to esengine/DeepSeek-Reasonix" width="860"/> |
| 223 | </a> |
| 224 | </p> |
| 225 | |
| 226 | <br/> |
| 227 | |
| 228 | --- |
| 229 | |
| 230 | <p align="center"> |
| 231 | <sub>MIT — see <a href="./LICENSE">LICENSE</a></sub> |
| 232 | <br/> |
| 233 | <sub>Built by the community at <a href="https://github.com/esengine/DeepSeek-Reasonix/graphs/contributors">esengine/DeepSeek-Reasonix</a></sub> |
| 234 | </p> |
| 235 | |
| 236 | --- |
| 237 | |
| 238 | <p align="center"><sub><strong>Support this project</strong></sub></p> |
| 239 | |
| 240 | If Reasonix has been useful and you'd like to say thanks, you can. It stays a |
| 241 | coffee, not a contract — donations don't buy feature priority or change how |
| 242 | issues get triaged. |
| 243 | |
| 244 | - **International** — PayPal: [paypal.me/yuhuahui](https://paypal.me/yuhuahui) |
| 245 | - **国内** — 微信支付（扫码） |
| 246 | |
| 247 | <p align="center"> |
| 248 | <img src=".github/sponsor/wechat-pay.jpg" alt="WeChat Pay QR code" width="180"/> |
| 249 | </p> |
| 250 |