cloi is a terminal-oriented, local-first coding agent powered by Ollama. You talk to it, and it reads, searches, writes, and edits files in your workspace and runs commands to answer you. Everything runs on your machine—no API key required, and data never leaves your machine.
How to run it On first run it automatically executes cloi setup and picks a suitable model based on your hardware. Requirements: Ollama, Node 22.5+, and a model that supports tool calling.
Models are selected based on measured performance on the machine setup reads VRAM, RAM, and core count, and proposes two models for different constraints: a primary model that fits in VRAM and runs every step, and a fallback model that runs infrequently and only needs to fit in RAM. It then loads the primary model and asks Ollama where it actually lands, stepping down level by level if the prediction is wrong. Tier represents measured capability, not model size—a 4B model scoring 63% will rank above an 8B model scoring 46% (see docs/models.md).
Escalation mechanism when a turn fails Six signals indicate that a turn is stalled: repeated identical calls, consecutive tool failures, unusable calls, and steps that only narrate but never execute. Any of these signals hands the conversation to a larger model, which inherits everything already attempted. Routing is based on observed failures, not on guessing the task type in advance.
Answers are validated before you see them Assertions about whether a file contains something are adjudicated by the file itself. Line references are checked against line counts, quotations are checked against what was actually read, and "does not exist" conclusions are checked against the proportion of files the agent actually opened. This process does not call a model—the workspace itself already knows the answer. Model-based secondary review runs only after escalation, because that is exactly when the answer is worth doubting.
Nameable, reusable results Every substantive result is stored in full under a name taken from its arguments (such as stats_js, grep_completionrate, npm_test): recall can read it back in full, slice it, or search it. Stored copies remain complete even if the content shown to the model is truncated, and they outlive the conversation that produced them.
Python, and these results are already in scope An interpreter that runs throughout the session, in which every stored result is a variable and every tool is a callable function. A single cell can drive loops that would otherwise require one tool call per turn. Variables, imports, and helper functions persist across sessions. NeedPermissioned tools still ask for permission, so approving one cell is not the same as approving everything it can reach.
History is summarized, not silently dropped Ollama will not refuse an overly long prompt—it drops the earliest tokens, so the agent forgets what it was asked while behaving as if it still remembers. cloi instead summarizes the earlier half, cutting only where a tool result is inseparable from its call. Nothing is deleted: the summary records how far it covered, and the earlier messages are simply no longer sent.
Guardrails on what can be reached Paths are confined to the workspace. Writes, edits, and shell commands ask first, with three options: once only, always allow this tool, no. Child processes run with a sanitized environment, so commands cannot read your API keys; any secret that enters the output is redacted before being stored or sent.
In-session commands: /model, /tools, /plan, /usage, /sessions, /help. Ctrl+C interrupts a turn, Ctrl+D exits.
Documentation docs/models.md: how models are chosen, and the benchmarks behind the catalog. docs/internals.md: the loop, guardrails, validation, and the changes that measurement brought. docs/configuration.md: every setting and its default.
Limitations Ollama only. The provider sits behind one module, but beyond that no other service is integrated. No subagents, no MCP, no network access. For every model that fits in 8 GB, difficult cross-file debugging is beyond its capability ceiling—0/12 in the benchmarks, and that is the honest limit. License: MIT, see LICENSE.
