DeepSeek-Reasonix: DeepSeek-Native AI Coding Agent for Your Terminal with Prefix-Cache Stability

DeepSeek-Reasonix is an open-source, DeepSeek-native AI coding agent designed specifically for terminal use. Unlike generic agent frameworks that treat caching as an afterthought, Reasonix engineers every layer around prefix-cache stability, enabling developers to leave the agent running for long sessions without burning through API budgets. With a real-world cache hit rate of 99.82%, flash-first cost control that keeps tasks under $0.05 per turn, and a sophisticated four-pass tool-call repair pipeline, Reasonix represents a new class of opinionated coding agents that optimize for economic sustainability rather than just capability. Built with React 19 in the terminal via Ink, it offers a modern TUI experience with live cost badges, parallel tool dispatch, and an extensible MCP bridge.

Key Insight: A real user running Reasonix for a single day processed 435 million input tokens with a 99.82% cache hit rate, reducing the cost from approximately $61 to just $12. Cache stability is not a feature you turn on; it is an invariant the entire loop is designed around.

Understanding the Architecture

The architecture diagram above illustrates the layered design of DeepSeek-Reasonix, organized around three pillars that solve problems generic agent frameworks do not even see because they were designed for different cache mechanics.

CLI / TUI Layer: The user interface is built with Ink, a React renderer for the terminal. The App.tsx root component orchestrates the entire TUI experience at approximately 1984 lines of code. The StatsPanel displays live cost and cache-hit metrics with color-coded badges: green for under $0.05, yellow for $0.05-$0.20, and red for $0.20+ per turn. The PromptInput component provides cursor-aware multi-line input. The EventLog renders historical rows with tool calls and results. The PlanConfirm, EditConfirm, and ShellConfirm modals provide review gates before destructive operations. Slash commands are implemented across 13 per-topic handler modules, each under 200 lines.

Core Engine: The CacheFirstLoop is the heart of the system, implementing Pillar 1 and Pillar 3. The DeepSeek Client handles fetch and SSE streaming to the DeepSeek API. The ToolRegistry manages tool registration, dispatch, and parallel-safe grouping. The Session Manager handles JSONL persistence and per-workspace session isolation. The Telemetry module tracks cost, cache-hit accounting, and session summaries.

Three Pillars: Pillar 1, the Cache-First Loop, partitions context into three regions: an immutable prefix containing system prompts and tool specs, an append-only conversation log that grows monotonically, and a volatile scratch area for R1 thoughts that is distilled before folding into the log. Pillar 2, Tool-Call Repair, implements four passes: flatten for dot-notation schema presentation, scavenge for recovering tool calls from reasoning content, truncation for repairing unbalanced JSON, and storm for suppressing duplicate calls. Pillar 3, Cost Control, uses flash-first defaults, turn-end auto-compaction to a 3000-token cap, /pro one-shot arming, and failure-signal auto-escalation.

Tool Ecosystem: The agent has access to eight built-in tool categories. Filesystem tools include read, list, search, edit, and write operations. The shell tool runs commands and background jobs via the JobRegistry. Web search supports Mojeek, SearXNG, and Metaso engines. Memory tools allow remembering and recalling user knowledge. Skills invoke SKILL.md playbooks. Subagents spawn isolated child loops. Plans go through a submit_plan review gate. The MCP bridge connects stdio and SSE servers.

Persistence Layer: Configuration lives at ~/.reasonix/config.json with per-project overrides under .reasonix/. Sessions are persisted as JSONL files. Usage is rolled up into usage.jsonl. Project memory and global memory store user-private knowledge.

External Integrations: The DeepSeek API provides v4-flash and v4-pro models with prefix-cache billing at approximately 10% of the miss rate. The DeepSeek V3 tokenizer is ported locally for accurate token counting. Web search integrates with Mojeek by default, with SearXNG and Metaso as alternatives.

Data Flow: The user enters a prompt through the Ink TUI. The CacheFirstLoop constructs the context with immutable prefix, append-only log, and volatile scratch. The DeepSeek Client streams the request via SSE. The model’s response is parsed for tool calls, which go through the four-pass repair pipeline. Parallel-safe tools are dispatched concurrently via Promise.allSettled. Tool results are appended to the log, and the loop continues until the task is complete or max rounds are reached.

Takeaway: Reasonix is DeepSeek-only by design. Coupling to one backend is the feature, not a limitation, because every layer is tuned to the byte-stable prefix-cache mechanic that makes long sessions economically viable.

Understanding the Features

The features diagram shows the six core capabilities of DeepSeek-Reasonix, each branching into specific sub-features that make it a production-ready terminal coding agent.

Cache-First Loop: The immutable prefix contains system prompts, tool specifications, and few-shot examples. It is computed once per session, hashed, and pinned. The append-only conversation log grows monotonically with assistant turns and tool results, preserving the prefix of prior turns. The volatile scratch holds R1 thoughts and transient plan state, which is distilled before folding into the log. Parallel tool dispatch groups consecutive parallel-safe calls into chunks and races them via Promise.allSettled, with a default max chunk size of 3 and a hard cap of 16.

Tool-Call Repair: The flatten pass auto-detects schemas with more than 10 leaf params or depth greater than 2 and presents them to the model in dot-notation form. The scavenge pass uses regex and JSON parser sweeps of reasoning_content to recover tool calls the model forgot to emit. The truncation pass detects unbalanced JSON and repairs it by closing braces or requesting a continuation completion. The storm pass suppresses identical tool-and-args tuples within a sliding window and injects a reflection turn.

Cost Control: Flash-first defaults use v4-flash with max effort as the baseline, costing 1x. The auto preset escalates to v4-pro on hard turns, costing 1-3x. The pro preset uses v4-pro at approximately 12x cost. Turn-end auto-compaction shrinks tool results exceeding 3000 tokens. The /pro command arms the next turn for pro-tier execution, visible as a yellow pill in the header. Failure-signal auto-escalation switches to v4-pro after three visible struggle events per turn.

Tool Ecosystem: Filesystem tools support read, edit, write, search files, search content, list directory, directory tree, and get file info. The shell tool runs commands with a gated allowlist and supports background jobs. Web search uses Mojeek by default with SearXNG and Metaso alternatives. Memory tools store user, feedback, project, and reference types. Skills load Markdown playbooks in inline or subagent mode. Subagents spawn isolated loops with flash+high defaults. Plans require review before execution. The MCP bridge connects stdio and SSE servers.

Session and Persistence: Sessions are persisted as JSONL files with full conversation history. Per-workspace sessions keep context isolated. Global and project memory store user-private knowledge. Usage JSONL provides cost roll-ups over time. Transcript replay allows reviewing past sessions.

UI and Experience: The Ink TUI renders React 19 components in the terminal. The live stats panel shows cost and cache-hit badges. Slash commands include /pro, /skill, /mcp, /todo, /undo, /history, and more. SEARCH/REPLACE edits require review before application. A Tauri-based desktop client is in prerelease. QQ channel integration enables remote session access.

Amazing: Reasonix’s four-pass tool-call repair pipeline addresses empirical DeepSeek failure modes that generic frameworks miss: JSON inside reasoning blocks, dropped arguments in large schemas, call storms, and truncation mid-structure.

How It Works

Reasonix operates through a cache-first agent loop that treats prefix stability as a fundamental invariant rather than an optimization. When a session starts, the system computes the immutable prefix containing the system prompt, tool specifications, and few-shot examples. This prefix is hashed and pinned for the entire session.

As the conversation progresses, each turn appends to the log without rewriting prior entries. This append-only design ensures that the byte prefix of subsequent requests matches the previous request, triggering DeepSeek’s automatic prefix caching at approximately 10% of the miss rate. The volatile scratch area holds R1 reasoning content and transient state, which is distilled before any information is folded into the log.

Tool calls are dispatched through the repair pipeline. The flatten pass simplifies complex schemas. The scavenge pass recovers forgotten calls from reasoning blocks. The truncation pass fixes incomplete JSON. The storm pass prevents duplicate invocations. Parallel-safe tools like read_file and web_search are grouped and executed concurrently, while mutating tools like write_file run serially.

Cost control operates transparently. The default flash preset keeps most turns under $0.05. When the model struggles, indicated by SEARCH-not-found errors or repair pipeline activations, the system auto-escalates to v4-pro for the remainder of the turn, announced via a yellow warning row. Users can manually arm /pro for the next turn when they anticipate a difficult task.

Important: Reasonix requires Node 22 or higher and a paid DeepSeek API key. It is not air-gapped or fully free. For zero-cost local runs, consider Aider plus Ollama or Continue.dev.

Installation

# Install globally for the reasonix command on PATH
npm install -g reasonix

# Start the coding agent in the current directory
reasonix code my-project

# Or run once without installing globally
cd my-project
npx reasonix code

# The shorter dsnix alias is also available
npm install -g dsnix
npx dsnix@latest code

On first run, paste your DeepSeek API key. It persists in ~/.reasonix/config.json for future sessions.

Grab a DeepSeek API key: https://platform.deepseek.com/api_keys

Desktop client (prerelease): Download platform installers from GitHub Releases. The desktop bundles its own Node runtime and requires no separate npm install.

Usage

Start coding:

reasonix                    # equivalent to reasonix code
reasonix code /path/to/project --dir /path/to/project

Chat mode (no filesystem tools):

reasonix chat

One-shot task:

reasonix run "Refactor the auth module to use JWT"

Health check:

reasonix doctor

Upgrade:

reasonix update

Key slash commands:

• /pro — Arm the next turn for v4-pro execution
• /skill new my-skill — Create a SKILL.md playbook
• /mcp add — Add an MCP server
• /todo — Manage task lists
• /undo — Revert the last edit
• /history — Show edit history
• /search-engine — Switch web search provider

Features

Feature	Description
Cache-First Loop	Immutable prefix + append-only log + volatile scratch for 99%+ cache hits
Tool-Call Repair	Four-pass pipeline: flatten, scavenge, truncation, storm
Cost Control	flash-first defaults, auto-compaction, /pro arming, failure escalation
Parallel Dispatch	Promise.allSettled for parallel-safe tools with serial barriers
Filesystem Tools	read, edit, write, search, list, tree, info
Shell Tool	run_command with gated allowlist + background jobs
Web Search	Mojeek default, SearXNG and Metaso alternatives
Memory	user, feedback, project, reference types
Skills	Markdown playbooks in inline or subagent mode
MCP Bridge	stdio and SSE server connections
Session Persistence	JSONL per-workspace sessions
Ink TUI	React 19 terminal UI with live cost badges
Desktop Client	Tauri-based GUI in prerelease
QQ Channel	Remote session integration

Conclusion

DeepSeek-Reasonix is a bold reimagining of what a terminal coding agent can be when economic sustainability is treated as a first-class design goal. By engineering every layer around DeepSeek’s prefix-cache mechanic, the project achieves cache hit rates above 99% and keeps typical tasks under a few cents. The three-pillar architecture, four-pass tool-call repair, and transparent cost control mechanisms demonstrate that opinionated, backend-specific design can outperform generic frameworks on the metrics that matter for daily use. With an active open-source community, comprehensive benchmarks, and a growing ecosystem of skills and MCP integrations, Reasonix is positioned as a serious alternative to closed-source coding agents for developers who want control, transparency, and affordability.

Links:

• GitHub Repository: https://github.com/esengine/DeepSeek-Reasonix
• Website: https://esengine.github.io/DeepSeek-Reasonix/
• Configuration Guide: https://esengine.github.io/DeepSeek-Reasonix/configuration.html
• Architecture Docs: https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/ARCHITECTURE.md
• Discord Community: https://discord.gg/XF78rEME2D

Enjoyed this post? Never miss out on future posts by following us