CLIO User Guide

June 23, 2026 · View on GitHub

Complete guide to using CLIO (Command Line Intelligence Orchestrator)

Introduction
Installation
Getting Started
Slash Commands Reference
Core Concepts
Available Tools
Usage Examples
Configuration
Customization
Skills
Security & Sandbox Mode
Tips & Best Practices
Troubleshooting
FAQ

Introduction

What is CLIO?

CLIO is a terminal-native AI coding tool. It works inside your shell, uses real tools to inspect and change a codebase, and stays collaborative while it works.

You can ask CLIO to read files, explain code, search a repository, edit files, run tests, use git, fetch documentation, and work through development tasks step by step.

CLIO is not just chat in a terminal, and it is not just autocomplete. It is built for people who want AI help without leaving a terminal-first workflow.

How CLIO Works

A typical CLIO workflow looks like this:

You describe a task
CLIO investigates by reading files, searching code, or checking repository state
CLIO presents findings or a plan when your input matters
After approval, CLIO does the work using files, git, commands, web fetches, or other tools
CLIO verifies results and reports back

That means CLIO can help with real development work, not just produce text.

Why Choose CLIO?

Terminal-Native: CLIO works in local shells, SSH sessions, tmux, GNU Screen, Zellij, containers, and headless environments.

Tool-Powered: CLIO uses real tools to read files, run commands, inspect git state, and modify a project. It does not need you to paste everything into chat.

Action Transparency: Every operation shows exactly what it is doing. You can see what CLIO reads, what commands it runs, and what changes it makes.

Persistent Context: Conversations are saved automatically. You can resume later with full history, and long-term memory can carry useful discoveries and patterns forward.

Lightweight: CLIO is written in Perl, uses core modules, and avoids heavy runtime dependencies.

Professional Output: CLIO renders markdown, code blocks, tables, and structured output clearly in the terminal.

What Can CLIO Do?

Code Understanding: Read and analyze code, explain functions, trace logic
File Operations: Read, write, search, edit files across your project
Version Control: Git operations (status, diff, commit, branch, merge, worktree)
Command Execution: Run terminal commands and scripts
Code Refactoring: Restructure code with intelligent changes
Documentation: Generate docs, write README files, create comments
Research: Fetch web content, analyze documentation
Task Management: Create and manage todo lists
Memory: Store and recall information across sessions

Installation

Prerequisites

System Requirements:

macOS 10.14+ or Linux (any modern distribution)
Perl 5.32 or higher
Git (for version control operations)
ANSI-compatible terminal emulator

AI Provider Requirements:

OpenRouter API key with MiniMax (recommended), OR
GitHub Copilot subscription (supports GPT, Claude, and more), OR
API key from any supported provider: OpenAI, Anthropic, Google Gemini, DeepSeek, MiniMax, OR
Local model server: llama.cpp, LM Studio, or SAM (no API key needed)

Installation Steps

1. Clone the Repository

git clone https://github.com/SyntheticAutonomicMind/CLIO.git
cd CLIO

2. Run the Installer

sudo ./install.sh

The installer will:

Install CLIO executable to /usr/local/bin/clio
Set up library files in /usr/local/lib/clio/
Create configuration directories
Set proper permissions

3. Verify Installation

clio --help

You should see:

CLIO - Command Line Intelligence Orchestrator
AI-Powered Development Assistant

USAGE:
    clio [OPTIONS]
...

Configuration

GitHub Copilot Setup (Default - Recommended)

No environment variables needed! Just start CLIO and login:

./clio
: /api login
# Follow browser prompts to authorize with GitHub
# Tokens are saved automatically to ~/.clio/github_tokens.json

Want More AI Models?

The default OAuth authentication provides access to dozens of models. For additional preview models, use a Personal Access Token (PAT):

Create a PAT at GitHub:
- Go to https://github.com/settings/tokens
- Click "Generate new token (classic)"
- Select scopes: copilot and manage_billing:copilot
- Generate and copy the token

Set the PAT in CLIO:

./clio
: /api set github_pat ghp_your_token_here

Verify you have more models:

: /api models
# Should show additional preview and premium models

Note: PAT authentication takes priority over OAuth when both are configured. To revert to OAuth, clear the PAT with /api set github_pat "".

Alternative Provider Setup

Use /api commands interactively:

./clio
: /api set provider openai
: /api set key YOUR_OPENAI_API_KEY
: /api set model <model-name>

All /api set commands save globally by default. To set a value for the current session only, add --session:

: /api set model gpt-4.1 --session       # Only affects this session
: /api set provider llama.cpp --session   # Only affects this session

Use /api show to see your current configuration and whether any values are session overrides.

See PROVIDERS.md for setup instructions for all 14 providers.

Optional Environment Variables

# Set custom session directory
export CLIO_SESSION_DIR="$HOME/.clio/sessions"

Debug Output

Use the --debug flag to enable debug output: clio --debug --new

Note: API keys and providers are configured with /api commands, not environment variables.

Getting Your GitHub Copilot Token

Open VS Code or your GitHub Copilot-enabled editor
Access the Copilot settings
Generate an API token
Copy and set as GITHUB_COPILOT_TOKEN

Getting Started

Your First Session

Start CLIO:

clio --new

You'll see the welcome banner:

------------------------------------------
CLIO - Command Line Intelligence Orchestrator
Session ID: sess_20260118_143052
You are connected to claude-sonnet-4
Press "?" for a list of commands.
------------------------------------------

YOU:

A Good First Prompt

Start with something grounded in a real project:

Read this codebase and explain how configuration is loaded.

Or:

Find the code path that handles failed authentication.

Or:

Review the repository and tell me where tests are defined.

These kinds of prompts help you see how CLIO investigates before it changes anything.

Keyboard Controls

During AI Responses:

Key	Action
`Space` / `Any Key`	Continue to next page (long responses)
`q` / `Q`	Quit pagination, return to prompt
`Up` / `Down` (Arrows)	Navigate pages (non-streaming mode)
`Ctrl+D` or `Ctrl+C`	Exit CLIO
Any key	Interrupt workflow, return to prompt

In Text Input:

Key	Action
`Left` / `Right` (Arrows)	Move cursor one character
`Alt+Left` / `Alt+Right`	Jump by word
`Home` / `End`	Move to start/end of line
`Ctrl+A` / `Ctrl+E`	Start/end of line (emacs)
`Tab`	Auto-complete commands/paths
`ESC`	Cancel multi-line input

Input Modes

Single-Line Input (Default):

: Your question here...

Multi-Line Input - Open your editor for complex prompts:

: /multiline
# or
: /ml
# (Opens $EDITOR for full prompt composition)

Smart Pagination

CLIO automatically handles long responses intelligently:

During AI Thinking: No pagination interruption (tool operations flow freely)
During Final Response: Automatic pause at screen height (press any key to continue)
Stream Mode: Quick confirmation pauses for long outputs
Page Navigation: Arrow keys to scroll back through pages (non-streaming)

This means you can stay focused - no constant prompts during tool work, but clean pagination when the AI is presenting results.

Try a simple command:

YOU: Please list the files in this directory

SYSTEM: [file_operations] - listing ./ (15 files, 8 directories)

CLIO: I can see you have several files and directories here:

**Directories:**
- lib/ (source code modules)
- docs/ (documentation)
- scripts/ (utility scripts)
- sessions/ (saved conversations)

**Files:**
- clio (main executable)
- README.md (project documentation)
- install.sh (installation script)
...

Ask CLIO to read a file:

YOU: Show me the contents of README.md

SYSTEM: [file_operations] - Reading ./README.md (466 lines)

CLIO: Here's the README.md file:

# CLIO - Command Line Intelligence Orchestrator

**An AI code assistant that works in your terminal...**
...

Make a code change:

YOU: In lib/CLIO/Core/Main.pm, change the timeout from 30 to 60 seconds

SYSTEM: [file_operations] - Reading lib/CLIO/Core/Main.pm
SYSTEM: [file_operations] - Replacing string in lib/CLIO/Core/Main.pm

CLIO: I've updated the timeout in Main.pm from 30 to 60 seconds:

[Shows diff of the change]

End your session:

Type exit or press Ctrl+D to end the session. Your conversation history is automatically saved.

Resuming Sessions

Resume your most recent session:

clio --resume

List available sessions:

ls sessions/

Output:

sess_20260118_143052.json
sess_20260118_150234.json
sess_20260118_163421.json

Resume a specific session:

clio --resume sess_20260118_143052

Your entire conversation history, including all tool operations and responses, will be restored exactly as you left it.

Slash Commands Reference

CLIO provides 35+ slash commands. Type /help in any session to see the full list.

Basics

Command	Purpose
`/help`, `/h`	Display command help
`/exit`, `/quit`, `/q`	Exit CLIO
`/clear`	Clear screen

Project Setup

Command	Purpose
`/design`	Collaborative PRD development with AI architect
`/init`	Initialize project with custom instructions
`/init --force`	Re-initialize project (updates instructions from PRD)
`/spec`	OpenSpec spec-driven development (see below)
`/spec init`	Initialize `openspec/` directory
`/spec propose <name>`	Create change + AI generates planning artifacts
`/spec status [name]`	Show artifact completion status
`/spec archive <name>`	Archive completed change

API & Configuration

Command	Purpose
`/api`	Show API settings help
`/api show`	Display current configuration (shows session overrides)
`/api set provider <name>`	Change AI provider (saved globally)
`/api set model <name>`	Set AI model (saved globally)
`/api set key <value>`	Set API key (saved per-provider)
`/api set base <url>`	Set API base URL (saved globally)
`/api set thinking on\|off`	Toggle reasoning display
`/api set thinking_effort low\|medium\|high`	Set reasoning depth (default: medium)
`/api set temperature <value>`	Override sampling temperature
`/api set top_p <value>`	Override top_p sampling
`/api set top_k <value>`	Override top_k sampling
`/api set context_window <value>`	Cap model's context window (e.g. `128k`, `256000`, `1M`)
`/api set max_output <value>`	Cap max output tokens (e.g. `16k`)
`/api set max_prompt <value>`	Cap max prompt tokens (e.g. `200k`)
`/api set tools on\|off\|auto`	Force tool calling on/off (auto = model default)
`/api set vision on\|off\|auto`	Force vision support on/off
`/api set reasoning on\|off\|auto`	Force reasoning support on/off
`/api set <setting> <value> --session`	Set value for this session only
`/api models`	List available models
`/api alias <name> <model>`	Create a model alias
`/api alias`	List all model aliases
`/api alias <name> --delete`	Remove a model alias
`/model <name>`	Quick model switch (saved globally)
`/model`	Show current model and aliases
`/api login`	Authenticate with GitHub Copilot
`/api logout`	Sign out from GitHub
`/config save`	Save non-API config (theme, working directory)
`/config show`	Display current configuration

Session Management

Command	Purpose
`/session list`	List all saved sessions
`/session switch <id>`	Resume a specific session
`/session export [path]`	Export session as self-contained HTML
`/session trim [days]`	Remove sessions older than N days (default: 30)

File & Git Operations

Command	Purpose
`/file read <path>`	View file contents
`/file write <path>`	Create/overwrite file
`/file edit <path>`	Edit file in $EDITOR
`/read <path>`	View file (shorthand)
`/edit <path>`	Edit file (shorthand)
`/git status`	Show git status
`/git diff [file]`	Show git differences
`/git log [n]`	Show commit history
`/git commit [msg]`	Create git commit
`/git branch`	List/create/delete branches
`/git switch <name>`	Switch to branch
`/git push [remote] [branch]`	Push changes to remote
`/git pull [remote] [branch]`	Pull changes from remote
`/git stash [save\|apply\|drop]`	Manage stashed changes
`/git tag [name]`	List/create/delete tags
`/git blame <file>`	Show who changed each line
`/git worktree list`	List all worktrees
`/git worktree add <path> [branch]`	Add a new worktree
`/git worktree remove <path>`	Remove a worktree
`/git worktree prune`	Prune stale worktrees
`/git worktree merge <path>`	Merge worktree branch into current branch
`/status`	Show git status (shorthand)
`/diff`	Show git diff (shorthand)
`/commit`	Create commit (shorthand)

Task Management

Command	Purpose
`/todo`	View agent's current todo list
`/todo add <text>`	Add new todo
`/todo done <id>`	Mark todo as complete

Memory & Learning

Command	Purpose
`/memory`	View long-term memory patterns
`/memory list [type]`	List discoveries, solutions, patterns
`/memory store <type>`	Store new pattern (via AI)
`/memory stats`	Show LTM statistics
`/memory prune [days]`	Remove old/low-confidence entries
`/memory clear`	Clear all patterns

User Profile

Command	Purpose
`/profile`	View profile status
`/profile build`	Analyze session history and build profile (AI-assisted)
`/profile show`	Display current profile
`/profile edit`	Open profile in your editor
`/profile clear`	Remove profile
`/profile path`	Show profile file location

Your profile lives at ~/.clio/profile.md and is never stored in any git repo. It personalizes how CLIO interacts with you across all projects and sessions. Run /profile build after ~10 sessions to generate a profile from your interaction history.

Specs (OpenSpec)

Command	Purpose
`/spec`	Show spec overview (specs + active changes)
`/spec init`	Initialize `openspec/` directory structure
`/spec list`	List all specs and active changes
`/spec show <domain>`	Display a spec
`/spec new <name>`	Create a new change scaffold
`/spec propose <name>`	Create change + AI generates all artifacts
`/spec status [name]`	Show which artifacts are done/ready/blocked
`/spec tasks [name]`	Show tasks with completion status
`/spec archive <name>`	Archive a completed change
`/spec help`	Show command help

OpenSpec integration lets you define structured requirements (proposal, specs, design, tasks) before implementation. The AI sees spec context automatically and implements against the agreed plan. See FEATURES.md for the full guide.

Device Registry

Command	Purpose
`/device add <name> <host>`	Register a named device for remote execution
`/device list`	List all registered devices
`/device remove <name>`	Remove a device from registry
`/device show <name>`	Show device details

Example:

: /device add staging user@staging.example.com
: /device add prod user@prod.example.com
: /device list

Device Groups

Command	Purpose
`/group create <name> <devices...>`	Create a device group for parallel execution
`/group list`	List all device groups
`/group remove <name>`	Remove a device group

Example:

: /group create webservers staging prod
: /group list

MCP (Model Context Protocol)

Command	Purpose
`/mcp status`	Show connected MCP servers
`/mcp add <name> <command> [args...]`	Add a new MCP server
`/mcp remove <name>`	Remove an MCP server
`/mcp tools <name>`	List tools from an MCP server

Example:

: /mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /path/to/files
: /mcp status
: /mcp tools filesystem

MCP servers extend CLIO's capabilities with external tools. Tools from MCP servers are available as mcp_<server>_<tool>. See FEATURES.md for details.

Developer Tools

Command	Purpose
`/debug [on\|off]`	Toggle debug mode
`/loglevel <level>`	Set log level (DEBUG, INFO, WARNING, ERROR) - persists to config
`/context`	View token usage statistics
`/multiline`, `/ml`	Open editor for multi-line input
`/theme <name>`	Change color theme
`/theme list`	List available themes

Skills & Customization

Command	Purpose
`/skill`	Show skill system help
`/skills list`	List all available skills grouped by scope
`/skills list --scope=<scope>`	Show skills for a single scope (user, project, session, freeform, repository, builtin)
`/skills add <name> "<text>" [--global\|--project\|--session]`	Create a new skill in the named scope
`/skills delete <name>`	Delete a skill
`/skills show <name>`	Display skill contents
`/skills use <name> [file]`	Execute skill as user message
`/skills load <name>`	Load skill into system prompt (session-wide)
`/skills unload <name>`	Remove loaded skill from system prompt
`/skills loaded`	Show currently loaded skills
`/skills search [query]`	Search the skills catalog
`/skills install <name> [--global\|--project\|--session]`	Install skill from catalog (default: project)

Execution & Utilities

Command	Purpose
`/exec <cmd>`	Execute shell command
`/! <cmd>`	Execute shell command (shorthand)
`/shell`	Open interactive shell
`/undo`	Revert file changes from last AI turn
`/undo list`	Show recent turns with file change counts
`/undo diff`	Preview what would be reverted
`/subagent spawn <task>`	Spawn sub-agent for parallel work
`/subagent list`	List active sub-agents
`/subagent inbox`	View messages from sub-agents
`/subagent send <id> <msg>`	Send message to sub-agent
`/subagent status <id>`	Show detailed agent status
`/subagent kill <id>`	Terminate an agent
`/subagent killall`	Terminate all agents
`/subagent projects`	List detected child projects (puppeteer mode)
`/subagent locks`	Show file/git locks held by agents
`/subagent discoveries`	Show shared discoveries from agents
`/subagent warnings`	Show shared warnings from agents

Stats & Performance

Command	Purpose
`/stats`	Memory and performance snapshot (TTFT, TPS, token counts)
`/stats history`	Per-iteration memory and token timeline
`/stats log [N]`	Raw log entries (last N, default 20)
`/stats help`	Show stats command help

Multiplexer Integration

When running inside tmux, GNU Screen, or Zellij, CLIO can manage panes for sub-agent output:

Command	Purpose
`/mux status`	Show multiplexer type and managed panes
`/mux agent <id>`	Open a pane tailing a specific agent's log
`/mux close <id>`	Close a specific managed pane
`/mux close all`	Close all CLIO-managed panes
`/mux auto [on\|off]`	Toggle automatic pane creation on agent spawn

Core Concepts

Sessions

Every CLIO conversation is a session. Sessions are:

Persistent: Automatically saved to sessions/ directory
Resumable: Pick up exactly where you left off
Complete: Include full conversation history and tool operations
Timestamped: Named with creation date/time (e.g., sess_20260118_143052)

Session Storage: Sessions are stored as JSON files in sessions/ directory:

{
  "id": "sess_20260118_143052",
  "created_at": "2026-01-18T14:30:52Z",
  "conversation": [...],
  "model": "claude-sonnet-4",
  "state": {...}
}

Tools

CLIO interacts with your system through tools. When you ask CLIO to do something, it selects appropriate tools and executes them.

Tool Categories:

File Operations: Read, write, search, edit files
Version Control: Git operations
Terminal: Execute commands
Memory: Store and recall information
Todo Lists: Task management
Web: Fetch web content

Tool Transparency: Every tool operation shows an action description:

SYSTEM: [file_operations] - Reading ./src/main.c (247 lines)
SYSTEM: [git] - Executing git status in ./
SYSTEM: [terminal] - Executing: find lib -name "*.pm" | wc -l

Action Descriptions

Action descriptions tell you exactly what CLIO is doing:

SYSTEM: [file_operations] - Reading ./config.yaml (45 lines)
SYSTEM: [file_operations] - Writing ./config.yaml (47 lines)
SYSTEM: [git] - Creating branch feature/new-feature
SYSTEM: [terminal] - Executing: perl -c lib/CLIO/Core/Main.pm

This transparency means:

No surprise file modifications
No hidden command execution
Complete visibility into CLIO's actions
Easy auditing of what changed

Streaming Responses

CLIO provides real-time streaming for all AI responses:

AI Responses Stream Immediately:

Text appears as it's generated
Markdown rendering applies live
Code blocks appear with syntax highlighting

Tool Operations Show Live:

SYSTEM: [file_operations] - Reading ./lib/Main.pm (245 lines)
SYSTEM: [git] - Executing git status in ./
SYSTEM: [terminal] - Running: perl -I./lib -c lib/Main.pm

Every action is transparent and immediate - no hidden work, no waiting.

Markdown Rendering

CLIO renders responses as formatted markdown in your terminal:

Headers:

# Large Header
## Medium Header
### Small Header

Code Blocks:

```perl
sub hello {
    print "Hello, world!\n";
}
```

Lists:

- Item 1
- Item 2
  - Nested item

Tables:

| Column 1 | Column 2 |
|----------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| Data 1   | Data 2   |

Emphasis:

**Bold text**
*Italic text*
`Inline code`

All of these render beautifully in your terminal with proper colors, indentation, and formatting.

Memory System

CLIO can remember information across sessions:

Store information:

YOU: Remember that our production API endpoint is https://api.example.com/v2

Recall later (even in a different session):

YOU: What's our production API endpoint?

CLIO: Your production API endpoint is https://api.example.com/v2 
(stored on 2026-01-18)

Search memories:

YOU: What do I know about database configuration?

CLIO: I found 3 memories related to database configuration:
1. Database host: db.example.com (stored 2026-01-15)
2. Database name: production_db (stored 2026-01-15)
3. Connection pool size: 20 (stored 2026-01-16)

Available Tools

File Operations

read_file - Read file contents

YOU: Show me the contents of src/auth.pm

write_file - Create or overwrite a file

YOU: Create a new file called test.txt with the content "Hello, world!"

create_file - Create a new file with content

YOU: Create a Python script that prints the Fibonacci sequence

delete_file - Delete a file or directory

YOU: Delete the temp/ directory

rename_file / move_file - Rename or move files

YOU: Rename config.yaml to config.yaml.backup

list_dir - List directory contents

YOU: What files are in the lib/ directory?

file_search - Find files by name pattern

YOU: Find all Perl modules in the project

grep_search - Search file contents for patterns

YOU: Search for all TODO comments in the codebase

semantic_search - Natural language code search

YOU: Find functions that handle authentication

replace_string - Find and replace in files

YOU: In config.yaml, replace the port number 8080 with 9000

get_errors - Get compilation or linting errors

YOU: Check for syntax errors in all Perl modules

get_file_info - Get file metadata

YOU: What's the size and modification date of README.md?

file_exists - Check if file exists

YOU: Does config.yaml exist?

Version Control (Git)

git_status - Show working tree status

YOU: What's the current git status?

git_diff - Show changes

YOU: Show me what changed in the last commit
YOU: What are my uncommitted changes?

git_log - Show commit history

YOU: Show me the last 10 commits
YOU: Show commits from the last week

git_commit - Create a commit

YOU: Commit all changes with message "Fix authentication bug"

git_push - Push changes to remote

YOU: Push my commits to origin

git_pull - Pull changes from remote

YOU: Pull the latest changes from main branch

git_branch - Branch operations

YOU: Create a new branch called feature/new-login
YOU: List all branches

git_checkout - Switch branches or restore files

YOU: Switch to the main branch
YOU: Restore the file config.yaml from the last commit

git_merge - Merge branches

YOU: Merge the feature/new-login branch into main

git_reset - Reset changes

YOU: Undo the last commit but keep the changes

Terminal Operations

execute_command - Run a shell command

YOU: Run the test suite
YOU: Count the lines of code in all Perl files
YOU: Show me the current disk usage

get_terminal_output - Get output from a previous command

YOU: What was the output of the last command?

Memory Operations

store_memory - Store information

YOU: Remember that the database password is in /etc/secrets/db.conf

retrieve_memory - Recall specific information

YOU: What did I store about the database password?

search_memory - Search stored memories

YOU: Find all information about API endpoints

list_memories - List all stored memories

YOU: Show me everything you remember

delete_memory - Forget stored information

YOU: Forget the information about the old API endpoint

Long-Term Memory (LTM) Management:

/memory stats    # Show LTM statistics (entry counts, timestamps)
/memory prune    # Remove old/low-confidence entries (default 90 days)
/memory prune 30 # Remove entries older than 30 days

Todo List Operations

manage_todo_list - Create and manage tasks

YOU: Create a todo list for this refactoring project
YOU: Mark task 3 as complete
YOU: Show me all remaining tasks
YOU: Add a new task to implement caching

Web Operations

fetch_webpage - Fetch and analyze web content

YOU: Fetch the documentation from https://docs.example.com/api
YOU: Summarize the content of https://blog.example.com/article

Remote Execution

execute_remote - Run AI tasks on remote systems via SSH

YOU: Use remote execution to check the disk space on myserver
YOU: Execute on admin@webserver: create a system health report
YOU: Remote execute on builder@arm-device: compile the project and report any errors

check_remote - Verify remote system is ready for execution

YOU: Check if server@production is ready for remote CLIO execution

prepare_remote - Pre-stage CLIO on a remote system

YOU: Prepare CLIO on dev@buildserver for repeated tasks

Remote execution enables distributed workflows - run analysis on servers, build on specific hardware, gather diagnostics from multiple systems, and more. See Remote Execution Guide for complete documentation.

Device Registry - Register named devices for quick access:

: /device add staging user@staging.example.com
: /device add prod user@prod.example.com
: /device list

Device Groups - Group devices for parallel execution:

: /group create webservers staging prod
: /device list

The execute_parallel operation runs the same task on multiple devices at once and aggregates results.

Code Intelligence

list_usages - Find all references to a symbol across the codebase

YOU: Find all usages of the function validate_token

search_history - Semantic search through git commit messages

YOU: When did we fix the authentication bug?
YOU: Show me commits related to performance improvements

Apply Patch

A lightweight diff-based tool for efficient multi-file changes. The AI can apply surgical patches rather than rewriting entire files:

YOU: Fix the off-by-one error in the loop on line 42 of parser.pm

The AI generates a targeted patch with context anchors, making changes precise and reviewable.

Multi-Agent Coordination

CLIO supports spawning multiple AI agents that work in parallel while coordinating to prevent conflicts.

Puppeteer Mode: If your working directory contains child projects (subdirectories with .clio/), CLIO activates puppeteer mode - orchestrating work across multiple repositories from a single session. See Puppeteer Mode for the full guide.

Sub-Agent Commands (/subagent or /agent):

# Agent Lifecycle
/subagent spawn <task> [--model <name>]    # Spawn a new sub-agent
/subagent spawn <task> --persistent        # Spawn persistent agent (stays alive)
/subagent list                              # List active agents
/subagent status <agent-id>                 # Show detailed status
/subagent kill <agent-id>                   # Terminate agent
/subagent killall                           # Terminate all agents

# Communication
/subagent inbox                             # Check messages from agents
/subagent send <agent-id> <message>         # Send guidance to agent
/subagent reply <agent-id> <response>       # Reply to agent question
/subagent broadcast <message>               # Send message to all agents

# Coordination
/subagent locks                             # Show file/git locks
/subagent discoveries                       # Show shared discoveries
/subagent warnings                          # Show shared warnings

How It Works:

When you spawn sub-agents, CLIO automatically starts a coordination broker that manages:

File Locking: Prevents concurrent edits to the same file
Git Locking: Serializes commits to avoid conflicts
Knowledge Sharing: Agents can share discoveries and warnings
Message Bus: Agents can send questions, status updates, and completion messages

Agent Modes:

Oneshot (Default): Agent completes one task and exits
Persistent (--persistent): Agent stays alive, polls for messages, handles multiple tasks

Communication Flow:

Agent has question         -> Uses interact tool
                           -> Question routed to broker
                           -> Appears in your inbox

You see the question       -> Run /subagent inbox
                           -> Reply with /subagent reply <id> <answer>

Agent receives answer      -> Continues work with your guidance
                           -> Sends completion message when done

Example with Messaging:

YOU: /subagent spawn "refactor auth module" --persistent

CLIO: [OK] Spawned sub-agent: agent-1 (PERSISTENT MODE)
      Task: refactor auth module
      Model: minimax-m2.7

[Agent works autonomously... then has a question]

CLIO: ─────────────────────────────────────────────
      Agent Message: agent-1 [QUESTION]
      Should I split the auth module into OAuth and BasicAuth?
      Or keep them unified with a common interface?
      Reply: /subagent reply agent-1 <your-response>

YOU: /subagent reply agent-1 "Split them but use a common AuthProvider interface"

CLIO: Reply sent to agent-1 (id: 5)

[Agent continues with your guidance...]

CLIO: ─────────────────────────────────────────────
      Agent Message: agent-1 [COMPLETE]
      Refactoring complete. Created:
      - lib/Auth/OAuth.pm
      - lib/Auth/Basic.pm
      - lib/Auth/Provider.pm (interface)
      All tests passing.

Example Multi-Agent Workflow:

YOU: /subagent spawn "analyze lib/Module/A.pm" --model minimax/minimax-m2.7

CLIO: [OK] Spawned sub-agent: agent-1
      Task: analyze lib/Module/A.pm and document key patterns
      Model: minimax/minimax-m2.7
      
      Use /subagent list to monitor progress

YOU: /subagent spawn "create tests for lib/Module/B.pm" --model github_copilot/claude-sonnet-4

CLIO: [OK] Spawned sub-agent: agent-2
      Task: create tests for lib/Module/B.pm
      Model: github_copilot/claude-sonnet-4

YOU: /subagent list

CLIO: Active Sub-Agents:
      
       agent-1      [running]    analyze lib/Module/A.pm (2m15s)
       agent-2      [running]    create tests for lib/Module/B.pm (45s)

YOU: /subagent inbox

CLIO: === Agent Messages (2) ===

      [status] from agent-1 (id: 3)
        progress: 50%
        current_task: Documenting function signatures
      
      [question] from agent-2 (id: 4)
        Should I use Test::More or Test2::V0 for the tests?
      
      Use '/subagent reply <agent-id> <response>' to respond

YOU: /subagent reply agent-2 "Use Test::More for consistency with existing tests"

CLIO: Reply sent to agent-2 (id: 5)

Best Practices:

Use Different Models for Different Tasks: Use a larger model for complex analysis, a smaller model for simple tasks. Run /api models to see what's available
Monitor Your Inbox: Check /subagent inbox periodically for questions
Use Persistent Mode for Complex Work: Agents can ask questions and receive guidance
Check Logs: Agent logs are in /tmp/clio-agent-<agent-id>.log
Avoid Overlapping Work: Don't spawn multiple agents to edit the same files
Review Before Commit: Check agent outputs before committing changes

When to Use Multi-Agent Mode:

Parallel Tasks: Multiple independent changes across different files
Long-Running Work: Spawn agents for complex analysis while continuing other work
Different Expertise: Use different models for different types of tasks
Bulk Operations: Process multiple files/modules in parallel

Limitations:

Sub-agents cannot spawn additional sub-agents (prevents fork bombs)
Sub-agents cannot use remote_execution tool
Broker requires /dev/shm (Linux) or /tmp (macOS)
Agent logs accumulate in /tmp (clean up periodically)

For more details, see the Multi-Agent Coordination documentation.

Usage Examples

Example 1: Project Design & Setup

Starting a new project with /design:

YOU: /design

CLIO: Let's design your application together. Tell me about your project 
      idea - what problem are you trying to solve?

YOU: I want to build a markdown-based personal wiki that runs in the terminal

CLIO: A terminal-based markdown wiki - interesting! Let's explore the 
      architecture...
      
      First, let's understand the requirements:
      - Will this be single-user or multi-user?
      - Do you need search functionality?
      - Should it support linking between pages?
      - Any special markdown extensions needed?

YOU: Single user, yes to search and linking. I'd like to support task lists.

CLIO: Perfect. For a terminal markdown wiki with those features, I'm thinking:
      
      **Architecture Pattern:** File-based storage with indexed search
      - Pro: Simple, version-controllable with git
      - Con: Search requires indexing
      
      Have you considered using a database instead? Or are you committed 
      to plain files?

YOU: Plain files for sure - I want git integration

CLIO: Smart choice. That gives you version history for free. Here's what I'm 
      thinking for the stack:
      
      **Technology:**
      - Perl 5.32+ (matches your terminal preferences)
      - Text::Markdown::Discount (fast markdown parsing)
      - Search::Elasticsearch or Lucy for full-text search
      - Git integration via Git::Repository
      
      **Architecture:**
      ```
      wiki/
        pages/           # Markdown files
        .index/          # Search index
        .git/            # Version history
      ```
      
      **Components:**
      - Page Manager: CRUD for markdown files
      - Link Parser: Extract [[WikiLinks]]
      - Search Engine: Index and query
      - Git Handler: Auto-commit on save
      - Terminal UI: Browse, edit, search
      
      What do you think? Any concerns with this approach?

YOU: Looks good, but I'm worried about search performance with lots of pages

CLIO: Valid concern. Let me suggest two options:
      
      **Option 1: Lucy (lightweight, pure Perl)**
      - Pro: No external dependencies, fast enough for <10k pages
      - Con: Slower than Elasticsearch for large wikis
      
      **Option 2: ripgrep + fzf (external tools)**
      - Pro: Blazing fast, no index needed
      - Con: External dependencies, less structured queries
      
      For a personal wiki, ripgrep might be perfect. Thoughts?

YOU: Let's go with ripgrep for simplicity

CLIO: Perfect! I'll document that decision. Creating your PRD now...

SYSTEM: [file_operations] - Writing .clio/PRD.md

CLIO: I've created a comprehensive PRD at `.clio/PRD.md` with:
      
      **Project: TermWiki**
      - Purpose: Terminal-based personal wiki with git version control
      - Architecture: File-based storage + ripgrep search
      - Stack: Perl, Text::Markdown::Discount, ripgrep, Git
      - Components: 5 main modules documented
      - MVP Features: Create/edit/delete pages, wiki links, search, git auto-commit
      - Phase 2: Tag system, templates, export to HTML
      
      Would you like to initialize the project? (Type '/init')

YOU: /init

SYSTEM: [web_operations] - Fetching CLIO methodology docs
SYSTEM: [file_operations] - Reading .clio/PRD.md
SYSTEM: [file_operations] - Writing .clio/instructions.md

CLIO: Project initialized! I've created custom instructions that include:
      
      **From Your PRD:**
      - Project purpose and architecture
      - Technology stack (Perl + ripgrep)
      - Testing strategy (unit + integration tests)
      - Development workflow (TDD with git auto-commit)
      
      **CLIO Methodology:**
      - The Unbroken Method principles
      - Collaboration checkpoints
      - Code quality standards
      
      Ready to start building! Try: "Create the Page Manager module"

Later, updating the design:

YOU: /design

SYSTEM: [file_operations] - Reading .clio/PRD.md

CLIO: I found your TermWiki PRD (last updated 5 days ago).
      
      **Current Design:**
      - Markdown wiki with file-based storage
      - ripgrep search
      - Git version control
      - 5 MVP features defined
      
      What's changed? New requirements? Technical insights? Scope adjustments?

YOU: I want to add a web interface for viewing (not editing)

CLIO: Interesting - a read-only web view. This changes the architecture 
      significantly. Let's think through the implications...
      
      **Two Approaches:**
      
      1. **Static Site Generation**
         - Generate HTML from markdown on save
         - Serve with any web server
         - Pro: Simple, fast, no runtime
         - Con: Manual publish step
         
      2. **Live Web Server**
         - Perl web server (Mojolicious/Dancer)
         - Renders markdown on-the-fly
         - Pro: Always current, dynamic search
         - Con: Needs to run continuously
         
      For a personal wiki, I'd lean toward static generation. Thoughts?

YOU: Static generation sounds perfect

CLIO: Great! Updating your PRD...
      
      **Changes:**
      - Added Phase 2 feature: HTML export & static site generation
      - New component: SiteBuilder module
      - Updated dependencies: Template::Toolkit for HTML templates
      - New milestone: Web viewer (after MVP)
      
      Your architecture has evolved - consider running '/init --force' to 
      update project instructions with this new component.

YOU: /init --force

SYSTEM: [file_operations] - Backing up .clio/instructions.md
SYSTEM: [file_operations] - Reading .clio/PRD.md
SYSTEM: [file_operations] - Writing .clio/instructions.md

CLIO: Instructions updated! Now includes:
      - SiteBuilder module architecture
      - HTML generation workflow
      - Static site deployment strategy
      
      Ready to implement the web export feature.

Example 2: Code Exploration

Understanding a new codebase:

YOU: I'm new to this project. Can you give me an overview of the codebase structure?

SYSTEM: [file_operations] - listing ./ (15 files, 8 directories)
SYSTEM: [file_operations] - Reading ./README.md
SYSTEM: [file_operations] - listing ./lib

CLIO: Here's an overview of the codebase:

**Project Structure:**
This is CLIO, a Perl-based AI code assistant. The structure is:

- `lib/CLIO/` - Core implementation
  - `Core/` - Main system components (SimpleAIAgent, APIManager, WorkflowOrchestrator, etc.)
  - `Tools/` - Tool implementations (FileOperations, VersionControl, etc.)
  - `UI/` - Terminal user interface (Chat, Theme, Markdown, ANSI)
  - `Session/` - Session management
  - `Coordination/` - Multi-agent coordination
  - `Security/` - Authentication and authorization
  - `Memory/` - Context and memory systems
  
- `styles/` - Color style files (25 themes)
- `sessions/` - Saved conversation sessions
- `docs/` - User-facing documentation

**Key Components:**
- `clio` - Main executable (entry point)
- `lib/CLIO/Core/SimpleAIAgent.pm` - AI agent implementation
- `lib/CLIO/UI/Chat.pm` - Chat interface
- `lib/CLIO/Tools/Registry.pm` - Tool management

Would you like me to explain any specific component in detail?

Example 3: Refactoring Code

Improving error handling:

YOU: Find all database query functions and add try-catch error handling

SYSTEM: [file_operations] - Searching for pattern "query|execute" in ./lib
SYSTEM: [file_operations] - Reading lib/CLIO/Database/Connection.pm
SYSTEM: [file_operations] - Replacing string in lib/CLIO/Database/Connection.pm

CLIO: I found 8 database query functions and added comprehensive error 
handling to all of them. Here's an example of the changes:

Before:

sub get_user {
    my ($self, $user_id) = @_;
    my $sth = $dbh->prepare("SELECT * FROM users WHERE id = ?");
    $sth->execute($user_id);
    return $sth->fetchrow_hashref;
}

After:

sub get_user {
    my ($self, $user_id) = @_;
    
    eval {
        my $sth = $dbh->prepare("SELECT * FROM users WHERE id = ?");
        $sth->execute($user_id);
        return $sth->fetchrow_hashref;
    };
    
    if ($@) {
        print STDERR "[ERROR][Database] Failed to get user $user_id: $@\n";
        return undef;
    }
}

All 8 functions now have:

eval blocks to catch exceptions
Error logging to STDERR
Graceful failure with undef return

Example 3: Git Workflow

Feature branch workflow:

YOU: Create a new feature branch, add logging to the APIManager, and commit the changes

SYSTEM: [git] - Creating branch feature/add-api-logging
SYSTEM: [git] - Switching to feature/add-api-logging
SYSTEM: [file_operations] - Reading lib/CLIO/Core/APIManager.pm
SYSTEM: [file_operations] - Replacing string in lib/CLIO/Core/APIManager.pm (5 changes)
SYSTEM: [git] - Staging lib/CLIO/Core/APIManager.pm
SYSTEM: [git] - Committing with message "feat(api): add comprehensive logging"

CLIO: Done! I've created the feature/add-api-logging branch, added logging 
at key points in APIManager, and committed the changes.

**What was added:**
- Request initiation logging (endpoint + parameters)
- Response status and timing
- Error logging with full context
- Token usage tracking

**Commit details:**

commit a1b2c3d4 Author: CLIO clio@example.com Date: Sat Jan 18 14:30:52 2026

feat(api): add comprehensive logging

Added logging to APIManager for debugging and monitoring:
- Request tracking
- Response metrics
- Error context
- Token usage


The branch is ready for review or testing.

Example 4: Documentation Generation

Creating comprehensive documentation:

YOU: Create API documentation for all public methods in lib/CLIO/Tools/FileOperations.pm

SYSTEM: [file_operations] - Reading lib/CLIO/Tools/FileOperations.pm
SYSTEM: [file_operations] - Creating docs/API/FileOperations.md

CLIO: I've created comprehensive API documentation for FileOperations:

**docs/API/FileOperations.md** (165 lines)

The documentation includes:

**For each method:**
- Method signature
- Purpose and description
- Parameters (with types and defaults)
- Return values
- Usage examples
- Error handling

**Methods documented:**
- read_file
- write_file
- create_file
- delete_file
- list_dir
- file_search
- grep_search
- replace_string
...and 9 more

**Format:**
Markdown with code examples, tables for parameters, and practical usage scenarios.

Would you like me to generate similar documentation for other modules?

Example 5: Multi-Step Analysis

Security audit:

YOU: Analyze the codebase for potential security issues: SQL injection, command injection, and insecure file operations

SYSTEM: [file_operations] - Searching for SQL patterns
SYSTEM: [file_operations] - Reading lib/CLIO/Database/*.pm (3 files)
SYSTEM: [file_operations] - Searching for exec/system patterns
SYSTEM: [file_operations] - Reading lib/CLIO/Tools/TerminalOperations.pm
SYSTEM: [file_operations] - Searching for file operation patterns
SYSTEM: [file_operations] - Reading lib/CLIO/Tools/FileOperations.pm

CLIO: Security audit complete. Here's what I found:

**SQL Injection: ✅ SAFE**
All database queries use parameterized statements via prepare/execute.
No string concatenation in SQL found.

**Command Injection: ⚠️ NEEDS ATTENTION**
Found 3 instances where user input is passed to exec without sanitization:

1. lib/CLIO/Tools/TerminalOperations.pm:145
   - `system($user_command)` with no input validation
   - **Risk:** High - arbitrary command execution
   - **Fix:** Use IPC::Run or validate input against whitelist

**File Operations: ✅ MOSTLY SAFE**
File operations use Path::Class and validated paths.
One minor issue:

1. lib/CLIO/Tools/FileOperations.pm:89
   - Symbolic link following not disabled
   - **Risk:** Low - potential directory traversal
   - **Fix:** Add -T check or use File::Spec->no_upwards

**Recommendations:**
1. **URGENT:** Fix command injection in TerminalOperations.pm
2. Add input validation for all user-controlled paths
3. Consider adding AppArmor/SELinux profiles for additional protection

Would you like me to implement these fixes?

Example 6: Research and Analysis

Investigating a framework:

YOU: Fetch the FastAPI documentation and explain how to create a REST API endpoint

SYSTEM: [web] - Fetching https://fastapi.tiangolo.com/tutorial/first-steps/
SYSTEM: [web] - Fetching https://fastapi.tiangolo.com/tutorial/path-params/

CLIO: Based on the FastAPI documentation, here's how to create a REST API endpoint:

Basic Endpoint:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello World"}

With Path Parameters:

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "query": q}

Key Concepts:

Decorator-based routing: Use @app.get(), @app.post(), etc.
Automatic validation: Path and query parameters are type-checked
JSON responses: Return dicts/objects, FastAPI handles serialization
Documentation: Auto-generated OpenAPI/Swagger docs at /docs

Running the server:

uvicorn main:app --reload

Path Parameters vs Query Parameters:

Path: /items/5 - Required, part of URL path
Query: /items?q=search - Optional, key=value after ?

Want me to create a complete example FastAPI application for you?

Example 7: Working with Images

Analyzing a screenshot:

YOU: What does this error say? @screenshot.png

CLIO: [Image: screenshot.png (image/png, 245KB)]

      The error is a "Connection refused" on port 5432. This means your
      PostgreSQL server isn't running. Start it with:

      sudo systemctl start postgresql

Comparing two images:

YOU: What's different between these? @before.png and @after.png

CLIO: [Image: before.png (image/png, 120KB)]
      [Image: after.png (image/png, 125KB)]

      The after image has a new "Settings" button in the top-right corner
      that wasn't present in the before image.

Attaching images with spaces in the path:

YOU: Analyze @"/path/to/my screenshot.png"

Images are sent to vision-capable models automatically. CLIO detects whether your current model supports images and handles the encoding. On kitty or iTerm terminals, images from the model are displayed inline. On other terminals, they're saved to ~/.clio/images/.

Configuration

Interactive Configuration (Recommended)

CLIO is designed to be configured interactively using slash commands:

GitHub Copilot (Default):

./clio
: /api login
# Browser opens → Authorize → Done!

Other Providers:

./clio
: /api set provider openai         # Set provider (saved globally)
: /api set key YOUR_API_KEY        # Set API key (saved per-provider)
: /api set model <model-name>      # Set model (saved globally)

Available /api commands:

/api show                           # Show current config (highlights session overrides)
/api providers                      # List all available providers
/api set provider <name>            # Set current provider
/api set key <key>                  # Set API key for current provider
/api set model <model>              # Set model
/api set base <url>                 # Set API base URL
/api models                         # List available models
/api set thinking on                # Enable reasoning display
/api set thinking_effort high       # Deep reasoning (low|medium|high)
/api set temperature 1.0            # Override sampling temperature
/api set top_p 0.95                 # Override top_p
/api set top_k 40                   # Override top_k
/api set temperature reset          # Revert to provider default

/api set context_window 128k        # Cap DeepSeek's 1M context to 128k
/api set max_output 16k             # Cap max output tokens
/api set max_output reset           # Clear cap, use model default
/api set tools off                  # Force-disable tool calling for this model
/api set vision on                  # Force-enable vision (override model default)
/api set context_window 256k --session  # Session-only override
/api alias <name> <model>           # Create model alias

Add --session to any /api set command to apply it to the current session only:

/api set model gpt-4.1 --session      # Session-only override
/api set provider llama.cpp --session  # Session-only override

Session overrides are visible in /api show and the session header.

Available /config commands:

/config show                    # Show current configuration
/config save                    # Save theme, working directory, etc.

Note: /api set commands save automatically - you don't need /config save after changing API settings.

Debug Output (Advanced)

For advanced users, debug output can be enabled:

# Enable debug output via command-line flag
clio --debug --new

# Or with any clio command
clio --debug --resume

Note: The --debug flag sets CLIO_LOG_LEVEL=DEBUG internally.

Session Configuration:

# Custom session storage directory
export CLIO_SESSION_DIR="$HOME/.clio/sessions"

# Session auto-save interval (seconds)
export CLIO_AUTOSAVE_INTERVAL=60

Tool Filtering:

CLIO supports restricting which tools are available, via CLI flags or persistent config:

# CLI flags (session-scoped, not persisted)
clio --enable file_operations,terminal_operations --input "list files"
clio --disable web_operations,remote_execution --new

# Persistent config (applies to all sessions)
/config set enabled_tools file_operations,terminal_operations
/config set disabled_tools web_operations,remote_execution

--enable creates an allowlist (only listed tools register). --disable creates a blocklist (everything except listed tools). They are mutually exclusive. CLI flags override config values.

System Prompt Override:

# Use a different system prompt for one session
clio --prompt minimal --new

# List available prompts
/prompt list

Proxy Configuration:

Route all outbound requests through an HTTP or SOCKS proxy:

# Via config command (persists)
/config set http_proxy http://proxy.example.com:8080

# Via environment variable (session-scoped)
export HTTPS_PROXY=http://proxy.example.com:8080
export ALL_PROXY=socks5://proxy.example.com:1080

Supported proxy formats: http://, https://, socks5://, socks5h://, socks4://. Config http_proxy takes priority over environment variables.

Configuration File

CLIO can also be configured via a config file at ~/.clio/config.yaml:

# ~/.clio/config.yaml

ai_provider: github_copilot
model: claude-sonnet-4

session:
  directory: ~/.clio/sessions
  autosave_interval: 60

tools:
  enabled:
    - file_operations
    - version_control
    - terminal
    - memory
    - todo
    - web

network:
  http_proxy: ""    # HTTP/SOCKS proxy URL (empty = no proxy)

logging:
  level: info
  file: ~/.clio/logs/clio.log

ui:
  theme: photon
  markdown: true
  colors: true

Note: Environment variables take precedence over config file settings.

Customization

Color Styles

Styles control the colors used in CLIO's terminal output. Change styles to match your terminal's color scheme or personal preference.

Available Commands:

: /style list          # Show all available styles
: /style show          # Display current style name
: /style set <name>    # Switch to a different style
: /style save <name>   # Save current colors as new custom style

Built-in Styles:

Style	Description
`default`	Bright colors on dark background
`photon`	Retro BBS-inspired (cyan/magenta/green)
`dark`	Subdued colors for dark terminals
`light`	High contrast for light backgrounds
`slate`	Professional blue/grey retro theme
Retro/Vintage
`green-screen`	Classic phosphor terminal (bright green)
`amber-terminal`	Warm amber CRT glow
`bbs-bright`	Classic BBS bright cyan
`retro-rainbow`	PhotonBBS multi-color palette
`dos-blue`	MS-DOS blue/white palette
`commodore-64`	Commodore 64 light blue
`apple-ii`	Apple II green/white
`vt100`	DEC VT100 terminal professional

Example:

# List available styles
: /style list
Available styles:
  - default
  - photon
  - dark
  - light

# Switch to photon style
: /style set photon
Style changed to: photon

# Show current style
: /style show
Current style: photon

Creating Custom Styles:

Styles are defined in ~/.clio/styles/ directory using a simple key=value format:

# ~/.clio/styles/my_style.style
name=my_style

# User interaction colors
user_prompt=@BRIGHT_GREEN@
user_text=@BRIGHT_YELLOW@

# Agent colors
agent_label=@BRIGHT_BLUE@
agent_text=@WHITE@

# System messages
system_message=@BRIGHT_MAGENTA@
error_message=@BRIGHT_RED@

See styles/README.md for complete style file format and available color codes.

Output Themes

Themes control the structure and format of CLIO's output. Change themes to adjust how much information is displayed.

Available Commands:

: /theme list          # Show all available themes
: /theme show          # Display current theme name
: /theme set <name>    # Switch to a different theme
: /theme save <name>   # Save current templates as new theme

Built-in Themes:

Theme	Description
`default`	Standard output with all elements visible
`compact`	Minimal output, fewer labels
`verbose`	Detailed output with extra context

Example:

# Switch to compact theme for less visual noise
: /theme set compact
Theme changed to: compact

# Switch back to default
: /theme set default

Creating Custom Themes:

Themes are defined in ~/.clio/themes/ directory using template format with placeholders:

# ~/.clio/themes/my_theme.theme
name=my_theme

# Prompts
user_prompt_format={style.user_prompt}> @RESET@
agent_prefix={style.agent_label}AI: @RESET@

# Banner
banner_line1={style.banner}CLIO@RESET@

Themes use placeholders:

{style.key} - Replaced with color codes from current style
{var.key} - Replaced with runtime values (session_id, model, etc.)

See themes/README.md for complete theme file format and available placeholders.

Skills

Skills are specialized prompt templates that give CLIO expertise in specific tasks. They provide structured instructions for common workflows like code review, testing, and documentation.

Viewing Available Skills

: /skills                                # List all skills grouped by scope
: /skills --scope=project                # Show only project-scoped skills
: /skills --scope=user                   # Show only user-scoped skills
: /skills --scope=builtin                # Show only built-in skills
: /skills show <name>                    # Display skill details (includes scope and source file)

/skills groups the output by scope and shows a short description of each scope so you know where a skill is stored. The --scope= filter narrows the list to one scope. Use it with any of: user, project, session, freeform, repository, builtin.

Built-in Skills:

Skill	Description
`explain`	Explain selected code
`review`	Review code for issues
`test`	Generate comprehensive tests
`fix`	Propose fixes for problems
`doc`	Generate documentation
`design`	Create a Product Requirements Document (PRD)
`init`	Initialize CLIO for a project

Using Skills

: /skills use explain lib/MyModule.pm     # Explain code in a file
: /skills use review src/auth.py          # Review code for issues
: /skills use test controllers/user.rb    # Generate tests

Skills Catalog

CLIO includes a curated skills catalog you can browse and install:

: /skills search              # Browse all available skills
: /skills search perl         # Search for specific skills
: /skills install <name>      # Install a skill

Installing Skills:

Run /skills search to see available skills
Run /skills install <name> to preview and install
Review the skill content before confirming installation
Use with /skills use <name>

Skill Repositories

Add external Git repositories as skill sources. This lets you use community skill collections like ComposioHQ/awesome-claude-skills alongside built-in and custom skills.

: /skills repo add <name> <url>    # Add a skill repository
: /skills repo remove <name>       # Remove a repository and its cache
: /skills repo list                 # List configured repositories
: /skills repo sync [name]         # Sync all repos (or a specific one)
: /skills repo enable <name>       # Enable a disabled repository
: /skills repo disable <name>      # Disable without removing

Adding a repository:

: /skills repo add awesome https://github.com/ComposioHQ/awesome-claude-skills

CLIO clones the repository to a local cache (~/.clio/skill-cache/) and scans for SKILL.md files. Three repository layouts are supported:

Layout	Structure	Example
Root-level	`repo/skill-name/SKILL.md`	ComposioHQ/awesome-claude-skills
Subdirectory	`repo/.github/skills/name/SKILL.md`	Claude Code default
Single skill	`repo/SKILL.md`	Individual skill repos

Optional flags when adding a repository:

: /skills repo add my-skills https://github.com/user/skills --branch develop
: /skills repo add nested https://github.com/user/skills --subpath .github/skills

Repository skills are read-only. They appear in /skills list under the "REPOSITORY SKILLS" section with their source repository shown. Custom skills override repository skills with the same name.

Custom Skills

Create your own skills. Skills land in a scope you pick so they show up where you need them.

: /skills add my-skill "Review code for ${lang} best practices: ${code}"
: /skills add team-style --project "Always run cargo fmt before suggesting changes"
: /skills add perl-tips --global 'Use 3-arg open and lexical filehandles by default'
: /skills add brainstorming --session 'Push back on vague requirements and ask for examples'

The scope flag controls which file the skill is written to. When you omit the flag, the skill lands in the project scope if the current working directory has a .clio/ subdirectory, otherwise it goes to user.

Flag	Aliases	Backing file	Visible in
`--global`	`--user`, `--scope=user`	`~/.clio/skills.json`	Every project on this machine
`--project` (default)	`--scope=project`	`<project>/.clio/skills.json`	This project only
`--session`	`--scope=session`	`sessions/<id>/skills.json`	This session only, gone when the session ends
(no flag, freeform)	edit the file directly	`<dir>/.clio/skills/<name>.md`	Wherever the file lives

The freeform scope is special: a .clio/skills/<name>.md file is automatically picked up, and editing the file in place is how you modify that skill. /skills show <name> on a freeform skill points at the .md path so you can open it in your editor.

Scope

Skills live in one of six scopes. The list and show commands surface the scope and the backing file so it is always clear where a skill is stored and what to edit.

Scope	Source	Editable	Use for
`user`	`~/.clio/skills.json`	yes	Personal skills you want in every project
`project`	`<cwd>/.clio/skills.json`	yes	Skills tied to a single codebase, commit to the repo
`session`	`sessions/<id>/skills.json`	yes	Throwaway skills for the current session, cleared on exit
`freeform`	`<dir>/.clio/skills/<name>.md`	yes (edit the .md)	Markdown-form skills for long-form content, version controlled alongside code
`repository`	`~/.clio/skill-cache/<repo>/`	no (re-sync instead)	Skills pulled from a configured Git repository
`builtin`	bundled with CLIO	no	Read-only skills shipped with CLIO (`explain`, `review`, `test`, `fix`, `doc`, `design`, `init`, `init-with-prd`, `design-review`)

Skill Priority

When skills have the same name across sources, the priority order is:

Session skills (highest - current session only)
Project skills (.clio/skills.json)
User skills (~/.clio/skills.json)
Freeform skills (.clio/skills/<name>.md)
Repository skills (from configured Git repos)
Built-in skills (lowest - shipped with CLIO)

System Prompts

System prompts define CLIO's base behavior and personality. You can customize them per project.

Viewing Prompts:

: /prompt                    # Show prompt status
: /prompt show               # Display full active prompt
: /prompt list               # List all available prompts

Switching Prompts:

: /prompt set <name>         # Switch to named prompt
: /prompt reset              # Reset to default

Custom Prompts:

: /prompt edit <name>        # Edit in $EDITOR
: /prompt save <name>        # Save current as new
: /prompt delete <name>      # Delete custom prompt

Per-Project Instructions: Create .clio/instructions.md in your project root. This content is automatically appended to the system prompt when working in that directory.

Variables in ${brackets} are replaced when the skill is executed.

Security & Sandbox Mode

CLIO provides multiple layers of security to protect your system and sensitive data.

Secret and PII Redaction

CLIO automatically redacts sensitive information from tool output before it's sent to the AI provider. This includes:

PII (Personally Identifiable Information): Email addresses, phone numbers, SSN, credit cards
Cryptographic Material: Private keys, database connection strings with passwords
API Keys: AWS, GitHub, Stripe, OpenAI, Slack, Discord, etc.
Authentication Tokens: JWT, Bearer tokens, Basic auth headers

Redaction Levels:

Configure the level of redaction using /config set redact_level <level>:

Level	What Gets Redacted	Use Case
`strict`	Everything (PII + crypto + API keys + tokens)	Maximum security
`standard`	Same as strict	Default for production
`api_permissive`	PII + crypto only (API keys/tokens allowed)	When agent needs to work with tokens
`pii`	Only PII (default)	Development with API key usage
`off`	Nothing	Testing only (use with caution)

Example:

# Allow API keys to pass through (for GitHub token work, etc.)
/config set redact_level api_permissive

# Return to default PII-only protection
/config set redact_level pii

# Maximum protection
/config set redact_level strict

Important Notes:

PII is always redacted unless you set level to off
At api_permissive, database passwords and private keys are still protected
Redaction happens before data is sent to the AI provider
Git operations use strict level by default to prevent accidental commits

Soft Sandbox (`--sandbox` flag)

Restricts file operations to your project directory:

clio --sandbox --new

What Gets Restricted:

File operations: blocked outside project
Remote execution: completely blocked
Version control: limited to project repository
Terminal operations: NOT restricted

Chat Mode (`--chat` flag)

A conversational AI mode optimized for quick questions and web access. Chat mode:

Auto-enables sandbox mode for safety
Restricts tools to: web, file read, memory, interact, todos
Uses a lighter system prompt optimized for chat

clio --chat --new

When to use Chat Mode:

Quick questions without modifying code
Web searches and research
Explaining concepts or code
General debugging help

When to use Agent Mode (default):

Making changes to files
Running commands
Multi-step refactoring
Autonomous task completion

Container Sandbox (Docker)

For complete isolation, run CLIO in a container:

# Using the wrapper script
./clio-container ~/projects/myapp

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

What Gets Restricted:

Filesystem: only project directory accessible
All other host files: completely inaccessible
Network: unrestricted (potential risk)

Tool Filtering

CLIO can restrict which tools are available to the AI agent, independent of sandbox mode:

# Only allow specific tools (allowlist)
clio --enable file_operations,version_control --new

# Block specific tools (blocklist)
clio --disable web_operations,remote_execution --new

For persistent configuration:

/config set disabled_tools web_operations,remote_execution

--enable and --disable are mutually exclusive. CLI flags override config values. Disabled tools never register, so the AI agent cannot call them at all.

Use cases:

Bot deployments: disable interact for non-interactive mode
Read-only analysis: enable only file_operations and code_intelligence
Network-restricted environments: disable web_operations and remote_execution
Minimal surface area: enable only the tools you need

When to Use Each Mode

Scenario	Recommendation
Trusted environment	No sandbox needed
Unfamiliar codebase	`--sandbox` flag
Sensitive project	`--sandbox` flag
Bot or automation	`--disable` specific tools
Read-only analysis	`--enable` specific tools
Maximum security	Container sandbox

For detailed information, see docs/SANDBOX.md.

Tips & Best Practices

Effective Prompting

Be Specific:

[Bad] "Fix the code"
[Good] "In auth.pm, add input validation to the login function to prevent SQL injection"

Provide Context:

[Bad] "Update the config"
[Good] "In config.yaml, change the database connection pool size from 10 to 20 to handle increased load"

Multi-Step Requests:

[Good] "Create a new branch called feature/api-v2, refactor the API endpoints in lib/API.pm to use FastAPI instead of Flask, and commit the changes"

CLIO handles multi-step workflows naturally. Don't break them down unless you need to review intermediate steps.

Using Sessions Effectively

Name Your Sessions Mentally: As you work, think of each session as having a purpose:

"Refactoring auth module session"
"Bug investigation session"
"Documentation writing session"

While CLIO doesn't have custom session names (they're timestamped), mentally organizing your sessions helps you remember which one to resume.

Resume Recent Work:

# Quick resume (most recent)
clio --resume

# Resume specific date/time
clio --resume sess_20260118_143052

Clean Up Old Sessions:

# Sessions are in sessions/ directory
ls -lt sessions/ | head -20  # See recent sessions
rm sessions/sess_2026011*.json  # Delete old sessions

Managing Complex Tasks

Use Todo Lists:

YOU: Create a todo list for this refactoring project with these tasks:
1. Read and understand current authentication flow
2. Design new JWT-based auth system
3. Implement token generation and validation
4. Update all API endpoints to use new auth
5. Write tests for auth system
6. Update documentation

...

YOU: Mark task 1 as complete

...

YOU: What's next on the list?

Break Down Large Changes: For complex refactoring, ask CLIO to show you the plan first:

YOU: I want to refactor the database layer to use an ORM. Show me a plan for how to do this without breaking existing code.

[CLIO provides plan]

YOU: Good, let's implement step 1 first.

Code Review with CLIO

Before Committing:

YOU: Review my changes before I commit. Look for:
- Potential bugs
- Security issues
- Code style violations
- Missing error handling

SYSTEM: [git] - Executing git diff
SYSTEM: [file_operations] - Reading modified files

CLIO: I reviewed your changes. Here's what I found:

**Potential Issues:**
1. auth.pm:45 - Missing error handling for database connection failure
2. api.pm:123 - Race condition in session creation (not thread-safe)

**Code Style:**
1. Inconsistent indentation in auth.pm (mix of tabs and spaces)
2. Missing POD documentation for new subroutines

**Security:**
1. ✅ Input validation present
2. ✅ SQL injection protected (parameterized queries)
3. ⚠️ Consider adding rate limiting to login endpoint

**Recommendation:** Fix the error handling and race condition before committing.

Debugging with CLIO

Trace Execution:

YOU: Help me debug why the authentication is failing. Trace the code execution from login endpoint to database query.

SYSTEM: [file_operations] - Reading lib/API/Auth.pm
SYSTEM: [file_operations] - Reading lib/Database/Users.pm
SYSTEM: [file_operations] - Reading lib/Session/Manager.pm

CLIO: Here's the execution flow and where the issue likely is:

1. **API/Auth.pm:login()** (line 45)
   - Receives username/password from request
   - Validates input format ✅
   - Calls Database::Users->authenticate()

2. **Database/Users.pm:authenticate()** (line 89)
   - Queries database for user
   - **[ISSUE]:** Password comparison uses `eq` instead of secure compare
   - Returns user object if match

3. **Session/Manager.pm:create_session()** (line 156)
   - Creates new session
   - Stores in session table
   - Returns session token

**The Problem:**
Line 89 in Database/Users.pm uses simple string comparison (`eq`) which is:
1. Vulnerable to timing attacks
2. Not comparing hashed passwords properly

**The Fix:**
Use Digest::SHA and constant-time comparison.

Would you like me to implement the fix?

Keyboard Shortcuts

In Chat:

Ctrl+D or type exit - End session
Ctrl+C - Cancel current AI response
? - Show help (when implemented)
Up/Down Arrow - History navigation (terminal-dependent)

Command Line:

# Quick access
alias c='clio --resume'     # Resume last session
alias cn='clio --new'        # New session
alias cd='clio --debug'      # Debug mode

Terminal Tips

Use a Good Terminal Emulator:

macOS: iTerm2 (better than default Terminal.app)
Linux: GNOME Terminal, Konsole, Alacritty
Windows: Windows Terminal with WSL

Terminal Settings:

Enable 256-color support for best markdown rendering
Use a monospace font with good Unicode support (FiraCode, JetBrains Mono)
Set scroll back buffer to at least 10,000 lines

Tmux/Screen Integration: CLIO works great in tmux or screen for persistent sessions:

# In tmux
tmux new -s clio
clio --resume

# Detach: Ctrl+B, D
# Reattach: tmux attach -t clio

Troubleshooting

Installation Issues

Problem: "perl: command not found"

Perl is not installed or not in PATH.

Solution:

# macOS
brew install perl

# Ubuntu/Debian
sudo apt-get install perl

# Verify
perl --version

Problem: "Can't locate CLIO/Core/Main.pm"

Library path not set correctly.

Solution:

# Reinstall to ensure paths are set
sudo ./install.sh

# Or set PERL5LIB manually
export PERL5LIB=/usr/local/lib/clio/lib:$PERL5LIB

Problem: "Permission denied"

Installation requires sudo for system directories.

Solution:

sudo ./install.sh

API/Token Issues

Problem: "API authentication failed"

GitHub Copilot authentication failed or not configured.

Solution:

# Start CLIO and login
./clio
: /api login
# Follow browser prompts

# Or check if you have saved tokens
ls ~/.clio/github_tokens.json

# For other providers, use /api commands
: /api set provider openai
: /api set key YOUR_KEY

Problem: "Rate limit exceeded"

Too many API requests in short time.

Solution: Wait a few minutes, or use a different AI provider if available.

Session Issues

Problem: "Session file corrupt"

Session JSON file is malformed.

Solution:

# Check session file
cat sessions/sess_20260118_143052.json | python -m json.tool

# If corrupt, delete and start new
rm sessions/sess_20260118_143052.json
clio --new

Problem: "Cannot resume session"

Session ID doesn't exist.

Solution:

# List available sessions
ls sessions/

# Resume with correct ID
clio --resume sess_YYYYMMDD_HHMMSS

Output/Display Issues

Problem: "Garbled output / weird characters"

Terminal doesn't support ANSI codes or UTF-8.

Solution:

# Check terminal type
echo $TERM

# Should be xterm-256color or similar
# If not, set it:
export TERM=xterm-256color

# Verify UTF-8
locale | grep UTF-8

# If not UTF-8:
export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

Problem: "No colors in output"

ANSI colors disabled or not supported.

Solution:

Use a better terminal emulator (see Tips section)
Check if colors are disabled: export CLIO_NO_COLOR=0
Try different theme: Edit ~/.clio/config.yaml

Performance Issues

Problem: "CLIO is slow to respond"

Network latency to AI provider API.

Solution:

Check internet connection
Try different AI provider
Use --debug to see where time is spent

Problem: "High memory usage"

Large session history or file operations.

Solution:

# Start new session to clear memory
clio --new

# Or clean up old sessions
rm sessions/sess_2025*.json  # Delete old sessions

Tool Issues

Problem: "File operation failed"

Permission denied or file doesn't exist.

Solution: Check file permissions and paths. CLIO runs with your user privileges:

# Check permissions
ls -la /path/to/file

# If permission issue, fix it:
chmod 644 /path/to/file

Problem: "Git operation failed"

Not in a git repository or git not installed.

Solution:

# Verify git is installed
git --version

# Verify you're in a git repo
git status

# If not, initialize:
git init

FAQ

General Questions

Q: Is CLIO free?

A: CLIO itself is open-source and free (GPL v3). You need access to an AI provider - GitHub Copilot (included with GitHub subscriptions), Anthropic, OpenAI, Google, DeepSeek, OpenRouter, MiniMax, or a local model (llama.cpp, LM Studio, SAM).

Q: Does CLIO work offline?

A: With cloud providers, you need an internet connection. With local providers (llama.cpp, LM Studio, SAM), CLIO works completely offline. Session data is always stored locally regardless of provider.

Q: Can I use CLIO with ChatGPT/Claude directly?

A: Yes. CLIO supports multiple providers including Anthropic (Claude models directly), OpenAI (GPT models directly), Google Gemini, DeepSeek, OpenRouter (access to hundreds of models), MiniMax, and local models. See PROVIDERS.md for setup.

Q: Is CLIO safe to use with sensitive code?

A: CLIO only sends context to the AI provider that's necessary for the current request. Sensitive data (API keys, tokens, passwords) is automatically redacted before transmission. For complete privacy, use local providers where your data never leaves your machine. Review your organization's policies before using cloud providers with proprietary code.

Feature Questions

Q: Can CLIO write entire applications for me?

A: CLIO is a tool to assist development, not replace it. It can:

Generate boilerplate code
Refactor existing code
Write documentation
Debug issues
Answer questions

But you should review all changes and understand what CLIO does.

Q: Does CLIO learn from my code?

A: Not within CLIO itself. The AI providers may use interactions for improvement depending on their individual policies. CLIO's local memory system (LTM) stores only what you explicitly ask it to remember, and that data stays on your machine.

Q: Can CLIO work with multiple programming languages?

A: Yes! CLIO works with any text-based files and languages. It has been tested with Perl, Python, JavaScript, Ruby, Go, C, C++, Java, and many others.

Q: Can multiple people share sessions?

A: Not directly. Sessions are stored as local JSON files. However, you could share session files between machines manually, though this isn't officially supported.

Technical Questions

Q: What AI models does CLIO use?

A: CLIO supports models from multiple providers. The recommended option is MiniMax via OpenRouter. GitHub Copilot gives you access to GPT-5, Claude Opus and Sonnet, MiniMax, and more. Direct provider access gives you the full model catalog from OpenAI, Google, DeepSeek, OpenRouter, and MiniMax. Local models (llama.cpp, LM Studio) work for offline use.

Q: How much does API usage cost?

A: This depends on your AI provider. Check your provider's website for current pricing. Local models (llama.cpp, LM Studio, SAM) run on your hardware at no cost. CLIO itself doesn't add any costs.

Q: Can I add custom tools to CLIO?

A: Yes! See docs/DEVELOPER_GUIDE.md for information on extending CLIO with custom tools.

Q: Does CLIO support Windows?

A: CLIO should work on Windows with WSL (Windows Subsystem for Linux) or Cygwin, but it's primarily developed and tested on macOS and Linux.

Workflow Questions

Q: Should I use CLIO or a GUI AI assistant?

A: Use CLIO if:

You prefer terminal workflows
You want file/git/terminal integration
You value session persistence
You want transparent tool execution

Use GUI assistant if:

You prefer visual interfaces
You primarily need conversation, not tool integration

Q: Can I use CLIO for non-coding tasks?

A: Yes! CLIO can:

Write documentation
Research topics (web fetch)
Manage todos
Store notes (memory system)
Analyze text files

Q: How do I switch between AI providers?

A: Use /api commands. See PROVIDERS.md for full details:

# Switch to OpenAI
: /api provider openai
: /api key YOUR_OPENAI_KEY
: /config save

# Switch to DeepSeek
: /api provider deepseek
: /api key YOUR_DEEPSEEK_KEY
: /config save

# Switch back to GitHub Copilot
: /api provider github_copilot
# (uses saved token from /api login)
unset GITHUB_COPILOT_TOKEN

Provider and API key settings persist across sessions when you run /config save.

Next Steps

Explore More:

Provider Configuration - Configure AI providers
Developer Guide - Learn to extend CLIO
Architecture - Understand how CLIO works

Get Help:

Contribute: See DEVELOPER_GUIDE.md for contribution guidelines.

Happy coding with CLIO!