[ coding-agent harness ]

A complete 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.

$ install
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.

✦ paste into your AI agent
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.

Local tree execution Prompt goes out. Source does not.

Learns your codebase · Self-improves · SoL-Pi inside · Open beta

[ learns your codebase ]

It shows up already briefed.

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 ]

Every verified win makes the next task sharper.

Grist only remembers what you approved or what tests proved. The gate calibrates to your repo. Unreviewed noise never becomes knowledge.

[ SoL-Pi ]

Same quality. Fewer tokens. That’s 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

ObservationPack

Handle plus excerpt. Full text stays on disk.

Turn compression

One call

Edit and verify fuse into a single move.

[ the gate ]

Frontier when it has to be. Cents when it doesn’t.

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 ]

The repo never leaves the machine.

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 ]

How a prompt becomes a diff.

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.

  1. 1

    You prompt

    CLI, TUI, or desktop. The client sends the task and names a rung — never a vendor model id.

  2. 2

    Gateway admits

    grist_sk identifies your account. Spend caps are hard: over cap returns 402, not a bill.

  3. 3

    Jev gate routes

    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.

  4. 4

    Ladder resolves

    Rung becomes a model. Defaults are ours — your dashboard can override any rung.

  5. 5

    Your key pays

    The provider call rides your BYOK key. Inference bills to your provider account; Grist never holds your budget.

  6. 6

    Memory compounds

    Approved diffs and proven changes become memory — code map, ownership, Supermemory. The next run starts briefed.

  7. 7

    Specialists delegate

    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 ]

Rebuilt on OpenCode 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.

[ get started ]

Open to everyone.

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 ]

Stop re-teaching the agent your codebase.

Open to everyone. Bring your own key. Your code stays on your machine.

[ docs ]

Using Grist

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.

Install

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.

Sign in

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.

Start in a repo

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.

The gate

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.

Specialists

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).

Memory

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

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

Spend

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.

Agents

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 ]

Quickstart

From zero to a running coding agent in under five minutes. No subscription, no markup — you bring your own inference key.

What it is

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.

Install

npm install -g grist-ai

Authenticate

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.

Inference keys — how billing works

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.)

First run

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.

The ladder — don't pass -m

The 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.

Useful commands

CommandWhat it does
gristInteractive TUI
grist run "<prompt>"Headless agentic run in the current directory
grist run -cContinue the last session
grist doctorHealth checks: auth, gateway, gate, service, updates
grist updateUpgrade to the latest release
grist modelsList available models
grist statsUsage statistics

Desktop app

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.

Help

Source and issues: github.com/grist-ai/grist.

[ docs ]

Agent skills

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

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

Download SKILL.md

When to reach for Grist

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.

Prerequisites

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.

How to invoke

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:

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.

Workflow

  1. Pull the repo. Create a fresh branch. Never work on main.
  2. Write a precise prompt (files, behavior, tests). Run Grist as above.
  3. Read the diff. If it is wrong or too broad, continue the session with a tighter prompt or stop.
  4. Run the repo’s tests.
  5. Push the branch. Open or describe a PR. Never merge to main.
  6. Report back.

Hard rules

What the agent reports

[ docs ]

Release notes

What changed in Grist, in plain language. Items marked shipped are live; items marked in progress are built and under review.

Specialist subagents shipped

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.

Effort dial in progress

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"

Warm subagent resume in progress

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 actually checks your key in progress

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 sessions survive the gateway size limit in progress

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 ]

Welcome to Grist

Create an account or sign in to get your API key and start running agents.

or email

[ cli ]

You’re in.

Return to the terminal. This machine is authenticated.

Go to dashboard

[ beta ]

Usage

—

CLI


        

[ admin ]

Account codes

Usage

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 ]

Privacy Policy

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.

1. Who we are

Grist (“we,” “us”) is the service at grist.lol, including the related CLI, desktop, and gateway software. Contact for privacy requests: admin@grist.lol.

2. Scope

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.

3. What we do not take

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.

4. What we collect

Account and access

Usage and metering

Inference payload

Technical data

5. Why we collect it

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.

6. Processors and subprocessors

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.

7. Training, sale, and sharing

8. Retention

9. Your rights

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.

10. Children

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.

11. International transfers

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.

12. Security

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.

13. Changes

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.

14. Contact

Privacy requests and complaints: admin@grist.lol. Site: https://grist.lol. Related documents: Terms of Use, Acceptable Use Policy, Cookie Policy.

[ legal ]

Terms of Use

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.

1. Agreement

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”).

2. Open beta

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.

3. Eligibility

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.

4. Accounts and security

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.

5. The software

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.

6. Your code and your machine

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.

7. AI output — no reliance

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.

8. Acceptable use

You must follow the Acceptable Use Policy. Breach is grounds for immediate revocation without notice.

9. Third parties

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.

10. Disclaimers

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.

11. Limitation of liability

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.

12. Indemnity

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.

13. Termination

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.

14. Changes

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.

15. Governing law

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.

16. General

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.

17. Contact

admin@grist.lol · https://grist.lol

[ legal ]

Acceptable Use Policy

Grist can edit files and run commands on your machine. This policy is the bright line. Violations void access immediately.

You must

You must not

Local execution

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.

Enforcement

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.

Contact

Report abuse: admin@grist.lol.

[ legal ]

Cookie Policy

This page lists the cookies, local storage, and similar technologies Grist uses. We do not use advertising cookies.

1. What we mean by “cookies”

Browsers may store cookies, local storage keys, and similar items. Some are set by us, some by processors (Google / Firebase).

2. Strictly necessary

3. Access requests

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.

4. What we do not use

5. How to control them

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.