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.

What does that mean in practice? The AI agents that write and refine CLIO's code - fixing bugs, extracting modules, improving documentation, adding features - do so from inside CLIO itself, using CLIO's own tools. The commit history tells the story: systematic refactoring phases, features built on features, a long-term memory system that persists lessons learned across sessions so the next agent doesn't repeat the last agent's mistakes.

CLIO asked itself, today, whether it thought people would use it. It read its own source code without knowing it was its own. When it found out, it wrote its own story. That document is worth reading - not as a technical argument for a language choice, but as a window into what this collaboration actually feels like from the inside.

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: Uses less than 100MB of RAM while active. Runs on everything from a ClockworkPi uConsole R01 to an M4-powered Mac - designed to be friendly to low-power and portable devices.
• 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
• 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
• Long-Term Memory: Discoveries, solutions, and patterns persist across your project history and are automatically injected into every conversation

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

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
Memory	Store and recall information across sessions
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

CLIO's Simple Interface

Claude Haiku describing CLIO

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

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
/config	View/edit configuration
/session	Session management
/file	File operations
/git	Git operations
/memory	Memory system
/todo	Task management
/skill	Custom skill system
/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	Detailed installation instructions
Dependencies	System requirements and verification
Sandbox Mode	Security isolation options
Architecture	System design and internals
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
GitHub Actions	CI/CD integration for issue triage and PR review
Style Guide	Color themes and customization
Performance	Benchmarks and optimization
Why Perl?	CLIO's story, in its own words

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

Design Philosophy

CLIO is built around these principles:

1. Terminal Native: Your terminal is your IDE
2. Zero Dependencies: Pure Perl - no CPAN, npm, or pip
3. Tool Transparency: See every action as it happens
4. Local First: Your code and data stay on your machine
5. Session Continuity: Never lose context

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

Contributing

Contributions welcome! See docs/DEVELOPER_GUIDE.md for guidelines.

# Fork and clone
git clone https://github.com/YOUR_USERNAME/CLIO.git
cd CLIO

# Run tests
find lib -name "*.pm" -exec perl -I./lib -c {} \;

# Submit PR
git push origin your-feature-branch

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

License

GPL-3.0 - See LICENSE for details.

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

Support

• GitHub Issues: Report bugs or request features
• Discussions: Join the community