DeepSeek-Reasonix Terminal Coding Agent Setup SOP

DeepSeek's prefix cache pricing makes long-session coding agent costs bifurcate: cache-hit input costs only 0.02 yuan per million tokens, while cache-miss input costs 1 yuan--a 50x gap. The same long-context programming task can cost an order of magnitude more depending on how well you manage the session.

But mainstream terminal coding agents (Claude Code, Codex, etc.) are not optimized for DeepSeek's cache mechanism. They are designed for general-purpose models: system prompts, tool lists, and context window maintenance are not tuned for prefix cache stability. The result is you pay DeepSeek's API costs but eat cache-miss rates.

Reasonix fills this gap--a community-built DeepSeek-native terminal coding agent (not an official DeepSeek product, repo esengine/DeepSeek-Reasonix) tuned around DeepSeek's prefix cache to keep long-session token costs low. This SOP walks through the full flow from installation to cache tuning to dual-model configuration. All commands are from the README; config examples are labeled as illustrative with a caveat to consult official docs.

1. The Problem: Why Long-Session Costs Spiral

First, DeepSeek's pricing model (from DeepSeek's official documentation):

Cache hit vs. miss is a 50x difference. A long-session programming task easily accumulates tens of thousands of tokens across system prompt + tool definitions + conversation history. If every turn triggers a cache miss (prefix changed), costs multiply by 50.

When does the cache fail? When the request's prefix (the leading tokens up to a certain position) changes. Common causes:

• System prompt modified mid-session
• Tool list order changed or tools added/removed
• Context compression losing the original prefix structure
• New content inserted mid-conversation shifting the prefix

Claude Code and Codex are general-purpose coding agents that do not specifically align with DeepSeek's prefix cache rules. Reasonix's cache-aware mechanism is designed to fill this gap.

2. Preparation: Install Reasonix and Get a DeepSeek API Key

Reasonix is a Go single-binary tool (CGO_ENABLED=0, sole dependency is a TOML parser) with cross-compilation support for 6 targets (darwin / linux / windows x amd64 / arm64). Choose your installation path by platform.

Path A: npm global install (any OS, simplest)

npm i -g reasonix

Path A alternative: macOS Homebrew

brew install esengine/reasonix/reasonix

Path D: Build from source (requires Go)

git clone https://github.com/esengine/DeepSeek-Reasonix.git
cd DeepSeek-Reasonix
make build    # produces bin/reasonix
make cross    # cross-compiles 6 targets, produces dist/

Verify installation:

reasonix --help

If you also want the desktop app (Path B) or VS Code extension (Path C), you must complete Path A first. The VS Code extension ID is SivanLiu.reasonix-agent; it launches a local reasonix acp backend.

Next, prepare your DeepSeek API key. Obtain one from the DeepSeek open platform, then set it as an environment variable (replace with your real key):

export DEEPSEEK_API_KEY=your_key

The exact environment variable name follows the reasonix setup interactive prompt.

3. Configuration: reasonix setup and reasonix.toml

After installation, the first step is to initialize configuration:

reasonix setup

reasonix setup guides you through configuring a provider and model. DeepSeek is the preset provider--select it and enter your API key. Once configured, launch the interactive TUI:

reasonix

Reasonix's core philosophy is config-driven: everything is declared in a reasonix.toml file, with no hardcoded models. The README explicitly states that reasonix.toml manages the following conceptual sections:

• providers: API endpoint configuration. DeepSeek is preset; any OpenAI-compatible endpoint works with a single config entry.
• agent: agent behavior configuration.
• enabled tools / plugins: the list of enabled built-in tools and external plugins.

The README does not fully document reasonix.toml field definitions. The following is an illustrative structure based on the conceptual sections mentioned in the README; exact field names and defaults are subject to the official GUIDE / SPEC docs:

# reasonix.toml illustrative structure
# Based on conceptual sections mentioned in README, not a complete field definition
# Exact fields per official GUIDE / SPEC docs

# [providers] section
# DeepSeek is the preset provider
# Any OpenAI-compatible endpoint works with one config entry

# [agent] section
# agent behavior configuration

# enabled tools / plugins
# Built-in tools (self-registered at compile time) and external plugins (MCP-compatible)

For the full command list, run reasonix --help.

4. Cache Tuning: Maximizing Prefix Cache Hit Rate

This is Reasonix's core differentiator from general-purpose coding agents. DeepSeek's prefix cache requires the request prefix to remain stable to qualify for the 0.02 yuan hit rate. Reasonix's cache-aware mechanism maintains prefix stability at three levels:

1. Stable Environment Summary Injection

Reasonix injects a stable environment summary at startup that remains constant throughout the session, forming a stable base for the prefix cache. As long as this prefix does not move, subsequent request prefixes hit the cache.

2. Stale Tool Output Pruning

When the conversation grows long and summary compression is needed, Reasonix prunes stale tool output before compressing rather than bluntly truncating history. This preserves the integrity of the prefix structure, preventing prefix shifts from cache invalidation.

3. Tool Schema Contracts

Built-in tools self-register at compile time, with schema contracts documented for regression review. This means tool definitions are stable and predictable--they will not change mid-session and destabilize the prefix.

Practical reference table:

Core formula: cache hit 0.02 yuan vs. miss 1 yuan, a 50x gap. Reasonix's cache-aware mechanism keeps you on the hit side.

5. Advanced: Dual-Model executor + planner

Reasonix supports an optional dual-model mode: executor and planner run in two independent, cache-stable sessions.

Why split into two sessions? Different tasks have different context needs:

• planner: responsible for planning, needs a global view, larger context
• executor: responsible for executing specific coding tasks, more focused context

In a single session, the planner's planning context and the executor's execution context interfere with each other, causing the prefix to shift frequently and the cache to miss. Split into two independent sessions, and each maintains a stable prefix with a higher hit rate.

Illustrative dual-model config in reasonix.toml (exact fields per official docs):

# Illustrative: dual-model executor + planner, separate sessions
# Each is independent and cache-stable
# DeepSeek is the preset model; different OpenAI-compatible endpoints also work
# Exact config fields per official GUIDE / SPEC docs

Dual-model is not required--single model (DeepSeek preset) covers most scenarios. Enable dual-model when you notice planning and execution interfering in a single session and cache hit rate dropping.

6. MCP Plugins: Connecting External Tools

Reasonix's plugin mechanism is MCP-compatible: external tools run as subprocesses communicating via stdio JSON-RPC. Built-in tools self-register at compile time; external tools are connected through the plugin system.

This means you can connect existing MCP servers (file system, database, search, etc.) to Reasonix, extending the agent's capability boundary. Plugins are declared in the enabled tools / plugins section of reasonix.toml.

Exact plugin configuration fields are per the official docs. Run reasonix --help for the full command list.

7. Complete Workflow

Putting it all together, a typical Reasonix coding workflow:

1. npm i -g reasonix               # Install
2. export DEEPSEEK_API_KEY=your_key # Set API key
3. reasonix setup                   # Configure provider + model
4. reasonix                         # Launch TUI
5. Describe your task in the TUI    # Agent begins planning
6. Agent executes coding tasks     # cache-aware keeps prefix stable
7. Review agent output              # Human confirmation

Advanced workflow (dual-model):

1. Complete Path A install + reasonix setup
2. Configure executor + planner dual-model in reasonix.toml (illustrative, fields per official docs)
3. Launch reasonix; planner + executor run in separate sessions
4. Each session's prefix is independently stable, maximizing cache hit rate

8. Pitfall Log

Pitfall 1: Reasonix is not an official product, no SLA. Reasonix is a community-built tool (repo esengine/DeepSeek-Reasonix), not an official DeepSeek product. There is no official SLA. Production use carries risk; track the repo's issues for stability.

Pitfall 2: Frequently changing the system prompt destroys the cache. Prefix cache requires prefix stability. If you modify the system prompt or add/remove tools mid-session, the prefix changes and the cache misses, jumping from 0.02 yuan to 1 yuan. Reasonix's cache-aware mechanism helps maintain stability, but frequent manual changes still invalidate it.

Pitfall 3: You must bring your own DeepSeek API key. Reasonix is a client-side tool with no bundled model access. You must obtain an API key from the DeepSeek open platform and configure it via environment variable.

Pitfall 4: Desktop app / VS Code extension depends on Path A. Path B (desktop app) and Path C (VS Code extension) cannot be used standalone--you must complete Path A (CLI / TUI install) first. The VS Code extension launches a local reasonix acp backend.

Pitfall 5: Do not copy the illustrative config structure verbatim. The reasonix.toml illustration in this article only reflects the conceptual sections mentioned in the README (providers / agent / enabled tools / plugins), not a complete field definition. Always consult the official GUIDE / SPEC docs for actual field names and defaults before writing your config.

9. FAQ

Q1: Reasonix or Claude Code? Claude Code is Anthropic's official terminal agent, optimized for Claude models. Reasonix is a community-built DeepSeek-native terminal agent, tuned for DeepSeek's prefix cache. If you primarily use DeepSeek and care about long-session costs, Reasonix's cache-aware mechanism keeps you at the 0.02 yuan hit rate. If you use Claude models, Claude Code is the native choice. They are not mutually exclusive--use each for its respective model.

Q2: How is cache hit calculated? DeepSeek's prefix cache: when a request's prefix (the leading tokens up to a position) matches a previous request, that portion uses the cache-hit rate (0.02 yuan / million tokens); non-matching portions use the miss rate (1 yuan). Reasonix maintains prefix stability by injecting a stable environment summary, pruning stale tool output, and fixing tool schemas to maximize hit rate.

Q3: Can it connect to MCP? Yes. Reasonix's plugin mechanism is MCP-compatible: external tools run as subprocesses via stdio JSON-RPC. Built-in tools self-register at compile time; external MCP servers are declared in the enabled tools / plugins section of reasonix.toml. Exact configuration fields per official docs.

Q4: Does it work on Windows? Yes. npm i -g reasonix supports Windows; building from source with make cross produces windows amd64 / arm64 targets. Reasonix is a CGO_ENABLED=0 single binary with no CGO dependency, running directly on Windows.

Q5: How to configure dual-model executor + planner? Dual-model is an optional mode: executor and planner run in two independent sessions, each with a stable prefix. Configuration is declared in reasonix.toml (exact fields per official GUIDE / SPEC docs). DeepSeek is the preset model; different OpenAI-compatible endpoints also work. Single model covers most scenarios; enable dual-model when planning and execution interfere and cache hit rate drops.

References

• esengine/DeepSeek-Reasonix GitHub Repository
• DeepSeek Official Pricing Documentation
• Reasonix official GUIDE / SPEC docs (per README links in the repository)