CodeRill

LOCAL CODING AGENT · OPEN SOURCE

让编程 Agent
重新变得可读。

CodeRill 是一个可在本地运行的 Python 编程 Agent。它让模型提出下一步，调用工具读取或修改项目，并把每一步记录下来。沿着一次请求，你能读懂 Agent 怎样工作。

开始安装 查看源码

Python 3.10+ · OpenAI 兼容接口 / Anthropic · MIT License

一个可跟读的工作回合

you › 修复 parse() 对空输入的错误

01 读取文件与上下文

02 模型提出修改

CodeRill › 显示 diff，等待你的确认

+ return json.loads(text) if text else {}

you › 同意

03 写入文件 · 运行测试 · 记录会话

✓ 返回结果

示意流程 · 不代表一次真实模型运行

START WITH THE BASICS

先弄清 Agent 里有什么。

普通聊天只生成回答；编程 Agent 还会根据目标选择工具、查看结果，再决定下一步。CodeRill 把这个过程拆成能追踪的部分。

01

模型

负责理解请求和提出行动，例如“先读文件，再修改这一行”。模型的建议需要由程序执行和检查。

02

工具

让模型能读取文件、搜索代码、查看 Git 状态或运行命令。每个工具都有明确的输入和输出。

03

运行时

串起模型和工具：发送上下文、接收工具调用、执行并回传结果，直到任务完成或需要你审批。

04

会话

保存请求、工具结果和审批状态。中断后，CodeRill 根据事件记录重建它已知的进度。

ONE REQUEST, STEP BY STEP

一次“修复测试”会怎样走？

下面是教学示意。实际步骤由模型回复和任务需要决定，未必每次都会改文件或运行测试。

  1. 01

    你提出目标

    CLI 或 TUI 接收“修复失败的测试”，创建或续接会话，并把请求交给同一个 Agent 运行时。

    app/ → agent/runtime.py
  2. 02

    组织上下文并询问模型

    运行时准备对话和工具定义；上下文模块检查请求预算，模型适配器负责与选定服务通信。

    context/ → providers/
  3. 03

    执行模型选的工具

    例如先搜索失败的测试，再读取相关源码。工具结果会回到模型，形成下一轮判断。

    tools/ → agent/runtime.py
  4. 04

    审查改动

    在标准模式下，需要修改文件时先展示差异并等待确认；如果等待期间文件变了，旧审批会失效。

    permissions/review.py
  5. 05

    记录结果并继续

    工具结果与最终回复写入追加式会话日志。任务中断后可以恢复；无法确认结果的外部操作不会自动重试。

    session/ → 下一轮或结束

关键区别：模型负责提出行动，运行时负责执行顺序，权限层决定哪些行动必须由你确认。

真正值得研究的 Agent，应该能回答三个问题：

它为什么这么做？它改了什么？出错后能否恢复？

INSIDE THE LOOP

把流程对应到源码。

每一层只处理一类问题。点开路径，就能从网站的解释直接进入对应源码。

01 / ENTRY

入口与界面

命令行和可选的 TUI 接收请求。两种界面通过同一装配入口创建运行时，因此审批和会话行为一致。

coderill/app/ ↗
02 / LOOP

Agent 回合

异步运行时安排模型调用、工具执行、审批暂停和恢复。连续只读工具可并行，写操作按顺序处理。

coderill/agent/runtime.py ↗
03 / MODEL

模型适配

统一模型请求、工具调用和流式事件的格式；适配器负责转换 OpenAI 兼容接口与 Anthropic 的数据。

coderill/providers/ ↗
04 / ACTION

工具与权限

工具负责文件、Shell、Git 等具体操作；权限层保存审查请求与改动预览，避免模型的提议直接变成执行许可。

coderill/tools/ ↗ · permissions/ ↗
05 / MEMORY

会话与上下文

会话保存可回放的事件；上下文层控制发给模型的内容大小，并归档旧工具输出供之后查回。

coderill/session/ ↗ · context/ ↗
06 / PROCESS

进程与后台任务

进程层处理命令超时、取消、长期运行任务和日志；子 Agent 的可写任务使用独立 Git worktree。

coderill/runtime/ ↗

当前边界：Shell 命令没有操作系统沙箱；Git worktree 只隔离目录。真实模型调用需要你自己的 API Key。

阅读完整架构与故障语义 ↗

READING ROUTE

第一次读源码，按这条路线走。

先看最短的主链路，再研究审批与恢复。每一步都有对应的观察重点。

  1. 1. 看入口app/cli.py：找到用户输入怎样进入运行时。
  2. 2. 跟回合agent/runtime.py：跟踪模型调用、工具结果和下一轮请求。
  3. 3. 看边界permissions/review.py：观察文件变化为何让旧审批失效。
  4. 4. 验证恢复examples/failure_demo.py：无需 API Key，运行故障演示再回看会话代码。

GET STARTED

在本地跑起来。

需要 Python 3.10 或更新版本。先克隆 GitHub 仓库，再按 README 的开发环境方式安装。将 API Key 写入项目目录的 .env 后，即可试一次只读提问。

查看配置说明 ↗
01 · 克隆并进入项目git clone https://github.com/YeChenglin8888/CodeRill.git
cd CodeRill
02 · 安装pip install -e ".[tui,mcp]"可选的 TUI 与 MCP 依赖一起安装。
03 · 配置密钥OPENAI_API_KEY=你的密钥写入项目的 .env 文件；.env 已列入 .gitignore。也可用环境变量。
04 · 试一次只读任务coderill "解释这个项目的主要模块"

想先了解恢复机制？运行 python examples/failure_demo.py，无需 API Key。

READ THE CODE

从 README 开始，
沿着调用链往下读。

源码、测试和设计取舍都在仓库里。你可以运行它，也可以把它当作一份可以逐层拆解的 Agent 实例。

打开 GitHub 仓库