Clio Coder

Why I built it

Most coding agents ask you to trust a remote model with a shell. That is a bad deal for the code science runs on: simulation kernels, numerical libraries, data pipelines, and build systems that take twenty minutes and fail in ways no cloud model has ever seen. The people who maintain that code often cannot send it to a cloud API at all, and they frequently have exactly one GPU.

So I started Clio Coder in April 2026 with a different bet. The harness should be strong enough that a 20B model on your own GPU is genuinely useful, and honest enough that you can reconstruct every decision afterwards. I have written almost every commit since. It is the piece of CLIO I am proudest of.

What it is

A terminal coding agent. You bring the model: a llama.cpp, Ollama, LM Studio, vLLM, or SGLang server on your GPU; a cloud API; a Claude or ChatGPT subscription; or the Argonne Leadership Computing Facility inference gateway. Clio brings the harness around it.

npm install -g @iowarp/clio-coder
clio-coder configure      # pick a runtime, an endpoint, a model; probe it
clio-coder                # start the session in any repository

Inside the session, type what you want. /settings changes the model, /context shows what is in the window and what it costs, /run coder "..." delegates to a fleet agent, /tree and /fork branch a session, /export writes a self-contained HTML transcript. Outside the session, the same engine runs headless with clio-coder run "<task>" --json, and it speaks the Agent Client Protocol over stdio for editors.

The four decisions that matter

The model never gets a shell by default. There are twenty typed tools in seven policy planes: observe, mutate, execute, orchestrate, retrieve, interact, artifact. Bash is default-deny behind damage-control rules and per-project policy. Reads are bounded by a truncation envelope, so one grep cannot blow the window. Writes are queued and reviewable. Every privileged call goes through one admission path that the model cannot talk its way around. The autonomy dial (read-only, suggest, auto-edit, full-auto) changes what runs immediately and what parks for approval; it never changes the tool surface.

Local models are the design target, not a fallback. The compiled prompt and tool schemas stay byte-stable so a llama.cpp prefix cache stays hot across turns and sessions. Every tool result is bounded. The ledger records a per-call cache verdict, so you can see when and why the cache went cold. This release was hardened against Qwen3.8-27B on llama.cpp and LM Studio, because a 4-bit quantization at 131072 context fits in 24 GB with a q8_0 KV cache, and that is the machine a lot of scientists actually have.

Work goes to bounded workers, not one long context. The orchestrator dispatches focused agents (architect, coder, tester, verifier, debugger, documenter, scout, researcher, provenance, git-master) with explicit tool profiles, call budgets, cost ceilings, and typed result contracts. A worker that cannot produce a conforming answer fails loudly instead of returning confident prose. Since v0.3.7 a dispatch carries typed intent: which roots it may read and write, which paths matter, which outputs are expected, and which verification checks the host runs afterwards with no shell.

Everything is auditable. Every run seals a receipt covering tokens, priced cost, tool activity, safety decisions, routing, worker attestation, and result conformance. clio-coder evidence inspect and /view verify <runId> check it. Commits made through Clio get evidence-backed provenance trailers; the human stays the author. Nothing in the audit trail is reconstructed from prose.

Your cluster is the runtime

Declare your nodes in a fleet and the same worker protocol tunnels over SSH with the same prompts, the same safety matrix, and the same receipts.

fleet:
  nodes:
    - id: node-a
      host: node-a.example.net
      maxWorkers: 2
    - id: node-b
      host: node-b.example.net
      maxWorkers: 1

clio-coder doctor preflights every node. clio-coder fleet run <contract> drives a multi-step DAG; --resume <runId> replays a settled prefix. Placement is deterministic and pinnable, and capacity is governed by durable leases that survive process death. The fleet demo runbook in the repository is the recorded multi-node walkthrough.

Science is a first-class domain

CLIO Kit adds MCP servers for HDF5, Slurm, ParaView, Pandas, NetCDF, FITS, Zarr, and ArXiv, and the shipped skills catalog includes scientific debugging and experiment-protocol guides. clio-coder context init drafts a CLIO-CODER.md handbook from your actual source tree and can adopt existing CLAUDE.md, AGENTS.md, and Cursor or Copilot context with provenance. clio-coder context index builds a codewiki so a model finds a symbol without reading half the repository into its window.

Where it stands

v0.3.7 shipped on August 24, 2026 and is on npm. Clio Coder is experimental: I ship quickly, interfaces may change between minor versions, and model-specific behavior varies by target. Keep important repositories under version control and review what it proposes. Every release is gated by the deterministic npm run ci:release suite; the SWE-bench, SciCode, and Terminal-Bench harnesses under benchmarks/ are opt-in because no deterministic suite can promise that every local model behaves identically.

It is built on the Pi agent framework from Earendil Works, the Anthropic Claude Agent SDK for Claude Code worker runs, the Agent Client Protocol for editor frontends, and Globus Auth for ALCF’s inference gateways. Eneko Gonzalez and Dependabot have landed commits; the rest is me. Bug reports go to the repository; security reports go through SECURITY.md.

What I want next

• Live worker views in the terminal, so delegation is something you can watch rather than a spinner.
• User-programmable verifiers, so a Rust, C, or Python project can declare its own checks and Clio can help you write them.
• A public behavioral regression corpus for the built-in agents, with variance gates, so “better” becomes measurable.
• Cleaner permission dialogs. The safety net should look different from an ordinary question.