Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

# CoreCoder

**The nanoGPT of coding agents. A 1.5k-line engine inside 3,374 readable lines of pure Python: understand how a coding agent actually works, then fork your own.**
**The nanoGPT of coding agents. A 1.5k-line engine inside 3,451 readable lines of pure Python: understand how a coding agent actually works, then fork your own.**

*learn from it · fork it · ship something better*

Expand All @@ -25,7 +25,7 @@

| | CoreCoder | Claude Code | aider | nanoGPT |
|---|---|---|---|---|
| Lines of code | ~1,532 engine / 3,374 total | hundreds of thousands (closed) | tens of thousands of Python | ~600 (two files) |
| Lines of code | ~1,532 engine / 3,451 total | hundreds of thousands (closed) | tens of thousands of Python | ~600 (two files) |
| Time to read it all | one afternoon | can't (closed) | a few days of slogging | one afternoon |
| Breakpoint, change, rerun? | yes, every line | no | yes, but there's a lot | yes |
| What it's for | understand one, then fork your own | production coding assistant | terminal pair-programming | minimal GPT for teaching |
Expand All @@ -36,7 +36,7 @@ The nanoGPT column is there as a reference point: minimal, readable, but it teac

I've always felt coding agents get talked about as if they were arcane. Strip a tool like Claude Code or Cursor all the way down and the core is a `while` loop wrapped around a large model, plus seven or eight tools that let it actually do things. The hard part was never the loop; it's everything the loop has to cope with once it meets the real world. CoreCoder is the minimal version that writes that core out honestly.

The engine (loop, model interface, context, tools, sessions) is 1,532 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 26 files: 3,374 physical lines, 2,787 net, every one short enough to read in a single sitting. The growth since the original 1,161-line snapshot went into visible features: plan mode, hooks and checkpoints, each documented below.
The engine (loop, model interface, context, tools, sessions) is 1,532 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 26 files: 3,451 physical lines, 2,859 net, every one short enough to read in a single sitting. The growth since the original 1,161-line snapshot went into visible features: plan mode, hooks and checkpoints, each documented below.

And it really runs: reads and writes files, executes shell, spawns sub-agents, compacts context in three tiers, and tells you the tokens and dollars a run burned whenever you ask. Anything that would mutate your disk or run a command stops for your consent first. The suite has 373 offline tests and an opt-in live smoke test. But the point of it running isn't to become your daily driver. It runs so the walkthrough can't lie: a reference that shows how an agent works has to actually work.

Expand Down Expand Up @@ -96,7 +96,7 @@ corecoder/
├── permissions.py consent for mutating tools 81 lines
├── hooks.py Pre/PostToolUse shell hooks 87 lines
├── shell.py POSIX shell routing (Git Bash on Windows) 61 lines
├── mcp.py MCP tools, text resources + stdio 313 lines
├── mcp.py MCP tools, resources, prompt templates 390 lines
├── mcp_http.py remote Streamable HTTP transport 211 lines
├── prompt.py system prompt 41 lines
├── cli.py REPL + slash commands + one-shot 404 lines
Expand Down Expand Up @@ -209,7 +209,7 @@ Going deeper, the directions are out in the open too. None of the following is i
- **The dangerous-command blocking in bash is just a regex blacklist.** It guards against slips, not a security sandbox. Facing untrusted input means reaching for seccomp or container isolation. This is the hardest of the four; it goes all the way down to the syscall and isolation layer.
- **Retry is only exponential backoff.** No fallback model, no hard dollar budget. Follow `llm.py` down and add a fallback model chain plus a stop-on-over-budget gate; the change stays mostly inside that one file.
- **Agent teams join before returning.** Named workers already run concurrently with isolated contexts; asynchronous background jobs, streaming progress and role-specific tool presets remain open extension points rather than another orchestration layer to add by default.
- **No RAG, prompt API, or resource subscriptions.** MCP text references are fetched on demand; CoreCoder does not build a retrieval index or run a background synchronization loop. Retrieval-based code location for big repos is still open.
- **No RAG or resource subscriptions.** MCP text references and prompt templates are fetched on demand; CoreCoder does not build a retrieval index or run a background synchronization loop. Retrieval-based code location for big repos is still open.

The README only points; the seventh essay picks up the code details for each. Pick one and start; that's the whole reason the core is kept this small.

Expand Down Expand Up @@ -300,6 +300,8 @@ Both transports handshake and discover server capabilities at startup. Remote to

A server advertising `resources` also adds one `mcp__<server>__resources` tool. It lists resources, discovers URI templates and reads text context without expanding the catalog into the prompt. Resource-only servers work without a `tools/list` implementation. If that tool name is already taken, the bridge appends underscores until it finds a free name, leaving remote tools unchanged.

A server advertising `prompts` adds `mcp__<server>__prompts`. Prompt-only servers also work without `tools/list`. Use `{"action": "list"}` to discover prompt names, or `{"action": "get", "name": "code_review", "arguments": {"code": "print('hello')"}} to render one with the server's arguments. Text messages come back as external data; non-text content and results over 32,768 characters fail explicitly.

For a server named `remote`, the bridge accepts these argument objects. Use a URI returned by that server in place of the example `project://guide`:

```json
Expand All @@ -310,7 +312,7 @@ For a server named `remote`, the bridge accepts these argument objects. Use a UR

Pass a returned `nextCursor` unchanged as `cursor` to fetch another list or template page. The URI goes to the configured server, never to a local file reader or a separate HTTP fetch. Multiple text contents retain their URI and MIME metadata; binary resources and results over 32,768 characters fail explicitly instead of being silently omitted or truncated. Resource calls keep the existing permission, plan-mode and hook checks, so fetching a reference does not add an automatic read-only grant.

Startup requests use fifteen-second timeouts and tool calls use sixty. HTTP accepts JSON or SSE replies, carries the negotiated protocol and session headers, caps each response at 4 MiB, and checks the remaining call budget between body reads. DNS and status/header parsing still use the standard library's blocking network behavior, not a hard end-to-end deadline. There is no legacy SSE endpoint discovery, OAuth flow, resource subscription or prompt API. Use HTTPS for remote credentials; redirects are not followed. Configured header values are literal strings, not environment-variable templates.
Startup requests use fifteen-second timeouts and tool calls use sixty. HTTP accepts JSON or SSE replies, carries the negotiated protocol and session headers, caps each response at 4 MiB, and checks the remaining call budget between body reads. DNS and status/header parsing still use the standard library's blocking network behavior, not a hard end-to-end deadline. There is no legacy SSE endpoint discovery, OAuth flow or resource subscription. Use HTTPS for remote credentials; redirects are not followed. Configured header values are literal strings, not environment-variable templates.

The tool wrappers and handshake remain in `mcp.py`; `mcp_http.py` owns only the HTTP transport. With no config, nothing changes. See the [local filesystem example](examples/mcp_filesystem.md) or the [remote HTTP setup](examples/mcp_http.md).

Expand Down
14 changes: 8 additions & 6 deletions README_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

# CoreCoder

**编程 agent 里的 nanoGPT。1.5k 行引擎、整包 3374 行纯 Python 全部一口气可读,读懂一个 coding agent 到底怎么运作,再 fork 出你自己的。**
**编程 agent 里的 nanoGPT。1.5k 行引擎、整包 3451 行纯 Python 全部一口气可读,读懂一个 coding agent 到底怎么运作,再 fork 出你自己的。**

*learn from it · fork it · ship something better*

Expand All @@ -25,7 +25,7 @@

| | CoreCoder | Claude Code | aider | nanoGPT |
|---|---|---|---|---|
| 代码量 | 引擎约 1532 行 / 整包 3374 行 | 几十万行(闭源) | 数万行 Python | 约 600 行(两个文件) |
| 代码量 | 引擎约 1532 行 / 整包 3451 行 | 几十万行(闭源) | 数万行 Python | 约 600 行(两个文件) |
| 读完要多久 | 一个下午 | 读不了(闭源) | 得啃几天 | 一个下午 |
| 能不能下断点改了再跑 | 能,每一行 | 不能 | 能,但量大 | 能 |
| 定位 | 读懂并 fork 出你自己的 agent | 生产级编程助手 | 终端结对编程 | 教学用最小 GPT |
Expand All @@ -36,7 +36,7 @@ nanoGPT 那一列是拿来对照的:它最小、可读,但教的是训一个

我一直觉得 coding agent 被讲得太玄了。把 Claude Code、Cursor 这类工具扒到底,核心是一个 while 循环套着一个大模型,外加七八个让它能真正动手的工具。难的从来不是这个循环,而是循环跑进真实世界以后要兜的那些底。CoreCoder 就是把这个核心老老实实写出来的最小版本。

引擎部分(循环、模型接口、上下文、工具、会话)去掉空行和注释是 1532 行。连最外层的 CLI、配置、打包一起算,整个包 26 个文件、物理 3374 行、净 2787 行,每个文件都短到能一口气读完。自 1161 行快照之后的增长都花在了看得见的功能上:plan mode、hooks、checkpoints,下文各有交代。
引擎部分(循环、模型接口、上下文、工具、会话)去掉空行和注释是 1532 行。连最外层的 CLI、配置、打包一起算,整个包 26 个文件、物理 3451 行、净 2859 行,每个文件都短到能一口气读完。自 1161 行快照之后的增长都花在了看得见的功能上:plan mode、hooks、checkpoints,下文各有交代。

它真能跑:读写文件、执行 shell、派子 agent、分三层压上下文,还能随时把这趟烧掉的 token 和美元数报给你。任何要动你磁盘、要跑命令的调用,都会先停下来等你点头。现在有 373 个离线测试,另有按需开启的真实 API 冒烟。但能跑不是为了劝你拿去日用,而是为了让这份「注释」不撒谎:一个解释 agent 怎么运作的范例,自己得真能运作。

Expand Down Expand Up @@ -96,7 +96,7 @@ corecoder/
├── permissions.py 改动类工具的用户授权 81 行
├── hooks.py 工具调用前后的用户 shell 钩子 87 行
├── shell.py POSIX shell 路由(Windows 走 Git Bash) 61 行
├── mcp.py MCP 工具、文本资源和 stdio 313 行
├── mcp.py MCP 工具、文本资源和提示模板 390 行
├── mcp_http.py 远程 Streamable HTTP 连接 211 行
├── prompt.py 系统提示词 41 行
├── cli.py REPL + 斜杠命令 + 一次性模式 404 行
Expand Down Expand Up @@ -209,7 +209,7 @@ print(Agent(llm=llm).chat("找出项目里所有 TODO 注释并列出来"))
- **bash 的危险命令拦截只是正则黑名单。** 防手滑,不是安全沙箱。要面对不可信输入,就得上 seccomp 或容器隔离。这条最硬,要一路走到系统调用和隔离那一层。
- **重试只做了指数退避。** 没有 fallback 模型,也没有美元硬预算。顺着 `llm.py` 往下,加一条 fallback 模型链和超预算自动停的闸,改动基本就集中在这一个文件。
- **子 agent 团队会在返回前汇合。** 命名 worker 已经能带着隔离上下文并发执行;异步后台任务、流式进度和角色专属工具预设仍是扩展点,不为了多 agent 就默认再加一层编排框架。
- **不做 RAG、提示词 API 或资源订阅。** MCP 文本资料只按需读取,不建检索索引,也不跑后台同步。给大仓加检索式代码定位仍然是留给你扩展的方向。
- **不做 RAG 或资源订阅。** MCP 文本资料和提示模板只按需获取,不建检索索引,也不跑后台同步。给大仓加检索式代码定位仍然是留给你扩展的方向。

README 只给方向,每条的代码细节第七篇接着讲。挑一个动手,就是把它做得更好的开始。

Expand Down Expand Up @@ -299,6 +299,8 @@ REPL 里 `/plan` 开关计划模式。开着的时候,提示符变成 `(plan)`

声明了 `resources` 的服务器还会多一个 `mcp__<服务器>__resources` 工具,用来列资料、查 URI 模板、按需读取文本,不把整份资源目录塞进提示词。只有资源、没有 `tools/list` 的服务器也能接入。若名字与远程工具冲突,资源桥会在末尾加下划线找空位,不覆盖原有工具。

声明了 `prompts` 的服务器则多一个 `mcp__<服务器>__prompts` 工具,只有提示模板、没有 `tools/list` 的服务器也能接入。用 `{"action": "list"}` 查看模板名,或用 `{"action": "get", "name": "code_review", "arguments": {"code": "print('hello')"}} 传入服务器定义的参数并渲染模板。返回的文本消息只是外部数据;非文本内容和超过 32,768 字符的结果会明确报错。

例如名为 `remote` 的服务器,资源桥接受以下参数。示例里的 `project://guide` 要换成该服务器实际返回的 URI:

```json
Expand All @@ -309,7 +311,7 @@ REPL 里 `/plan` 开关计划模式。开着的时候,提示符变成 `(plan)`

翻页时,把返回的 `nextCursor` 原样放进 `cursor`,目录和模板都按页读取。URI 只传给已配置的服务器,不会被客户端拿来打开本地文件或另发 HTTP 请求。一次读取可以带回多个文本条目,保留各自 URI 和 MIME 信息;二进制资源和超过 32,768 字符的结果会明确报错,不悄悄省略或截断。资源调用仍受原有授权、plan mode 和 hooks 控制,不因为叫“读取”就自动放行。

初始化请求的超时是十五秒,工具调用是六十秒。HTTP 支持 JSON 和 SSE 响应,携带协商后的协议版本与会话头,每个响应最多 4 MiB,读取正文时会检查剩余调用预算。DNS 和状态行、响应头解析仍遵循标准库的阻塞网络行为,不承诺严格的端到端截止时间。不实现旧式 SSE 地址发现、OAuth 登录、资源订阅或提示词 API。远程认证请用 HTTPS;客户端不跟随重定向。请求头按字面值使用,不会展开环境变量。
初始化请求的超时是十五秒,工具调用是六十秒。HTTP 支持 JSON 和 SSE 响应,携带协商后的协议版本与会话头,每个响应最多 4 MiB,读取正文时会检查剩余调用预算。DNS 和状态行、响应头解析仍遵循标准库的阻塞网络行为,不承诺严格的端到端截止时间。不实现旧式 SSE 地址发现、OAuth 登录或资源订阅。远程认证请用 HTTPS;客户端不跟随重定向。请求头按字面值使用,不会展开环境变量。

握手和工具包装仍共用 `mcp.py`,`mcp_http.py` 只管 HTTP 传输。没有配置文件时一切照旧。可直接照着[本地文件系统示例](examples/mcp_filesystem.md)或[远程 HTTP 配置](examples/mcp_http.md)试。

Expand Down
2 changes: 1 addition & 1 deletion article/00-index.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ CoreCoder 做的事,是把这套骨架压到一千五百行出头的纯 Python
5. [并行执行与子 agent](05-parallel-and-subagents.md)。模型一次返回多个工具调用时,CoreCoder 用线程池并发跑。这篇老实讲这个简化版相对 Claude Code 的流式执行器差在哪,并发又会引入什么新麻烦,以及子 agent 为什么不准递归。
6. [把它跑成一个真正的命令行工具](06-session-and-cli.md)。会话存盘、断点续聊、斜杠命令、一次性模式。`session.py` 里有个不起眼但很要命的安全细节:怎么防住用恶意会话名做路径穿越。
7. [Fork CoreCoder,搭一个你自己的 coding agent](07-build-your-own.md)。收尾的实操篇。从 clone 到换成你常用的模型,到加一个真正有用的自定义工具,到改系统提示词调教它的风格,到打包发布。读完前六篇你已经懂了原理,这篇让你真有一个东西。
8. [不动主循环的三种加法:MCP、钩子与计划模式](08-extensibility.md)。给 agent 加东西的三条正路:`mcp.py`(313 行)把远程工具接成与内建同权,hooks 用退出码 2 否决一次调用却永远杀不死循环,计划模式用一个布尔量压住包括 `--yes` 在内的整个权限层。最后一节把三块收拢回同一条契约:工具同形、错误是普通返回值、循环不被外围杀死。
8. [不动主循环的三种加法:MCP、钩子与计划模式](08-extensibility.md)。给 agent 加东西的三条正路:`mcp.py`(390 行)把远程工具接成与内建同权,hooks 用退出码 2 否决一次调用却永远杀不死循环,计划模式用一个布尔量压住包括 `--yes` 在内的整个权限层。最后一节把三块收拢回同一条契约:工具同形、错误是普通返回值、循环不被外围杀死。

不想按顺序也行。想搞懂「它凭什么敢自动跑命令」直接跳第二篇;想接自己的模型直接跳第三篇;只想赶紧 fork 出个能用的,第七篇是自洽的。

Expand Down
2 changes: 1 addition & 1 deletion article/00-index_EN.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ The first six are about understanding. Each one fixes on a single subsystem of t
5. [Parallel execution and sub-agents](05-parallel-and-subagents_EN.md). When the model returns several tool calls at once, CoreCoder runs them concurrently on a thread pool. This piece is honest about where this simplified version falls short of Claude Code's streaming executor, what new trouble concurrency brings in, and why a sub-agent is not allowed to recurse.
6. [Turning it into a real command-line tool](06-session-and-cli_EN.md). Session save, resume, slash commands, one-shot mode. `session.py` holds an unremarkable but critical security detail: how to stop a malicious session name from turning into a path traversal.
7. [Fork CoreCoder and build your own coding agent](07-build-your-own_EN.md). The hands-on finale. From clone, to switching to the model you actually use, to adding a genuinely useful custom tool, to tuning the system prompt to shape its style, to packaging and release. After the first six pieces you understand the principles; this one leaves you with something real.
8. [Three ways to extend without touching the loop: MCP, hooks, and plan mode](08-extensibility_EN.md). The three right ways to grow an agent: `mcp.py` (313 lines) wires remote tools in as first-class citizens, hooks veto a single call with exit code 2 yet can never kill the loop, and plan mode is one boolean that outranks the entire permission layer including `--yes`. The coda folds all three back into one contract: uniform tools, errors as ordinary return values, and a loop its perimeter cannot kill.
8. [Three ways to extend without touching the loop: MCP, hooks, and plan mode](08-extensibility_EN.md). The three right ways to grow an agent: `mcp.py` (390 lines) wires remote tools in as first-class citizens, hooks veto a single call with exit code 2 yet can never kill the loop, and plan mode is one boolean that outranks the entire permission layer including `--yes`. The coda folds all three back into one contract: uniform tools, errors as ordinary return values, and a loop its perimeter cannot kill.

You don't have to read in order. Want to understand how it dares to run commands on its own? Jump to piece two. Want to plug in your own model? Jump to piece three. Just want to fork something usable fast? Piece seven stands on its own.

Expand Down
Loading
Loading