cloi 是一个面向终端的本地优先编码智能体，由 Ollama 驱动。你与它对话，它会在你的工作区中读取、搜索、写入、编辑文件并运行命令来回答你。所有内容都在你的机器上运行——无需 API 密钥，数据不会离开本机。
运行方式 首次会自动执行 cloi setup，并根据你的硬件挑选合适的模型。使用要求：Ollama、Node 22.5+，以及一个支持工具调用的模型。
模型按机器实测挑选 setup 会读取 VRAM、RAM 和核心数，并针对不同约束提出两个模型：一个能装进 VRAM、负责每一步运行的主模型，以及一个不常运行、只需装进 RAM 的备用模型。随后加载主模型并询问 Ollama 它的实际落点，如果预测有误则逐级下调。 层级（tier）代表实测能力，而非模型大小——一个得分 63% 的 4B 模型会排在一个得分 46% 的 8B 模型之上（见 docs/models.md）。
回合出错时的升级机制 六种信号表明一个回合陷入停滞：重复的相同调用、连续的工具失败、无法使用的调用、只叙述却从未执行的步骤。出现任一信号都会把对话交给更大的模型，后者继承此前已尝试的一切。路由依据的是观察到的失败，而不是事先猜测任务类型。
答案在你看到之前先被校验 关于文件是否包含某内容的断言由文件本身裁定。行引用会与行数核对，引文会与实际读取到的内容核对，而“不存在”的结论会与智能体实际打开的文件比例核对。此过程不调用模型——工作区本身已知道答案。基于模型的二次复查只在升级之后运行，因为那正是答案值得怀疑的时刻。
可命名、可复用的结果 每个实质性结果都会以一取自其参数的名字完整存储（如 stats_js、grep_completionrate、npm_test）：recall 可以整体读回、切片或搜索。存储副本即使展示给模型的内容被截断也保持完整，并且比产生它的对话存活更久。
Python，且这些结果已在作用域内 一个贯穿整个会话的解释器，其中每个存储结果都是变量，每个工具都是可调用函数。一个单元格就能驱动原本每回合需要一次工具调用的循环。变量、导入和辅助函数可跨会话保留。需要许可的工具仍会请求许可，因此批准一个单元格并不等于批准它能触及的一切。
历史被摘要，而非被静默丢弃 Ollama 不会拒绝过长的提示——它会丢弃最早的 token，于是智能体忘记了被问过什么，却表现得像还记得。cloi 改为对较早的一半做摘要，只在工具结果与其调用不可分割之处切断。什么都不会被删除：摘要会记录它覆盖到多远，较早的消息只是不再发送。
可触及范围的护栏 路径被限制在工作区内。写入、编辑和 shell 命令会先询问，有三个选项：仅一次、此工具始终允许、否。子进程以净化后的环境运行，因此命令无法读取你的 API 密钥；任何进入输出的机密在存储或发送前都会被脱敏。
会话内命令：/model、/tools、/plan、/usage、/sessions、/help。Ctrl+C 中断一个回合，Ctrl+D 退出。
文档 docs/models.md：模型如何被挑选，以及目录背后的基准。 docs/internals.md：循环、护栏、校验，以及实测带来的改变。 docs/configuration.md：每项设置及其默认值。
限制 仅支持 Ollama。提供方位于一个模块之后，但除此之外没有接入其他服务。没有子智能体，没有 MCP，没有网络访问。对于能装进 8 GB 的每一个模型来说，困难的跨文件调试都超出其能力上限——基准中为 0/12，这就是诚实的极限。 许可证：MIT，见 LICENSE。
