CLIO - Command Line Intelligence Orchestrator

An AI code assistant for people who live in the terminal. Portable, privacy-first, and designed for real work.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Why I Built CLIO

I built CLIO for myself. As someone who prefers working in the terminal, I wanted an AI assistant that felt native to my workflow. One that respected my privacy, worked anywhere Perl runs, and gave me full control over my code and tools. I couldn't find anything that met those needs, so I created CLIO.

Starting with version 20260119.1, CLIO has been building itself. All of my development is now done through pair programming with AI agents using CLIO.

CLIO is part of the Synthetic Autonomic Mind (SAM) organization, which is dedicated to building user-first, privacy-respecting AI tools. If you value transparency, portability, and the power of the command line, CLIO is for you.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

What Makes CLIO Different

• Terminal-First Experience: Runs entirely in your terminal with professional markdown rendering, color themes, and streaming output
• Light & Nimble: ~50 MB at startup, grows moderately with session activity. Works on everything from a ClockworkPi uConsole R01 to an M4-powered Mac.
• Portable & Minimal: Works with standard Unix tools (git, curl, etc.) - no heavy frameworks or package managers required. See docs/DEPENDENCIES.md for details.
• Actually Autonomous: CLIO doesn't just suggest code - it reads, writes, tests, commits, and iterates. Give it a task and it works through it end-to-end.
• Tool-Powered: Real file, git, and terminal operations with real-time action descriptions
• Privacy & Control: Your code stays on your machine - only minimum context sent to AI providers. Built-in secret redaction catches API keys, tokens, PII, and credentials before they reach the AI.
• Persistent Sessions: Pick up exactly where you left off with full conversation history
• Scriptable & Extensible: Fits into your workflow, not the other way around
• Remote Execution: SSH into any machine, deploy CLIO, run an AI task, and get results back - across your entire fleet in parallel
• Multi-Agent Coordination: Spawn parallel agents with file locks, git locks, and coordinated API rate limiting for safe collaboration
• Multiplexer Integration: When running inside tmux, GNU Screen, or Zellij, sub-agent output streams live in separate panes
• Long-Term Memory: Discoveries, solutions, and patterns persist across your project history and are automatically injected into every conversation
• User Profile: CLIO learns your communication style, preferences, and working patterns from session history and personalizes every interaction
• Interrupt Anytime: Press any key to stop the agent mid-task. CLIO pauses, asks what you need, and adapts - like tapping your pair programmer on the shoulder

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Core Features

| Category | Capabilities | |----------|--------------| | Files | Read, write, search, edit, manage files | | Git | Status, diff, commit, branch, push, pull, stash, tag | | Terminal | Execute commands and scripts directly | | Remote | Run AI tasks on remote systems via SSH | | Multi-Agent | Spawn parallel agents for complex work | | Multiplexer | Live agent output panes via tmux, GNU Screen, or Zellij | | Memory | Store and recall information across sessions | | Profile | Learns your working style and personalizes collaboration | | Todos | Manage tasks within your workflow | | Web | Fetch and analyze web content | | MCP | Connect to external tool servers via Model Context Protocol | | AI Providers | GitHub Copilot, OpenAI, Anthropic, Google Gemini, DeepSeek, OpenRouter, llama.cpp, LM Studio, SAM |

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Screenshots

<table> <tr> <td width="50%"> <h3>CLIO's Simple Interface</h3> <img src=".images/clio1.png"/> </td> <td width="50%"> <h3>Claude Haiku describing CLIO</h3> <img src=".images/clio2.png"/> </td> </tr> </table>

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Real-World Performance

CLIO is built to run for hours without breaking a sweat. These are stats from real development sessions:

Session 1 - Active development (1h, 244 turns):
  Baseline: 46 MB | RSS: 73 MB | Tool calls: 244

Session 2 - Heavy multi-hour session:
  Typical range: 50-100 MB depending on context size

CLIO starts at ~50 MB and grows gradually as session context accumulates. Multi-hour sessions with hundreds of tool calls typically stay under 100 MB. No memory leaks, no degradation, no restart needed.

Billing Awareness

CLIO tracks your API usage in real time with /usage:

Premium Quota
──────────────────────────────────────────────────────────────
  Status:                   891 used of 1500 (59.3%)
  Resets:                   2026-03-01
Token Usage
──────────────────────────────────────────────────────────────
  Total Tokens:             13,428,981
    Prompt:                 13,422,054 tokens
    Completion:             6,927 tokens

No surprises at the end of the month. See your quota consumption, billing multipliers for premium models, per-request token counts, and reset dates. CLIO warns you when premium models cost extra (e.g., Claude Opus at 3x) so you can make informed choices.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Quick Start

Check Dependencies

./check-deps  # Verify all required tools are installed

CLIO requires standard Unix tools (git, curl, perl 5.32+, etc.). See docs/DEPENDENCIES.md for details.

Install

Homebrew (macOS)

brew tap SyntheticAutonomicMind/homebrew-SAM
brew install clio

Docker (Any Platform)

docker run -it --rm \
    -v "$(pwd)":/workspace \
    -v clio-auth:/root/.clio \
    -w /workspace \
    ghcr.io/syntheticautonomicmind/clio:latest \
    --new

Manual

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

For detailed options, see docs/INSTALLATION.md.

Configure AI Provider

GitHub Copilot (Recommended - no config needed)

./clio
: /api login
# Follow browser prompts to authorize

Other Providers

./clio
: /api set provider openai
: /api set key YOUR_API_KEY
: /config save

Start Using CLIO

./clio --new          # New conversation
./clio --resume       # Resume last session
./clio --debug        # Debug mode

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Slash Commands (Quick Reference)

| Command | Description | |---------|-------------| | /help | Show available commands | | /api | Configure AI providers and models | | /config | View/edit configuration | | /session | Session management | | /file | File operations | | /git | Git operations | | /undo | Revert AI changes from last turn | | /memory | Long-term memory system | | /profile | Build and manage user personality profile | | /todo | Task management | | /agent | Spawn and manage sub-agents | | /mux | Terminal multiplexer panes (tmux/screen/Zellij) | | /mcp | Model Context Protocol servers | | /skill | Custom skill system | | /update | Check for and install updates | | /usage | API billing and quota tracking | | /stats | Memory and performance stats | | /device | Remote device management | | /theme | Change color theme | | /clear | Clear screen | | /exit | Exit CLIO |

For complete command reference, see docs/USER_GUIDE.md.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Example Usage

You: Read the main config file and explain its structure

CLIO: [Reading lib/CLIO/Core/Config.pm]

The Config module handles CLIO's configuration system. Key sections:
- **Defaults**: Provider settings, model preferences
- **Persistence**: JSON-based storage in ~/.clio/config.json
- **Runtime overrides**: Environment variables and CLI flags

You: Fix the bug in the login function

CLIO: [Reading lib/CLIO/Security/Auth.pm]
      [Identified issue: token validation missing null check]
      [Writing fix to lib/CLIO/Security/Auth.pm]
      
Fixed the bug. The issue was...

For more examples, see docs/USER_GUIDE.md.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Requirements

• macOS 10.14+ or Linux (any modern distribution)
• Perl 5.32+ (included with most systems)
• Git (for version control operations)
• ANSI-compatible terminal

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Documentation

| Document | Description | |----------|-------------| | User Guide | Complete usage guide with examples | | Feature Guide | Every feature explained in detail | | Installation | Getting started with CLIO | | Providers | AI provider configuration guide | | Dependencies | System requirements and verification | | Sandbox Mode | Security isolation options | | Architecture | System design and internals | | Memory Architecture | How CLIO remembers and learns across sessions | | Developer Guide | Contributing and extending CLIO | | Remote Execution | Distributed AI workflows | | Multi-Agent | Parallel agent coordination | | MCP Integration | Model Context Protocol support | | Custom Instructions | Per-project AI customization | | [Automation](docs/AUTOMAT