Cloi is a local, context-aware debugging agent that runs entirely in your terminal. It analyzes errors, retrieves the relevant slices of your codebase, and proposes diffs you can accept or reject — without your code ever leaving your machine.
The idea
Most "AI debuggers" today are wrappers around hosted models. They're convenient, but they ship your stack traces, source files, and sometimes credentials to a remote inference endpoint. For anyone working on proprietary code, regulated data, or research with private datasets, that's a non-starter. Cloi was built around a single constraint: by default, the model and the code never leave your laptop.
The second observation: debugging is overwhelmingly a context problem, not a reasoning problem. Once a capable model has the failing command, the relevant code, and the right slice of the codebase, it usually gets the fix right on the first try. Cloi's job is to assemble that context automatically.
How it works
You install it once with npm install -g @cloi-ai/cloi and invoke it inside any project that just errored out:
cloiFrom there, Cloi exposes a handful of slash commands:
/debug— auto-fix the most recent error,/index— (re)index the current codebase,/model— switch between local Ollama models and Anthropic Claude (Sonnet 4, Opus),/logging— enable a zsh hook so cloi can read past command output without re-running anything,/help— show the command list.
RAG over your code
When you run /debug, Cloi runs a hybrid retrieval pass over your repo before talking to the model:
- Semantic search with CodeBERT embeddings (≈500 MB), served by a local HTTP service on port 3090.
- Keyword search with BM25, to catch things embedding similarity misses (exact identifiers, error strings, etc.).
- FAISS as the vector store, so similarity search stays fast as codebases grow.
The retrieval setup is downloaded and installed automatically the first time you run /debug — no separate setup step.
Local by default, cloud when you want it
Out of the box, Cloi talks to whatever Ollama models you already have. If you'd rather use a frontier model, dropping ANTHROPIC_API_KEY into ~/.zshrc exposes Claude Sonnet 4 and Opus through the same /model picker — no additional config.
Terminal logging
The /logging command (zsh only, for now) installs a shell hook that streams terminal output to ~/.cloi/terminal_output.log with auto-rotation at 1 MB. The point is to let Cloi reason about errors after they happen — without having to re-run a command that may have side effects.
Design decisions worth flagging
- Diffs, not rewrites. The agent always proposes a patch, never replaces a whole file. Blast radius stays small and reviewable.
- One model per session. No router, no agent-of-agents. Whichever model you pick handles every step, and you always know who you're talking to.
- Shell-native UX. No web UI, no electron app — if you're in a terminal when the error happens, you stay there.
"The best debugger is the one that's already running when the bug happens."
Status & what's next
Cloi is in beta and currently most tested on macOS (Big Sur+) with Apple Silicon (M2 / M3). Node 14+ and Python 3.6+ are required. Zsh is the primary supported shell, with fish and bash working in limited testing.
The active areas of work are calibration (making /debug silent and confident enough to run unattended), better test-runner integration (so a failing pytest or jest can trigger a fix-and-verify loop), and broader shell support.
Cloi is GPL-3.0 licensed and accepting contributions at github.com/gabrielchasukjin/cloi. The fastest way to try it is:
npm install -g @cloi-ai/cloi
cd your-project-that-just-errored
cloi