Tools Reference

Complete guide to CLIO's built-in tools

CLIO provides a comprehensive set of tools for interacting with your system. Each tool is operation-based with multiple capabilities.

file_operations

Purpose: File and directory management

Operations:

• read_file - Read file content with optional line ranges
• write_file - Overwrite existing file
• create_file - Create new file with content
• append_file - Append content to file
• replace_string - Find and replace text
• multi_replace_string - Batch replace operations across multiple files
• insert_at_line - Insert content at specific line
• delete_file - Delete file or directory
• rename_file - Rename or move file
• create_directory - Create directory with parents
• list_dir - List directory contents (optionally recursive)
• file_exists - Check if file or directory exists
• get_file_info - Get file metadata (size, type, modified time)
• file_search - Find files matching glob pattern
• grep_search - Search file contents with regex
• semantic_search - Hybrid keyword and symbol search across codebase

version_control

Purpose: Git version control operations

Operations:

• status - Repository status and changes
• diff - Show differences between commits/branches
• log - Git commit history
• commit - Create commits
• branch - Branch operations (list, create, switch, delete)
• push - Push changes to remote
• pull - Pull changes from remote
• stash - Stash operations (save, list, apply, drop)
• tag - Tag operations (list, create, delete)
• blame - Show file annotation
• worktree - Worktree operations (list, add, remove, prune, merge, pr)

terminal_operations

Purpose: Execute shell commands safely with validation and timeout

Operations:

• exec - Run command and capture output
• validate - Check command safety before execution

Commands are classified by intent (network access, credential reading, system destruction) and confirmed with the user based on risk level.

memory_operations

Purpose: Store and recall information across sessions

Session Memory:

• store - Store key-value pairs
• retrieve - Get stored information
• search - Find memories by keyword
• list - List all memory keys
• delete - Remove stored memory

Long-Term Memory (LTM):

• recall_sessions - Search previous session history with keyword extraction and ranked results
• add_discovery - Store discovered facts with confidence levels
• add_solution - Store problem-solution pairs with example file paths
• add_pattern - Store code/workflow patterns
• update_ltm - Update existing LTM entries (correct outdated information)
• prune_ltm - Remove old/low-confidence entries
• ltm_stats - Get LTM statistics

todo_operations

Purpose: Manage structured task lists with progress tracking

Operations:

• read - Get current todo list
• write - Create/replace entire list
• update - Change status of existing todos
• add - Append new todos

web_operations

Purpose: Fetch URLs and search the web

Operations:

• fetch_url - Fetch content from URL
• search_web - Web search (SerpAPI, Brave Search, or DuckDuckGo fallback)

code_intelligence

Purpose: Code analysis, symbol search, and project history

Operations:

• list_usages - Find all references to a symbol across the codebase
• search_history - Semantic search through git commit messages (find past work by natural language query)

user_collaboration

Purpose: Request user input during tasks

Operations:

• request_input - Ask for clarification or decisions

This tool implements checkpoint discipline - the AI pauses execution and waits for human input before proceeding. It's free (doesn't consume an API request) and blocks until the user responds.

apply_patch

Purpose: Apply diff-based patches to create, modify, or delete files

Uses a lightweight diff format that's more efficient than full file rewrites. Each patch can contain multiple file operations with context-based anchoring for precise edits.

Supported operations within a patch:

• Add new files
• Update existing files with contextual anchors
• Delete files

remote_execution

Purpose: Execute CLIO tasks on remote systems via SSH

Operations:

• execute_remote - Run CLIO task on remote system
• execute_parallel - Run task on multiple devices simultaneously
• prepare_remote - Pre-stage CLIO without executing
• cleanup_remote - Remove CLIO from remote
• check_remote - Verify remote connectivity
• transfer_files - Copy files to remote
• retrieve_files - Fetch files from remote

Copies the local CLIO installation to remote systems via rsync, ensuring version consistency. API keys are passed via environment variables and never persisted on remote systems.

agent_operations

Purpose: Spawn and manage sub-agents for parallel work

Operations:

• spawn - Create a new sub-agent with a specific task
• list - List all active sub-agents and their status
• status - Get detailed status of a specific agent
• inbox - Check for unread messages from sub-agents
• acknowledge - Mark messages as read
• history - View all messages from the session
• send - Send guidance to a specific agent
• broadcast - Send message to all agents
• kill - Terminate a specific agent
• killall - Terminate all agents

Sub-agents run as separate processes and communicate with the parent agent via a message-passing system. The parent acts as a manager - spawning tasks, monitoring progress, and validating results.

Tool Transparency

When CLIO uses tools, you see real-time notifications showing what's happening:

SYSTEM: [file_operations] - Reading ./config.json (254 lines)
SYSTEM: [version_control] - git status
SYSTEM: [terminal_operations] - Executing: npm install

All tool calls are visible, so you always know what CLIO is doing on your system.

Next Steps

• Workflows - Learn common usage patterns
• Remote Execution - Use CLIO on remote systems
• Multi-Agent - Parallel AI coordination