Clio Coder

The coding agent for the people who maintain the code that science runs on.
Your models. Your machines. Work you can inspect.

Get started · Capabilities · Models · Documentation · Contribute

Clio Coder is an open-source agent for working in real repositories from your terminal. Explain a codebase, investigate a failing test, implement a change, or coordinate several workers. Follow the tool calls, inspect the diff, and check the evidence behind the result.

Built for scientific software and high-performance computing, Clio works with simulation kernels, numerical libraries, data pipelines, and everyday software engineering. Connect a model on your workstation, your institution's gateway, or a cloud service. Start with one conversation; add workers and specialized workflows when the task calls for them.

v0.5.0 brings Clio to its public launch: the terminal is the primary working interface, and the bundled browser app provides documentation and an early preview of the wider graphical experience. Clio is pre-1.0 software. Review changes and validate scientific results with your own reference checks.

Get started

You need Node.js 22.19 or newer and a model service. Linux and macOS are the primary terminal platforms; Windows support is best effort.

npm install -g @iowarp/clio-coder
cd /path/to/your/project
clio-coder configure
clio-coder

Choose Quick Connect in the configuration launcher. Paste your endpoint, provide credentials if required, select a model, and review the connection. For example, LM Studio commonly listens at localhost:1234 and Ollama at localhost:11434. For subscription sign-in or other provider-specific setup, use Settings → Connections.

Then give Clio a concrete task:

Explain how this repository builds and tests its solver. Find the main entry points and suggest one small, useful verification task before changing code.

The default auto-edit mode allows workspace edits and recognized test commands. Other commands and protected operations may ask for approval. Configure permissions and limits when you need a different balance.

Installation options

Use case	Command
Install with pnpm	pnpm add -g @iowarp/clio-coder
Try without a global install	npx --yes @iowarp/clio-coder@latest
Omit the optional Claude SDK worker dependency	npm install -g @iowarp/clio-coder --omit=optional
Check your installation	clio-coder doctor

Node.js is still required when another package manager performs the install. The optional Claude Agent SDK includes a platform-specific binary; ordinary chat and native workers do not require it.

For the bootstrap installer, source builds, upgrades, and removal, see Installation and Lifecycle.

What you can do

Workflow	What Clio provides	Learn more
Understand a repository	File and symbol navigation, a project handbook, bounded search, and a structural code index.	Project context
Make and verify changes	File edits and diffs, shell execution, declared checks, numerical comparisons, and performance budgets.	Tools
Delegate focused work	Coding, testing, review, and research recipes; separate worker models; bounded assignments and recorded results.	Workers and fleets
Keep long tasks moving	Context accounting, compaction, task memory, durable conversation history, and fork/resume navigation.	Memory
Add domain knowledge	Operator-activated skills, prompt templates, plugins, harness extensions, and local MCP tool servers.	Library
Inspect what happened	Tool activity, usage, traces, decisions, evidence, and worker receipts.	Observability

These capabilities work together. A worker result is a lead you can inspect; a successful command is evidence of that command's outcome; neither substitutes for scientific validation.

Work in the terminal

The TUI keeps the conversation, tool activity, diffs, and permission decisions in one place. Its footer shows the active model and context use; dashboards provide more detail without taking over the conversation.

Want to…	Use…
Find commands and shortcuts	/help
Choose a model or change settings	/model, /settings
Attach a project file	Type @ and choose a path
Inspect context, memory, or cost	/context, /memory, /cost
Browse skills and recipes	/library or Alt+L
Inspect workers	Alt+W
Manage the task board	/tasks
Branch or recover a conversation	/tree, /fork, /resume
Leave the session	/quit

With the default bindings, Enter steers an active turn, Ctrl+Q queues a follow-up, and Escape interrupts. Permission cards provide separate Deny and Stop actions. For the main agent, deny skips the displayed invocation; stop ends the turn. Worker cards explain when identical calls in the same run can reuse a permission decision.

Clio includes contextual guidance by default. Use clio-coder --no-demo for a quieter session, or change interface.demo in /settings. Guidance does not automatically run demonstrations. See the full command and shortcut reference.

Start small, then delegate

Give the main agent a bounded change and its acceptance criteria:

Add a regression for the boundary case, make the smallest fix, and run the relevant checks. Keep the public API unchanged. Do not commit or push.

When an independent second pass would help, run a worker explicitly:

/run verifier Review the current diff and run the relevant existing checks. Do not edit files.

Configure a different worker model under Settings → Fleet, or build repeatable multi-step workflows with fleets. Local workers are enough to get started; SSH placement is optional.

Use the same harness in automation

clio-coder run --autonomy read-only "Summarize this repository's entry points."
clio-coder run --json "Investigate the failing parser test and report the evidence."
clio-coder acp

Headless text mode writes the final answer to stdout and diagnostics to stderr; --json emits JSONL events. ACP connects compatible editor hosts. Headless runs cannot answer interactive permission prompts. See output and exit codes and ACP integration.

Choose your models

A saved connection is a target. Chat, workers, and optional model-assisted memory can use different targets and models.

Where the model runs	Examples
Your workstation or server	Ollama, LM Studio, llama.cpp, vLLM, SGLang, Lemonade
A gateway or compatible API	LiteLLM, OpenAI-compatible and Anthropic-compatible endpoints
Cloud APIs	OpenAI, Anthropic, Google, OpenRouter, Groq, Mistral, DeepSeek, Amazon Bedrock
Subscription sign-in	ChatGPT through openai-codex; Claude through anthropic-max
Institutional inference	Argonne ALCF Sophia and Metis through Globus OAuth

Model capabilities vary. Check tool calling, context capacity, and reasoning support for the route you choose. Subscription integrations depend on vendor sign-in support and terms; a gateway controls its own backend placement.

The connection guide covers setup, and the model catalog explains measured capabilities and runtime differences. Without a separate memory route, task memory uses rules rather than another model.

Documentation you can ask about

Ask Clio how to use or extend Clio. Her documentation, prompt fragments, agent recipes, and source ship with the package. The harness directs questions about its own features to the installed documentation, so Clio can look up the version you are actually running instead of guessing from your project's files.

Try: “How do I use a different model for workers?” or “What can you do without asking me?” Treat her answer as an explanation you can check against the linked guide and effective settings.

Read the same documentation in your browser:

clio-coder docs
clio-coder docs safety

The browser app renders the bundled Markdown with navigation and page outlines. It runs locally and is also the preview home for Clio's graphical features. The terminal remains the primary coding interface for this release. See browser app documentation for launch and lifecycle details.

Looking for…	Start here
A map of the documentation	Documentation index
First connection and effective settings	Configuration and targets
Commands and keyboard controls	Commands and modes
Connection or installation trouble	Troubleshooting
Scientific checks and measurements	Scientific validation
How to extend the harness	Extensions and plugins

Choose authority, keep the evidence

Clio offers read-only, suggest, auto-edit (the default), and full-auto modes. Full-auto removes routine autonomy prompts; it does not disable safety-net checks, protected-path rules, or explicit task constraints. Workers remain bounded by the authority and scope of their assignment.

Clio is not a general operating-system sandbox. Tool admission, receipts, and validation help you supervise work; they cannot establish scientific correctness or make arbitrary shell programs safe. The tracked dollar budget also depends on available usage and pricing data and is not a provider billing cap.

Read the safety model, use reference tests, and review changes before delivery. Report security problems privately through SECURITY.md.

Install

The npm command in Get started is the shortest path. The installation guide also covers the bootstrap installer, upgrades, selective resets, and removal.

Build and install a published release from source

From source, pin the release you intend to run. The following selects v0.5.0 once its release tag is published; for development before the tag, use the contributor checkout instructions.

git clone --branch v0.5.0 https://github.com/iowarp/clio-coder.git
cd clio-coder
corepack enable pnpm
pnpm run install:local
export PATH="$HOME/.local/bin:$PATH"
hash -r
"$HOME/.local/bin/clio-coder" --version

The installer resolves dependencies, builds, and links the launcher into ${CLIO_CODER_BIN_DIR:-$HOME/.local/bin}. If Corepack is unavailable, install pnpm with npm install -g pnpm@10.34.5. Preview with bash scripts/install-local.sh --dry-run.

Run command -v clio-coder to check which launcher your shell reaches. After changing PATH, use hash -r in Bash or rehash in Zsh. An older global installation can otherwise shadow the launcher you just installed.

Update or remove an npm installation

npm install -g @iowarp/clio-coder@latest
clio-coder upgrade --post-install
clio-coder doctor

npm uninstall -g @iowarp/clio-coder removes the package and preserves user data. If you installed the optional background app service, remove it with clio-coder gui background uninstall before removing the package. For a deliberate Clio data purge, first inspect clio-coder uninstall --dry-run; see the lifecycle guide for exact scope.

Contribute

A difficult build, an unreliable connection, or a workflow that takes too much babysitting makes a useful bug report. Include your Clio and Node versions, reproduction steps, and relevant clio-coder doctor output. Remove credentials and sensitive project data.

• Report an issue or suggest an improvement
• Set up a development checkout
• Read the release notes and roadmap
• Contribute a skill or workflow

Participation follows the Code of Conduct.

Built by IOWarp, on open source

Clio Coder is developed by the Gnosis Research Center at Illinois Tech, in collaboration with the University of Utah, as part of IOWarp. The IOWarp CLIO architecture is supported by the National Science Foundation under Award #2411318.

Clio builds on Earendil Works' Pi framework, the Agent Client Protocol, and the work of open-source runtime, terminal, compiler, model-serving, and scientific-tool communities. Optional Claude SDK workers use Anthropic's Claude Agent SDK. See NOTICE for component acknowledgements and distributed notices.

CLIO means Context Layer for Input/Output. Explore the wider ecosystem: clio-core for data and context storage, and clio-kit for scientific tool servers.

---

Clio Coder · Apache-2.0 · License · Notices
_{Built for the people who maintain the code that science runs on.}