Deterministic-first agent routing · v0.2.0-rc.1

Scale down before you scale up.

GrokMax is a deterministic-first execution pipeline for GrokBot-heavy teams. It sends each task to the cheapest executor that can actually do the work, slims context to what matters, and caches the result so an identical ask is not paid for twice.

Get GrokMax See the pipeline

$0: model spend on a math task
5: cache layers (+L0 hot)
33: benchmark fixtures, 100% match
279: tests, all passing

Fixtures and tests run locally with the deterministic resolver only — zero model spend, no model in the loop. 5 of the 33 fixtures are escape cases where declining is the correct outcome. Savings on GrokBot usage are router-level proxies, honestly labeled as such. The terminal above is an illustrative example, not captured output.

grokmax — deterministic-first

$ grokmax route "Calculate 7*8 and return the integer result"

ROUTE DETERMINISTIC

CACHE MISS (cold)

7*8 = 56 (zero cost, cached for the next identical ask)

$ grokmax optimize "Calculate 7*8 and return the integer result"

ROUTE NONE

CACHE L0 hit — exact cache hit (canonical hash)

served from cache in 0ms · GrokBot not invoked

How it works

Most tasks are not GrokBot-only tasks.

GrokMax catches cheap work before it becomes an expensive invocation. The pipeline treats GrokBot as the last resort, not the default.

Slice context

Target ~1,500 relevant tokens instead of 20,000. That is a design budget, not a measured typical result — and token reduction is a proxy for cost, never a billed measurement.

Compile the micro-prompt

Hard constraints survive verbatim. validatePreservation fails loudly if a constraint token — including a negation like “do not” — is ever lost in compression.

Route to the cheapest capable worker

deterministic > api > chatgpt > opencode > grokbot. GrokBot is the most capable and the most expensive, so it sits last in the hierarchy — unless you explicitly pin an executor.

Execute responsibly

Zero-model-cost local resolvers handle math, hashing, file counts, and git. A worker that exits non-zero is reported as a failure, never as a success.

Cache across five layers

L1 exact, L2 normalized, L3 semantic, L4 artifact, L5 durable knowledge, plus an L0 in-flight hot cache. A cached result is only reused when its critical literals still match.

Ledger everything

Every run is recorded with honest labels: measured, estimated, or proxy. Measured and proxy rows are never averaged into one number.

Route	Est. cost	Handles	Chosen
deterministic	$0	math · hash · file-count · git	when it fits
api	$	direct tools and endpoints	when it fits
chatgpt	$$	research & cheap generation	when it fits
opencode	$$	repository modification	when it fits
grokbot	$$$$	persistent · authed · unavailable	only when nothing else can

Cost column is a relative ranking from GrokMax’s internal estimate model, not a measured price sheet. GrokBot is unavailable unless a bridge is configured.

Product modes

Two ways to reach GrokBot — or not reach it at all.

Both modes exist as runnable code with test coverage. Neither is production-verified: that requires an independent GrokBot audit that has not happened yet.

Edge Mode

verification candidate

Runs the real pipeline and only touches GrokBot when the router concludes no other executor can do the job. A task is reported as GrokBot-avoided only if it completed, met its contract, and GrokBot was never invoked. Failed work is never counted as savings.

grokmax edge "<task>"

Shipped:: Code and tests exist in v0.2.0-rc.1.
Not yet:: No independent GrokBot audit has verified live behaviour. Not production-verified.

In-Bot Mode

verification candidate

A tiny GrokBot skill calls preflight once and receives one of four actions: return an existing result, delegate to another worker, act yourself, or fail. It is told not to redo cached work, not to redo repository engineering, and not to ingest context it was not given.

grokmax preflight "<task>" --json

Shipped:: Code, contract and skill exist in v0.2.0-rc.1.
Not yet:: No independent GrokBot audit has verified live behaviour. Not production-verified.

No savings percentage is published for either mode. Any number of the form “avoided GrokBot on N/M tasks” is generated only when every task in the denominator completed, met its contract, and left GrokBot uninvoked — and until an independent audit has run the live suite, that number would be a projection, not a measurement.

Why the honesty matters

Integrity is the product.

Every number GrokMax reports is labeled. Savings are proxies unless they were manually imported from live observation — because that is the only honest way to talk about a platform we cannot see into.

Claim	Figure	Honest label
Benchmark fixtures	33 fixtures · 5 suites · 100% match	measured locally, deterministic resolver only. 5 escape fixtures are expected declines, not successful resolutions
Automated tests	279 tests across 26 files	measured locally on v0.2.0-rc.1, reproducible via pnpm test in the grokmax repo
Math task	$0.00 — local evaluator, no model in the loop	measured
Savings on GrokBot usage	router-level avoided-GrokBot counts	proxy — GrokBot platform usage is not directly observable
Context reduction	proportion of tokens trimmed	proxy for token cost, not a billed measurement
Cursor / platform usage	unknown	there is no billing API; a number appears only from two measured_platform observations

We never claim to measure GrokBot’s platform usage. We also never ship a version whose lint, typecheck, test, or build gates are red. If GrokMax cannot prove it, GrokMax does not claim it.

CLI

One binary. Honest answers.

Install locally with pnpm, run the doctor, and let the pipeline decide who pays for what.

Example output from a local run

# grokmax doctor
STATUS: WARNING
SUMMARY: 15 healthy, 3 warning, 0 failure
  ! node             Node 22.22.0 (>=24 recommended for node:sqlite)
  ✓ sqlite           SQLite read/write verified
  ✓ exact-cache      L1 exact cache round-trip verified
  ✓ semantic-cache   semantic cache reachable, cold miss as expected
  ✓ routing          router works; sample route=opencode
  ✓ prompt-compiler  compiler works; constraints preserved verbatim
  ! opencode-cli     OpenCode CLI not detected; repo work will fail
  ! grokbot-bridge   GROKMAX_GROKBOT_BRIDGE unset; GrokBot unavailable

Sample output from one machine at v0.1.1. Warnings here reflect that machine’s environment (Node 22, no OpenCode CLI, no GrokBot bridge), not a defect in GrokMax.

Commands

grokmax optimize "<goal>"Full pipeline: plan + outcome
grokmax route "<goal>"Routing decision only — never executes
grokmax dry-run "<goal>"Skip execution, show what would happen
grokmax doctorHealth checks across every subsystem
grokmax benchmarkRun the fixture suites, measured locally
grokmax savingsHonest report — proxies labeled as such
grokmax cache stats | prune | clearCache health and maintenance
grokmax statusOne-view aggregate across everything

Get started

Scale down before you scale up.

Clone the repo, install with pnpm, and run the doctor on your own workspace. See which of your own tasks stop needing an expensive executor.

git clone grokmaxpnpm install && pnpm cli doctor