English  ·  简体中文  ·  Website  ·  Guide  ·  Architecture  ·  Benchmarks

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.

Install

cd my-project
npx reasonix code   # paste a DeepSeek API key on first run; persists after

Requires Node ≥ 22. Works on macOS · Linux · Windows (PowerShell · Git Bash · Windows Terminal). Grab a DeepSeek API key → · reasonix code --help for flags.

npx is the recommended path — no global install, always latest. If you use Reasonix daily and want it on PATH, run reasonix update once.

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

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

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:

📘 Configuration Guide · 中文

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	Mojeek by default; switch to self-hosted SearXNG 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 (Mojeek + SearXNG)	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
• 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. The contributors wall below isn't decoration — every avatar 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 in ls. 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

---

_{MIT — see LICENSE
Built by the community at esengine/reasonix}