Install Reasonix globally if you want the reasonix command available on your PATH: ~~~bash npm install -g reasonix reasonix code my-project # paste a DeepSeek API key on first run; persists after ~~~ Or run it once without installing globally:
[!WARNING] This is the legacy TypeScript line (Reasonix 0.x), in maintenance mode. Active development moved to the Go rewrite — see the
main-v2branch (the new default) and the migration guide. Only bug fixes land here.
English · 简体中文 · 日本語 · Website · Guide · Architecture · Benchmarks · Discord
A DeepSeek-native AI coding agent for your terminal.
Engineered around prefix-cache stability — so token costs stay low across long sessions, and you can leave it running.
[!TIP] Cache stability isn't a feature you turn on; it's an invariant the loop is designed around. That's the whole reason Reasonix is DeepSeek-only — every layer is tuned to the byte-stable prefix-cache mechanic.
[!NOTE] Real user, single day (2026-05-01): 435M input tokens, 99.82% cache hit, ~$12 instead of the ~$61 the same workload would cost with no cache on
v4-flash— see the case study. DeepSeek provides the cacheable bytes; the four mechanisms in Pillar 1 are how Reasonix keeps them cacheable across long sessions.
[!IMPORTANT] Community · 加入社区 — bilingual Discord with channels for setup help (
#help/#求助), workflow showcases, feature ideas, and contributor-only PR coordination. Verify your GitHub in-server to get the Contributor role automatically. → https://discord.gg/XF78rEME2D
Install
Requires Node ≥ 22. Works on macOS · Linux · Windows (PowerShell · Git Bash · Windows Terminal).
Install Reasonix globally if you want the reasonix command available on your PATH:
npm install -g reasonix
reasonix code my-project # paste a DeepSeek API key on first run; persists after
Or run it once without installing globally:
cd my-project
npx reasonix code # always uses the latest package by default
Grab a DeepSeek API key → · reasonix code --help for flags.
If you use Reasonix daily, global install is the simplest path. If you just want to try it, use npx.
Prefer fewer keystrokes? The shorter dsnix alias resolves to the same CLI:
npm install -g dsnix # exposes `dsnix` on PATH, depends on reasonix
npx dsnix@latest code # one-shot via the shorter command
A global npm install -g reasonix also drops a dsnix shim on PATH, so the two are interchangeable.
Bare reasonix (no subcommand) launches code in the current directory — typing reasonix and reasonix code are equivalent.
| Command | When |
|---|---|
reasonix / reasonix code [dir] | The coding agent. Start here. |
reasonix chat | Plain chat — no filesystem or shell tools. |
reasonix run "task" | One-shot, streams to stdout. Good for pipes. |
reasonix doctor | Health check: Node, API key, MCP wiring. |
reasonix update | Upgrade Reasonix itself. |
Other subcommands (replay · diff · events · stats · index · mcp · prune-sessions) are in reasonix --help and the CLI reference.
QQ channel
QQ can extend an existing chat, code, or desktop session as a remote channel. It is part of the current session flow, not a separate runtime mode.
- CLI: start a session, then run
/qq connect - Desktop: open
Settings -> General -> QQ Channel
Once connected, QQ messages can enter the current session, assistant replies route back to QQ, and follow-up interactions can continue remotely.
For full setup, desktop quick start, and troubleshooting, see QQ channel setup.
Desktop client (prerelease)
A native Tauri client for users who want a GUI over the same loop. Multi-tab, the right-panel shows files the agent has read or edited this session, the same cost / cache / token meters live at the bottom. Same DeepSeek API key, same ~/.reasonix config — the desktop bundles its own Node runtime, no separate npm install step.
Download platform installers from GitHub Releases. The desktop ships as a prerelease: the loop and protocol are the same as the CLI, but the UI is still being polished and the installers aren't code-signed yet.
- macOS — first launch hits Gatekeeper. One-time fix:
xattr -dr com.apple.quarantine /Applications/Reasonix.app(or right-click → Open → confirm). - Windows — SmartScreen warns "Unknown publisher". Click More info → Run anyway.
- Linux —
.deband.AppImageship plain, no extra step.
The CLI remains the canonical surface. Anything that lands in the CLI is also available from the desktop's composer.
Working in another folder · chat vs. code · author a skill
Working in a different folder. Reasonix scopes filesystem tools to the launch directory; pass --dir to retarget. Mid-session switching isn't supported by design (memory paths would tangle with stale roots) — quit and relaunch.
npx reasonix code --dir /path/to/project
Picking chat vs code. code is the default and the only mode with filesystem / shell tools and SEARCH/REPLACE review. chat is the lighter, tools-off shell — reach for it when you want a thinking partner with MCP attached but no disk access.
| What you get | code | chat |
|---|---|---|
Filesystem tools + edit_file | ✓ | — |
SEARCH/REPLACE → /apply review | ✓ | — |
| Shell tool (gated) | ✓ | — |
Plan mode · /todo · /skill new · /mcp add | ✓ | — |
Memory (remember / recall_memory) | project + global | global only |
MCP servers from config · web search · ask_choice | ✓ | ✓ |
| Coding system prompt | ✓ | generic |
| Session scope | per-directory | shared default |
Author your first skill. No remote registry — write them directly. Edit the file (description: frontmatter + body), then /skill list. Add runAs: subagent to spawn an isolated subagent loop instead of inlining the body.
/skill new my-skill # <project>/.reasonix/skills/my-skill.md
/skill new my-skill --global # ~/.reasonix/skills for cross-project use
Claude-format skills also load. <project>/.claude/skills/<name>/SKILL.md and ~/.claude/skills/ are read alongside Reasonix's native paths, so tooling that emits Claude-format skills works out of the box. Example — drop OpenSpec workflows in without an upstream adapter:
npx openspec init --tools claude # writes .claude/skills/openspec-*/SKILL.md
/skill openspec-propose <task> # then invoke from Reasonix
Configuration
One JSON file at ~/.reasonix/config.json plus per-project overrides under <project>/.reasonix/. The full bilingual reference — every key, every slash command, the on-disk shape of skills/memory/hooks — lives at:
| Topic | Quick read |
|---|---|
| MCP servers | stdio · SSE · Streamable HTTP. One spec format works for both config.json and --mcp. |
| Skills | Markdown playbooks the model can invoke. inline or subagent mode. |
| Memory | User-private knowledge pinned into the prefix. user / feedback / project / reference types. |
| Hooks | Shell commands on lifecycle events. PreToolUse (gating) · PostToolUse · UserPromptSubmit · Stop. |
| Permissions | Per-workspace shell allowlist. Exact-prefix match. |
| Web search | Bing by default; switch to Baidu AI Search, self-hosted SearXNG, Metaso, Tavily, Perplexity, Exa, Brave, or Ollama with /search-engine. |
| Semantic index | reasonix index — local Ollama or any OpenAI-compatible embedding endpoint. |
What makes Reasonix different
The loop is organized around three pillars. Each one solves a problem generic agent frameworks don't even see — because they were designed for a different cache mechanic.
Click through to the full architecture writeup → Pillar 1 — Cache-first loop · Pillar 2 — Tool-call repair · Pillar 3 — Cost control
Capabilities
How it compares
| Reasonix | Claude Code | Cursor | Aider | |
|---|---|---|---|---|
| Backend | DeepSeek | Anthropic | OpenAI / Anthropic | any (OpenRouter) |
| License | MIT | closed | closed | Apache 2 |
| Cost profile | low per task | premium | subscription + use | varies |
| DeepSeek prefix-cache | engineered | not applicable | not applicable | incidental |
| Embedded web dashboard | yes | — | n/a (IDE) | — |
| Configurable web search engine | /search-engine | — | — | — |
| Persistent per-workspace sessions | yes | partial | n/a | — |
| Plan mode · MCP · hooks · skills | yes | yes | yes | partial |
| Web search (Bing + Baidu + SearXNG + API engines) | yes | yes | yes | yes |
| Open community development | yes | — | — | yes |
For live cache-hit rates, costs, and methodology, see benchmarks/ — the numbers move with model pricing, so they live with the harness, not in the README.
Documentation
- Architecture — three pillars: cache-first loop, tool-call repair, cost control
- CLI Reference — every shell subcommand, every slash command, every keybinding
- QQ channel setup — CLI first-connect flow, desktop entry, and QQ Open Platform credentials
- Benchmarks — τ-bench-lite harness, transcripts, cost methodology
- Website — getting started, dashboard mockup, TUI mockup
- Contributing — comment policy, error-handling rules, library-over-hand-rolled
- Code of Conduct · Security policy
Community
[!NOTE] Reasonix is open source and community-developed. Every avatar in the Acknowledgments wall at the bottom of this file is a real PR that shipped.
Scoped starter tickets — each with background, code pointers, acceptance criteria, and hints — live under the good first issue label. Pick anything open.
Open Discussions — opinions wanted:
- #20 · CLI / TUI design — what's broken, what's missing, what would you change?
- #21 · Dashboard design — react against the proposed mockup
- #22 · Future feature wishlist — what would you build into Reasonix next?
Already using Reasonix and willing to help others discover it? Publish blog posts, articles, screenshots, talks, or videos to Show and tell. The project has no marketing budget — community word of mouth is how new users find it. Sustained advocates earn the badge below, displayed next to the contributors wall once awarded:
Before your first PR: read CONTRIBUTING.md — short, strict rules (comments, errors, libraries-over-hand-rolled). tests/comment-policy.test.ts enforces the comment ones; npm run verify is the pre-push gate. By participating you agree to the Code of Conduct. Security issues → SECURITY.md.
Non-goals
[!IMPORTANT] Reasonix is opinionated. Some things it deliberately doesn't do — listed here so you can pick the right tool for your work.
- Multi-provider flexibility. DeepSeek-only on purpose. Coupling to one backend is the feature, not a limitation.
- IDE integration. Terminal-first. The diff lives in
git diff, the file tree inls. The dashboard is a companion, not a Cursor replacement. - Hardest-leaderboard reasoning. Claude Opus still wins some benchmarks. DeepSeek is competitive on coding; if your work is "solve this PhD proof" rather than "fix this auth bug," start with Claude.
- Air-gapped / fully-free. Reasonix needs a paid DeepSeek API key. For air-gapped or zero-cost runs see Aider + Ollama or Continue.
Star History
Support
If Reasonix has been useful and you'd like to say thanks, you can. It stays a coffee, not a contract — donations don't buy feature priority or change how issues get triaged.
- International — PayPal: paypal.me/yuhuahui
- 国内 — 微信支付（扫码）
Acknowledgments
A small list of folks whose work has shaped Reasonix the most — measured by both commit count and code volume. Listed alphabetically, no ordering of importance. The full contributor graph is on GitHub.
- ctharvey
- dimasd-angga (Dimas D. Angga)
- Evan-Pycraft
- ForeverYoungPp
- GTC2080 (TaoMu)
- kabaka9527
- lisniuse (Richie)
- wade19990814-hue
- wviana (Wesley Viana)
Also a separate thank-you to Bernardxu123
for designing the project logo (see docs/brand/), and to
AIGC Link for promoting the project on XiaoHongShu.
MIT — see LICENSE
Built by the community at esengine/DeepSeek-Reasonix
Videos
the ONLY way to run Deepseek...
NetworkChuck · 1224K views
DeepSeek’s New AI Is A Game Changer
Two Minute Papers · 310K views
What people are saying
“Reasonix 1.0: a ground-up Go rewrite is now the default — **Reasonix 1.0 is a ground-up rewrite in Go**, and it is now the project's default branch (`main-v2`). This is not an incremental upgrade of the `0.x` TypeScript …”
GH↑ 5esengine↗
“能不能增加移动端？”
GH↑ 3ook826092-cloud↗
“希望能添加会话恢复功能 — 功能请求 Reasonix 退出后，之前的会话内容完全丢失，无法像 Claude Code 的 `/resume` 命令那样恢复之前的对话上下文。 使用场景 - 长时间编码会话中需要关机/重启 - 不小心关闭了终端窗口 - 想要在不同终端之间切换继续同一段对话 期望行为 支持类似 `/resume` 的会话恢复命令，退出后重新进入能选择恢复之前的对话。 替代方案 目前只能靠终端的历史…”
GH↑ 2peihuaLJH↗
“聊天气泡功能建议 — 我建议在己方的气泡下方添加“copy”，“edit”功能，就像codex那样，比较方便”
GH↑ 2jiuzaizhezheer↗
“Add user_id Data Isolation for Reasonix System — Overview Reasonix currently shares all user sessions, memory, task and API request resources globally without user_id isolation. When serving multiple end-users under one …”
GH↑ 2zeroro88↗
“A permanent 75% discount on the high-performance Chinese AI 'DeepSeek-V4-Pro' is being offered, and attention is also being drawn to 'Reasonix,' a coding agent specifically designed for DeepSeek. - GIGAZINE — GIGAZINE”
NEWSGIGAZINE↗
You might also like
AI
career ops
Companies use AI to filter candidates. I just gave candidates AI to choose companies. Career-Ops (career-ops.org, also known as careerops) turns any AI coding CLI into a full job search command center. Instead of manually tracking applications in a spreadsheet, you get an AI-powered pipeline that: Career-ops is agentic: Claude Code navigates career pages with Playwright, evaluates fit by reasoning about your CV vs the job description (not keyword matching), and adapts your resume per listing.
AI
CLI Anything
CLI-Anything: Bridging the Gap Between AI Agents and the World's Software 🌐 CLI-Hub: pip install cli-anything-hub then cli-hub install — browse, install, and manage all community-built CLIs. Want to add your own? Open a PR — the hub updates instantly. 🎬 See Demos: Watch AI agents use generated CLIs plus preview, live preview, and trajectory loops to produce real artifacts — CAD builds, 3D scenes, diagrams, gameplay, subtitles, and more.
AI
odysseus
A self-hosted AI workspace -- meant to be the self-hosted version of the UI experience you get from ChatGPT and Claude. But with more jank and fun. Running on your own hardware, with your own data -- local-first, privacy-first, and no trojan. A full, hover-to-play tour lives on the landing page (docs/index.html). Defaults work out of the box: clone, run, then configure models/search/email inside Settings. Only edit .env for deployment-level overrides like APPBIND, APPPORT, AUTHENABLED, DATABASEURL, or a pre-seeded admin password.
AI
ai engineering from scratch
Most AI material teaches in scattered pieces. A paper here, a fine-tuning post there, a flashy agent demo somewhere else. The pieces rarely line up. You ship a chatbot but can't explain its loss curve. You hook a function to an agent but can't say what attention does inside the model that's calling it. This curriculum is the spine. 20 phases, 503 lessons, four languages: Python, TypeScript, Rust, Julia. Linear algebra at one end, autonomous swarms at the other. Every algorithm gets built from raw math first. Backprop. Tokenizer. Attention. Agent loop. By the time PyTorch shows up, you already know what it's doing under the hood. Each lesson runs the same loop: read the problem, derive the math, write the code, run the test, keep the artifact. No five-minute videos, no copy-paste deploys,