The core idea
Sage is built for inexpensive reasoning models that think for a long time, and it is tuned on DeepSeek V4.1 Flash and tested on it and GLM-5.3. On DeepSeek, reading a cached input token costs 1/50 as much as reading a fresh one and 1/200 as much as generating an output token. Context is cheap. What costs time and money is starting another turn of thinking.
At the same time, coding agents rarely fail because they cannot write code. They fail because a small mistake slips past unnoticed and the next five steps build on top of it. Sage addresses both problems with one rule: before a command runs, the model states what should happen, and the harness checks the outcome.
- PredictThe model says what should happen: exit 0, print a line, or not.
- RunSage runs the step inside the project workspace.
- CheckSage compares the real output against the prediction.
-
ReceiptMatched: the model gets a short one-line receipt instead of a wall of logs.SurpriseMismatched: remaining steps stop, and the error comes back with the relevant code lines attached.
Everything else in Sage builds on that loop: how edits are applied, how tests stay green, and how the harness verifies finished work.
Built for low cost
Sage is built to do the same work as a conventional agent loop for less: fewer turns of thinking, fewer tokens, and less waiting. Every mechanism on this page serves that aim.
On 36 Python, Rust and Go tasks with hidden tests, it solved as many as OpenCode on DeepSeek V4.1 Flash, 44 of 72 runs each, for about 40% less cost and time, and more than OpenCode on GLM-5.3 for less than half the cost. The benchmarks have the details. On your own code, results can differ from other harnesses in either direction, so the best test is your own work.
Each mechanism below was measured on and off on real tasks before it stayed, so none of them is taken on faith.
Multi-step replies
Most harnesses run a single tool call, return the output, and pay for another round of model thinking to decide the next step. In Sage, a model reply can bundle an entire sequence of steps that runs like a shell script with set -e turned on:
- Steps run in order, so each step sees the files and state left by the one before it.
- As soon as any step fails or contradicts its prediction, execution stops on the spot.
- Any remaining steps are marked as skipped with the reason, so the model knows exactly where its plan broke.
Because a broken check automatically cancels everything queued behind it, the model can safely edit code, run tests, and call finish in one turn.
# One model turn: edit the file, run the test suite, and finish.
edit src/queue.py 41kq-47px # replace the body of pop()
shell pytest -q expect_exit "0"
finish "pop() no longer drops the final item"
# If pytest fails, the script halts there and finish never runs.
When Sage shows a file, each line begins with a short tag like 41kq| — line 41 plus a two-letter hash of its text. To edit a file, the model points to those tags instead of retyping old code. If an earlier edit in the same turn shifted line numbers, Sage tracks the offset automatically; if the underlying line changed, Sage rejects the edit and shows the fresh lines instead of patching the wrong spot.
Predictions and receipts
Whenever the model runs a shell command, it can state what a healthy run looks like using one or more checks:
expect_exit- Expected exit status:
"0", a specific code,"nonzero", or"any". expect_has- Text or a
/regex/that should appear in the command’s output. expect_lacks- Text or a
/regex/that must not appear in the output.
When a predicted command succeeds as expected, Sage replaces its full stdout with a compact one-line receipt while saving the raw log on disk in case the model ever asks to inspect it. When a command contradicts its prediction, Sage strips terminal noise, keeps the tail where assertion failures live, and attaches the exact source lines mentioned in the traceback — complete with edit tags so the very next turn can fix the bug directly.
Standing watches
A watch is a background check — a test suite, build, or linter — that Sage re-runs automatically after any file change. Watches stay silent while their status stays the same and speak up the moment a passing check turns red or a failing check turns green.
The model does not need to configure watches manually. If the user’s prompt names a test command, Sage runs it before turn one and locks it in as a standing watch. Otherwise, the first real test command the model runs becomes a watch automatically. Throwaway commands in /tmp or one-off inline scripts are ignored so they never hijack the project’s real test suite.
Why watches save turns. When the model makes an edit, Sage runs the watched test suite before handing control back. The model learns immediately whether its edit worked without spending an extra turn just to re-run tests.
Ready before turn one
Instead of making the model spend its first three turns exploring the directory, checking versions, and opening obvious files, Sage gathers what it can mechanically and puts it straight into the opening message:
- Workspace snapshot: working directory, installed runtimes and tools, git branch, and any uncommitted changes already present before the session began.
- Named files pre-opened: any file paths mentioned in the prompt are attached with edit tags so the model can patch them on turn one, and whole files already shown can be replaced cleanly with
writewithout an extra confirmation round-trip. - Initial test run: if the task names a test command, its starting output is included right away.
- Small-project survey: in workspaces with up to 40 files, Sage lists every file with its line count and attaches up to 1,000 lines (up to 24 files, 250 lines per file) so small projects need zero search turns.
Finish gates and contracts
Agents often claim a task is done while subtle bugs or missing deliverables remain. Sage checks three things before accepting finish:
- Fresh evidence
- If files changed, a real check capable of failing (such as
pytestorcd app && npm test, neverecho ok) must have passed since the latest edit. Once tests pass, Sage reminds the model to make sure every rule in the task and its spec is covered before finishing. - Task contracts
- Before turn one, Sage reads the task prompt for explicit boundaries — files marked “Do not edit…” or “Do not change any code”, and required outputs like “Write
findings.json” or “Createroman.py”. Protected files are hashed up front, and required deliverables must exist at the exact requested path (and parse cleanly if JSON) beforefinishis accepted, even if no existing file was edited. This check uses zero model tokens. - Session goals
- You can set an explicit condition with
--goalor/goal. Before the session ends, a separate tool-less model call with a clean context checks the goal againstgit statusand the session’s diff, sending the worker back up to three times if anything is still unmet.
Safety valves prevent infinite loops: if the evidence gate refuses
finishtwice on the same code, the third attempt is accepted and clearly marked unverified. And one turn before a reply or time budget runs out, Sage warns the model so it can hand in a clean summary.
Effort, caching, and cost
Sage keeps conversation history strictly append-only and byte-identical from turn to turn so provider prompt caches hit reliably. Every API response is audited to distinguish a provider-side cache miss from anything the harness changed, and older tool outputs are trimmed only when token pricing math says trimming saves money over keeping the cache warm.
Reasoning effort is Auto by default, and Auto is the recommended setting. It can also be fixed at Low, High or Max.
- Auto effort starts low and scales up: sessions start at
loweffort and step up after three surprises in a row. Starting low solved just as many benchmark tasks as starting high while cutting time roughly in half. - Overthinking protection: if a turn streams nothing but internal reasoning past ~16,000 tokens (~24,000 tokens at
Maxeffort) without writing an answer or calling a tool, Sage cuts the runaway stream and retries one level lower — then restores any manually chosen effort level as soon as the model acts. After the third such cut in a row, the next reply is the run’s last.
Permissions
By default Sage acts on its own: it edits files and runs commands without asking, so a task gets done while you do something else. Set permissions to Ask first (/permissions ask in the terminal, or the picker under the message box in the app) and every edit and command waits for a yes or no, one key in the terminal.
Whatever the setting, a command that would wipe a home or root directory always stops for approval, and in an unattended run it is refused outright. The model is never allowed to read Sage’s own configuration, where the API keys are kept.
A tripwire, not a sandbox. These checks catch the catastrophic, not every mistake. Work in a git repository you can reset, or in a container.
Questions, skills, and restarts
When a task leaves a major choice genuinely open — such as starting a brand-new app without naming a framework — the model can call ask to pause and present one clear question with up to six options, putting its recommended pick first. In the terminal you answer with the option’s number, or in your own words. In unattended runs, Sage tells the model to pick the best option itself and note its assumption in finish.
Six focused playbooks come built in (ui, security, cleanup, debug, tests, and performance) and are switched on with /skills in the terminal or the app. A project can override them or add its own in .sage/skills, alongside custom AGENTS.md instructions.
Every turn also saves an atomic snapshot.json protected by an OS file lock. If you quit the desktop app, stop the CLI, or restart your machine, reopening the session in the app, or sage -c and /resume in the terminal, picks up right where the conversation left off — preserving your effort level, standing watches, and active /goal.