AI/reasonix.md

Table of Contents

Reasonix

reasonix is an MIT-licensed, DeepSeek-only AI coding agent that runs in your terminal. It's engineered around DeepSeek's prefix-cache mechanic for dramatically lower costs.

reasonix code vs reasonix chat

reasonix has two modes — the only difference is tool access:

Mode Command Tools available What it's for
code npx reasonix code Filesystem (read/write/search), git, MCP, full tool suite Development work — explore codebases, edit files, run commands
chat npx reasonix chat (or just npx reasonix) None by default (web search only) Conversation — answer questions, write, brainstorm, research

Same underlying model in both modes. code unlocks the toolchain for development; chat is a pure conversational interface with no codebase access.

Quick start

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

Requires Node ≥ 22. Works on macOS, Linux, and Windows (PowerShell, Git Bash, Windows Terminal).

Cost comparison

Reasonix Claude Code Cursor Aider
Backend DeepSeek V4 Anthropic OpenAI / Anthropic any (OpenRouter)
Cost / typical task ~¥0.01–0.04 ~¥0.40–4 ¥150/mo + usage varies
DeepSeek prefix-cache hit 94% (live) n/a n/a ~33% (baseline)

How the cache works

DeepSeek's prefix-cache is byte-stable — the cache fingerprints from byte 0 of the prompt. reasonix's loop is designed around append-only growth (no re-ordering, no marker-based compaction), so the cache prefix survives every tool call. At $0.07/Mtok uncached / $0.014/Mtok cached, the difference between 50% and 94% hit rate is roughly 2.5× on input cost alone.

DeepSeek-specific fixes reasonix handles

Problem reasonix's fix
R1 leaks tool-call JSON inside <think> tags Scavenge pass pulls escaped tool calls back out
DeepSeek silently drops deeply-nested object/array params Auto-flatten — nested params rewritten to single-level prefixed names
Malformed args like string="false" ToolCallRepair heals common shapes before dispatch
V4's reasoning_effort knob (max / high) /effort slash command + --effort flag for cheap turns

Key features

  • Plan mode — propose changes for review before they touch disk
  • Edit review — SEARCH/REPLACE blocks gated by user approval per edit
  • MCP first-class — built-in MCP client with stdio + SSE transports
  • Embedded web dashboard — companion UI for session history, stats, and visualization
  • Persistent per-workspace sessions — resume where you left off
  • Memory & skills — project-level and user-level memory, reusable skill playbooks
  • Hooks — pre/post tool-call hooks for custom automation
  • Permissions — allow / ask / deny per tool

API key

Get a key at platform.deepseek.com/api_keys. The key is stored locally after the first npx reasonix code run.

Config & MCP

reasonix stores all its configuration at ~/.reasonix/config.json. The file is a flat JSON object — here's what it looks like:

{
  "editMode": "auto",
  "editModeHintShown": true,
  "mouseClipboardHintShown": true,
  "preset": "pro",
  "mcp": [
    "qwestly=node /Users/dominick/Work/llm/qwestly-mcp-dev/src/index.js",
    "notes=node /Users/dominick/Work/notes/mcp/src/index.js",
    "asana=npx -y mcp-remote@latest https://mcp.asana.com/v2/mcp 3334 --static-oauth-client-info ...",
    "granola-local=node /Users/dominick/Work/llm/granola-local-mcp/dist/index.js",
    "desktop-commander=node /Users/dominick/Work/llm/DesktopCommanderMCP/dist/index.js"
  ]
}

Key points:

  • mcp is a top-level key — an array of MCP server definition strings, each in name=command args... format.
  • No separate mcp.json — everything lives in one config.json.
  • No mcpServers wrapper object — unlike Claude Code's claude_desktop_config.json, Reasonix uses a flat array keyed directly as "mcp".
  • The file is auto-managed — Reasonix writes to it when you add/remove MCP servers or change settings.
  • API key is stored elsewhere (not in this file) — Reasonix manages it separately.

Workflow (local setup)

We run a locally-patched reasonix that listens on 0.0.0.0 instead of 127.0.0.1. For daily development, SSH into the dev terminal and run npx reasonix code — the TUI works fine over SSH.

When a web UI is more convenient (e.g. on a tablet or another machine):

  1. Launch npx reasonix code — it prints the local port (e.g. 4321).
  2. Expose it via our proxy command:
    proxy expost {PORT} {optional_alias}
  3. Open http://{alias}.dph.am from anywhere — or the auto-generated subdomain if no alias is given.

This works because the patched server binds 0.0.0.0:PORT, so the proxy can reach it from outside localhost.

Prefix caching: Reasonix vs Claude Code

Both tools exploit caching to dramatically cut costs, but the mechanisms are fundamentally different:

Dimension Reasonix (DeepSeek) Claude Code (Anthropic)
Cache trigger Auto — exact byte-for-byte prefix match from position 0 Explicit — cache_control breakpoints you set in the prompt
Granularity All-or-nothing per prefix (mutate anything → miss) Per-section — system prompt, tool defs, conversation turns cached independently
Cache stability Brittle — any change to the leading prefix (even whitespace) nukes the cache More flexible — you can break cache at strategic points without losing earlier sections
Architecture fit The entire loop is designed around the cache (append-only growth, no compaction) Cache is a user-facing API feature, not the architecture's foundation
Savings ~80% on cached input ($0.014/Mtok vs $0.07/Mtok) 50-90% on cached sections (cached reads ~10% of normal rate)
How to maximize Keep the prompt prefix byte-identical across calls (no re-ordering, no markers, append only) Put static content first, use cache_control breakpoints, avoid dynamic elements in cached zones

Practical implications

  • Reasonix's approach is automatic and invisible — you don't need to think about it as long as you don't mess with the prefix. The "append-only loop" pattern is the optimization.
  • Claude Code's approach is more flexible — you can selectively cache system prompts, tool schemas, or long context files independently. But you have to be intentional about placing cache_control markers.
  • If you're running Claude Code with a DeepSeek backend (via Anthropic-compatible endpoint), prompt caching doesn't work — DeepSeek's byte-stable prefix-cache is incompatible with Anthropic's ephemeral cache markers. You get the tool suite but lose cached input pricing.

DeepSeek's pricing lever

At DeepSeek's scale ($0.07/Mtok uncached / $0.014/Mtok cached), the difference between a 50% cache hit rate and Reasonix's 94% is roughly 2.5× on input cost alone. Reasonix's design is basically: make the cache hit impossible to miss.

Limitations

  • DeepSeek-only by design — every layer is tuned around DeepSeek's cache mechanic. Multi-provider is not a goal.
  • Terminal-first — no IDE integration. The dashboard is a companion, not a Cursor replacement.
  • Paid API required — needs a DeepSeek API key. Not air-gapped / free.
  • Hardest-leaderboard reasoning — Claude Opus still wins some benchmarks. DeepSeek V4 is competitive on coding; for pure reasoning challenges Claude may still be stronger.

MCP Prompts in Reasonix

Reasonix does not have a native /prompt command that sources external .md files and executes them. Typing /prompt code-review only prints the file contents — it doesn't "run" the prompt.

What's available instead

Command / action What it does
/skill <name> Runs a built-in Reasonix playbook (e.g. /skill explore, /skill review, /skill test)
run_skill({ name, arguments }) Same, from tool-call context
Ask the assistant in prose Say "Run the code-review prompt from my prompts dir" — the assistant reads the file and follows its instructions step-by-step

Using your MCP prompt collection

Your prompts live at ~/Work/llm/mcp-prompts/prompts/ and include:

  • code-review.md
  • security-review.md
  • accessibility-audit.md
  • write-unit-tests.md
  • optimize-performance.md
  • add-documentation.md
  • add-error-handling.md
  • generate-pr-description.md
  • create-pr.md
  • git-commit.md
  • diagrams.md
  • visualize.md
  • deslop.md
  • generate-api-docs.md

Three ways to run them

A — Inline (works right now) — Just tell the assistant: "Run the <prompt-name> prompt from my prompts dir." The assistant loads the file and executes its instructions (git diff, analysis, etc.).

B — Register as Skills — Copy the prompts into .reasonix/skills/ so /skill code-review works natively. Requires a one-time setup.

C — Display + execute — Type /prompt code-review to see the instructions, then say "do that" and the assistant acts on them.

Skills

Skills are playbooks I can invoke with run_skill. Entries tagged [🧬 subagent] spawn an isolated subagent — a fresh child loop that runs the playbook in its own context and returns only the final answer.

Skill Tag Description
explore [🧬 subagent] Read-only investigation across the codebase — returns one distilled answer. Use for "find all places that…", "how does X work across the project".
research [🧬 subagent] Web search + code reading combined. Best for "is X supported by Y", "what's the canonical way to Z".
review [🧬 subagent] Review pending changes (current branch diff) — flags correctness, security, and general issues.
security-review [🧬 subagent] Security-focused review of the current branch diff — flags injection, authz, sensitive-data exposure.
gh-pr-review inline GitHub PR review — fetch diffs, run code review prompts, and post inline or full comments via the gh CLI.
gog inline Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets, and Docs.
nextjs-developer inline Expert Next.js developer — App Router, server components, server actions, performance & SEO.
pdf-to-markdown inline Convert entire PDF documents to clean, structured Markdown for full context loading.
software-architecture inline Guide for quality-focused software architecture design and coding.
svg-precision inline Deterministic SVG generation, validation, and rendering — icons, diagrams, charts, UI mockups.
sync-claude-skills inline Sync skills from ~/.claude/skills/ into ~/.reasonix/skills/ — copies new Claude playbooks over.
test inline Run the project's test suite, diagnose failures, propose fixes, re-run until green.
ui-ux-pro-max inline UI/UX design intelligence — 50 styles, 21 palettes, 50 font pairings, 20 charts, 8 stacks.