{"id":40398887,"url":"https://github.com/syntheticautonomicmind/clio","last_synced_at":"2026-04-18T21:07:45.055Z","repository":{"id":333661876,"uuid":"1136941035","full_name":"SyntheticAutonomicMind/CLIO","owner":"SyntheticAutonomicMind","description":"Command Line Intelligence Orchestrator","archived":false,"fork":false,"pushed_at":"2026-02-19T02:13:07.000Z","size":5815,"stargazers_count":34,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-19T06:55:32.907Z","etag":null,"topics":["agentic-ai-development","ai","apple","artificial-intelligence","autonomous-agents","chat","developer-tools","development","development-environment","github-copilot","linux","macos","open-source","openai","oss","pair-programming","perl","wsl2"],"latest_commit_sha":null,"homepage":"","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SyntheticAutonomicMind.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"patreon":"fewtarius"}},"created_at":"2026-01-18T16:28:55.000Z","updated_at":"2026-02-19T02:13:09.000Z","dependencies_parsed_at":"2026-02-19T03:05:58.521Z","dependency_job_id":null,"html_url":"https://github.com/SyntheticAutonomicMind/CLIO","commit_stats":null,"previous_names":["syntheticautonomicmind/clio"],"tags_count":103,"template":false,"template_full_name":null,"purl":"pkg:github/SyntheticAutonomicMind/CLIO","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SyntheticAutonomicMind%2FCLIO","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SyntheticAutonomicMind%2FCLIO/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SyntheticAutonomicMind%2FCLIO/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SyntheticAutonomicMind%2FCLIO/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SyntheticAutonomicMind","download_url":"https://codeload.github.com/SyntheticAutonomicMind/CLIO/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SyntheticAutonomicMind%2FCLIO/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29704420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-22T03:17:42.375Z","status":"ssl_error","status_checked_at":"2026-02-22T03:17:31.622Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai-development","ai","apple","artificial-intelligence","autonomous-agents","chat","developer-tools","development","development-environment","github-copilot","linux","macos","open-source","openai","oss","pair-programming","perl","wsl2"],"created_at":"2026-01-20T13:08:30.557Z","updated_at":"2026-04-13T01:41:37.174Z","avatar_url":"https://github.com/SyntheticAutonomicMind.png","language":"Perl","funding_links":["https://patreon.com/fewtarius"],"categories":[],"sub_categories":[],"readme":"# CLIO - Command Line Intelligence Orchestrator\n\n**A terminal-native AI coding tool that can read your code, edit files, run commands, use git, and work through tasks with you.**\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## What CLIO Is\n\nCLIO is for people who already work in a shell and want AI help without leaving that workflow.\n\nIt is not just chat in a terminal, and it is not just autocomplete. CLIO can inspect a real repository, use real tools, make changes, run commands, check git state, and keep working through a task with you in the loop.\n\nWhen you give it a task, CLIO can:\n\n- read files and search your codebase\n- edit files and apply patches\n- run shell commands, tests, and linters\n- inspect and manage git state\n- pause for approval at decision points\n- keep context across sessions\n- work on remote systems over SSH\n- coordinate parallel sub-agents for larger tasks\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## How CLIO Works\n\nThe basic loop is simple:\n\n1. **You describe the task**\n2. **CLIO investigates** by reading code, searching files, or checking git state\n3. **CLIO proposes a plan** when your input matters\n4. **After approval, CLIO does the work** - edits files, runs commands, and verifies results\n5. **CLIO reports back** and asks before committing significant changes\n\nThat makes CLIO closer to pair programming than prompt-and-response chat.\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## Why People Use CLIO\n\n- **Terminal-native:** works in local shells, SSH sessions, tmux, GNU Screen, Zellij, containers, and headless servers\n- **Tool-powered:** uses files, git, terminal, web, memory, remote execution, and other tools instead of pretending\n- **Portable:** pure Perl with standard core modules - no CPAN, npm, or pip\n- **Persistent:** resumes sessions with history and project memory intact\n- **Private and controllable:** local-first workflow with secret redaction, path authorization, command analysis, and sandboxing\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## Why I Built CLIO\n\nI built CLIO for myself. As someone who prefers working in the terminal, I wanted an AI assistant that felt native to my workflow. One that respected my privacy, worked anywhere Perl runs, and gave me full control over my code and tools. I couldn't find anything that met those needs, so I created CLIO. Like most of my work, I build tools for myself first and release them as open source in the hope that they're useful to other people too.\n\nStarting with version 20260119.1, CLIO has been building itself. All of my development is now done through pair programming with AI agents using CLIO.\n\nCLIO is part of the [Synthetic Autonomic Mind (SAM)](https://github.com/SyntheticAutonomicMind) organization, which is dedicated to building user-first, privacy-respecting AI tools. If you value transparency, portability, and the power of the command line, CLIO is for you.\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## What Makes CLIO Different\n\n- **Terminal-First Experience:** Runs entirely in your terminal with professional markdown rendering, color themes, and streaming output\n- **Light \u0026 Nimble:** ~50 MB at startup, grows moderately with session activity. Works on everything from a ClockworkPi uConsole R01 to an M4-powered Mac.\n- **Portable \u0026 Minimal:** Works with standard Unix tools (git, curl, etc.) - no heavy frameworks or package managers required. See [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md) for details.\n- **Actually Autonomous:** CLIO doesn't just suggest code - it reads, writes, tests, commits, and iterates. Give it a task and it works through it end-to-end.\n- **Tool-Powered:** Real file, git, and terminal operations with real-time action descriptions\n- **Privacy \u0026 Control:** Your code stays on your machine - only minimum context sent to AI providers. Built-in secret redaction catches API keys, tokens, PII, and credentials before they reach the AI.\n- **Persistent Sessions:** Pick up exactly where you left off with full conversation history\n- **Scriptable \u0026 Extensible:** Fits into your workflow, not the other way around\n- **Remote Execution:** SSH into any machine, deploy CLIO, run an AI task, and get results back - across your entire fleet in parallel\n- **Multi-Agent Coordination:** Spawn parallel agents with file locks, git locks, and coordinated API rate limiting for safe collaboration\n- **Multiplexer Integration:** When running inside tmux, GNU Screen, or Zellij, sub-agent output streams live in separate panes\n- **Long-Term Memory:** Discoveries, solutions, and patterns persist across your project history and are automatically injected into every conversation\n- **User Profile:** CLIO learns your communication style, preferences, and working patterns from session history and personalizes every interaction\n- **Interrupt Anytime:** Press any key to stop the agent mid-task. CLIO pauses, asks what you need, and adapts - like tapping your pair programmer on the shoulder\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## Core Features\n\n| Category | Capabilities |\n|----------|--------------|\n| **Files** | Read, write, search, edit, manage files |\n| **Git** | Status, diff, commit, branch, push, pull, stash, tag |\n| **Terminal** | Execute commands and scripts directly |\n| **Remote** | Run AI tasks on remote systems via SSH |\n| **Multi-Agent** | Spawn parallel agents for complex work |\n| **Multiplexer** | Live agent output panes via tmux, GNU Screen, or Zellij |\n| **Memory** | Store and recall information across sessions |\n| **Profile** | Learns your working style and personalizes collaboration |\n| **Todos** | Manage tasks within your workflow |\n| **Web** | Fetch and analyze web content |\n| **MCP** | Connect to external tool servers via [Model Context Protocol](docs/MCP.md) |\n| **AI Providers** | GitHub Copilot, OpenAI, Google Gemini, DeepSeek, OpenRouter, MiniMax, llama.cpp, LM Studio, SAM |\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## Screenshots\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003ch3\u003eCLIO's Simple Interface\u003c/h3\u003e\n      \u003cimg src=\".images/clio1.png\"/\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003ch3\u003eClaude Haiku describing CLIO\u003c/h3\u003e\n      \u003cimg src=\".images/clio2.png\"/\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## Real-World Performance\n\nCLIO is built to run for hours without breaking a sweat. These are stats from real development sessions:\n\n```\nSession 1 - Active development (1h, 244 turns):\n  Baseline: 46 MB | RSS: 73 MB | Tool calls: 244\n\nSession 2 - Heavy multi-hour session:\n  Typical range: 50-100 MB depending on context size\n```\n\nCLIO starts at ~50 MB and grows gradually as session context accumulates. Multi-hour sessions with hundreds of tool calls typically stay under 100 MB. No memory leaks, no degradation, no restart needed.\n\n### Billing Awareness\n\nCLIO tracks your API usage in real time with `/usage`:\n\n```\nPremium Quota\n──────────────────────────────────────────────────────────────\n  Status:                   891 used of 1500 (59.3%)\n  Resets:                   2026-03-01\nToken Usage\n──────────────────────────────────────────────────────────────\n  Total Tokens:             13,428,981\n    Prompt:                 13,422,054 tokens\n    Completion:             6,927 tokens\n```\n\nNo surprises at the end of the month. See your quota consumption, billing multipliers for premium models, per-request token counts, and reset dates. CLIO warns you when premium models cost extra so you can make informed choices.\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## Quick Start\n\n### Check Dependencies\n\n```bash\n./check-deps  # Verify all required tools are installed\n```\n\nCLIO requires standard Unix tools (git, curl, perl 5.32+, etc.). See [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md) for details.\n\n### Install\n\n**Homebrew (macOS)**\n```bash\nbrew tap SyntheticAutonomicMind/homebrew-SAM\nbrew install clio\n```\n\n**Docker (Any Platform)**\n```bash\ndocker run -it --rm \\\n    -v \"$(pwd)\":/workspace \\\n    -v clio-auth:/root/.clio \\\n    -w /workspace \\\n    ghcr.io/syntheticautonomicmind/clio:latest \\\n    --new\n```\n\n**Manual**\n```bash\ngit clone https://github.com/SyntheticAutonomicMind/CLIO.git\ncd CLIO \u0026\u0026 sudo ./install.sh\n```\n\nFor detailed options, see [docs/INSTALLATION.md](docs/INSTALLATION.md).\n\n### Configure AI Provider\n\n**GitHub Copilot** (Recommended - no config needed)\n```bash\n./clio\n: /api login\n# Follow browser prompts to authorize\n```\n\n**Other Providers**\n```bash\n./clio\n: /api set provider openai\n: /api set key YOUR_API_KEY\n: /config save\n```\n\n### First Prompt\n\nStart with something grounded in a real repository:\n\n```text\nRead this project and tell me how configuration is loaded.\n```\n\nOr give CLIO a real bug to investigate:\n\n```text\nFind the bug causing the login endpoint to return 500 when the session is expired.\n```\n\n### Start Using CLIO\n\n```bash\n./clio --new          # New conversation\n./clio --resume       # Resume last session\n./clio --debug        # Debug mode\n./clio --enable file_operations  # Restrict to specific tools\n./clio --disable web_operations  # Block specific tools\n```\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## Slash Commands (Quick Reference)\n\n| Command | Description |\n|---------|-------------|\n| `/help` | Show available commands |\n| `/api` | Configure AI providers and models |\n| `/config` | View/edit configuration |\n| `/session` | Session management |\n| `/file` | File operations |\n| `/git` | Git operations |\n| `/undo` | Revert AI changes from last turn |\n| `/memory` | Long-term memory system |\n| `/profile` | Build and manage user personality profile |\n| `/todo` | Task management |\n| `/agent` | Spawn and manage sub-agents |\n| `/mux` | Terminal multiplexer panes (tmux/screen/Zellij) |\n| `/mcp` | Model Context Protocol servers |\n| `/skill` | Custom skill system |\n| `/update` | Check for and install updates |\n| `/usage` | API billing and quota tracking |\n| `/stats` | Memory and performance stats |\n| `/device` | Remote device management |\n| `/theme` | Change color theme |\n| `/clear` | Clear screen |\n| `/exit` | Exit CLIO |\n\nFor complete command reference, see [docs/USER_GUIDE.md](docs/USER_GUIDE.md#slash-commands).\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## Example Usage\n\n```\nYou: Read the main config file and explain its structure\n\nCLIO: [Reading lib/CLIO/Core/Config.pm]\n\nThe Config module handles CLIO's configuration system. Key sections:\n- **Defaults**: Provider settings, model preferences\n- **Persistence**: JSON-based storage in ~/.clio/config.json\n- **Runtime overrides**: Environment variables and CLI flags\n\nYou: Fix the bug in the login function\n\nCLIO: [Reading lib/CLIO/Security/Auth.pm]\n      [Identified issue: token validation missing null check]\n      [Writing fix to lib/CLIO/Security/Auth.pm]\n      \nFixed the bug. The issue was...\n```\n\nFor more examples, see [docs/USER_GUIDE.md](docs/USER_GUIDE.md#usage-examples).\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## Requirements\n\n- **macOS 10.14+** or **Linux** (any modern distribution)\n- **Perl 5.32+** (included with most systems)\n- **Git** (for version control operations)\n- **ANSI-compatible terminal**\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [User Guide](docs/USER_GUIDE.md) | Complete usage guide with examples |\n| [Feature Guide](docs/FEATURES.md) | Every feature explained in detail |\n| [Installation](docs/INSTALLATION.md) | Getting started with CLIO |\n| [Providers](docs/PROVIDERS.md) | AI provider configuration guide |\n| [Dependencies](docs/DEPENDENCIES.md) | System requirements and verification |\n| [Sandbox Mode](docs/SANDBOX.md) | Security isolation options |\n| [Architecture](docs/ARCHITECTURE.md) | System design and internals |\n| [Memory Architecture](docs/MEMORY.md) | How CLIO remembers and learns across sessions |\n| [Developer Guide](docs/DEVELOPER_GUIDE.md) | Contributing and extending CLIO |\n| [Remote Execution](docs/REMOTE_EXECUTION.md) | Distributed AI workflows |\n| [Multi-Agent](docs/MULTI_AGENT_COORDINATION.md) | Parallel agent coordination |\n| [MCP Integration](docs/MCP.md) | Model Context Protocol support |\n| [Custom Instructions](docs/CUSTOM_INSTRUCTIONS.md) | Per-project AI customization |\n| [Automation](docs/AUTOMATION.md) | CLIO-helper daemon and CI/CD integration |\n| [Style Guide](docs/STYLE_GUIDE.md) | Color themes and customization |\n| [Performance](docs/PERFORMANCE.md) | Benchmarks and optimization |\n| [Context Management](docs/CONTEXT_MANAGEMENT.md) | How CLIO handles long sessions and context limits |\n| [Security](docs/SECURITY.md) | Security model and secret redaction |\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## Design Philosophy\n\nCLIO is built around these principles:\n\n1. **Terminal Native**: Your terminal is your IDE\n2. **Zero Dependencies**: Pure Perl - no CPAN, npm, or pip\n3. **Tool Transparency**: See every action as it happens\n4. **Local First**: Your code and data stay on your machine\n5. **Session Continuity**: Never lose context\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## Part of the Ecosystem\n\nCLIO is part of [Synthetic Autonomic Mind](https://github.com/SyntheticAutonomicMind) - a family of open source AI tools:\n\n- **[SAM](https://github.com/SyntheticAutonomicMind/SAM)** - Native macOS AI assistant with voice control, document analysis, and image generation\n- **[MIRA](https://github.com/SyntheticAutonomicMind/MIRA)** - Native graphical terminal for CLIO. Runs on macOS, Linux, and Windows.\n- **[ALICE](https://github.com/SyntheticAutonomicMind/ALICE)** - Local Stable Diffusion server with web interface and OpenAI-compatible API\n- **[SAM-Web](https://github.com/SyntheticAutonomicMind/SAM-web)** - Access SAM from iPad, iPhone, or any browser\n\nCLIO can use SAM as an AI provider. All three tools share the same commitment to privacy and local-first operation.\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## Spread the Word\n\nCLIO is a small open source project with no marketing budget. If it's been useful to you, the best way to help is to tell someone about it - a blog post, a tweet, a recommendation to a colleague, or a star on GitHub. Word of mouth is how projects like this grow.\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## Contributing\n\nContributions welcome! See [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md) for guidelines.\n\n```bash\n# Fork and clone\ngit clone https://github.com/YOUR_USERNAME/CLIO.git\ncd CLIO\n\n# Run tests\nfind lib -name \"*.pm\" -exec perl -I./lib -c {} \\;\n\n# Submit PR\ngit push origin your-feature-branch\n```\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## License\n\nGPL-3.0 - See [LICENSE](LICENSE) for details.\n\n**Created by:** Andrew Wyatt (Fewtarius)  \n**Website:** [syntheticautonomicmind.org](https://www.syntheticautonomicmind.org)  \n**Repository:** [github.com/SyntheticAutonomicMind/CLIO](https://github.com/SyntheticAutonomicMind/CLIO)\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n## Support\n\n- **Discussions**: [Join the conversation](https://github.com/orgs/SyntheticAutonomicMind/discussions)\n- **GitHub Issues**: [Report bugs or request features](https://github.com/SyntheticAutonomicMind/CLIO/issues)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyntheticautonomicmind%2Fclio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyntheticautonomicmind%2Fclio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyntheticautonomicmind%2Fclio/lists"}