Cloi CLI: Local debugging agent that runs in your terminal

Local debugging agent that runs in your terminal

Cloi is a local, context-aware agent designed to streamline your debugging process. Operating entirely on your machine, it ensures that your code and data remain private and secure. With your permission, Cloi can analyze errors and apply fixes directly to your codebase.

Disclaimer: Cloi is an experimental project under beta development. It may contain bugs, and we recommend reviewing all changes before accepting agentic suggestions. That said, help us improve Cloi by filing issues or submitting PRs, see down below for more info.

Install globally:

Works with your existing Ollama models - zero setup, no API key required.

Navigate to your project directory and call Cloi when you run into an error.

Cloi is built for developers who live in the terminal and value privacy:

• On-Device/API Models – Choose between local Ollama models or Anthropic models (Claude Sonnet 4, Opus).
• Smart Context Retrieval – RAG system automatically finds relevant code files for better debugging.
• Safe Changes – Review all diffs before applying. Full control to accept or reject.
• Zero Setup – RAG models, indexing, and dependencies install automatically on first use.
• Free to Use – Extensible architecture. Fork, contribute, and customize to your needs.

Want to use Claude Sonnet 4 or Opus-4 instead of local models? Just add your API key:

Add this line to your ~/.zshrc file, then restart your terminal. Claude models will automatically appear in /model selection - zero additional setup required.

Cloi uses Retrieval-Augmented Generation to find relevant code files across your entire codebase when debugging. RAG combines CodeBERT (500 MB) embeddings with BM25 keyword search to identify files related to your error. Auto-installs on first /debug run.

Enable automatic error capture without making cloi re-run commands. Run /logging to modify your .zshrc, then restart your terminal. All output gets saved to ~/.cloi/terminal_output.log with auto-rotation (1 MB). (zsh only) Note: Currently only tested with zsh shell.

We welcome contributions from the community! By contributing to this project, you agree to the following guidelines:

• Scope: Contributions should align with the project's goals of providing a secure, local AI debugging assistant
• License: All contributions must be licensed under the GNU General Public License v3.0 (GPL-3.0)
• Copyleft: Any derivative works must also be distributed under the GPL-3.0 license

For more detailed information on contributing, please refer to the CONTRIBUTING.md file.

• Feature: Integrated Retrieval-Augmented Generation (RAG) for enhanced debugging
  • Hybrid Search Algorithm: Combines BM25 keyword matching with semantic vector search for optimal code retrieval
  • FAISS Vector Store: Uses Facebook's FAISS library for efficient similarity search across code embeddings
  • CodeBERT Embeddings: Leverages Hugging Face's microsoft/codebert-base model for code understanding
  • Automatic Setup: Downloads CodeBERT model (~500MB) and installs Python dependencies automatically on first /debug run
  • Background Service: CodeBERT runs as local HTTP service (port 3090) for fast embedding generation

• Feature: Added automatic terminal output logging (zsh only)
  • Logs terminal output to ~/.terminal_output.log for better error analysis
  • Requires explicit user permission before modifying .zshrc
  • Configure with /logging command

• Feature: Included new phi4-reasoning:plus,qwen3, and ALL your locally installed Ollama models into boxen /model for easy access.

• Bug Fix: Resolved dependency issue in package.json
  • Updated Ollama dependency from deprecated version 0.1.1 to 0.5.15 which resolved ollama.chat API endpoints
  • Thank you @kingkongfft and @undecomposed for alerting by submitting this issue.

• Feature: Integrated structured outputs from Ollama's latest API
  • Creates more robust patches with JSON-based formatting
  • Falls back to traditional LLM calls if the structured API isn't available
• Feature: Implemented CLI model selection via --model flag
  • Specify your preferred Ollama model right from the command line
  • Credit to @canadaduane for the insightful suggestion!
• UI Enhancement: The /model command now displays ALL you locally installed Ollama models
• Refactor: Internal architecture adjustments to maintain conceptual integrity
  • Migrated history.js to the utils directory where it semantically belongs
  • Repositioned traceback.js to core since it's foundational to the debugging pipeline
• Improvements: Purged lingering references to our project's original name "FigAI" and cleaned the CLI --help interface