CLIO Architecture

June 18, 2026 · View on GitHub

Last Updated: May 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) 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/

ComponentFilePurpose
Terminal UIChat.pmMain interaction loop, streaming output
Markdown RendererMarkdown.pmConvert markdown to ANSI
Color/ANSIANSI.pmANSI escape sequences
ThemesTheme.pmColor themes and styling
DisplayDisplay.pmDisplay utilities (writeline, colors)
Tool Output FormatterToolOutputFormatter.pmFormat tool operation output
Command HandlerCommandHandler.pmRoute slash commands to handler modules
Progress SpinnerProgressSpinner.pmAnimated busy indicator
MultiplexerMultiplexer.pmTerminal multiplexer detection and pane management
Streaming ControllerStreamingController.pmManage streaming response display and pagination
Pagination ManagerPaginationManager.pmPage-based output display for long content
Diff RendererDiffRenderer.pmUnified diff display with syntax coloring
Terminal CapabilitiesTerminal.pmTerminal feature detection (color depth, image protocols)
Host ProtocolHostProtocol.pmStructured communication protocol for GUI host apps
Commands BaseCommands/Base.pmBase class providing display delegation for all slash command modules

How it works:

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

2. Core AI & Workflow

Files: lib/CLIO/Core/

ComponentFilePurpose
API ManagerAPIManager.pmAI provider integration, token management
Workflow OrchestratorWorkflowOrchestrator.pmMain agent loop, tool orchestration
Simple AI AgentSimpleAIAgent.pmLightweight AI agent for internal tasks
Tool ExecutorToolExecutor.pmInvokes tools, applies secret redaction
Tool Call ExtractorToolCallExtractor.pmExtract tool calls from AI responses
Prompt ManagerPromptManager.pmSystem prompts + custom instructions
Prompt BuilderPromptBuilder.pmPrompt construction utilities
Instructions ReaderInstructionsReader.pmReads .clio/instructions.md and AGENTS.md
ConfigConfig.pmAPI keys, provider selection, model aliases
ReadLineReadLine.pmCommand history & editing
EditorEditor.pmCore editing functionality
Hashtag ParserHashtagParser.pmParse hashtag commands
Tab CompletionTabCompletion.pmTab completion support
Skill ManagerSkillManager.pmManage AI skills
Skill RepositorySkillRepository.pmSkill repository configuration and management
Repository LoaderRepositoryLoader.pmLoad skills from cached Git repositories
Copilot User APICopilotUserAPI.pmGitHub Copilot user management
Device RegistryDeviceRegistry.pmNamed devices and groups for remote execution
Agent LoopAgentLoop.pmPersistent agent execution loop
Conversation ManagerConversationManager.pmConversation history management
Model RegistryModelRegistry.pmAI model metadata and management
Tool Error GuidanceToolErrorGuidance.pmContextual error recovery hints
Error ContextErrorContext.pmError taxonomy and structured error context
Message ValidatorAPI/MessageValidator.pmValidate and proactively trim messages for AI providers
Response HandlerAPI/ResponseHandler.pmParse and process AI provider responses
GitHub AuthGitHubAuth.pmGitHub OAuth authentication
GitHub Copilot Models APIGitHubCopilotModelsAPI.pmAccess GitHub Copilot models
Performance MonitorPerformanceMonitor.pmTrack timing metrics
Rate LimiterRateLimiter.pmAPI rate limit tracking and enforcement
Plugin ManagerPluginManager.pmPlugin system management
DefaultsDefaults.pmDefault configuration values
LoggerLogger.pmDebug and trace output

How it works:

  1. APIManager connects to AI provider (GitHub Copilot, OpenAI, Google, OpenRouter, MiniMax, Z.AI, Ollama Cloud, etc.)
  2. 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
  3. PromptManager provides system prompt + custom instructions
  4. ToolExecutor invokes selected tools
  5. Results processed and returned

3. Tool System

Files: lib/CLIO/Tools/

ToolFileOperations
File OperationsFileOperations.pmread, write, search, create, delete, rename, etc.
Version ControlVersionControl.pmgit status, log, diff, commit, branch, push, pull, blame, stash, tag, worktree
TerminalTerminalOperations.pmexec - run shell commands safely (fork+process group, ESC-interruptible)
MemoryMemoryOperations.pmstore, retrieve, search, list, delete
TodoTodoList.pmcreate, update, complete, list, track tasks
Code IntelligenceCodeIntelligence.pmlist_usages, search_history
WebWebOperations.pmfetch_url, search_web
InteractInteract.pmrequest_input - checkpoint prompts
Sub-Agent OperationsSubAgentOperations.pmSpawn and manage parallel agents
Remote ExecutionRemoteExecution.pmExecute AI tasks on remote systems
Apply PatchApplyPatch.pmApply lightweight diff patches
MCP BridgeMCPBridge.pmBridge to MCP tool servers
Base ToolTool.pmAbstract base class for all tools
RegistryRegistry.pmTool 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/

ComponentFilePurpose
Session ManagerManager.pmCreate/load/resume sessions
Session StateState.pmConversation history, metadata
Todo StoreTodoStore.pmPersist todos across sessions
Tool Result StoreToolResultStore.pmCache tool results for large output
File VaultFileVault.pmTargeted file backup for undo/revert
Session ExportExport.pmExport sessions to self-contained HTML
Session LockLock.pmLock files to prevent concurrent access

How it works:

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

5. Memory System

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

ComponentFilePurpose
Short-TermShortTerm.pmSession context (sliding window)
Long-TermLongTerm.pmProject-level knowledge (.clio/ltm.json)
YaRNYaRN.pmConversation archival and compression
Token EstimatorTokenEstimator.pmToken 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/

ComponentFilePurpose
AnalyzerAnalyzer.pmScan session history for personality patterns
ManagerManager.pmLoad/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/

ComponentFilePurpose
Tree-sitterTreeSitter.pmParse code into AST

How it works:

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

7. Security

Files: lib/CLIO/Security/

ComponentFilePurpose
AuthAuth.pmGitHub OAuth, token storage
AuthzAuthz.pmCheck file access permissions
Path AuthorizerPathAuthorizer.pmControl file access
Secret RedactorSecretRedactor.pmPII and secret redaction from tool output
Command AnalyzerCommandAnalyzer.pmIntent-based command risk classification
Invisible Char FilterInvisibleCharFilter.pmDetect and strip invisible Unicode characters from user input

How it works:

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

8. Logging & Monitoring

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

ComponentFilePurpose
LoggerCore/Logger.pmDebug/trace output
Tool LoggerLogging/ToolLogger.pmLog tool operations
Performance MonitorCore/PerformanceMonitor.pmTrack timing
Process StatsLogging/ProcessStats.pmRSS/VSZ memory and resource tracking

15. Utilities

Files: lib/CLIO/Util/

ComponentFilePurpose
Path ResolverPathResolver.pmTilde expansion, path canonicalization
Text SanitizerTextSanitizer.pmSanitize text for safe display
JSONJSON.pmOpportunistic fast JSON (JSON::XS > Cpanel::JSON::XS > JSON::PP)
JSON RepairJSONRepair.pmRepair malformed JSON from AI responses
Git IgnoreGitIgnore.pmAuto-manage .clio/ entries in .gitignore
Input HelpersInputHelpers.pmTerminal input utilities
XML Tool ParserAnthropicXMLParser.pmParse XML-format tool calls from AI responses
YAMLYAML.pmLightweight 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

ComponentFilePurpose
BrokerBroker.pmUnix socket coordination server (messaging, locks, status relay)
ClientClient.pmBroker connection API
SubAgentSubAgent.pmProcess spawning and lifecycle management
HostProtocolHostProtocol.pmOSC event emission and broker relay for agent status

How it works:

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

11. Terminal Multiplexer Integration

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

ComponentFilePurpose
MultiplexerMultiplexer.pmDetection, driver abstraction, pane lifecycle management
Tmux DriverMultiplexer/Tmux.pmtmux pane operations via CLI (split-window, kill-pane)
Screen DriverMultiplexer/Screen.pmGNU Screen window operations via CLI (-X commands)
Zellij DriverMultiplexer/Zellij.pmZellij pane operations via action commands
Mux CommandsCommands/Mux.pm/mux slash commands (status, agent, close, auto)

How it works:

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

12. AI Providers

Files: lib/CLIO/Providers/

ComponentFilePurpose
Provider RegistryProviders.pmAI provider registration and lookup
BaseBase.pmAbstract base class for providers
AnthropicAnthropic.pmNative Anthropic Messages API
GoogleGoogle.pmNative Google Gemini API

How it works:

  • Base.pm defines the provider interface
  • Each provider implements native API communication
  • Providers register via Providers.pm for runtime selection
  • GitHub Copilot and OpenAI-compatible providers are handled directly by APIManager

13. OpenSpec Integration

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

ComponentFilePurpose
Spec ManagerSpec/Manager.pmSpec and change lifecycle management
YAML ParserUtil/YAML.pmLightweight YAML parser for OpenSpec config/schema files
Spec CommandsUI/Commands/Spec.pm/spec slash command handler

How it works:

  1. User runs /spec init to create openspec/ directory structure
  2. /spec propose <name> creates a change and sends structured prompt to AI
  3. AI generates planning artifacts (proposal, specs, design, tasks) via file_operations
  4. User implements against tasks.md using normal CLIO workflow
  5. /spec archive moves completed change to archive
  6. PromptManager auto-injects spec context into system prompt when openspec/ exists
  7. 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

  1. Modularity - Each component has a single, well-defined responsibility
  2. Extensibility - Tools and protocols can be added without modifying core
  3. Separation of Concerns - UI, AI, tools, and storage are independent layers
  4. 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

  1. Read: docs/CUSTOM_INSTRUCTIONS.md - How projects customize CLIO
  2. Read: docs/DEVELOPER_GUIDE.md - Development guide and conventions
  3. 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

  1. Implement in appropriate module
  2. Add tests in tests/
  3. Run perl -I./lib -c on all changed modules
  4. Test with ./clio --debug --input "test" --exit
  5. 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.