Cloi – Local Debugging Agent in Your Terminal

TL;DR

TL;DR: Cloi is a free, open-source terminal-based debugging agent that uses local Ollama models or Claude to analyze errors, retrieve relevant code context via RAG, and apply fixes — all without sending your code anywhere.

Source and Accuracy Notes

This section is MANDATORY. All links verified from actual source, not guessed.

• Project page: github.com/cloi-ai/cloi
• NPM package: npmjs.com/package/@cloi-ai/cloi
• License: GPL-3.0 (verified via README badge)
• HN launch thread: news.ycombinator.com/item?id=43918405
• Source last checked: 2026-07-31 (README main branch)

What Is Cloi?

Cloi is a local, context-aware debugging agent designed to run inside your terminal. Unlike cloud-based AI coding assistants, Cloi processes everything on-device — your code and data never leave your machine. It integrates with local Ollama models (including Phi-4 at about 9.1GB) or optionally with Anthropic’s Claude Sonnet 4 and Opus if you provide an API key.

The tool works entirely through an interactive CLI. When you hit an error, you run cloi in the affected project directory. Cloi automatically indexes your codebase using a hybrid RAG system (CodeBERT embeddings + BM25 keyword search backed by FAISS), retrieves the most relevant files for the error context, and presents AI-generated fix suggestions that you can review and apply at your discretion.

Setup Workflow

Step 1: Install

npm install -g @cloi-ai/cloi

Requires Node.js 14+ and Python 3.6+. Ollama is installed automatically on first use if not already present.

Step 2: Run in a Project Directory

cd your-project/
cloi

This drops you into Cloi’s interactive REPL. The first run downloads the RAG dependencies (CodeBERT model, ~500MB) and sets up the vector index automatically.

Step 3: Debug an Error

/debug

Cloi analyzes the current error in context, retrieves relevant files from your codebase, and proposes a fix. You review the diff before applying — nothing changes without your approval.

Step 4: Switch Models (Optional)

/model

Choose between your locally running Ollama models or a Claude API key. To use Claude, set:

export ANTHROPIC_API_KEY="sk-ant-..."
# Add to ~/.zshrc for persistence

Step 5: Re-index After Major Changes

/index

Re-runs the RAG pipeline if your codebase has changed significantly since the last index.

System Requirements

| Component | Requirement | |---|---| | Memory | 8GB RAM minimum, 16GB+ recommended | | Storage | 10GB+ free (Phi-4 model: ~9.1GB) | | OS | macOS 11.0+ (tested on M2/M3) | | Shell | Zsh (recommended), Fish, Bash (limited testing) | | Runtime | Node.js 14+, Python 3.6+ |

Interactive Commands

| Command | Description | |---|---| | /debug | Auto-fix errors using AI models | | /index | Re-index codebase for improved accuracy | | /model | Switch between Ollama and Claude | | /logging | Set up automatic error logging (zsh only) | | /help | Show all available commands |

How the RAG System Works

On first /debug call, Cloi sets up a local Retrieval-Augmented Generation pipeline:

1. CodeBERT embeddings (~500MB, auto-downloaded) encode your source files into semantic vectors
2. FAISS (Facebook’s vector similarity search library) indexes those embeddings for fast retrieval
3. BM25 keyword search provides complementary keyword-matched results
4. Both signals are combined to retrieve the most relevant code files for the error at hand

The embedding service runs locally on port 3090 as a background HTTP service.

Security Notes

• On-device processing — code never leaves your machine unless you explicitly use Claude with an API key
• No telemetry — Cloi does not phone home; the RAG pipeline and model inference run locally
• Review-before-apply — all diffs require explicit user approval before being written to disk
• Disclaimer — Cloi is marked beta; review changes before accepting agentic suggestions

FAQ

Q: Does Cloi work with Windows? A: The primary development and testing targets macOS (M2/M3). Linux may work but is not officially tested. Windows is not currently supported.

Q: What Ollama models are recommended? A: The README specifically calls out Phi-4 (~9.1GB) as the default model. Any Ollama-compatible model should work, but smaller models like Phi-4 or Mistral are practical for local hardware.

Q: How is this different from asking an AI in a chat window? A: Cloi combines RAG over your actual codebase with the error context, so fixes are grounded in your real code — not generic patterns. It also integrates directly into your terminal workflow without switching contexts.

Q: Is this free to use? A: Yes. Cloi is open-source under GPL-3.0 and free to install via npm. If you use Ollama models locally, there are no API costs. Using Claude requires your own API key.

Conclusion

Cloi fills a specific niche: developers who want AI-assisted debugging without leaving the terminal or sending code to a third-party service. The built-in RAG pipeline, automatic model setup, and diff-review workflow make it a practical option for local-first development on macOS. The beta label is honest — it’s experimental software — but the core workflow (index, debug, review, apply) is solid.

If you already live in the terminal and prefer Ollama or Claude for local inference, Cloi is worth a try. Install it with one command and call it when you hit a wall.