May 26, 2026 · 7 min read

How to Use Reasonix: Complete Setup Guide for DeepSeek's Coding Agent

This is the step-by-step setup guide for Reasonix, the DeepSeek-native coding agent that achieves 99.82% cache hit rates. By the end of this guide you will have Reasonix installed, configured, and running your first coding session.

If you want the full feature overview and comparison with other tools, see our Reasonix complete guide. This article focuses purely on getting you productive as fast as possible.

Prerequisites

You need three things:

Node.js >= 22. Check your version:

node --version

If you are below v22, upgrade via nvm:

nvm install 22
nvm use 22

A DeepSeek API key. Get one from platform.deepseek.com. See our DeepSeek V4 API guide for the full walkthrough on account creation and key generation.
A terminal. Reasonix runs in any terminal on macOS, Linux, or Windows (PowerShell or WSL).

Installation

Two options:

Global install (recommended for daily use):

npm install -g reasonix

Run without installing (try it first):

npx reasonix code

Verify the installation:

reasonix --version

You can also use the shorter alias:

dsnix --version

API key configuration

Set your DeepSeek API key. Three methods, pick one:

Environment variable (recommended):

# Add to ~/.bashrc, ~/.zshrc, or equivalent
export DEEPSEEK_API_KEY=sk-your-key-here

Global config file:

mkdir -p ~/.reasonix
cat > ~/.reasonix/config.json << 'EOF'
{
  "apiKey": "sk-your-key-here"
}
EOF

Per-project config:

mkdir -p .reasonix
cat > .reasonix/config.json << 'EOF'
{
  "apiKey": "sk-your-key-here"
}
EOF

Run the doctor

Before your first session, verify everything works:

reasonix doctor

This checks:

Node.js version (must be >= 22)
API key presence and validity
Network connectivity to DeepSeek’s API
Config file syntax
Git availability (for checkpoints)

Fix any issues it reports before continuing.

Your first session

Navigate to a project directory and start:

cd ~/projects/my-app
reasonix code

Reasonix will:

Scan your project structure
Build a semantic index (first run takes a few seconds)
Load any memory files from .reasonix/memory.md
Present an interactive prompt

Type your request:

> Add a health check endpoint at GET /health that returns { status: "ok", timestamp: ... }

Reasonix reads your existing code, identifies the right files, and makes the changes. It shows you what it plans to do (if plan mode is on) or directly edits files.

Follow up naturally:

> Also add a readiness check at /ready that verifies the database connection

The session maintains full context. Each follow-up builds on previous work.

Essential commands

These slash commands work inside any Reasonix session:

Command	What it does
`/pro`	Switch to V4 Pro for the next turn
`/preset max`	Switch entire session to V4 Pro
`/preset default`	Switch back to V4 Flash
`/plan`	Toggle plan mode on/off
`/effort low`	Minimal reasoning, fast responses
`/effort high`	Deep reasoning, slower but thorough
`/clear`	Clear conversation context
`/checkpoint`	Create a manual git checkpoint
`/undo`	Revert to last checkpoint
`/web "query"`	Search the web
`/skill name`	Run a saved skill
`/help`	Show all available commands

Modes explained

Code mode (default)

reasonix code

Full access to your filesystem. Reads files, writes code, runs shell commands, creates and deletes files. This is your primary working mode.

Use code mode when you want Reasonix to actually make changes to your project.

Chat mode

reasonix chat

No filesystem access. Reasonix cannot read or modify your files. It can only respond based on what you paste into the conversation.

Use chat mode for:

Architecture discussions
Code review (paste the code in)
Brainstorming approaches
Learning and explanation

Run mode (one-shot)

reasonix run "add error handling to all API routes"

Executes a single task and exits. No interactive session. Perfect for:

Scripted tasks:

reasonix run "generate TypeScript types from this OpenAPI spec" < openapi.yaml

Piped input:

git diff HEAD~1 | reasonix run "write a changelog entry for these changes"

CI/CD integration:

reasonix run "review this PR for security issues" < pr-diff.patch

Switching models: /pro and /preset

Reasonix uses V4 Flash by default ($0.07/1M input, $0.28/1M output). For complex tasks, upgrade to V4 Pro ($0.435/1M input, $0.87/1M output).

Per-turn upgrade with /pro:

> /pro
> Redesign the authentication system to support OAuth2 + PKCE flow

V4 Pro handles this single response, then Reasonix reverts to Flash for subsequent turns. Use this for individual complex questions within an otherwise simple session.

Full session upgrade with /preset max:

> /preset max

Every subsequent turn uses V4 Pro until you switch back with /preset default. Use this for:

Complex multi-file refactors
Architecture-level changes
Debugging subtle issues that Flash struggles with

Cost impact:

Flash session (30 min): ~$0.03-0.08
Pro session (30 min): ~$0.14-0.35
Single /pro turn: ~$0.02-0.05 extra

With the permanent 75% discount, even Pro sessions are remarkably cheap.

Plan mode

Plan mode makes Reasonix show its intended changes before executing them.

Enable for current session:

> /plan

Enable permanently in config:

{
  "planMode": true
}

With plan mode on, Reasonix responds to requests with a structured plan:

Plan:
1. Create src/middleware/auth.ts with JWT verification logic
2. Modify src/routes/index.ts to apply auth middleware to protected routes
3. Add JWT_SECRET to .env.example
4. Update src/types/express.d.ts with user type on Request

Proceed? [y/n/edit]

You can approve (y), reject (n), or edit the plan before execution. This is essential for:

Learning how Reasonix approaches problems
Preventing unwanted changes in sensitive codebases
Complex refactors where you want oversight

MCP server setup

Reasonix supports Model Context Protocol servers for external data access. Configure them in your project’s .reasonix/config.json:

{
  "mcp": {
    "servers": {
      "github": {
        "command": "npx",
        "args": ["@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_TOKEN": "ghp_your_token"
        }
      },
      "filesystem": {
        "command": "npx",
        "args": ["@modelcontextprotocol/server-filesystem", "/path/to/docs"]
      },
      "postgres": {
        "command": "npx",
        "args": ["@modelcontextprotocol/server-postgres"],
        "env": {
          "DATABASE_URL": "postgresql://..."
        }
      }
    }
  }
}

With MCP servers configured, Reasonix can:

Read GitHub issues and PRs directly
Query your database schema
Access external documentation
Interact with any MCP-compatible service

Tips for effective use

1. Create a memory file

Create .reasonix/memory.md in your project root:

# Project: MyApp

## Stack
- Next.js 15, TypeScript, Tailwind
- Prisma + PostgreSQL
- Jest for testing

## Conventions
- Use named exports, not default exports
- Error handling: throw AppError instances, catch in middleware
- API routes return { data, error, meta } shape
- Tests go in __tests__ adjacent to source files

## Architecture
- src/lib/ for shared utilities
- src/services/ for business logic
- src/routes/ for API handlers

This loads at the start of every session, giving Reasonix project context without you repeating it.

2. Keep sessions long

Prefix cache hits improve as sessions grow. Starting a new session resets the cache. If you are working on related tasks, keep the same session open rather than starting fresh. See how prefix caching works for the full technical explanation of why longer sessions save more money.

3. Use /effort appropriately

/effort low for simple edits, typo fixes, adding imports
/effort high for debugging, architecture decisions, complex logic

4. Use auto-checkpoints

Enable in config:

{
  "autoCheckpoint": true
}

Reasonix creates git commits at logical breakpoints. If something goes wrong, /undo reverts to the last checkpoint instantly.

5. Use hooks for automation

{
  "hooks": {
    "afterEdit": "npx prettier --write . && npx eslint --fix .",
    "afterSession": "npm test"
  }
}

This ensures every edit is formatted and linted automatically, and tests run when you end a session.

Troubleshooting

“API key invalid” error:

Verify your key at platform.deepseek.com
Check for trailing whitespace in the key
Ensure the environment variable is exported (not just set)

Slow first response:

First turn in a session has no cache. This is normal.
Subsequent turns should be faster as the cache warms up.

“Node version too low” error:

Reasonix requires Node >= 22
Run nvm install 22 && nvm use 22

Files not being found:

Run from the project root directory
Check .reasonix/ for any ignore patterns
Run reasonix doctor to verify project detection

FAQ

How much does Reasonix cost to use daily?

With V4 Flash defaults and typical cache hit rates, a full day of active coding costs $0.50-1.00. Heavy usage with V4 Pro might reach $2-3/day. Compare this to Claude Code which can easily cost $20-50/day for similar usage. See our Reasonix vs Claude Code comparison for a detailed breakdown of when each tool makes sense.

Can I use Reasonix without a DeepSeek account?

No. Reasonix requires a DeepSeek API key. Create an account at platform.deepseek.com. There is no free tier, but with V4 Flash at $0.07/1M input tokens, $10 of credit lasts weeks of normal use.

Does Reasonix support other editors or IDEs?

Reasonix is terminal-first. The prerelease desktop app (Tauri-based) provides a GUI, but there is no VS Code extension or IDE plugin. It is designed to work alongside your editor, not inside it.

How do I update Reasonix?

npm update -g reasonix

Can Reasonix run tests automatically?

Yes. Configure a hook:

{ "hooks": { "afterEdit": "npm test" } }

Or ask it directly: “run the tests and fix any failures.”

What happens if I lose internet mid-session?

Your session state is saved locally. Reconnect and continue where you left off. Persistent sessions survive terminal closures, network drops, and system restarts.

Is Reasonix safe to use on production codebases?

Yes, with plan mode and auto-checkpoints enabled. Plan mode prevents unexpected changes. Auto-checkpoints let you revert instantly. Start with plan mode on until you trust the tool’s judgment on your specific codebase.