Reasonix: A Claude-Code-Style Coding Agent on DeepSeek

If you like the Claude Code way of working — a coding agent living in your terminal, reading files, running commands, fixing its own mistakes — but you'd rather pay fractions of a cent per task than a monthly subscription, this is the recipe: Reasonix, a Claude-Code-style CLI agent, pointed at DeepSeek's API.

What you end up with

You open a terminal in a project, type reasonix, and describe what you want: "add a --dry-run flag to this script and update the README." The agent reads the relevant files, edits them, runs the script to check its work, and reports back — the same loop Claude Code users know. The differences are in the plumbing:

• The brain is DeepSeek, billed per token. Two tiers cover everything: a flash model for everyday edits and glue work, and a pro reasoning model for gnarly refactors and debugging. My always-on agent stack runs on these same two tiers and cost $24.08 for a full month ($9.54 flash + $14.54 pro) — the same workload priced out at roughly $475–$915 on the flagship APIs.
• It's yours to schedule. Because there's no seat license, you can leave it grinding through long busy-work — batch refactors, test writing, documentation passes — without watching a usage meter.
• State lives in your home directory. Reasonix keeps a dotfolder (~/.reasonix/) with its config file plus per-project session history and memory, so it remembers context per repo across runs.

Step 1: install

It's an npm global package:

npm install -g reasonix
reasonix --version

That's the entire install. If you keep Node under a nonstandard prefix, note the full path to npm — you'll want it again for the updater in step 4.

Step 2: point it at DeepSeek

Create an API key on DeepSeek's platform site (pay-as-you-go; my whole agent stack's first eleven days of July came to $2.23). Then describe the provider in ~/.reasonix/config.toml:

# ~/.reasonix/config.toml — the shape, not a paste of mine
default_model = "deepseek-flash"

[[providers]]
name        = "deepseek"
base_url    = "https://api.deepseek.com"
models      = ["deepseek-v4-flash", "deepseek-v4-pro"]
api_key_env = "DEEPSEEK_API_KEY"    # NAME of the variable, not the key itself

Field names vary between agent CLIs, but every one of them reduces to the same triple: base URL, credential, model id(s). Two hygiene rules regardless of tool:

• chmod 600 anything holding the key, and never pass it on a command line — it ends up in shell history and ps output. The api_key_env indirection exists precisely so the secret and the config can be handled differently: the config is a file you might paste into a chat for help, the .env is not.
• Declare both tiers. Flash-for-default, pro-for-hard is the whole cost story: most turns are cheap, and you escalate only when the model is visibly struggling.

Step 3: subagents and skills

Subagents are scoped workers the main agent spawns — "search the codebase for every caller of this function" — and on per-token billing they're also the cost lever, since workers can run the flash tier while the orchestrator thinks on pro. Skills are instruction files the agent loads on demand, so a deploy procedure or a test-writing convention gets written down once instead of re-explained every session.

Current versions let you set that routing explicitly rather than hoping the defaults are sensible, and this is the config block worth understanding, because it is the bill:

[agent]
# planner_model  = "deepseek-pro"    # two-model collaboration: pro plans, flash executes
# subagent_model = "deepseek-pro"    # default tier for spawned workers
# subagent_models = { review = "deepseek-pro", security_review = "deepseek-pro" }
# recovery_model = "deepseek-pro"    # steps in when a turn fails

The per-skill map on the third line is the useful one. Most delegated work — grep this, rename that, write the obvious test — is flash work. A code review or a security pass is not; those are exactly the tasks where a cheap model produces confident, plausible, wrong output. Naming the few skills that deserve the expensive tier gets you the good judgement where it matters and leaves everything else cheap, which is a better trade than picking one tier for all subagents.

Step 4: keep it updated on a schedule

Agent CLIs move fast, and a stale one misses tool fixes. There's now a built-in for this, which is the right first answer:

reasonix upgrade

with the track selected in config:

[cli]
update_channel = "stable"   # stable | preview

If you'd rather it happen without you, schedule it. Mine runs unattended and the CLI is currently on v1.18.0 without my having thought about it. The script below wraps npm directly, which is still worth reading even if you use the built-in, because a naive npm update -g on a timer has two failure modes worth guarding:

#!/usr/bin/env bash
set -euo pipefail
LOG="$HOME/logs/update-reasonix.log"
NPM="$(command -v npm)"

# 1. Lock guard — two overlapping npm runs corrupt the install
exec 9>"${LOG%.log}.lock"
flock -n 9 || { echo "update already running"; exit 0; }

# 2. Log rotation — cron logs grow forever unless you trim them
[ -f "$LOG" ] && tail -n 5000 "$LOG" > "$LOG.tmp" && mv "$LOG.tmp" "$LOG"

echo "before: $("$NPM" list -g reasonix --depth=0 | grep reasonix)" >> "$LOG"
"$NPM" update -g reasonix >> "$LOG" 2>&1
echo "after:  $("$NPM" list -g reasonix --depth=0 | grep reasonix)" >> "$LOG"

Wire it to cron or a systemd timer — either works. Logging the version before and after matters more than it looks: when the agent's behavior changes overnight, the log tells you whether an update did it.

Using it on a real project

Everything above is global setup. The thing that makes an agent CLI actually useful is the per-project layer, and Reasonix resolves config in a specific order worth knowing:

flag  >  ./reasonix.toml  >  ~/.reasonix/config.toml  >  built-in defaults

So a reasonix.toml committed at the root of a repo becomes that project's standing instructions, while your global file keeps the credential and your personal preferences. Some fields are deliberately global-only — the update channel, CLI preferences — so a repo you cloned can't quietly change how your installation updates itself. That's a sensible boundary, and it's the reason a per-project file is safe to accept from someone else.

Session state and memory are scoped per project too, under ~/.reasonix/projects/<project>/sessions/. Launch it from a project directory rather than your home folder and you get continuity per repo — it remembers what it learned about that codebase last time instead of starting cold. Launching from $HOME works, but you get one undifferentiated pile of context, which is worth avoiding if you work across several repos.

What I'd put in a project file, in rough order of payoff:

• The build and test commands. The single highest-value line. An agent that knows how to verify its own work stops guessing.
• The escalation map — the subagent_models block from above, tuned per repo. A project with a security surface wants a different default from a static site.
• The things it must not do. Deploy gates, files it may never touch, "never run this against production." Write it down once.
• Skills for anything procedural — the deploy runbook, the release checklist — so the procedure lives in the repo instead of in your memory.

For worked examples of the kind of project this suits, the self-hosted chat app, the backup GUI, and the WordPress-to-static rebuild are all the same shape: a defined codebase, a real verification command, and a gate before anything ships.

Bonus: put it in your chat app

A terminal agent doesn't have to stay in a terminal. Because Reasonix is just a CLI on a PTY, you can stream it into a web UI with xterm.js and use it from any device on your network. My self-hosted chat app does exactly that — Reasonix appears as a "terminal bot" alongside the regular chat agents, with start/restart/stop controls. The whole setup is written up in DisPatch: a self-hosted AI chat.

Gotchas

• Reasoning models look stalled before they answer. The pro tier streams its thinking before the reply; if a wrapper or gateway around the agent has a short idle timeout, long thinks get killed mid-thought. Raise the timeout, don't blame the model.
• Never put the key in argv. Config file (chmod 600) or environment file only. Command-line flags leak via history and process lists.
• Pin your npm path in the updater. Cron runs with a minimal PATH; npm in an interactive shell and in cron can resolve differently. Hard-code or resolve it explicitly in the script.
• Lock your update job. Without flock, a slow npm registry plus an eager schedule eventually gives you two concurrent global installs and a broken CLI.
• Watch the escalation habit. Pay-per-token stays cheap only if flash is the default. If every task runs on pro "just in case," you've reinvented the subscription — track spend for the first week.
• Session folders grow. Per-project history is great until a chatty agent has months of it; prune the dotfolder's session data occasionally.
• Config schemas move under you. This tool carries a config_version marker precisely because the shape changes between releases — the credential moving out of config.toml and behind api_key_env is one such change. If the agent suddenly can't authenticate after an update, check the config shape against the current docs before you regenerate your key.
• Resuming an old session isn't free. Reopening a conversation after the provider's prompt-cache window has expired means the context gets re-sent at full price. There's a setting to prune stale tool output on cold resume; leave it on. A fresh session is often cheaper than resurrecting a stale one.

Related reading: the broader DeepSeek-everywhere wiring guide covers pointing the actual Claude Code CLI at DeepSeek's Anthropic-compatible endpoint — the same idea from the other direction.