Pre-release

This release is a pre-release and may not be stable for production use.

CLIO Agent — Cognitive Layer for Adaptive Universal Data & Intelligent Operations

Beta Python 3.12+ UV FastMCP IOWarp

⚠️ 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: use uv tool install --with dspy==3.3.0b1 clio-agent==0.10.0a1 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 / .exe for Windows, .dmg for macOS, .deb / .AppImage / .rpm for Linux), standalone clio-tui-<os>-<arch> binaries, and the web bundle.
  • 🐳 Docker (no install) — docker run -it --rm ghcr.io/iowarp/clio-tui:latest, or docker compose up clio-web for the browser UI.
  • 🖥️ Browser UI — clio --web serves 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

CLIO Agent architecture: user interfaces, the Intelligence Layer (CEI) with the orchestrator and tier-2 experts, tier-3 nanoagents, ARC memory, the optimizer layer, and CTE multi-tier storage

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:

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},
}

Project links

Data verified by PyPI on Aug 19, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Stable release available (0.9.1.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for jcernuda from gravatar.com jcernuda

Credits

Author: Jaime Cernuda

Maintainer: Jaime Cernuda

GitHub Statistics

Data verified by PyPI on Aug 19, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

BSD License (BSD-3-Clause)

Requires

Python >=3.12

Provides Extra

adios all argonne claude-code dev optimizers

Tags

a2a-protocol adios agent-registry arc-memory autonomous-agent clio clio-agent data-io-optimization data-science fastmcp hdf5 hpc iowarp llm-agents mcp multi-agent optimizer-layer parquet react-pattern scientific-computing self-improving slurm

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

clio_agent-0.10.0a1.tar.gz (1.9 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

clio_agent-0.10.0a1-py3-none-any.whl (2.0 MB view details)

Uploaded Python 3

File details

Details for the file clio_agent-0.10.0a1.tar.gz.

File metadata

  • Download URL: clio_agent-0.10.0a1.tar.gz
  • Upload date:
  • Size: 1.9 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","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}

File hashes

Hashes for clio_agent-0.10.0a1.tar.gz
Algorithm Hash digest
SHA256 2714ed2203ab116db5398d19b4f3c1e9b7ca7e5e65a133ac8af7bdcaed55007a
MD5 5f68008dd9613741680249ed2aead819
BLAKE2b-256 f279ff0db6a5182e99aa15565803b36d6c76e71ae8629b9acf475ba66d453567

See more details on using hashes here.

File details

Details for the file clio_agent-0.10.0a1-py3-none-any.whl.

File metadata

  • Download URL: clio_agent-0.10.0a1-py3-none-any.whl
  • Upload date:
  • Size: 2.0 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","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}

File hashes

Hashes for clio_agent-0.10.0a1-py3-none-any.whl
Algorithm Hash digest
SHA256 81ba3e19ef19520fd91d59cd2dd094d0fb2a5986948c2a409372a41734ffc60e
MD5 637cd869ab719ee31c1c1711c0e8cbf4
BLAKE2b-256 5604821e1699ce262eea21b7482e5da0b53e1667afc2a7b2b003b6c198521bd9

See more details on using hashes here.

Release history Release notifications | RSS feed

This release
Pre-release

0.10.0a1 This release

2 files

0.9.1.1

2 files

0.9.1

2 files

0.9.0

2 files

0.8.1

2 files

0.8.0

2 files

0.7.12

2 files

0.7.11

2 files

0.7.10

2 files

0.7.9

2 files

0.7.8

2 files

0.7.7

2 files

0.7.6

2 files

0.7.5

2 files

0.7.4

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.1

2 files

0.6.0

2 files

0.5.18

2 files

0.5.17

2 files

0.5.16

2 files

0.5.15

2 files

0.5.14

2 files

0.5.13

2 files

0.5.12

2 files

0.5.11

2 files

0.5.10

2 files

0.5.9

2 files

0.5.8

2 files

0.5.7

2 files

0.5.6

2 files

0.5.5

2 files

0.5.4

2 files

0.5.3

2 files

0.5.1

2 files

0.5.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page