Open source · BSD-3-Clause

Contributing to CLIO

Welcome! CLIO is built in the open and we'd love your help: whether that's a bug report, a docs fix, a new tool, or a deep dive into the agent core.

Clone & run from source

CLIO uses uv for dependency management and execution. Git submodules carry the bundled tool servers, so clone recursively.

$ git clone --recurse-submodules https://github.com/iowarp/clio-agent
$ cd clio-agent
$ uv sync --extra optimizers --extra argonne
$ uv run src/clio_agent/ui/cli.py

Build the front-ends from source

The terminal, web, and desktop front-ends live in the gact-tui repo, vendored here as the external/gact-tui submodule: so clone with --recurse-submodules (the command above already does). The front-ends all talk to the same backend server.

Backend (server)

Start the server the front-ends connect to:

$ uv run clio-agent-gact

Terminal UI

Build the TUI binary, then run it: it connects to the running server. The script bakes in GACT_BRAND=clio.

$ GACT_TUI_ROOT=external/gact-tui ./scripts/build_clio_tui.sh dist/clio-tui
$ dist/clio-tui

Web

Build the web bundle. The server serves it when pointed at the dist via CLIO_WEB_DIR: or just use docker compose up clio-web.

$ cd external/gact-tui/apps
$ GACT_BRAND=clio GACT_BRAND_ROOT="$PWD/../../branding" pnpm --filter @clio/web build

Desktop

The desktop app is built with Tauri from external/gact-tui/apps/desktop, using the CLIO branding overlay at branding/clio/tauri.clio.conf.json. The CI bundles workflow is the reference build: see the gact-tui workflows.

Project layout

• src/clio_agent/: the agent: planner loop, experts, registry, ARC memory, optimizer, runtime, tools, and the CLI / REST UIs.
• tests/: unit and integration tests (pytest).
• install/: the install scripts and the clio launcher.
• docs/: architecture notes and reference material.

Dev workflow

We follow gitflow:

• Branch off develop for your work.
• Open a pull request into develop.
• Releases merge develop → main and tag vX.Y.Z.

Before you push: make sure the tests pass and lint is clean.

$ uv run pytest tests/
$ uv run ruff check --fix src/ && uv run ruff format src/