Contributing

CLIO is open source under the BSD 3-Clause license and is developed by the Gnosis Research Center at Illinois Institute of Technology, as part of IOWarp. It is in beta, so expect rough edges. Fixes, tests, documentation, and bug reports are all welcome.

The repositories

Repository	What it holds
iowarp/clio-agent	The Python backend, the install scripts, Docker files, and this website (in site/)
iowarp/gact-tui	The workspace interfaces: terminal UI, web app, and desktop app
iowarp/clio-agent-marketplace	The default catalog of agent blueprints

The backend repository includes the other two as git submodules, pinned to released tags. Do not change a submodule pin in a feature pull request. Pins are updated as part of a release.

Workflow

CLIO uses gitflow:

1. Branch off develop.
2. Open a pull request into develop.
3. Releases merge develop into main and tag vX.Y.Z.

Write commit messages in conventional style, such as feat:, fix:, docs:, test:, or refactor:. In the pull request, explain the problem and the fix, link any issue, and include the output of the checks below. Add or update tests for changes in behavior.

Set up

You need uv and Python 3.13.

git clone --recurse-submodules https://github.com/iowarp/clio-agent
cd clio-agent
uv sync --extra dev --extra optimizers

Run the checks

Run these before opening a pull request:

uv run ruff check src/ tests/
uv run ruff format src/ tests/
uv run mypy src/
uv run pytest tests/ -m "not integration"

The file tool tests write into the system temp folder, so that folder must be an allowed root:

CLIO_ALLOWED_ROOTS="$TMPDIR:$PWD" uv run pytest tests/

Run the backend from source

uv run clio-agent serve

Then connect an interface to it. Run the backend on its default port, 8100, or pass --port.

Note

Run only one backend at a time against the same user configuration folder. See Install.

The interfaces

The terminal UI, web app, and desktop app live in gact-tui. Its repository has the build and test steps for each, so follow them there.

Improve this website

The website lives in the site/ folder of the backend repository. It is built with Astro and Starlight, and each page is a Markdown or MDX file under site/src/content/docs/. Read site/WRITING.md first. It sets the voice and the accuracy rules: every command, path, and variable on a page must match the source. See site/README.md for how to run the site locally. The “Edit page” link at the bottom of each page opens the file on GitHub.

Report a problem

Run clio report and attach its output to a new issue at github.com/iowarp/clio-agent/issues. Remove anything private first. Say what you did, what you expected, and what happened.

Next steps

TroubleshootingGather the details a good bug report needs.

Command lineThe clio and clio-agent commands.