Run Clio Coder against a model on your own GPU

Clio Coder treats a model as a named target: a runtime, an endpoint, a model id, and credentials. The point of this note is to get from nothing to a working target on your own hardware and to see what a run leaves behind. The commands are the ones documented in the v0.3.7 README and --help.

Prerequisites

• Node.js 22.19 or newer and npm.
• Linux or macOS. Windows is best effort until a stable release.
• A local inference server. Any of llama.cpp, Ollama, LM Studio, vLLM, or SGLang works; the runtime ids are llamacpp, ollama-native, lmstudio, vllm, and sglang.
• A model loaded in that server. If you have one GPU with 24 GB or more, the release was hardened against Qwen3.8-27B (the unsloth/Qwen3.8-27B-GGUF quantizations) on llama.cpp and LM Studio. A 4-bit quantization at 131072 context fits in 24 GB with a q8_0 KV cache.

Version as of August 26, 2026:

$ clio-coder --version
Clio Coder 0.3.7

1. Install

npm install -g @iowarp/clio-coder
clio-coder --version

From source instead, pinned to the release:

git clone --branch v0.3.7 https://github.com/iowarp/clio-coder.git
cd clio-coder
npm run install:local
export PATH="$HOME/.local/bin:$PATH"
hash -r

npm run install:local builds the CLI, links it at ${CLIO_CODER_BIN_DIR:-$HOME/.local/bin}/clio-coder, and initializes the home directory. If an older install is on your PATH, command -v clio-coder shows which binary the bare name reaches.

2. Start the model server

For llama.cpp, start it with the flags the README asks for so tool calls and reasoning parse cleanly:

llama-server --jinja --reasoning on -m /path/to/Qwen3.8-27B-Q4_K_M.gguf -c 131072

LM Studio needs nothing beyond loading the model. Note the port your server listens on; 8080 is llama.cpp’s default and 1234 is LM Studio’s.

3. Configure a target

The interactive way:

clio-coder configure

The wizard lists runtimes, asks for the endpoint and model, probes it, and saves it as both the chat and worker target. Bare clio-coder opens the same wizard when nothing usable is configured.

The scripted way, which does the same thing without prompts:

clio-coder configure --id local-lmstudio --runtime lmstudio \
  --url http://localhost:1234 --model your-model-id \
  --set-orchestrator --set-fleet-default
clio-coder targets --probe

clio-coder targets prints every configured target with its tier, runtime, auth state, URL, model, health, and capability flags. --probe actually connects. The model id has to match what the server advertises: if LM Studio has a different model resident than the one in your target, the turn fails immediately with a message naming the resident instances instead of silently routing to whatever is loaded. That is deliberate.

4. Run one headless turn

From any repository:

clio-coder run "Summarize this repository layout and its entry points." --json

--json streams JSONL events: a session record with the session id, working directory, target, model, and Clio version; agent_start, turn_start, message_start, message_end, turn_end, and agent_end; and tool events in between when the model calls tools. The agent_end event carries measured usage (input, output, cache reads and writes, reasoning tokens, API calls, and cost in dollars). Add --autonomy read-only if you want the guarantee that nothing can be mutated or executed on this turn; every mutating call is denied and the denial is recorded.

To hand the same task to a fleet agent instead of the main loop:

clio-coder run "<task>" --agent coder

That run gets its own receipt.

5. Read the receipt

clio-coder evidence list
clio-coder evidence inspect <runId>

A receipt covers routing intent, the resolved route, worker attestation, priced cost, phase timing, tool activity, safety decisions, and result conformance. Inside an interactive session, /view verify <runId> shows the same thing. clio-coder trace reads the durable dispatch trace.

6. Go interactive

cd your-project
clio-coder context init     # drafts CLIO-CODER.md from the source tree
clio-coder

context init writes the project handbook Clio loads every session and can adopt an existing CLAUDE.md, AGENTS.md, or GEMINI.md with provenance. In the session, /settings changes the model or autonomy level, /context and /cost show what is in the window and what it costs, and /help lists the rest.

Limitations

• Clio Coder is experimental. Interfaces may change between minor versions, and model-specific behavior varies by target. Keep the repository under version control and review what it proposes.
• A local model’s usefulness depends on the quantization, the context length you can afford, and whether tool calls parse cleanly. The model catalog in the repository records what has been checked per family; other models may need --jinja or a different chat template.
• The receipt records what the harness observed. It does not make the model’s reasoning correct.
• Connecting a Claude or ChatGPT subscription over OAuth uses the same path as the vendors’ own tools; using subscription credentials outside a vendor’s first-party apps may not align with their terms. That is your call, not Clio’s.
• Windows is best effort.

If something in here does not match what you see, clio-coder doctor plus clio-coder --version and node --version is what I need in a bug report. Redact secrets and private prompts first.