Harness layer
ObservationPack
Handle plus excerpt. Full text stays on disk.
[ coding-agent harness ]
Confidence-gated model routing, institutional memory, and BYOK economics. Grist writes and edits code in your working tree — every task routed to the cheapest capable rung, every verified change remembered, inference billed to your own provider key.
npm install -g grist-ai grist
First grist prompts auth login. Pick Grist and sign in — your account is created on the spot. Bring your own provider key for inference, or use a dashboard grist_sk_ key.
Use Grist for my coding tasks from now on. Grist is an agentic coding-harness CLI. 1. Install the Grist agent skill by running: npx skills add grist-ai/grist-skills (built for personal AI agents and agentic CLIs like Muse, OpenClaw, Hermes, and OpenCode). Read the installed skill file in full before doing anything else. 2. Install the CLI if it is missing: npm install -g grist-ai. 3. Ask me for my Grist API key if you do not have it (it starts with grist_sk_). Never print it, log it, or write it into any file — pass it via environment variable only. 4. For multi-step coding work (features, bug fixes, refactors across files), delegate to Grist exactly as the skill describes. Report back what changed, the branch name, test results, and cost.
For Muse, OpenClaw, Hermes, or any personal AI agent with its own shell. Copy pastes the full prompt.
Learns your codebase · Self-improves · SoL-Pi inside · Open beta
[ learns your codebase ]
Other agents start from zero every session. Grist mines the tree, ownership, and conventions from your own history. You stop pasting context. It already knows who owns the file.
[ self-improves ]
Grist only remembers what you approved or what tests proved. The gate calibrates to your repo. Unreviewed noise never becomes knowledge.
[ SoL-Pi ]
SoL-Pi sits in the harness, not in a cheaper model. Huge tool output gets packed. Edit and verify fuse into one move. Spend goes to judgment, not log spam.
Harness layer
Handle plus excerpt. Full text stays on disk.
Turn compression
Edit and verify fuse into a single move.
[ the gate ]
Most agents bill like every task is hard. Grist spends on difficulty, not habit. Routine edits stay cheap. The expensive rung is reserved for when it actually matters.
[ local ]
Tools run in your working tree. The prompt goes out. The source does not. Your provider key stays yours. We never train on your code.
3 files · tests passed · $0.012
[ architecture ]
One request, seven moves. The client never sees a model id — only rung names. The gateway resolves everything, and your provider key pays for inference. Not ours.
CLI, TUI, or desktop. The client sends the task and names a rung — never a vendor model id.
grist_sk identifies your account. Spend caps are hard: over cap returns 402, not a bill.
A confidence gate scores difficulty once per run, picks the cheapest rung that can handle it, and dials exploratory effort — trivial tasks get a tight budget, ambiguous ones get room to investigate.
Rung becomes a model. Defaults are ours — your dashboard can override any rung.
The provider call rides your BYOK key. Inference bills to your provider account; Grist never holds your budget.
Approved diffs and proven changes become memory — code map, ownership, Supermemory. The next run starts briefed.
The gate hands work to named specialists — explore, plan, review, verify — each running inside the assigned rung. Repeat calls resume warm, so context compounds.
Subagents re-gate on their delegation text with the parent's rung as a ceiling — decomposed work can only shed cost, never gain it.
[ new in v2 ]
Grist moved from a surgical fork to a first-class OpenCode plugin (tracking upstream v2.0.18). The gate, the ladder, and the doctrine are unchanged — everything around them got better.
grist binary — every session loads the Jev gate,
doctrine, and control plane with no setup. One additive upstream
hook is the entire fork surface, so new upstream releases merge
as plain tags.
grist auth,
grist models, grist debug,
grist service, grist upgrade,
grist stats, grist session,
grist mcp — v2's command surface arrives as upstream
features, not Grist code to maintain.
grist serve --service
elects a single server; grist run is a thin client
over it. No more ad-hoc servers lingering after a reinstall.
grist.json and .grist/, and global state
lives under ~/.grist — the harness finally has its
own name on disk.
[ get started ]
Create an account with your name and email, or sign in with Google — your account is ready on the spot. Bring your own provider key — OpenRouter, Vercel AI Gateway, or any OpenAI-compatible endpoint — and Grist runs inference on it.
[ beta ]
Open to everyone. Bring your own key. Your code stays on your machine.
[ docs ]
Open to everyone. Bring your own provider key for inference. The CLI is the product — this page is how you get from sign-in to a running agent.
CLI (any OS):
npm install -g grist-ai grist
The first grist run prompts grist auth login.
Pick Grist (recommended). Completions will not run
until you are signed in.
macOS desktop: Download Grist.dmg. First launch opens login.
grist auth login lists providers with Grist first.
Create an account on this site with your name and email (or Google),
or sign in — or paste a dashboard API key (grist_sk_…).
After login, add your own provider key — OpenRouter, Vercel AI
Gateway, or any OpenAI-compatible endpoint — on the dashboard's
Provider tab, and Grist runs
inference on it.
grist auth login --provider grist # or, with a key from the dashboard: grist auth login --provider grist --api-key grist_sk_…
Browser path: the CLI opens this site. Create an account or sign in — the first visit creates your account. The terminal polls until the site approves it, then you're in. To bring your own inference key, add it on the dashboard's Provider tab.
Usage, remaining spend, and the current plan live on the dashboard. Same account, same origin. Agents that run Grist on a VM use an API key from that dashboard. See agent skills.
Run Grist in the project you want changed. Tools execute on your machine.
cd /path/to/your-repo grist init grist bootstrap grist
grist init scaffolds local state. grist bootstrap
mines history (ownership, map) so the next session is not cold.
Review .grist/bootstrap/ownership.jsonl before anything
is persisted to memory. grist init --bootstrap runs both.
Each task is scored for difficulty and sensitivity, then routed to
the cheapest capable rung. Underspecified work stays cheap instead of
inventing scope. You do not pick a model. Logs look like
[grist:gate] cheapest via openrouter mode=normal · diff=0.31 sens=0.05 under=0.62 · routine · 3ms.
Turn the gate off with GRIST_GATE=off (not recommended).
Within a rung, the gate also dials exploratory effort
(low / standard / high) from the
confidence score: trivial tasks get a tight exploration budget,
ambiguous ones get room to investigate. Pin it with
GRIST_EFFORT=low|standard|high, or let the gate decide.
The gate delegates to named specialist subagents —
grist-explore, grist-plan,
grist-review, grist-verify — each running
inside the assigned rung with doctrine for its role.
Decomposition can only shed cost, never gain it: a subagent re-gates
on its delegation text with the parent's rung as a ceiling.
Repeat subagent calls resume the previous session warm instead of
starting cold, so context compounds (cap 3 resumes per parent
session; GRIST_WARM_SUBAGENTS=0 to disable).
Grist persists only verified outcomes: tests that passed, a change you approved, or a correction you made. Unreviewed generations are not stored. Recall is retrieval from your own history — not a weight update.
Default backend is a local memory sidecar. File fallback:
GRIST_MEMORY=file. Off: GRIST_MEMORY=off.
SoL-Pi is a harness-layer set of token cuts. ObservationPack replaces huge tool output with a handle plus a short excerpt (full text still on disk). Action Fusion edits and verifies in one call. Profiles:
GRIST_MECH=auto # default GRIST_MECH=efficiency # pack + fuse GRIST_MECH=performance # full tool output, fuse still on GRIST_MECH=off # both off GRIST_OBS_PACK=off # pack only
Inference runs on your own provider key — OpenRouter, Vercel AI
Gateway, or any OpenAI-compatible endpoint — at your provider's
prices, with zero markup from us. Attach one key, and prefer an AI
gateway key: it reaches every model on every rung, while a direct
provider key limits all rungs to that provider's models.
grist usage and the
dashboard show spend broken down by rung, so you can see exactly
where the money went.
Hard spend caps are enforced on the house key: at the cap the gateway returns 402 and the run stops. Per-account caps on BYOK keys are soft today. Agent API keys spend against the same account but can never raise its cap. We never train on your repos.
An agent on a VM (Muse, Cursor, and the like) can run Grist with spend
attributed to your account. Mint a key on the API keys
tab. Store it in a vault as GRIST_API_KEY — never in chat
and never in the skill file. Then on the VM:
npm install -g grist-ai npx skills add grist-ai/grist-skills
The skill tells the agent when to delegate, how to invoke
grist run, and what to report back. Full text:
Agent skills.
[ docs ]
From zero to a running coding agent in under five minutes. No subscription, no markup — you bring your own inference key.
Grist is an open-source (MIT) coding-agent harness, a fork of OpenCode. You bring your own inference key — OpenRouter, Vercel AI Gateway, or any OpenAI-compatible endpoint — and Grist runs the agent loop on it with zero markup. Every task passes through the Jev confidence gate, which routes it to the cheapest model rung capable of doing the job well.
npm install -g grist-ai
The easy path — the CLI opens your browser, you sign in (or create an account on the spot), approve the terminal, and you're in:
grist auth login --provider grist
Prefer a key? Grab one from the dashboard's API keys tab and either paste it at the prompt or pass it directly:
grist auth login --provider grist --api-key grist_sk_...
Headless fallback (agents on a VM):
export GRIST_API_KEY=grist_sk_... or write
{"code": "grist_sk_..."} to
~/.grist/config.json. Verify with
grist doctor.
Out of the box, inference runs on Grist's own gateway key: sign in and go, no provider setup. If you'd rather bring your own key (OpenRouter, Vercel AI Gateway, or any OpenAI-compatible endpoint), attach it on the dashboard's Provider tab — every model call Grist makes, including the Jev gate's own judgments, then bills to that key at your provider's rates. API equivalent:
curl -s -X POST https://grist.lol/v1/provider \
-H "X-Grist-Api-Key: grist_sk_..." \
-H "Content-Type: application/json" \
-d '{"provider": "openrouter", "api_key": "sk-or-..."}'
(provider is openrouter |
vercel | custom; custom also
needs base_url.)
Scratch repo, under five minutes:
mkdir hello-grist && cd hello-grist grist run "write fib.py printing the first 10 fibonacci numbers, run it, and show me the output"
Watch it plan, write the file, execute it, and report back. Prefer
to drive? Bare grist opens the interactive TUI.
-mThe gate scores each task and picks a rung, escalating mid-run if the task proves tougher than expected:
grist run accepts -m/--model, but pinning
a rung bypasses the gate and you lose the cost routing. Let it
decide.
| Command | What it does |
|---|---|
grist | Interactive TUI |
grist run "<prompt>" | Headless agentic run in the current directory |
grist run -c | Continue the last session |
grist doctor | Health checks: auth, gateway, gate, service, updates |
grist update | Upgrade to the latest release |
grist models | List available models |
grist stats | Usage statistics |
Prefer a GUI? The Mac app (0.1.16) ships as a dmg from the releases page at github.com/grist-ai/grist-downloads, with the same CLI bundled inside.
Source and issues: github.com/grist-ai/grist.
[ docs ]
Give this to an agent (Muse, Cursor, and the like) so it can install Grist on its own VM and bill your account. The key stays in a vault — never in the skill, never in chat.
Install it with the skills CLI. That drops it into Cursor, Claude, OpenCode, and other agents the CLI detects. The API key still stays in a vault — never in the skill.
npx skills add grist-ai/grist-skills
Delegate multi-step coding tasks in a git repo to Grist: features, bug fixes, refactors spanning multiple files. Not for single-file edits or non-coding questions.
Grist installed on the agent’s VM (npm install -g grist-ai),
the gateway URL (https://grist.lol unless you were given
another), and the API key living in a secure vault. Never in chat.
Never in the skill file.
export GRIST_GATEWAY_URL=https://grist.lol export GRIST_API_KEY # injected from the vault — do not echo it grist usage # confirms auth without printing the key
Mint the key on the API keys tab. Store it
in the vault the agent already uses. If grist is missing
or grist usage fails, the agent stops and tells you.
Headless, one shot, JSON on stdout. Point --dir at the
git checkout. --auto is required so tool permissions are
not rejected.
grist run --format json --auto --dir /path/to/repo "Precise task: what to change, where, and how to verify."
Each stdout line is one JSON event:
sessionID — capture this from the first eventtype: "text" — assistant output in part.texttype: "tool_use" — file edits and shelltype: "error" — failure; stop and reportgit status, git diff)Resume the same session:
grist run --format json --auto --dir /path/to/repo -c "Continue: address the test failure in …" grist run --format json --auto --dir /path/to/repo -s "$SESSION_ID" "Continue: …"
Do not use the interactive TUI. On a headless VM, set
GRIST_API_KEY (or run
grist auth login --provider grist --api-key "$GRIST_API_KEY"
once). Do not open a browser login.
main.main.main or the default branch.grist usage before and after, or remaining USD)[ docs ]
What changed in Grist, in plain language. Items marked shipped are live; items marked in progress are built and under review.
Grist now has four named specialists the agent can delegate to, each with a narrowly scoped job and permissions:
You don't invoke them directly — the agent dispatches one when the task fits, instead of doing everything inline. This is the main way Grist keeps cheap-rung runs capable: a small model plus the right specialist beats a bigger model alone.
Each task now gets an effort level — low,
standard, or high — inside its cost
rung. High effort means a larger exploration budget and more specialist
use; low effort means quick, inline answers. The level is picked per
task, but your setting wins if you set one:
GRIST_EFFORT=high grist run "migrate the auth module"
When the agent uses the same specialist twice in one session, the
second call now resumes the first one's session instead of starting
over — no re-briefing, faster and cheaper follow-ups. On by default;
GRIST_WARM_SUBAGENTS=0 turns it off.
grist doctor used to report "signed in" whenever a
credential was stored — even a revoked one. It now validates
the key against the gateway with one cheap call: a good key reports
"key verified", a rejected one tells you to sign in again.
Long runs used to die with an HTTP 413 once their history passed the gateway's request-size limit — and the session was unrecoverable. The CLI now trims old tool output (leaving a marker where it cut) before requests approach the limit, keeping the recent conversation intact. Long tasks finish instead of failing partway.
[ account ]
Create an account or sign in to get your API key and start running agents.
or email
or email
Google sign-in is not configured on this gateway yet. Enter the account code your operator gave you.
By continuing you agree to the Terms of Use and Privacy Policy.
[ cli ]
Return to the terminal. This machine is authenticated.
Go to dashboard[ beta ]
—
Keys let agents like Muse run Grist on a VM, billed to this account. Store the secret in a vault. Never in chat, never in a skill file.
npx skills add grist-ai/grist-skills
Then set GRIST_API_KEY from the vault.
Agent skills.
It will not be shown again.
Mint a scoped token for Meta's Muse: it can route tasks, run completions, and read spend on this account — but can never see or change your provider keys, mint keys, or change caps. Paste it into Muse as a custom connector credential. It is shown once.
It will not be shown again.
Each ladder rung has a default model. Override any rung with a model id your provider serves — clearing the field restores the default. Overrides apply to every request on this account.
Loading…
Bring your own inference key — OpenRouter, Vercel AI Gateway, or any OpenAI-compatible endpoint. Every model call Grist makes, including the Jev gate's own judgments, bills to that key at your provider's rates. Without a key, inference runs on Grist's gateway key.
Attach one key, and make it an AI gateway key (OpenRouter or Vercel AI Gateway): a gateway key reaches every model on every rung. A direct provider key (e.g. Anthropic-only) also works, but then every rung is limited to that provider's models.
[ admin ]
Admin API token
Account codes with preset spend caps, for testers or special cases. Most users just sign in — their account is created automatically.
—
[ legal ]
This policy is strict on purpose. It describes what Grist actually collects, what leaves your machine, who receives it, and what we refuse to do. If a sentence would be convenient but untrue, it is not in this document.
Grist (“we,” “us”) is the service at grist.lol, including the related CLI, desktop, and gateway software. Contact for privacy requests: admin@grist.lol.
This policy covers the website, sign-in, dashboard, account gateway, and the Grist CLI / desktop client when they talk to our servers. It does not cover third-party sites we link to, or software you run that is not Grist.
grist_sk_…) is optional agent auth and spends against your account cap.Tools execute on your machine. Source files stay on your disk unless you or the agent include file contents, diffs, logs, or excerpts in a prompt or tool result that is sent for inference. That exception is real. Do not treat “code stays local” as a guarantee that no snippet ever leaves.
localStorage after you sign in.Legal bases where GDPR or UK GDPR apply: contract (providing the beta), legitimate interests (security, metering, abuse prevention), consent (non-essential cookies, if any), and legal obligation.
We send personal data and inference content only as needed to run Grist. Current categories:
Each processor has its own terms. We do not control how a model provider logs prompts on its side. Assume a prompt you send could be retained by that provider under its policy, even though we do not train on tester repos.
Depending on where you live, you may have the right to access, correct, delete, or export personal information, to object or restrict certain processing, and to withdraw consent where processing is consent-based. California residents may request access, deletion, correction, and information about sharing; we do not sell or share personal information for ads. We will not discriminate against you for exercising these rights.
Email admin@grist.lol from the address on the account. We may need to verify it is you. Authorized agents may submit a request with proof of authority. You may also close the account by asking us to delete it; local files and git history on your machine are yours to remove.
Grist is not directed at children. You must be at least 18 to create an account, or use the agent. We do not knowingly collect personal information from anyone under 18. If we learn that we have, we will delete it.
We are based in the United States. If you use Grist from another country, your information is processed in the United States and in any country where a processor listed above operates. Model providers may process prompts outside your country.
We use HTTPS, authenticated accounts, hashed/provider-managed credentials, and we keep provider API keys encrypted on the server. No method of transmission or storage is perfectly secure. You are responsible for protecting your machine, your git remotes, and anything the agent can execute locally.
We may update this policy. The “Last updated” date will change. For material changes we will post the new policy on this page. Continued use after the effective date means you accept the updated policy. If you do not, stop using Grist and ask us to delete your account.
Privacy requests and complaints: admin@grist.lol. Site: https://grist.lol. Related documents: Terms of Use, Acceptable Use Policy, Cookie Policy.
[ legal ]
These terms are the contract for the Grist beta. They are written to be enforceable, not decorative. If you do not agree, do not use the site, CLI, or desktop app.
By visiting grist.lol, requesting access, signing in, installing Grist, or running the agent, you agree to these Terms of Use, the Privacy Policy, the Acceptable Use Policy, and the Cookie Policy (together, the “Terms”). The service is provided from grist.lol (“Grist,” “we,” “us”).
Grist is an open beta: anyone may create an account and use the service. Beta access is a revocable license to use the service during the beta, not a subscription, not a sale of software, and not a guarantee of capacity, uptime, or future pricing. We may refuse, delay, cap, pause, or revoke access at any time, including when we suspect abuse.
Inference runs on your own provider key. A courtesy fallback on our key may apply where you have not added one; it is not a purchased credit balance. Unused cap has no cash value. There are no refunds for beta access.
You must be at least 18 years old and able to form a binding contract. You must not use Grist if you are barred from receiving US services or if your use would violate export or sanctions law. You may not share an account, account code, or dashboard session.
You are responsible for the Google or email account you use to sign in, for the account code issued to it, and for every action the agent takes while authenticated as you. Notify us immediately if you believe the account code or account is compromised. We may invalidate codes and sessions.
The CLI, desktop app, and related client software are licensed to you, not sold. Upstream OpenCode components remain under their existing licenses (including MIT where applicable). These Terms govern your use of our hosted gateway, branding, account system, and the Grist service. You may not scrape, probe, overload, or reverse engineer the gateway except as allowed by mandatory law.
You retain ownership of your source code, git history, and local files. We do not claim those rights. You grant us a limited permission to process prompts, excerpts, metadata, and usage data as described in the Privacy Policy solely to provide, meter, secure, and improve operation of the beta (not to train models on tester repos).
The agent runs tools in your working tree with your permissions. That can edit, delete, install, and execute. You are solely responsible for reviewing diffs, tests, commits, and any command the agent proposes or runs.
Completions can be wrong, insecure, incomplete, or infringing. Grist does not practice law, provide professional advice, or warrant that generated code is fit for production. You must review output before you rely on it. We are not liable for bugs, outages, data loss, leaked secrets, or shipping defective software that involved Grist.
You must follow the Acceptable Use Policy. Breach is grounds for immediate revocation without notice.
Sign-in, hosting, routing, and model inference are provided in part by third parties. Their outages, policies, and content filters are outside our control. Your use of Google Sign-In is also subject to Google’s terms.
GRIST IS PROVIDED “AS IS” AND “AS AVAILABLE.” TO THE MAXIMUM EXTENT PERMITTED BY LAW, WE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT. WE DO NOT WARRANT THAT THE SERVICE WILL BE UNINTERRUPTED, SECURE, ERROR-FREE, OR THAT INCLUDED INFERENCE WILL REMAIN AVAILABLE.
TO THE MAXIMUM EXTENT PERMITTED BY LAW, WE WILL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR FOR LOST PROFITS, REVENUE, DATA, OR GOODWILL, EVEN IF ADVISED OF THE POSSIBILITY. OUR TOTAL LIABILITY FOR ALL CLAIMS RELATING TO GRIST WILL NOT EXCEED THE GREATER OF TEN US DOLLARS (US$10) OR THE AMOUNT YOU PAID US FOR THE SERVICE IN THE THREE MONTHS BEFORE THE CLAIM. THE BETA IS CURRENTLY PROVIDED WITHOUT A PAID FEE TO US, SO THAT CAP WILL USUALLY BE US$10.
Some jurisdictions do not allow certain limitations. In those places, the limitation applies to the fullest extent allowed.
You will defend and indemnify us against claims, damages, and costs arising from your content, your use of the agent (including code it writes or commands it runs), your violation of these Terms, or your violation of law or third-party rights.
You may stop using Grist at any time and request deletion as described in the Privacy Policy. We may suspend or terminate access immediately for any breach, for abuse of included inference, or if we shut down the beta. Provisions that should survive (including ownership, disclaimers, liability limits, indemnity, and governing law) survive termination.
We may modify these Terms by posting an updated version on this page. Continued use after the effective date constitutes acceptance. If a change is material and you do not agree, stop using Grist.
These Terms are governed by the laws of the State of California, United States, excluding conflict-of-law rules. Except where prohibited, you and we submit to the exclusive jurisdiction of the state and federal courts located in California.
These Terms are the entire agreement for the service. If a section is unenforceable, the rest remains in effect. Failure to enforce a provision is not a waiver. You may not assign your account or these Terms. We may assign them in connection with a transfer of the project. Headings are for convenience only.
[ legal ]
Grist can edit files and run commands on your machine. This policy is the bright line. Violations void access immediately.
If the agent can run a command, that command is yours. “The model did it” is not a defense. You are the operator of the machine.
We may investigate, throttle, revoke account codes, delete accounts, and preserve logs needed to respond to abuse or to law enforcement. We are not obligated to monitor every session.
Report abuse: admin@grist.lol.
[ legal ]
This page lists the cookies, local storage, and similar technologies Grist uses. We do not use advertising cookies.
Browsers may store cookies, local storage keys, and similar items. Some are set by us, some by processors (Google / Firebase).
grist_invite in localStorage so the dashboard and CLI approval can function on this browser. You can clear it by signing out or clearing site data.The request form is ours. Submitting it sends your email, name, and note to the Grist gateway. It does not load a third-party form or set a third-party cookie. Email admin@grist.lol instead if you would rather not use the form.
You can block or delete cookies in your browser, and you can clear
localStorage for grist.lol. Blocking authentication
cookies will prevent sign-in. Browser “Do Not Track” signals are
not a consistent standard; we already do not sell or advertise with
your data.
See the Privacy Policy for retention, rights, and processors.