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
• Portable & Minimal: Works with standard Unix tools (git, curl, etc.) - no heavy frameworks or package managers required. See docs/DEPENDENCIES.md for details.
• 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

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

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
AI Providers	GitHub Copilot, OpenAI, DeepSeek, OpenRouter, llama.cpp, 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.20+ (included with most systems)
• Git (for version control operations)
• ANSI-compatible terminal

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

Documentation

Document	Description
User Guide	Complete usage guide with examples
Installation	Detailed installation instructions
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
Custom Instructions	Per-project AI customization

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

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