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
12 changes: 6 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,343 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,359 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 @@ -12,7 +12,7 @@
[![Python](https://img.shields.io/badge/python-3.10+-blue)](https://python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Tests](https://github.com/he-yufeng/CoreCoder/actions/workflows/ci.yml/badge.svg)](https://github.com/he-yufeng/CoreCoder/actions)
[![engine](https://img.shields.io/badge/engine-1515_LoC-blue)](article/00-index_EN.md)
[![engine](https://img.shields.io/badge/engine-1528_LoC-blue)](article/00-index_EN.md)
[![essays](https://img.shields.io/badge/source--reading-8_bilingual-orange)](article/00-index_EN.md)

</div>
Expand All @@ -25,7 +25,7 @@

| | CoreCoder | Claude Code | aider | nanoGPT |
|---|---|---|---|---|
| Lines of code | ~1,515 engine / 3,343 total | hundreds of thousands (closed) | tens of thousands of Python | ~600 (two files) |
| Lines of code | ~1,515 engine / 3,359 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,9 +36,9 @@ 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,515 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 26 files: 3,343 physical lines, 2,762 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,515 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 26 files: 3,359 physical lines, 2,775 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 360 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.
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 363 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.

The code came out of a public teardown: open analyses have already exposed a lot of the load-bearing architecture inside production agents like Claude Code. I took the most essential layer and rewrote it honestly, in as little code as I could. So reading CoreCoder is roughly like reading a runnable, annotated take on how that kind of agent works, except it's only a minimal reimplementation, sitting right there on your machine for you to take apart and change.

Expand Down Expand Up @@ -105,7 +105,7 @@ corecoder/
├── demo.py offline end-to-end demo 101 lines
└── tools/
├── bash.py shell + dangerous-command gate + cd 203 lines
├── edit.py unique-match search/replace + diff 101 lines
├── edit.py unique-match search/replace + diff 117 lines
├── grep.py content search 93 lines
├── glob_tool.py filename matching 52 lines
├── read.py file read 56 lines
Expand Down
12 changes: 6 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 行引擎、整包 3343 行纯 Python 全部一口气可读,读懂一个 coding agent 到底怎么运作,再 fork 出你自己的。**
**编程 agent 里的 nanoGPT。1.5k 行引擎、整包 3359 行纯 Python 全部一口气可读,读懂一个 coding agent 到底怎么运作,再 fork 出你自己的。**

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

Expand All @@ -12,7 +12,7 @@
[![Python](https://img.shields.io/badge/python-3.10+-blue)](https://python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Tests](https://github.com/he-yufeng/CoreCoder/actions/workflows/ci.yml/badge.svg)](https://github.com/he-yufeng/CoreCoder/actions)
[![engine](https://img.shields.io/badge/engine-1515_LoC-blue)](article/)
[![engine](https://img.shields.io/badge/engine-1528_LoC-blue)](article/)
[![源码导读](https://img.shields.io/badge/源码导读-8篇双语-orange)](article/)

</div>
Expand All @@ -25,7 +25,7 @@

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

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

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

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

代码来自一次公开拆解。公开的源码分析里,Claude Code 这类生产级 agent 暴露出不少关键架构,我挑出最核心的一层,用尽量少的代码诚实地复写了一遍。所以读 CoreCoder,约等于读一份基于公开源码分析的「可运行注释版」:讲的是这类 agent 的核心思路,而它本身只是最小复写,就摆在你机器上,随你拆、随你改。

Expand Down Expand Up @@ -105,7 +105,7 @@ corecoder/
├── demo.py 离线端到端演示 101 行
└── tools/
├── bash.py shell + 危险命令闸 + cd 追踪 203 行
├── edit.py 唯一匹配搜索替换 + diff 101 行
├── edit.py 唯一匹配搜索替换 + diff 117 行
├── grep.py 内容搜索 93 行
├── glob_tool.py 文件名匹配 52 行
├── read.py 文件读取 56 行
Expand Down
4 changes: 2 additions & 2 deletions article/00-index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@

这是一份写给工程师的系列导读。它想干两件事。

第一,借 CoreCoder 这个核心一千四百行出头的开源项目,把 Claude Code 这类生产级编码 agent 的内部结构讲清楚。第二,带你把 CoreCoder fork 下来,改出一个属于你自己的 coding agent。
第一,借 CoreCoder 这个核心一千五百行出头的开源项目,把 Claude Code 这类生产级编码 agent 的内部结构讲清楚。第二,带你把 CoreCoder fork 下来,改出一个属于你自己的 coding agent。

## 为什么要绕一圈

因为 Claude Code 本体太大了。它的代码量在几十万行的量级,光一个负责跑 shell 命令的 BashTool 就上千行,真要逐行读完,多数人会在第三个文件就关掉编辑器。可 agent 的核心其实没那么复杂,复杂的是工程化之后那些为真实世界兜底的边角:模型半路被打断怎么办、上下文塞满了怎么办、十个工具调用同时回来怎么办、provider 偶尔抽风返回 500 又怎么办。这些东西摊在几十万行里,你很难一眼看到骨架。

CoreCoder 做的事,是把这套骨架压到一千四百行出头的纯 Python。准确说,agent 引擎(循环、模型接口、上下文、工具、会话)去掉空行和注释是 1515 行;连最外层的 CLI 终端、配置和打包都算上,整个包去掉空行和注释 2762 行,物理代码 3343 行。每个文件都短到能一口气读完,跑起来又确实是个能改代码、能跑命令、能自己开子任务、能压缩上下文、能算钱的 agent。它不是玩具。它是把生产级 agent 的每个设计决策,拣出最核心的那版,用最少的代码诚实地写一遍。
CoreCoder 做的事,是把这套骨架压到一千五百行出头的纯 Python。准确说,agent 引擎(循环、模型接口、上下文、工具、会话)去掉空行和注释是 1528 行;连最外层的 CLI 终端、配置和打包都算上,整个包去掉空行和注释 2775 行,物理代码 3359 行。每个文件都短到能一口气读完,跑起来又确实是个能改代码、能跑命令、能自己开子任务、能压缩上下文、能算钱的 agent。它不是玩具。它是把生产级 agent 的每个设计决策,拣出最核心的那版,用最少的代码诚实地写一遍。

读它,约等于读一份 Claude Code 的「可运行注释版」。区别在于,CoreCoder 的每一行你都能在自己机器上断点、改、跑、看它出什么效果。本系列里我引用的每一个行数、每一段代码,都是从仓库里现读现核的,不是凭印象。这点我后面会反复较真,因为编码 agent 这个领域,太多文章在凭感觉编数字。

Expand Down
4 changes: 2 additions & 2 deletions article/00-index_EN.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@

This is a series for engineers. It sets out to do two things.

First, use CoreCoder, an open source project whose core runs to just over fourteen hundred lines, to lay out clearly how a production-grade coding agent like Claude Code is built on the inside. Second, walk you through forking CoreCoder and turning it into a coding agent of your own.
First, use CoreCoder, an open source project whose core runs to just over fifteen hundred lines, to lay out clearly how a production-grade coding agent like Claude Code is built on the inside. Second, walk you through forking CoreCoder and turning it into a coding agent of your own.

## Why take the detour

Because Claude Code itself is too big. Its codebase runs into the hundreds of thousands of lines, and the BashTool alone, the part that runs shell commands, is over a thousand. Read it line by line and most people close the editor by the third file. Yet the core of an agent isn't really that complicated. What's complicated is everything engineered around it to survive the real world: what to do when the model gets interrupted mid-stream, when the context window fills up, when ten tool calls come back at once, when a provider hiccups and returns a 500. Spread across hundreds of thousands of lines, that skeleton is hard to see.

What CoreCoder does is squeeze the skeleton down to just over fourteen hundred lines of pure Python. To be precise, the agent engine (the loop, model interface, context, tools, session) is 1,515 lines once you drop blank lines and comments; add the outermost CLI terminal, config, and packaging and the whole package is 2,762 lines without blanks and comments, 3,343 physical. Every file is short enough to read in one sitting, and what runs is genuinely an agent: it edits code, runs commands, spins up its own subtasks, compresses context, tracks cost. It is not a toy. It takes every design decision a production agent makes, picks the most essential version of each, and writes it out honestly in the least code it can.
What CoreCoder does is squeeze the skeleton down to just over fifteen hundred lines of pure Python. To be precise, the agent engine (the loop, model interface, context, tools, session) is 1,528 lines once you drop blank lines and comments; add the outermost CLI terminal, config, and packaging and the whole package is 2,775 lines without blanks and comments, 3,359 physical. Every file is short enough to read in one sitting, and what runs is genuinely an agent: it edits code, runs commands, spins up its own subtasks, compresses context, tracks cost. It is not a toy. It takes every design decision a production agent makes, picks the most essential version of each, and writes it out honestly in the least code it can.

Reading it is close to reading a runnable, annotated edition of Claude Code. The difference is that every line of CoreCoder is something you can breakpoint, change, run, and watch on your own machine. Every line count and every snippet I quote in this series is read straight out of the repository, not recalled from memory. I'll keep being pedantic about that, because in the coding-agent space far too many write-ups just make the numbers up.

Expand Down
20 changes: 18 additions & 2 deletions corecoder/tools/edit.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
"""

import difflib
import os
from pathlib import Path
from typing import ClassVar

Expand Down Expand Up @@ -54,9 +55,19 @@ def execute(self, file_path: str, old_string: str, new_string: str) -> str:
return f"Error: {file_path} not found"

try:
content = p.read_text(encoding="utf-8")
# newline="" reads the file's own line endings, untranslated
with p.open(encoding="utf-8", newline="") as f:
raw = f.read()
except UnicodeDecodeError:
return f"Error: {file_path} is not a UTF-8 text file (edit_file only edits text files)"
# match on LF text, as read_file shows it, then write back the
# file's most common line ending instead of the platform's
crlf = raw.count("\r\n")
counts = {"\n": raw.count("\n") - crlf, "\r\n": crlf, "\r": raw.count("\r") - crlf}
eol = max(counts, key=counts.get) if any(counts.values()) else os.linesep
content = raw.replace("\r\n", "\n").replace("\r", "\n")
old_string = old_string.replace("\r\n", "\n")
new_string = new_string.replace("\r\n", "\n")
occurrences = content.count(old_string)

if occurrences == 0:
Expand All @@ -72,8 +83,13 @@ def execute(self, file_path: str, old_string: str, new_string: str) -> str:
)

new_content = content.replace(old_string, new_string, 1)
if "\n" in old_string + new_string:
out = new_content.replace("\n", eol)
else: # one-line edit: every other byte stays as it was
out = raw.replace(old_string, new_string, 1)
_record_checkpoint(p)
p.write_text(new_content, encoding="utf-8")
with p.open("w", encoding="utf-8", newline="") as f:
f.write(out)
_record_write(p, p.read_bytes())
_changed_files.add(str(p))

Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ build-backend = "hatchling.build"
[project]
name = "corecoder"
version = "0.13.0"
description = "Minimal AI coding agent (3,343 lines of Python) inspired by Claude Code. Works with any LLM. (formerly NanoCoder)"
description = "Minimal AI coding agent (3,359 lines of Python) inspired by Claude Code. Works with any LLM. (formerly NanoCoder)"
readme = "README.md"
license = "MIT"
requires-python = ">=3.10"
Expand Down
30 changes: 30 additions & 0 deletions tests/test_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -317,6 +317,36 @@ def test_edit_file_rejects_non_utf8(tmp_path):
assert "not a UTF-8 text file" in r


def test_edit_file_keeps_crlf_line_endings(tmp_path):
"""A CRLF file stays CRLF, and old_string matches typed with LF or CRLF."""
edit = get_tool("edit_file")
path = tmp_path / "win.txt"
path.write_bytes(b"one\r\ntwo\r\nthree\r\n")
r = edit.execute(file_path=str(path), old_string="one\ntwo", new_string="1\n2\n2b")
assert r.startswith("Edited")
assert path.read_bytes() == b"1\r\n2\r\n2b\r\nthree\r\n"
r = edit.execute(file_path=str(path), old_string="2b\r\nthree", new_string="3")
assert r.startswith("Edited")
assert path.read_bytes() == b"1\r\n2\r\n3\r\n"


def test_edit_file_keeps_lf_line_endings(tmp_path):
"""An LF file stays LF even where the platform default is CRLF."""
edit = get_tool("edit_file")
path = tmp_path / "unix.txt"
path.write_bytes(b"a\nb\nc\n")
edit.execute(file_path=str(path), old_string="b", new_string="B\nB2")
assert path.read_bytes() == b"a\nB\nB2\nc\n"


def test_edit_file_one_line_edit_leaves_mixed_endings_alone(tmp_path):
edit = get_tool("edit_file")
path = tmp_path / "mixed.txt"
path.write_bytes(b"a\r\nb\nc\r\n")
edit.execute(file_path=str(path), old_string="b", new_string="B")
assert path.read_bytes() == b"a\r\nB\nc\r\n"


# --- glob ---

def test_glob_finds_files():
Expand Down
Loading