English  ·  简体中文  ·  Website  ·  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.

Web search

Reasonix includes web_search and web_fetch tools. By default it uses Mojeek (no setup required). You can switch to a self-hosted SearXNG instance — a metasearch engine that aggregates whatever upstream engines your instance is configured for.

Switching engines (persists to disk)

The /search-engine slash command (alias /se) writes your choice to ~/.reasonix/config.json immediately — it survives restarts:

/search-engine mojeek              # default, no external deps
/search-engine searxng             # SearXNG at http://localhost:8080
/search-engine searxng http://192.168.1.100:8888  # custom endpoint

Equivalent ~/.reasonix/config.json:

{
  "webSearchEngine": "searxng",
  "webSearchEndpoint": "http://localhost:8080"
}

The tool picks up the change on the next call — no restart needed.

Starting SearXNG

podman run -d --replace --name searxng -p 8080:8080 docker.io/searxng/searxng
# or: docker run -d -p 8080:8080 searxng/searxng

Verify it's running:

curl http://localhost:8080/search?q=test
# → HTML search results page

Note: The endpoint must include the protocol (http://). localhost:8080 alone will fail — the tool will show a clear error telling you to install SearXNG if the server is unreachable.

Install

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

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

npx is the recommended path — no global install, always picks up the latest version. If you'll use Reasonix daily and want reasonix on your PATH, run reasonix update once and it'll do the npm install -g for you.

Subcommand cheatsheet

Command	When to use
reasonix code [dir]	Coding agent rooted at a project. Start here.
reasonix chat	Plain chat — no filesystem tools, just a conversation with persisted history.
reasonix run "task"	One-shot, streams the answer to stdout. Good for shell pipes.
reasonix doctor	Environment health check (Node version, API key, MCP wiring).
reasonix update	Upgrade Reasonix itself.

Other subcommands (replay · diff · events · stats · index · mcp · prune-sessions) are listed in reasonix --help and on the CLI reference.

Working in a different folder: Reasonix scopes filesystem tools to the launch directory. To work elsewhere, pass --dir:

npx reasonix code --dir /path/to/project   # or use a relative path

Mid-session switching isn't supported by design (the message log + memory paths get tangled with stale roots). Quit and relaunch with a new --dir to retarget. /status always shows the current pinned workspace.

Author your first skill: Skills are markdown playbooks the model can invoke (/skill <name>). There's no remote registry yet — you author them directly:

/skill new my-skill          # scaffolds <project>/.reasonix/skills/my-skill.md
/skill new my-skill --global # or under ~/.reasonix/skills for cross-project use

Edit the file (description: frontmatter + body), then /skill list to see it. Add runAs: subagent to the frontmatter to spawn an isolated subagent loop instead of inlining the body.

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
• 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}