Skip to content
Back to search

CLIO

An AI-assisted coding agent that runs in your terminal and supports many providers and models.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/SyntheticAutonomicMind/CLIO with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/SyntheticAutonomicMind/CLIO'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/syntheticautonomicmind--clio/badge.svg)](/listings/syntheticautonomicmind--clio)

HTML

<a href="/listings/syntheticautonomicmind--clio"><img src="/api/listings/syntheticautonomicmind--clio/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Check you have the essentials
./check-deps

# Install (macOS)
brew tap SyntheticAutonomicMind/homebrew-SAM && brew install clio

# Or install manually
git clone https://github.com/SyntheticAutonomicMind/CLIO.git
cd CLIO && sudo ./install.sh

# Or run in Docker (no local Perl needed)
docker run -it --rm -v "$(pwd)":/workspace -v clio-auth:/root/.clio \
  -w /workspace ghcr.io/syntheticautonomicmind/clio:latest --new

Then configure a provider - GitHub Copilot is the fastest path:

clio --new
: /api login
# Browser opens, you authorize, done

Or set an API key:

clio --new
: /api set provider openai
: /api set key YOUR_API_KEY
: /config save

Then give it a real task:

Find the bug causing the authentication failure, fix it, add a regression
test, run the relevant tests, and show me the resulting diff.

Or just start a conversation:

clio --new

Useful Commands

clio --new                    # Start a new session
clio --resume                 # Resume last session
clio --debug                  # Debug mode
clio --sandbox                # Restrict to project directory only
clio --enable file_operations # Allowlist specific tools
clio --disable web_operations # Block specific tools

CLIO requires Perl 5.32+ and standard Unix tools (git, curl, stty, tput, tar). All Perl modules are core - no external dependencies. See [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md) and [docs/INSTALLATION.md](docs/INSTALLATION.md) for details.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 206 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # CLIO
  2. **A terminal-native AI development agent and extensible agent harness. The model does the reasoning - CLIO provides the tools, context, session state, and recovery.**
  3. I built CLIO for myself. I spend more time in terminal sessions than I do using GUIs, and I wanted an AI coding tool that worked the way I work. It didn't really exist, so I built it. Starting with v20260119.1, CLIO has been building itself - all development on SAM, CLIO, and ALICE happens through pair programming with CLIO.
  4. [![GPL-3.0-only License](https://img.shields.io/badge/license-GPL--3.0--only-blue)](LICENSE) [![Perl 5.32+](https://img.shields.io/badge/perl-5.32%2B-blue)](docs/DEPENDENCIES.md) [![Discussions](https://img.shields.io/badge/discussions-join-brightgreen)](https://github.com/orgs/SyntheticAutonomicMind/discussions)
  5. ---
  6. Give CLIO a task and it works through it end to end - investigates your codebase, proposes a plan, implements after your approval, runs tests, and commits. It reads your code, edits files across multiple modules, searches with understanding, and runs shell commands. You can interrupt it mid-task with any keypress and it picks up where you left off next session.
  7. CLIO is a Perl-based agent harness that works anywhere Perl runs. No CPAN, no pip, no npm - just core Perl and standard Unix tools. It supports 24 AI providers including GitHub Copilot, OpenAI, Anthropic, Google Gemini, DeepSeek, OpenRouter, MiniMax, Z.AI, NVIDIA NIM, Opper, and local models via llama.cpp or LM Studio. You can also point it at any OpenAI-compatible endpoint.
  8. For the full architecture overview - the six-layer security model, memory system, multi-agent coordination, and how all the pieces fit together - the [website has a thorough writeup](https://www.syntheticautonomicmind.org/docs/CLIO/index.html). This README gets you running.
  9. ---
  10. ## What It Actually Does
  11. Here's the concrete list - things that happen when you use CLIO:
  12. - **Investigates before modifying.** CLIO searches your codebase, reads files, and builds understanding before proposing changes. It doesn't guess.
  13. - **Edits files with undo.** Changes are written through `file_operations` with path authorization. Every edit is backed up - `/undo` reverts any turn, not just the last one.
  14. - **Runs tests and git.** It commits, branches, stashes, and pushes. Test failures get fed back in for another iteration.
  15. - **Remembers across sessions.** CLIO stores discoveries, solutions, and code patterns in long-term memory. The next session on the same project starts with what was learned last time.
  16. - **Coordinates parallel work.** Spawn sub-agents with file and git locks so multiple agents can work on the same repo without stepping on each other. They communicate over a Unix socket message bus.
  17. - **Runs across your fleet.** SSH into any machine, deploy CLIO, run a task, get results back in your local session. Or deploy across your entire fleet in parallel.
  18. - **Integrates with terminals.** Live agent output in tmux, GNU Screen, or Zellij panes. Auto-detected - works without them too.
  19. - **Stays private by design.** Secret redaction strips API keys, tokens, and passwords from AI context before they reach the model. File access outside the project directory needs your approval. Invisible Unicode characters that could hide prompt injections are filtered automatically.
  20. - **Sandboxes when needed.** `--sandbox` blocks web, remote, and agent access and restricts file operations to the project directory. For true isolation, `clio-container` runs CLIO in Docker with `--cap-drop ALL`.
  21. - **Builds itself.** CLIO has been maintaining its own codebase, ALICE, and SAM through AI-assisted development since v20260119.1.
  22. ### Tools Available by Default
  23. CLIO exposes 9 tools to the model. Three more load conditionally based on config. MCP and plugin tools load dynamically.
  24. | Tool | What It Does |
  25. |---|---|
  26. | `file_operations` | Read, write, search, edit, delete, rename, list directories, grep, semantic search |
  27. | `version_control` | Full git: status, diff, log, commit, branch, push, pull, stash, tag, worktree, blame |
  28. | `terminal_operations` | Shell execution with fork+process-group isolation and risk classification |
  29. | `memory_operations` | Store/retrieve key-value state, LTM patterns, session recall |
  30. | `web_operations` | Fetch URLs, web search |
  31. | `todo_operations` | Create, update, complete, list multi-step tasks |
  32. | `code_intelligence` | Symbol references with definitions ranked first (list_usages), file outline (outline), semantic git commit search (search_history) |
  33. | `interact` | Checkpoint prompts - pause the agent loop to ask for your input |
  34. | `apply_patch` | Apply lightweight diff patches |
  35. Conditional: `remote_execution`, `agent_operations`, `skill_operations`.
  36. ### AI Providers
  37. 24 providers are configured in `lib/CLIO/Providers.pm`. Anthropic, Google, and NVIDIA use native protocol adapters - everything else is OpenAI-compatible or Copilot format.
  38. | Provider | Auth | Notes |
  39. |---|---|---|
  40. | GitHub Copilot | OAuth | Access to GPT-4, Claude, o1/o3, MiniMax |
  41. | OpenAI | API Key | GPT-5, o1/o3, GPT-4o |
  42. | Anthropic | API Key | Claude via native Messages API |
  43. | Google Gemini | API Key | Gemini 2.5 Pro/Flash |
  44. | DeepSeek | API Key | DeepSeek V4 |
  45. | llama.cpp (Local) | No auth | Local models via llama.cpp server |
  46. | LM Studio | No auth | Local models via LM Studio server |
  47. | OpenRouter | API Key | 100+ models, automatic fallback |
  48. | Ollama Cloud | API Key | Cloud-hosted Ollama |
  49. | MiniMax | API Key | MiniMax-M3 |
  50. | MiniMax Token Plan | API Key | Token-plan billing variant |
  51. | Z.AI (Chat) | API Key | GLM models |
  52. | Z.AI (Coding) | API Key | GLM coding-optimized |
  53. | NVIDIA NIM | API Key | Nemotron models |
  54. | Vercel AI Gateway | API Key | Vercel's managed gateway |
  55. | OrcaRouter | API Key | Auto-routing across upstreams |
  56. | KiloCode | API Key | Auto-rotating free models |
  57. | Opper | API Key | Most recent addition |
  58. | Charm Hyper | API Key | HyperCharm gateway |
  59. | Synap by Linkrra | API Key | Open-weight models; keyless x402 pay-per-call |
  60. | SAM | API Key | Use your local SAM instance |
  61. Run `/api models` after setup to see current model availability. Full setup instructions in [docs/PROVIDERS.md](docs/PROVIDERS.md).
  62. ---
  63. ## Quick Start
  64. ```bash
  65. # Check you have the essentials
  66. ./check-deps
  67. # Install (macOS)
  68. brew tap SyntheticAutonomicMind/homebrew-SAM && brew install clio
  69. # Or install manually
  70. git clone https://github.com/SyntheticAutonomicMind/CLIO.git
  71. cd CLIO && sudo ./install.sh
  72. # Or run in Docker (no local Perl needed)
  73. docker run -it --rm -v "$(pwd)":/workspace -v clio-auth:/root/.clio \
  74. -w /workspace ghcr.io/syntheticautonomicmind/clio:latest --new
  75. ```
  76. Then configure a provider - GitHub Copilot is the fastest path:
  77. ```bash
  78. clio --new
  79. : /api login
  80. # Browser opens, you authorize, done
  81. ```
  82. Or set an API key:
  83. ```bash
  84. clio --new
  85. : /api set provider openai
  86. : /api set key YOUR_API_KEY
  87. : /config save
  88. ```
  89. Then give it a real task:
  90. ```text
  91. Find the bug causing the authentication failure, fix it, add a regression
  92. test, run the relevant tests, and show me the resulting diff.
  93. ```
  94. Or just start a conversation:
  95. ```bash
  96. clio --new
  97. ```
  98. ### Useful Commands
  99. ```bash
  100. clio --new # Start a new session
  101. clio --resume # Resume last session
  102. clio --debug # Debug mode
  103. clio --sandbox # Restrict to project directory only
  104. clio --enable file_operations # Allowlist specific tools
  105. clio --disable web_operations # Block specific tools
  106. ```
  107. CLIO requires Perl 5.32+ and standard Unix tools (git, curl, stty, tput, tar). All Perl modules are core - no external dependencies. See [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md) and [docs/INSTALLATION.md](docs/INSTALLATION.md) for details.
  108. ---
  109. ## Privacy and Security
  110. CLIO is local-first and provider-independent. With local model backends, model interaction can stay on your hardware. When you select a hosted provider, the context required for that provider is sent to that provider.
  111. Defense in depth - these layers apply regardless of provider:
  112. - **Secret redaction** - API keys, tokens, passwords, and PII are stripped from AI context before it reaches the model
  113. - **Command analysis** - shell commands are classified by risk level (network, credential access, destructive) and require your approval for high-risk operations
  114. - **Path authorization** - file access outside the project directory needs your permission
  115. - **Invisible character filtering** - Unicode prompt injection is blocked automatically
  116. - **Sandbox mode** - `--sandbox` blocks web, remote, and agent access, restricts files to the project directory
  117. - **Container isolation** - `clio-container` runs CLIO inside Docker with dropped capabilities
  118. See [docs/SECURITY.md](docs/SECURITY.md) and [docs/SANDBOX.md](docs/SANDBOX.md).
  119. ---
  120. ## Screenshots
  121. <table>
  122. <tr>
  123. <td width="50%">
  124. <h3>CLIO investigating a repository, showing live tool execution</h3>
  125. <a href="https://raw.githubusercontent.com/SyntheticAutonomicMind/CLIO/main/.images/clio1.png">
  126. <img src=".images/clio1.png"/>
  127. </a>
  128. </td>
  129. <td width="50%">
  130. <h3>Multi-provider model configuration with thinking modes</h3>
  131. <a href="https://raw.githubusercontent.com/SyntheticAutonomicMind/CLIO/main/.images/clio2.png">
  132. <img src=".images/clio2.png"/>
  133. </a>
  134. </td>
  135. </tr>
  136. </table>
  137. ---
  138. ## Documentation
  139. The [website docs](https://www.syntheticautonomicmind.org/docs/CLIO/index.html) cover the user guide, architecture, security model, and methodology. In-repo docs:
  140. - [User Guide](docs/USER_GUIDE.md) - complete usage and slash commands
  141. - [Architecture](docs/ARCHITECTURE.md) - system design and internals
  142. - [Memory](docs/MEMORY.md) - how sessions, LTM, and recovery work
  143. - [Providers](docs/PROVIDERS.md) - AI provider setup
  144. - [Sandbox Mode](docs/SANDBOX.md) - isolation options
  145. - [Security](docs/SECURITY.md) - full security model
  146. - [Remote Execution](docs/REMOTE_EXECUTION.md) - fleet deployment
  147. - [Multi-Agent](docs/MULTI_AGENT_COORDINATION.md) - parallel agent coordination
  148. - [MCP Integration](docs/MCP.md) - Model Context Protocol support
  149. - [Skills](docs/FEATURES.md#11-skills-system) - custom skill management
  150. - [OpenSpec](docs/PUPPETEER_MODE.md) - spec-driven development
  151. - [Developer Guide](docs/DEVELOPER_GUIDE.md) - contributing
  152. ---
  153. CLIO is part of [Synthetic Autonomic Mind](https://github.com/SyntheticAutonomicMind). GPL-3.0-only for code, CC-BY-NC-SA-4.0 for documentation. Created by Andrew Wyatt (fewtarius).
  154. [Website](https://www.syntheticautonomicmind.org) | [GitHub](https://github.com/SyntheticAutonomicMind/CLIO) | [Discussions](https://github.com/orgs/SyntheticAutonomicMind/discussions)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.