⚠️ Beta. CLIO is under active development — interfaces, blueprints, and on-disk formats may change between releases. Pin a version for reproducibility.
What is CLIO Agent?
An autonomous agent for scientific data management — HDF5, Parquet, and CSV inspection through a FastMCP tool gateway, with a Bubbletea terminal UI (gact) for interactive work. CLIO is the Intelligence Layer (CEI) of the IOWarp platform.
The agent runs in three tiers: a main orchestrator (planner loop over registered tools and experts), domain experts (data / analysis / visualization), and ephemeral nanoagents for parallel sub-tasks. State lives in a local-first memory layer (ARC) that all tiers read and write.
- Multi-expert orchestration with capability-based routing
- FastMCP tool gateway, HDF5 + Parquet servers out of the box
- ARC memory with O(log N) context retrieval
- Optimizer layer for offline tuning + online learning
- Runtime doctor for LM / gateway / file-policy health
- Works with LM Studio, Ollama, OpenAI, Anthropic, OpenRouter, OpenAI Codex subscriptions, and the Argonne ALCF inference gateway
Quick Start
One line installs clio-agent from PyPI, downloads the matching CLIO-branded
TUI binary for your platform, and drops a clio command on your PATH.
Linux / macOS
curl -fsSL https://raw.githubusercontent.com/iowarp/clio-agent/main/install/install.sh | bash
clio
Windows (PowerShell)
irm https://raw.githubusercontent.com/iowarp/clio-agent/main/install/install.ps1 | iex
clio
clio boots the server (if it isn't already up) and attaches the TUI. On first connect, pick an LM provider in the modal and you're chatting.
Prerequisites for the default release install: uv
or Python 3.12+ with pip. git and Go are only needed when you opt into
source-build mode with CLIO_REF or GACT_REF.
CLIO pins its intentional DSPy 3.3 prerelease and the tested stable LiteLLM release.
Registry-backed uv tool install needs that exact DSPy dependency declared as an
explicit root and prerelease resolution enabled: use
uv tool install --prerelease allow --with dspy==3.3.0b1 clio-agent==0.9.4.1 for a
persistent backend-only install. This keeps unrelated dependencies on stable releases.
Reserve uvx / uv tool run for disposable checks. See
install/README.md for the full contract.
More ways to get CLIO
The install script above is one of several download options:
- 🌐 CLIO website → — guided downloads and a tour of the product.
- 📦 GitHub Releases → — desktop apps (
.msi/.exefor Windows,.dmgfor macOS,.deb/.AppImage/.rpmfor Linux), standaloneclio-tui-<os>-<arch>binaries, and the web bundle. - 🐳 Docker (no install) —
docker run -it --rm ghcr.io/iowarp/clio-tui:latest, ordocker compose up clio-webfor the browser UI. - 🖥️ Browser UI —
clio --webserves the web app locally.
Full matrix (script · docker · web · desktop · compose · source) with copy-paste commands: docs/INSTALL.md.
Using the clio command
clio with no arguments is the one-command UX. The subcommands manage the backing server without hunting PIDs:
| Command | What it does |
|---|---|
clio |
ensure the server is up, then attach the TUI |
clio start / stop / restart |
server lifecycle (process-tree kill on stop) |
clio status / ps |
PID, port, health |
clio logs [N] |
tail server + TUI stderr logs |
clio doctor |
check prerequisites and install layout |
clio report |
diagnostics bundle for filing GitHub issues |
clio completion <shell> |
tab-completion (bash / zsh / powershell) |
clio uninstall |
remove CLIO (--purge / -Purge to drop config too) |
Override paths with CLIO_PREFIX / CLIO_BIN_DIR and the server port with CLIO_PORT. Full install + uninstall reference: install/README.md.
Architecture
For the design rationale (three-tier hierarchy, ARC memory, optimizer layer, IOWarp integration), see docs/CLIO_AGENT_ARCHITECTURE.md.
Documentation
The full, organized index is in docs/README.md. Common starting points:
- Setup & install — release install, source build, smoke test
- Architecture — the three-tier design, ARC memory, and tool gateway
- Contributing — dev environment, quality checks, and where code goes
- Adding tools / experts — extend the agent
- Providers — configure an LM backend
- Roadmap — what's next
Contributing
Start with docs/CONTRIBUTOR_QUICKSTART.md. For guidance specific to AI agents working on the codebase, see AGENTS.md.
License + Citation
BSD-3-Clause.
@software{clioagent2026,
title = {CLIO Agent: Autonomous Agent for Scientific Data Management},
author = {IOWarp Team},
year = {2026},
url = {https://github.com/iowarp/clio-agent},
}
1 maintainer
Release files for clio-agent 0.9.4.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| clio_agent-0.9.4.1.tar.gz | 2.6 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| clio_agent-0.9.4.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 5.4 MB
Release files / clio_agent-0.9.4.1.tar.gz
| Download URL | clio_agent-0.9.4.1.tar.gz |
|---|---|
| Size | 2.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a7760b59ec187764e0e49086e7182329be4658af8b8f635d39de5df4e1344c63
|
|
BLAKE2b-256 checksum How to use checksums |
c637ae7fc8a504348c10b152012ad3f7fa23c85e4637216d3bf6e844aaf403ab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / clio_agent-0.9.4.1-py3-none-any.whl
| Download URL | clio_agent-0.9.4.1-py3-none-any.whl |
|---|---|
| Size | 2.8 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2a9d7964e4a56689e1c574d5b970df5219e20746f57f428955fb9521fe5fb82a
|
|
BLAKE2b-256 checksum How to use checksums |
0f8998b86daa37c1345df65bab8ca54b2819bda057f6b019bbcda0a29dd9b713
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
