Clio Coder

A coding agent for scientific software and everyday engineering.
Your models. Your machines. Work you can inspect.

Get started · Capabilities · Interfaces · Models · Website · Documentation

Clio Coder connects a model to repository tools, project context, verification, and worker delegation. Use her to understand a codebase, investigate a failing check, implement a change, or coordinate a workflow across local and SSH workers. The runtime records tool activity, changes, checks, and run receipts for review.

Developed for simulation kernels, numerical libraries, data pipelines, and mixed-language builds, Clio also supports general software development. Chat and workers can use different models on your workstation, an institutional gateway, or a cloud service. Clio is open-source, pre-1.0 software with active development.

Requires Node.js 22.19 or newer and a model with tool calling. Linux and macOS are the primary platforms; Windows support is best effort.

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

1. Choose Guided setup, then pick the description you recognize: an app on this computer, a model server, an AI subscription, or a provider account. Clio fills in the internal connection name, probes the endpoint when the provider allows it, and lets you select from the model list instead of typing an id. Connect by endpoint remains a shortcut when you already know a URL.

2. Start Clio in your project and give a concrete request:

   Explain how this repository builds and runs its tests. Identify the main entry points and suggest one verification task. Do not change files yet.

3. Use /help for commands, /model for model selection, and /settings for configuration. /settings keeps configure's section names and order, from Connections through Advanced. Reopen Connections → Add a target for Guided setup, Chat to change the answering model, or Fleet for worker defaults. See the settings walkthrough for model inheritance and session, project, and global saves. clio-coder doctor checks installation and connections.

Prefer a browser workspace? After installing the same package, run:

clio-coder gui --open

If you have already configured Clio, open a project and start a conversation. Otherwise, Guided setup in the browser connects your app, server, subscription, or provider account, selects a model, and reviews the connection before saving. You can enter a key or follow the browser sign-in instructions there; running clio-coder configure first is optional. The terminal and GUI share your saved connections and settings. Bare clio-coder still opens the terminal workspace.

# pnpm
pnpm add -g @iowarp/clio-coder

# Run without a global install
npx --yes @iowarp/clio-coder@latest

# Install without the optional Claude Agent SDK worker dependency
npm install -g @iowarp/clio-coder --omit=optional

git clone --branch v0.5.9 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
command -v clio-coder

The terminal brings conversation, tool calls, permissions, fleet activity, and context accounting into one workspace. The browser application provides project and conversation views, session controls, fleet previews, traces, evidence, and configuration through the same runtime. The browser interface is in alpha.

During a conversation, the left sidebar switches between project sessions, recorded runs, and configuration tools while your chat stays open. The collapsible Artifacts panel holds recorded file activity, results, and linked evidence. Open a dedicated trace or evidence viewer when you need more inspection space. Scroll up to read earlier messages; Jump to latest returns immediately to the newest output and resumes following the stream.

_{Terminal workspace. Select a capture to open its full-resolution image.}

clio-coder gui --open

clio-coder gui background install --open

• Repository tools and scientific verification. Read, search, edit, inspect Git, and run declared tests, builds, numerical comparisons, and performance checks. Repository quality policies map changed paths to required checks and track whether their evidence matches the current covered inputs.
• Project context and navigation. Combine an authored CLIO-CODER.md handbook, layered rules, a Tree-sitter codemap, bounded project orientation, and current Git and operator-task observations. Retrieve detail as needed.
• Long-running conversations. Working-set selection keeps model context within its budget while retaining the session ledger. Recall previous observations, inspect /context, and branch, resume, or prepare a handoff.
• Workers and fleets. Assign recipes with declared tools, scope, model, and result contracts. Compose parallel, sequential, review, and other workflows; use worktrees and SSH nodes, and review compiled fleet plans before execution.
• Inspectable execution. View tool activity, diffs, traces, token and cost accounting, checks, and sealed run records. Review and accept memory proposals linked to recorded evidence.
• System One decisions (experimental). Bind a fast decision engine to typed decision sites: the operator's request, a proposed tool call, external tool output, a finished turn, catalog ranking, direct consultation, and /draft judging. Answers are calibrated probabilities, and a site changes nothing until a fitted cut exists for the answering build. clio-coder doctor shows the bindings. See System One.
• Scientific infrastructure and agent interoperability. Connect MCP servers, including clio-kit Slurm workflows. Delegate through supported coding-agent connectors or open companion panes with Herdr and Yazi.
• Reusable procedures and extensions. Install or author skills, agents, prompts, fleets, and plugins. Add executable command tools through declared harness extensions.

# Prepare project guidance and the codemap
clio-coder context init

# Headless execution; timeout is in seconds
clio-coder run "Summarize this repository's entry points."
clio-coder run --json --timeout 300 "Run the existing parser tests and report the results."

# Agent Client Protocol server for editors and other hosts
clio-coder acp

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

A saved model connection is a target. Chat and workers can use different targets, models, and thinking settings. /model changes the current session; Settings → Fleet configures worker defaults.

Clio takes serving windows and capabilities from the live inference server first, then from its packaged model profiles and an optional model-profiles.yaml in your config directory, which can lower a reported capability but never raise it. /context shows where the window came from, and an unknown window stays unknown instead of guessed. Configure a model with the tool calling, context window, vision, and reasoning support your workflow requires. See connections and targets.

The default policy admits workspace reads, edits, and recognized checks, and requests permission for unfamiliar commands and outward actions. Permission cards show the invocation. Yolo removes ordinary approval prompts; protected paths, hard blocks, and damage-control rules continue to apply. In the terminal, Ctrl+G then y switches the current session between the default policy and Yolo without changing saved settings.

Commands execute with your operating-system permissions. Clio's runtime policy controls tool admission, while project tests, numerical references, performance budgets, and human review supply your acceptance criteria. See the safety model and quality policies.

Read the public documentation, open the installed package’s docs/ files in your editor, or ask Clio about her own configuration and source through the offline clio_docs capability. The package includes authored guides, architecture documentation, prompt fragments, agent recipes, and runtime source.

Clio is experimental, actively developed pre-1.0 software. Contributions target the current version branch; main advances with releases. Bug reports should include the Clio and Node versions, reproduction steps, and relevant diagnostics.

Issues · Discussions · Contributor guide · Code of Conduct · Changelog

Report security concerns through SECURITY.md.

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 collaborative awards OAC-2411318 and OAC-2411319, 2024–2029.

Clio builds on the Pi agent framework, ACP, and MCP. Dependency and component notices are in NOTICE.

CLIO means Context Layer for Input/Output. Related IOWarp projects include clio-core for data and context storage and clio-kit for scientific tool servers.