CLIO Architecture

Last Updated: July 2026

Quick Overview

CLIO is a terminal-first AI code assistant built in Perl. It integrates AI models (GitHub Copilot, Anthropic, OpenAI, Google, OpenRouter, Ollama Cloud, MiniMax, Z.AI, NVIDIA NIM, DeepSeek, SAM, llama.cpp, LM Studio) with local tools (file operations, git, terminal) to help developers work more effectively.

Core concept: User types → CLIO thinks → CLIO uses tools → Results displayed

User Input
   ↓
Terminal UI (Chat.pm)
   ↓
AI Agent (WorkflowOrchestrator.pm)
   ↓
Tool Selection & Execution
     - File Operations (FileOperations.pm)
     - Git (VersionControl.pm)
     - Terminal (TerminalOperations.pm)
     - Memory (MemoryOperations.pm)
     - Other tools...
   ↓
Response Processing
   ↓
Markdown Rendering (Markdown.pm)
   ↓
Terminal Output

System Components

1. User Interface Layer

Files: lib/CLIO/UI/

Component	File	Purpose
Terminal UI	`Chat.pm`	Main interaction loop, streaming output
Markdown Renderer	`Markdown.pm`	Convert markdown to ANSI
Color/ANSI	`ANSI.pm`	ANSI escape sequences
Themes	`Theme.pm`	Color themes and styling
Display	`Display.pm`	Display utilities (writeline, colors)
Tool Output Formatter	`ToolOutputFormatter.pm`	Format tool operation output
Command Handler	`CommandHandler.pm`	Route slash commands to handler modules
Progress Spinner	`ProgressSpinner.pm`	Animated busy indicator
Multiplexer	`Multiplexer.pm`	Terminal multiplexer detection and pane management
Streaming Controller	`StreamingController.pm`	Manage streaming response display and pagination
Pagination Manager	`PaginationManager.pm`	Page-based output display for long content
Diff Renderer	`DiffRenderer.pm`	Unified diff display with syntax coloring
Terminal Capabilities	`Terminal.pm`	Terminal feature detection (color depth, image protocols)
Host Protocol	`HostProtocol.pm`	Structured communication protocol for GUI host apps
Commands Base	`Commands/Base.pm`	Base class providing display delegation for all slash command modules

How it works:

User types message
Chat.pm sends to AI
Stream responses back to terminal
Markdown rendering converts formatting
Apply theme colors

2. Core AI & Workflow

Files: lib/CLIO/Core/

Component	File	Purpose
API Manager	`APIManager.pm`	AI provider integration, token management
Workflow Orchestrator	`WorkflowOrchestrator.pm`	Main agent loop, tool orchestration
Simple AI Agent	`SimpleAIAgent.pm`	Lightweight AI agent for internal tasks
Tool Executor	`ToolExecutor.pm`	Invokes tools, applies secret redaction
Tool Call Extractor	`ToolCallExtractor.pm`	Extract tool calls from AI responses
Prompt Manager	`PromptManager.pm`	System prompts + custom instructions
Prompt Builder	`PromptBuilder.pm`	Prompt construction utilities
Instructions Reader	`InstructionsReader.pm`	Reads `.clio/instructions.md` and `AGENTS.md`
Config	`Config.pm`	API keys, provider selection, model aliases
ReadLine	`ReadLine.pm`	Command history & editing
Editor	`Editor.pm`	Core editing functionality
Hashtag Parser	`HashtagParser.pm`	Parse hashtag commands
Tab Completion	`TabCompletion.pm`	Tab completion support
Skill Manager	`SkillManager.pm`	Manage AI skills
Skill Repository	`SkillRepository.pm`	Skill repository configuration and management
Repository Loader	`RepositoryLoader.pm`	Load skills from cached Git repositories
Copilot User API	`CopilotUserAPI.pm`	GitHub Copilot user management
Device Registry	`DeviceRegistry.pm`	Named devices and groups for remote execution
Agent Loop	`AgentLoop.pm`	Persistent agent execution loop
Conversation Manager	`ConversationManager.pm`	Conversation history management
Model Registry	`ModelRegistry.pm`	AI model metadata and management
Tool Error Guidance	`ToolErrorGuidance.pm`	Contextual error recovery hints
Error Context	`ErrorContext.pm`	Error taxonomy and structured error context
Message Validator	`API/MessageValidator.pm`	Validate and proactively trim messages for AI providers
Response Handler	`API/ResponseHandler.pm`	Parse and process AI provider responses
GitHub Auth	`GitHubAuth.pm`	GitHub OAuth authentication
GitHub Copilot Models API	`GitHubCopilotModelsAPI.pm`	Access GitHub Copilot models
Performance Monitor	`PerformanceMonitor.pm`	Track timing metrics
Rate Limiter	`RateLimiter.pm`	API rate limit tracking and enforcement
Plugin Manager	`PluginManager.pm`	Plugin system management
Defaults	`Defaults.pm`	Default configuration values
Logger	`Logger.pm`	Debug and trace output

How it works:

APIManager connects to AI provider (GitHub Copilot, OpenAI, Google, OpenRouter, MiniMax, Z.AI, Ollama Cloud, NVIDIA NIM, DeepSeek, SAM, llama.cpp, LM Studio, etc.)
WorkflowOrchestrator manages complex interactions, including:
- Proactive context trimming before each API call (keeps messages at ≤75% of context)
- Reactive trimming with 3-attempt escalation when the API rejects due to token overflow
- 400 Bad Request escalation: silent retry → tool_call repair → context trim → error surface
PromptManager provides system prompt + custom instructions
ToolExecutor invokes selected tools
Results processed and returned

3. Tool System

Files: lib/CLIO/Tools/

Tool	File	Operations
File Operations	`FileOperations.pm`	read, write, search, create, delete, rename, etc.
Version Control	`VersionControl.pm`	git status, log, diff, commit, branch, push, pull, blame, stash, tag, worktree
Terminal	`TerminalOperations.pm`	exec - run shell commands safely (fork+process group, ESC-interruptible)
Memory	`MemoryOperations.pm`	store, retrieve, search, list, delete
Todo	`TodoList.pm`	create, update, complete, list, track tasks
Code Intelligence	`CodeIntelligence.pm`	list_usages, search_history
Web	`WebOperations.pm`	fetch_url, search_web
Interact	`Interact.pm`	request_input - checkpoint prompts
Sub-Agent Operations	`SubAgentOperations.pm`	Spawn and manage parallel agents
Remote Execution	`RemoteExecution.pm`	Execute AI tasks on remote systems
Apply Patch	`ApplyPatch.pm`	Apply lightweight diff patches
Skill Operations	`SkillOperations.pm`	Manage AI skills
MCP Bridge	`MCPBridge.pm`	Bridge to MCP tool servers
Plugin Bridge	`PluginBridge.pm`	Bridge to plugin tools
Base Tool	`Tool.pm`	Abstract base class for all tools
Registry	`Registry.pm`	Tool registration and lookup

Architecture:

Base class: Tool.pm provides abstract interface
Each tool extends Tool.pm and implements execute()
Registry.pm maintains tool registry and handles lookup
ToolExecutor.pm (in Core) invokes tools and manages execution
ToolResultStore.pm (in Session) caches large tool outputs for efficiency

Tool Filtering: Tools can be restricted via --enable (allowlist) or --disable (blocklist) CLI flags, or the persistent enabled_tools/disabled_tools config keys. Filtering is applied in WorkflowOrchestrator::_register_default_tools() before any tool is registered. CLI flags override config. No tool is immune from filtering.

4. Session Management

Files: lib/CLIO/Session/

Component	File	Purpose
Session Manager	`Manager.pm`	Create/load/resume sessions
Session State	`State.pm`	Conversation history, metadata
Todo Store	`TodoStore.pm`	Persist todos across sessions
Tool Result Store	`ToolResultStore.pm`	Cache tool results for large output
File Vault	`FileVault.pm`	Targeted file backup for undo/revert
Session Export	`Export.pm`	Export sessions to self-contained HTML
Session Lock	`Lock.pm`	Lock files to prevent concurrent access

How it works:

New session: Create sessions/UUID.json
Each message appended to conversation history
Sessions persist on disk (in sessions/ directory)
Resume: Load session from disk, continue conversation

5. Memory System

Files: lib/CLIO/Memory/ Deep Dive: Memory Architecture

Component	File	Purpose
Short-Term	`ShortTerm.pm`	Session context (sliding window)
Long-Term	`LongTerm.pm`	Project-level knowledge (.clio/ltm.json)
YaRN	`YaRN.pm`	Conversation archival and compression
Token Estimator	`TokenEstimator.pm`	Token count estimation with learned ratio

How it works:

Short-term memory maintains a sliding window of recent messages for the active context
Long-term memory accumulates discoveries, solutions, and patterns across sessions
YaRN archives full conversations and compresses dropped messages during trimming
Token estimator learns from API responses to calibrate proactive trimming thresholds
See MEMORY.md for the complete architecture

5b. User Profile

Files: lib/CLIO/Profile/

Component	File	Purpose
Analyzer	`Analyzer.pm`	Scan session history for personality patterns
Manager	`Manager.pm`	Load/save/inject profile into prompts

How it works:

Profile stored at ~/.clio/profile.md (global, never in git)
Analyzer scans .clio/sessions/ across sibling projects
Manager injects profile into system prompt via PromptBuilder
/profile build triggers analysis + AI-assisted collaborative refinement

6. Code Analysis

Files: lib/CLIO/Code/

Component	File	Purpose
Tree-sitter	`TreeSitter.pm`	Parse code into AST

How it works:

TreeSitter parses source code into abstract syntax trees for code intelligence features

7. Security

Files: lib/CLIO/Security/

Component	File	Purpose
Auth	`Auth.pm`	GitHub OAuth, token storage
Authz	`Authz.pm`	Check file access permissions
Path Authorizer	`PathAuthorizer.pm`	Control file access
Secret Redactor	`SecretRedactor.pm`	PII and secret redaction from tool output
Command Analyzer	`CommandAnalyzer.pm`	Intent-based command risk classification
Invisible Char Filter	`InvisibleCharFilter.pm`	Detect and strip invisible Unicode characters from user input

How it works:

User runs /api login → GitHub device flow
Token stored securely in ~/.clio/
File operations check PathAuthorizer
Tool output passes through SecretRedactor before display/AI transmission
Audit logging of all operations

8. Logging & Monitoring

Files: lib/CLIO/Logging/, lib/CLIO/Core/

Component	File	Purpose
Logger	`Core/Logger.pm`	Debug/trace output
Tool Logger	`Logging/ToolLogger.pm`	Log tool operations
Performance Monitor	`Core/PerformanceMonitor.pm`	Track timing
Process Stats	`Logging/ProcessStats.pm`	RSS/VSZ memory and resource tracking

15. Utilities

Files: lib/CLIO/Util/

Component	File	Purpose
Path Resolver	`PathResolver.pm`	Tilde expansion, path canonicalization
Text Sanitizer	`TextSanitizer.pm`	Sanitize text for safe display
JSON	`JSON.pm`	Opportunistic fast JSON (JSON::XS > Cpanel::JSON::XS > JSON::PP)
JSON Repair	`JSONRepair.pm`	Repair malformed JSON from AI responses
Git Ignore	`GitIgnore.pm`	Auto-manage `.clio/` entries in `.gitignore`
Input Helpers	`InputHelpers.pm`	Terminal input utilities
XML Tool Parser	`AnthropicXMLParser.pm`	Parse XML-format tool calls from AI responses
YAML	`YAML.pm`	Lightweight YAML parser (no CPAN required)

How it works:

Debug mode: clio --debug
Output goes to STDERR with [DEBUG], [ERROR], [TRACE] prefixes
Tool operations logged via ToolLogger

9. Multi-Project Topology

Files: lib/CLIO/Protocols/Puppeteer.pm

Puppeteer.pm is a helper class (not a registered protocol) called directly from SubAgent.pm and PromptManager.pm to discover child projects and load their instructions. It is not part of the tool architecture.

CLIO has no other protocol modules. The earlier Architect.pm, Editor.pm, Validate.pm, Recall.pm, Manager.pm, and Handler.pm were removed in June 2026 because they were unregistered, their handler classes did not exist, and the dispatch method name (handle vs process_request) was inconsistent. The tool architecture in lib/CLIO/Tools/ is the active, working layer.

10. Multi-Agent Coordination

Files: lib/CLIO/Coordination/, lib/CLIO/UI/HostProtocol.pm

Component	File	Purpose
Broker	`Broker.pm`	Unix socket coordination server (messaging, locks, status relay)
Client	`Client.pm`	Broker connection API
SubAgent	`SubAgent.pm`	Process spawning and lifecycle management
HostProtocol	`HostProtocol.pm`	OSC event emission and broker relay for agent status

How it works:

Puppeteer detects child projects via .gitmodules and .clio/ directories
PromptManager injects topology into the agent's system prompt
Main session spawns sub-agents, optionally scoped to child projects (--project / working_dir)
Child agents load the target project's .clio/ context (LTM, instructions, memory)
Broker provides coordination via Unix socket (file locks, git locks, message bus, status relay)
Child agent status changes relay through broker to primary, then to host app via OSC events
API rate limiting is shared across all agents

11. Terminal Multiplexer Integration

Files: lib/CLIO/UI/Multiplexer.pm, lib/CLIO/UI/Multiplexer/

Component	File	Purpose
Multiplexer	`Multiplexer.pm`	Detection, driver abstraction, pane lifecycle management
Tmux Driver	`Multiplexer/Tmux.pm`	tmux pane operations via CLI (split-window, kill-pane)
Screen Driver	`Multiplexer/Screen.pm`	GNU Screen window operations via CLI (-X commands)
Zellij Driver	`Multiplexer/Zellij.pm`	Zellij pane operations via action commands
Mux Commands	`Commands/Mux.pm`	`/mux` slash commands (status, agent, close, auto)

How it works:

On initialization, detects multiplexer via environment variables ($TMUX, $STY, $ZELLIJ)
Detection priority: tmux > GNU Screen > Zellij
When /agent spawn is called inside a multiplexer, auto-opens a pane with tail -f of the agent's log
All operations are graceful no-ops when no multiplexer is detected
Each driver translates CLIO's pane API to multiplexer-specific CLI commands
Managed panes are tracked and can be listed/closed via /mux commands

12. AI Providers

Files: lib/CLIO/Providers/, lib/CLIO/Providers.pm

Component	File	Purpose
Provider Registry	`Providers.pm`	AI provider registration and lookup (18 providers)
Base	`Base.pm`	Abstract base class for providers
Anthropic	`Anthropic.pm`	Native Anthropic Messages API
Google	`Google.pm`	Native Google Gemini API
NVIDIA	`NVIDIA.pm`	Native NVIDIA NIM API

How it works:

Base.pm defines the provider interface
Each native provider implements its own API communication
18 providers configured in Providers.pm: SAM, GitHub Copilot, OpenAI, DeepSeek, llama.cpp, LM Studio, Ollama Cloud, OpenRouter, OrcaRouter, KiloCode, MiniMax, MiniMax Token Plan, Z.AI Chat, Z.AI Coding, Anthropic, Google Gemini, NVIDIA NIM, Vercel AI Gateway
OpenAI-compatible providers (OpenAI, DeepSeek, MiniMax, Z.AI, OpenRouter, etc.) and GitHub Copilot are handled directly by APIManager

13. OpenSpec Integration

Files: lib/CLIO/Spec/, lib/CLIO/Util/YAML.pm, lib/CLIO/UI/Commands/Spec.pm

Component	File	Purpose
Spec Manager	`Spec/Manager.pm`	Spec and change lifecycle management
YAML Parser	`Util/YAML.pm`	Lightweight YAML parser for OpenSpec config/schema files
Spec Commands	`UI/Commands/Spec.pm`	`/spec` slash command handler

How it works:

User runs /spec init to create openspec/ directory structure
/spec propose <name> creates a change and sends structured prompt to AI
AI generates planning artifacts (proposal, specs, design, tasks) via file_operations
User implements against tasks.md using normal CLIO workflow
/spec archive moves completed change to archive
PromptManager auto-injects spec context into system prompt when openspec/ exists
File format is 100% compatible with the OpenSpec Node.js CLI

Data Flow

Typical Interaction

graph TD
    A["1. User Input (Chat.pm)<br/>User: 'Please read config.py and explain what it does'"] --> B
    B["2. AI Processing (APIManager -> AI Provider)<br/>- Load system prompt (PromptManager)<br/>- Inject custom instructions (.clio/instructions.md)<br/>- Send to GitHub Copilot/OpenAI/etc.<br/>- Get response with tool calls"] --> C
    C["3. Tool Selection (ToolCallExtractor)<br/>- AI might request: 'FILE_OPERATION: read config.py'<br/>- Parse and validate tool call"] --> D
    D["4. Tool Execution (ToolExecutor)<br/>- Invoke FileOperations.pm:read('config.py')<br/>- Tool performs operation on real filesystem<br/>- Return results"] --> E
    E["5. Response Processing<br/>- Build response with tool results<br/>- Stream back to AI for analysis/explanation<br/>- Or display results to user"] --> F
    F["6. Display (Markdown.pm + Theme.pm)<br/>- Convert markdown formatting to ANSI<br/>- Apply theme colors<br/>- Stream to terminal"] --> G
    G[User sees response]
    
    style A fill:#e1f5ff
    style B fill:#fff3e0
    style C fill:#f3e5f5
    style D fill:#e8f5e9
    style E fill:#fce4ec
    style F fill:#e1bee7
    style G fill:#c8e6c9

Session Persistence

graph TD
    A[User Action] --> B[Add to Session.State.conversation]
    B --> C[Save sessions/UUID.json]
    C --> D[User resumes later]
    D --> E[Load sessions/UUID.json]
    E --> F[Conversation history restored]
    F --> G[Continue from where left off]
    
    style A fill:#e1f5ff
    style C fill:#fff3e0
    style E fill:#e8f5e9
    style G fill:#c8e6c9

Entry Points

`clio` Script (Main Executable)

#!/usr/bin/env perl
1. Load required modules
2. Parse command-line arguments (--new, --resume, --debug, etc.)
3. Initialize configuration
4. Create/load session
5. Instantiate Chat.pm UI
6. Start interactive loop

`clio --new`

Start fresh session
Create new sessions/UUID.json
Begin conversation

`clio --resume`

Find most recent session
Load conversation history
Resume from where left off

`clio --input "text" --exit`

Non-interactive mode
Process input and exit immediately
Used for scripting/automation

Configuration

Locations

API Keys: ~/.clio/config.json
Sessions: ./sessions/ (project directory)
Custom Instructions: ./.clio/instructions.md (project directory)
System Prompts: ~/.clio/system-prompts/ (user home)

Setup Process

clio --new           # First run
: /api login        # Authorize with GitHub Copilot
: /config show      # View config
: /api provider     # Check current provider

Dependencies

Required (Perl Core Only)

strict, warnings (language features)
JSON::PP (JSON parsing, core since 5.14)
HTTP::Tiny (HTTP requests, core since 5.14)
MIME::Base64 (base64 encoding, core since 5.8)
Digest::SHA (SHA hashing, core since 5.10)
File::Spec (cross-platform paths, core)
File::Path (directory operations, core)
File::Temp (temporary files, core)
File::Find (file tree traversal, core)
File::Basename (path manipulation, core)
Time::HiRes (high-resolution timers, core since 5.8)
POSIX (POSIX functions, core)
Cwd (working directory, core)
Plus other core modules

Optional (Non-Core, Graceful Degradation)

Text::Diff (diff visualization - has fallback if not installed)

External Tools Required

System git (for version control operations)
System perl 5.32+ (for script execution)

NOT Used

❌ CPAN modules (except optional Text::Diff with fallback)
❌ External npm/pip packages
❌ Build tools like Make or Gradle
❌ Term::ReadLine (not required, uses basic readline if missing)

Testing

Test Infrastructure

lib/CLIO/Test/MockAPI.pm - Mock API for testing
tests/run_all_tests.pl - Test runner
tests/unit/*.pl - Unit tests
tests/integration/*.pl - Integration tests
tests/e2e/*.pl - End-to-end tests

Running Tests

# Run all tests
./tests/run_all_tests.pl --all

# Run a specific unit test
perl -I./lib tests/unit/test_json_repair.pl

# Syntax check a module
perl -I./lib -c lib/CLIO/Core/Config.pm

Performance Considerations

Speed

Direct tool invocation (no remote API for file ops)
Streaming responses from AI (no wait for full response)
Token counting for efficient context usage

Memory

Session data in sessions/ (JSON files)
In-memory conversation history
Token estimator helps avoid OOM

Terminal Safety

TerminalOperations uses fork+exec with POSIX::setpgid(0,0) in the child, creating a process group
On timeout or ESC interrupt, kill(-TERM, $pgid) sends SIGTERM to the entire process group (kills ssh, sh -c wrappers, and grandchildren)
SIGKILL follows after 2 seconds if processes survive SIGTERM
/reset runs kill_stale_children() to clean up any orphaned processes from the current session
ESC interrupt is detected via ALRM timer (1Hz) throughout all execution phases - API calls, tool execution, and streaming

Scalability

Not designed for 1000s of projects
Designed for individual developer workflows
Can handle large codebases (>1GB)

Architectural Considerations

Design Principles

Modularity - Each component has a single, well-defined responsibility
Extensibility - Tools and protocols can be added without modifying core
Separation of Concerns - UI, AI, tools, and storage are independent layers
Graceful Degradation - Optional features fail safely (e.g., Text::Diff)

Extension Points

Tools: Create new tool in lib/CLIO/Tools/, register in Registry
Protocols: Create protocol handler in lib/CLIO/Protocols/, extend Handler.pm
UI Themes: Add theme file in themes/, define color scheme
AI Providers: Add provider logic in Core/APIManager.pm

Module Organization

lib/CLIO/
  Providers.pm             # AI provider registry (GitHub Copilot, OpenAI, Ollama, Z.AI, etc.)
  Update.pm                # Self-update system
  UI/                      # Terminal interface
      Chat.pm              # Main interactive loop
      Markdown.pm          # Markdown to ANSI
      ANSI.pm              # Color codes
      Theme.pm             # Color themes
      Display.pm           # Display utilities
      ToolOutputFormatter.pm # Tool output formatting
      CommandHandler.pm    # Slash command routing
      ProgressSpinner.pm   # Progress indicators
      StreamingController.pm # Streaming response display
      PaginationManager.pm # Page-based output
      DiffRenderer.pm      # Unified diff display
      Terminal.pm          # Terminal capability detection
      HostProtocol.pm      # GUI host app protocol
      Commands/            # Slash command handlers
          Base.pm          # Base class with display delegation for all command modules
          AI.pm            # AI-powered commands (/explain, /review, /doc)
          API.pm           # API/provider commands (/api, /model)
          API/Auth.pm      # API authentication sub-commands
          API/Config.pm    # API configuration sub-commands
          API/Models.pm    # API model listing sub-commands
          Billing.pm       # Billing/usage commands (/billing, /usage)
          Config.pm        # Configuration commands (/config, /theme)
          Context.pm       # Context window commands (/context)
          Device.pm        # Device management commands (/device)
          File.pm          # File commands (/file, /read, /edit)
          Git.pm           # Git commands (/git, /status, /diff)
          Log.pm           # Log commands (/log)
          Memory.pm        # Memory commands (/memory)
          Mux.pm           # Multiplexer commands (/mux)
          Profile.pm       # User profile commands (/profile)
          Project.pm       # Project setup commands (/design, /init)
          Prompt.pm        # Prompt commands (/prompt)
          Session.pm       # Session management commands (/session)
          Skills.pm        # Skill system commands (/skills)
          Spec.pm          # OpenSpec commands (/spec)
          Stats.pm         # Stats commands (/stats)
          SubAgent.pm      # Sub-agent commands (/subagent)
          System.pm        # System commands (/clear, /exit, /shell)
          Todo.pm          # Todo commands (/todo)
          Update.pm        # Update commands (/update)
      Multiplexer.pm       # Terminal multiplexer detection and abstraction
      Multiplexer/         # Multiplexer drivers
          Tmux.pm          # tmux driver
          Screen.pm        # GNU Screen driver
          Zellij.pm        # Zellij driver
  Core/                    # Core AI functionality
      APIManager.pm        # AI provider integration
      SimpleAIAgent.pm     # AI request/response
      PromptManager.pm     # System prompts
      PromptBuilder.pm     # Prompt construction
      InstructionsReader.pm # Custom instructions
      WorkflowOrchestrator.pm # Multi-step workflows
      ToolExecutor.pm      # Tool invocation
      ToolCallExtractor.pm # Extract tool calls
      ToolErrorGuidance.pm # Tool error assistance
      ConversationManager.pm # Conversation management
      Config.pm            # Configuration
      ModelRegistry.pm     # Model management
      ReadLine.pm          # Command history
      Editor.pm            # Core editing
      HashtagParser.pm     # Hashtag commands
      TabCompletion.pm     # Tab completion
      SkillManager.pm      # AI skills
      SkillRepository.pm   # Skill repository config
      RepositoryLoader.pm  # Load skills from Git repos
      GitHubAuth.pm        # OAuth
      GitHubCopilotModelsAPI.pm # Copilot models
      CopilotUserAPI.pm    # Copilot user API
      DeviceRegistry.pm    # Device management
      AgentLoop.pm         # Persistent agent loop
      PerformanceMonitor.pm # Performance tracking
      RateLimiter.pm       # API rate limiting
      PluginManager.pm     # Plugin system
      Defaults.pm          # Default configuration values
      Logger.pm            # Logging
      API/                 # API sub-modules
          MessageValidator.pm # Message format validation and proactive trimming
          ResponseHandler.pm  # AI provider response parsing
      ErrorContext.pm      # Error taxonomy and structured context
  Tools/                   # Tool implementations
      Tool.pm              # Base class
      Registry.pm          # Tool registry
      FileOperations.pm    # File I/O (17 operations)
      VersionControl.pm    # Git (10 operations)
      TerminalOperations.pm # Shell execution
      MemoryOperations.pm  # Memory operations
      TodoList.pm          # Todo tracking
      CodeIntelligence.pm  # Code analysis
      Interact.pm          # User checkpoints
      SubAgentOperations.pm # Multi-agent management
      RemoteExecution.pm   # Remote SSH execution
      ApplyPatch.pm        # Patch application
      MCPBridge.pm         # MCP tool bridge
      WebOperations.pm     # Web operations
  Session/                 # Session management
      Manager.pm           # Session CRUD
      State.pm             # Conversation state
      TodoStore.pm         # Todo persistence
      ToolResultStore.pm   # Large result storage
      FileVault.pm         # Targeted file backup for undo
      Export.pm            # Session export
      Lock.pm              # Session locking
  Memory/                  # Memory systems
      ShortTerm.pm         # Session context
      LongTerm.pm          # Persistent storage
      YaRN.pm              # Context windowing
      TokenEstimator.pm    # Token counting
  Code/                    # Code analysis
      TreeSitter.pm        # AST parsing
      Symbols.pm           # Symbol extraction
      Relations.pm         # Symbol relationships
  Coordination/            # Multi-agent coordination
      Broker.pm            # Coordination server
      Client.pm            # Broker connection API
      SubAgent.pm          # Process spawning
  Protocols/               # Protocol handlers
      Manager.pm           # Protocol registry
      Handler.pm           # Base class
      Architect.pm         # Design protocol
      Editor.pm            # Code editing protocol
      Recall.pm            # Memory recall
  Providers/               # Native API provider modules
      Base.pm              # Provider base class
      Anthropic.pm         # Anthropic Messages API
      Google.pm            # Google Gemini native API
  MCP/                     # Model Context Protocol
      Manager.pm           # MCP server management
      Client.pm            # MCP JSON-RPC client
      Auth/OAuth.pm        # MCP OAuth support
      Transport/Stdio.pm   # Stdio transport
      Transport/HTTP.pm    # HTTP/SSE transport
  Security/                # Security & auth
      Auth.pm              # OAuth
      Authz.pm             # Authorization
      PathAuthorizer.pm    # File access control
      SecretRedactor.pm    # PII/secret redaction
      Manager.pm           # Security manager
      InvisibleCharFilter.pm # Invisible Unicode character defense
  Logging/                 # Logging system
      ToolLogger.pm        # Tool operation logging
      ProcessStats.pm      # Process statistics
  Compat/                  # Compatibility layers
      HTTP.pm              # HTTP compatibility
      Terminal.pm          # Terminal compatibility
  Util/                    # Utilities
      PathResolver.pm      # Path resolution
      TextSanitizer.pm     # Text sanitization
      JSONRepair.pm        # JSON repair
      JSON.pm              # JSON module selection
      ConfigPath.pm        # Config path resolution
      InputHelpers.pm      # Input helpers
      AnthropicXMLParser.pm # XML-format tool call parser
      YAML.pm              # Lightweight YAML parser (OpenSpec support)
      GitIgnore.pm         # Auto-manage .clio/ entries in .gitignore
      AtomicWrite.pm       # Atomic file writes
      RateLimit.pm         # Rate limiting
      ImageAttachment.pm   # Image file handling
      ImageDisplay.pm      # Inline image display
  Spec/                    # OpenSpec integration
      Manager.pm           # Spec lifecycle management
  Test/                    # Testing utilities
      MockAPI.pm           # Mock API for tests
  Profile/                 # User personality profile
      Analyzer.pm          # Session history analysis
      Manager.pm           # Profile storage and injection
  Util/                    # Utility modules
      PathResolver.pm      # Path resolution
      TextSanitizer.pm     # Text sanitization
      ... (other utilities - see detailed listing above)
  NaturalLanguage/         # NL processing
      ... (NL modules)
  Compat/                  # Compatibility layer
      ... (compatibility modules)

For Developers

Getting Started

Read: docs/CUSTOM_INSTRUCTIONS.md - How projects customize CLIO
Read: docs/DEVELOPER_GUIDE.md - Development guide and conventions
Explore: Individual module POD docs

Understanding Code

Start with clio script entry point
Follow to Chat.pm for UI loop
Check WorkflowOrchestrator.pm for main agent loop and tool orchestration
See SimpleAIAgent.pm for the lightweight internal agent used in session naming and internal tasks
See ToolExecutor.pm for tool invocation

Adding Features

Implement in appropriate module
Add tests in tests/
Run perl -I./lib -c on all changed modules
Test with ./clio --debug --input "test" --exit
Update relevant docs

Common Tasks

Fix bug: Find module → Read code → Fix → Test → Commit
Add tool: Create lib/CLIO/Tools/MyTool.pm → Register in main script
Add protocol: Create lib/CLIO/Protocols/MyProtocol.pm → Register in Manager
Update UI: Modify lib/CLIO/UI/Chat.pm or Theme.pm

Summary

CLIO follows a layered architecture with clear separation of concerns:

graph TB
    A["User Interface Layer<br/>(UI/)"]
    B["AI & Workflow Layer<br/>(Core/)"]
    C["Tool Execution Layer<br/>(Tools/)"]
    D["Storage & Persistence<br/>(Session/, Memory/)"]
    
    A --> B --> C --> D
    
    style A fill:#e1f5ff
    style B fill:#fff3e0
    style C fill:#e8f5e9
    style D fill:#fce4ec

Key Architectural Features:

Plugin-based tool system - Tools register dynamically
Protocol-driven AI interaction - Structured AI communication
Persistent session state - Conversation history survives restarts
Zero external dependencies - Runs with Perl core modules only
Modular design - Each component can evolve independently

The architecture prioritizes clarity, maintainability, and extensibility - making it straightforward for developers to understand the codebase and add new capabilities.

Uh oh!

Uh oh!

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History

ARCHITECTURE.md

File metadata and controls

CLIO Architecture

Quick Overview

System Components

1. User Interface Layer

2. Core AI & Workflow

3. Tool System

4. Session Management

5. Memory System

5b. User Profile

6. Code Analysis

7. Security

8. Logging & Monitoring

15. Utilities

9. Multi-Project Topology

10. Multi-Agent Coordination

11. Terminal Multiplexer Integration

12. AI Providers

13. OpenSpec Integration

Data Flow

Typical Interaction

Session Persistence

Entry Points

clio Script (Main Executable)

clio --new

clio --resume

clio --input "text" --exit

Configuration

Locations

Setup Process

Dependencies

Required (Perl Core Only)

Optional (Non-Core, Graceful Degradation)

External Tools Required

NOT Used

Testing

Test Infrastructure

Running Tests

Performance Considerations

Speed

Memory

Terminal Safety

Scalability

Architectural Considerations

Design Principles

Extension Points

Module Organization

For Developers

Getting Started

Understanding Code

Adding Features

Common Tasks

Summary

`clio` Script (Main Executable)

`clio --new`

`clio --resume`

`clio --input "text" --exit`