corecoder 0.4.1__tar.gz → 0.4.2__tar.gz

{corecoder-0.4.1 → corecoder-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: corecoder
-Version: 0.4.1
+Version: 0.4.2
 Summary: Minimal AI coding agent (~1,000 lines of Python) inspired by Claude Code. Works with any LLM. (formerly NanoCoder)
 Project-URL: Homepage, https://github.com/he-yufeng/CoreCoder
 Project-URL: Repository, https://github.com/he-yufeng/CoreCoder
@@ -37,7 +37,7 @@ Description-Content-Type: text/markdown
 
 # CoreCoder
 
-**The nanoGPT of coding agents. 1,081 lines of pure Python — understand how a coding agent actually works, then fork your own.**
+**The nanoGPT of coding agents. 1,201 lines of pure Python — understand how a coding agent actually works, then fork your own.**
 
 *learn from it · fork it · ship something better*
 
@@ -47,7 +47,7 @@ Description-Content-Type: text/markdown
 [![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-1081_LoC-blue)](article/00-index_EN.md)
+[![engine](https://img.shields.io/badge/engine-1201_LoC-blue)](article/00-index_EN.md)
 [![essays](https://img.shields.io/badge/source--reading-8_bilingual-orange)](article/00-index_EN.md)
 
 </div>
@@ -60,7 +60,7 @@ Description-Content-Type: text/markdown
 
 | | CoreCoder | Claude Code | aider | nanoGPT |
 |---|---|---|---|---|
-| Lines of code | ~1,081 engine / 1,714 total | hundreds of thousands (closed) | tens of thousands of Python | ~600 (two files) |
+| Lines of code | ~1,201 engine / 2,008 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 |
@@ -71,7 +71,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,081 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 18 files: 1,714 physical lines, 1,385 net, every one short enough to read in a single sitting.
+The engine (loop, model interface, context, tools, sessions) is 1,201 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 21 files: 2,008 physical lines, 1,614 net, every one short enough to read in a single sitting.
 
 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. 103 tests, all green. 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.
 
@@ -219,6 +219,7 @@ Inside the REPL, `/help` lists everything; these are the ones you'll reach for:
 /compact         compact the context by hand
 /tokens          token usage and cost estimate
 /diff            files changed this session
+/undo            revert the most recent file change
 /save  /sessions save / list sessions
 quit / exit      exit (Ctrl+C cancels the current round)
 ```

{corecoder-0.4.1 → corecoder-0.4.2}/README.md

@@ -2,7 +2,7 @@
 
 # CoreCoder
 
-**The nanoGPT of coding agents. 1,081 lines of pure Python — understand how a coding agent actually works, then fork your own.**
+**The nanoGPT of coding agents. 1,201 lines of pure Python — understand how a coding agent actually works, then fork your own.**
 
 *learn from it · fork it · ship something better*
 
@@ -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-1081_LoC-blue)](article/00-index_EN.md)
+[![engine](https://img.shields.io/badge/engine-1201_LoC-blue)](article/00-index_EN.md)
 [![essays](https://img.shields.io/badge/source--reading-8_bilingual-orange)](article/00-index_EN.md)
 
 </div>
@@ -25,7 +25,7 @@
 
 | | CoreCoder | Claude Code | aider | nanoGPT |
 |---|---|---|---|---|
-| Lines of code | ~1,081 engine / 1,714 total | hundreds of thousands (closed) | tens of thousands of Python | ~600 (two files) |
+| Lines of code | ~1,201 engine / 2,008 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 |
@@ -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,081 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 18 files: 1,714 physical lines, 1,385 net, every one short enough to read in a single sitting.
+The engine (loop, model interface, context, tools, sessions) is 1,201 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 21 files: 2,008 physical lines, 1,614 net, every one short enough to read in a single sitting.
 
 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. 103 tests, all green. 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.
 
@@ -184,6 +184,7 @@ Inside the REPL, `/help` lists everything; these are the ones you'll reach for:
 /compact         compact the context by hand
 /tokens          token usage and cost estimate
 /diff            files changed this session
+/undo            revert the most recent file change
 /save  /sessions save / list sessions
 quit / exit      exit (Ctrl+C cancels the current round)
 ```

{corecoder-0.4.1 → corecoder-0.4.2}/README_CN.md

@@ -2,7 +2,7 @@
 
 # CoreCoder
 
-**编程 agent 里的 nanoGPT。1081 行纯 Python，读懂一个 coding agent 到底怎么运作，再 fork 出你自己的。**
+**编程 agent 里的 nanoGPT。1201 行纯 Python，读懂一个 coding agent 到底怎么运作，再 fork 出你自己的。**
 
 *learn from it · fork it · ship something better*
 
@@ -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-1081_LoC-blue)](article/)
+[![engine](https://img.shields.io/badge/engine-1201_LoC-blue)](article/)
 [![源码导读](https://img.shields.io/badge/源码导读-8篇双语-orange)](article/)
 
 </div>
@@ -25,7 +25,7 @@
 
 | | CoreCoder | Claude Code | aider | nanoGPT |
 |---|---|---|---|---|
-| 代码量 | 引擎约 1081 行 / 整包 1714 行 | 几十万行（闭源） | 数万行 Python | 约 600 行（两个文件） |
+| 代码量 | 引擎约 1201 行 / 整包 2008 行 | 几十万行（闭源） | 数万行 Python | 约 600 行（两个文件） |
 | 读完要多久 | 一个下午 | 读不了（闭源） | 得啃几天 | 一个下午 |
 | 能不能下断点改了再跑 | 能，每一行 | 不能 | 能，但量大 | 能 |
 | 定位 | 读懂并 fork 出你自己的 agent | 生产级编程助手 | 终端结对编程 | 教学用最小 GPT |
@@ -36,7 +36,7 @@ nanoGPT 那一列是拿来对照的：它最小、可读，但教的是训一个
 
 我一直觉得 coding agent 被讲得太玄了。把 Claude Code、Cursor 这类工具扒到底，核心是一个 while 循环套着一个大模型，外加七八个让它能真正动手的工具。难的从来不是这个循环，而是循环跑进真实世界以后要兜的那些底。CoreCoder 就是把这个核心老老实实写出来的最小版本。
 
-引擎部分（循环、模型接口、上下文、工具、会话）去掉空行和注释是 1081 行。连最外层的 CLI、配置、打包一起算，整个包 18 个文件、物理 1714 行、净 1385 行，每个文件都短到能一口气读完。
+引擎部分（循环、模型接口、上下文、工具、会话）去掉空行和注释是 1201 行。连最外层的 CLI、配置、打包一起算，整个包 21 个文件、物理 2008 行、净 1614 行，每个文件都短到能一口气读完。
 
 它真能跑：读写文件、执行 shell、派子 agent、分三层压上下文，还能随时把这趟烧掉的 token 和美元数报给你，103 个测试是绿的。但能跑不是为了劝你拿去日用，而是为了让这份「注释」不撒谎：一个解释 agent 怎么运作的范例，自己得真能运作。
 
@@ -184,6 +184,7 @@ README 只给方向，每条的代码细节第七篇接着讲。挑一个动手
 /compact         手动压缩上下文
 /tokens          查看 token 用量和费用估算
 /diff            查看本次会话改过的文件
+/undo            撤销最近一次文件改动
 /save  /sessions 保存 / 列出会话
 quit / exit      退出（Ctrl+C 取消当前回合）
 ```

{corecoder-0.4.1 → corecoder-0.4.2}/article/00-index.md

@@ -8,7 +8,7 @@
 
 因为 Claude Code 本体太大了。它的代码量在几十万行的量级，光一个负责跑 shell 命令的 BashTool 就上千行，真要逐行读完，多数人会在第三个文件就关掉编辑器。可 agent 的核心其实没那么复杂，复杂的是工程化之后那些为真实世界兜底的边角：模型半路被打断怎么办、上下文塞满了怎么办、十个工具调用同时回来怎么办、provider 偶尔抽风返回 500 又怎么办。这些东西摊在几十万行里，你很难一眼看到骨架。
 
-CoreCoder 做的事，是把这套骨架压到一千行出头的纯 Python。准确说，agent 引擎（循环、模型接口、上下文、工具、会话）去掉空行和注释是 1081 行；连最外层的 CLI 终端、配置和打包都算上，整个包去掉空行和注释 1385 行，物理代码 1714 行。每个文件都短到能一口气读完，跑起来又确实是个能改代码、能跑命令、能自己开子任务、能压缩上下文、能算钱的 agent。它不是玩具。它是把生产级 agent 的每个设计决策，拣出最核心的那版，用最少的代码诚实地写一遍。
+CoreCoder 做的事，是把这套骨架压到一千行出头的纯 Python。准确说，agent 引擎（循环、模型接口、上下文、工具、会话）去掉空行和注释是 1201 行；连最外层的 CLI 终端、配置和打包都算上，整个包去掉空行和注释 1614 行，物理代码 2008 行。每个文件都短到能一口气读完，跑起来又确实是个能改代码、能跑命令、能自己开子任务、能压缩上下文、能算钱的 agent。它不是玩具。它是把生产级 agent 的每个设计决策，拣出最核心的那版，用最少的代码诚实地写一遍。
 
 读它，约等于读一份 Claude Code 的「可运行注释版」。区别在于，CoreCoder 的每一行你都能在自己机器上断点、改、跑、看它出什么效果。本系列里我引用的每一个行数、每一段代码，都是从仓库里现读现核的，不是凭印象。这点我后面会反复较真，因为编码 agent 这个领域，太多文章在凭感觉编数字。
 

{corecoder-0.4.1 → corecoder-0.4.2}/article/00-index_EN.md

@@ -8,7 +8,7 @@ First, use CoreCoder, an open source project whose core runs to just over a thou
 
 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 a thousand lines of pure Python. To be precise, the agent engine (the loop, model interface, context, tools, session) is 1081 lines once you drop blank lines and comments; add the outermost CLI terminal, config, and packaging and the whole package is 1385 lines without blanks and comments, 1714 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 a thousand lines of pure Python. To be precise, the agent engine (the loop, model interface, context, tools, session) is 1201 lines once you drop blank lines and comments; add the outermost CLI terminal, config, and packaging and the whole package is 1614 lines without blanks and comments, 2008 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.
 

{corecoder-0.4.1 → corecoder-0.4.2}/corecoder/__init__.py

@@ -1,6 +1,6 @@
 """CoreCoder - Minimal AI coding agent inspired by Claude Code's architecture."""
 
-__version__ = "0.4.1"
+__version__ = "0.4.2"
 
 from corecoder.agent import Agent
 from corecoder.config import Config

corecoder-0.4.2/corecoder/checkpoints.py

@@ -0,0 +1,38 @@
+"""Session-scoped undo for file mutations.
+
+edit_file and write_file record a checkpoint before touching a file; /undo
+pops the latest one and restores the previous bytes (or removes the file if
+it did not exist). In-memory only: undo history dies with the process, and
+bash side effects are not tracked, only the two file-writing tools.
+"""
+
+from pathlib import Path
+
+# (path, prior bytes or None if the file did not exist)
+_stack: list[tuple[str, bytes | None]] = []
+
+
+def record(path: Path) -> None:
+    """Capture the pre-mutation state of path. Call right before writing."""
+    _stack.append((str(path), path.read_bytes() if path.exists() else None))
+
+
+def undo() -> str:
+    """Restore the most recent checkpoint."""
+    if not _stack:
+        return "Nothing to undo."
+    path_str, prior = _stack.pop()
+    p = Path(path_str)
+    if prior is None:
+        p.unlink(missing_ok=True)
+        return f"Removed {path_str} (created this session)."
+    p.write_bytes(prior)
+    return f"Restored {path_str}."
+
+
+def pending() -> int:
+    return len(_stack)
+
+
+def clear() -> None:
+    _stack.clear()

{corecoder-0.4.1 → corecoder-0.4.2}/corecoder/cli.py

@@ -213,6 +213,13 @@ def _repl(agent: Agent, config: Config):
                 for f in sorted(_changed_files):
                     console.print(f"  [cyan]{f}[/cyan]")
             continue
+        if user_input == "/undo":
+            from .checkpoints import pending, undo
+            console.print(undo())
+            left = pending()
+            if left:
+                console.print(f"[dim]{left} more checkpoint(s) on the stack.[/dim]")
+            continue
         if user_input == "/sessions":
             sessions = list_sessions()
             if not sessions:
@@ -261,6 +268,7 @@ def _show_help():
         "  /tokens        Show token usage\n"
         "  /compact       Compress conversation context\n"
         "  /diff          Show files modified this session\n"
+        "  /undo          Revert the most recent file change\n"
         "  /save          Save session to disk\n"
         "  /sessions      List saved sessions\n"
         "  quit           Exit CoreCoder\n"

{corecoder-0.4.1 → corecoder-0.4.2}/corecoder/tools/edit.py

@@ -10,6 +10,7 @@ import difflib
 from pathlib import Path
 from typing import ClassVar
 
+from ..checkpoints import record as _record_checkpoint
 from .base import Tool
 
 # track files changed this session for /diff
@@ -67,6 +68,7 @@ class EditFileTool(Tool):
                 )
 
             new_content = content.replace(old_string, new_string, 1)
+            _record_checkpoint(p)
             p.write_text(new_content, encoding="utf-8")
             _changed_files.add(str(p))
 

{corecoder-0.4.1 → corecoder-0.4.2}/corecoder/tools/write.py

@@ -3,6 +3,7 @@
 from pathlib import Path
 from typing import ClassVar
 
+from ..checkpoints import record as _record_checkpoint
 from .base import Tool
 from .edit import _changed_files
 
@@ -32,6 +33,7 @@ class WriteFileTool(Tool):
         try:
             p = Path(file_path).expanduser().resolve()
             p.parent.mkdir(parents=True, exist_ok=True)
+            _record_checkpoint(p)
             p.write_text(content, encoding="utf-8")
             _changed_files.add(str(p))
             n_lines = content.count("\n") + (1 if content and not content.endswith("\n") else 0)

{corecoder-0.4.1 → corecoder-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "corecoder"
-version = "0.4.1"
+version = "0.4.2"
 description = "Minimal AI coding agent (~1,000 lines of Python) inspired by Claude Code. Works with any LLM. (formerly NanoCoder)"
 readme = "README.md"
 license = "MIT"

corecoder-0.4.2/tests/test_checkpoints.py

@@ -0,0 +1,54 @@
+"""Undo checkpoints for edit_file / write_file."""
+
+from __future__ import annotations
+
+from corecoder import checkpoints
+from corecoder.tools.edit import EditFileTool
+from corecoder.tools.write import WriteFileTool
+
+
+def setup_function():
+    checkpoints.clear()
+
+
+def test_edit_then_undo_restores_previous_bytes(tmp_path):
+    f = tmp_path / "a.py"
+    f.write_text("v1\n", encoding="utf-8")
+    assert EditFileTool().execute(str(f), "v1", "v2").startswith("Edited")
+    assert f.read_text() == "v2\n"
+
+    assert checkpoints.undo() == f"Restored {f}."
+    assert f.read_text() == "v1\n"
+
+
+def test_undo_removes_file_created_by_write(tmp_path):
+    f = tmp_path / "new.py"
+    assert not f.exists()
+    WriteFileTool().execute(str(f), "print(1)\n")
+    assert f.exists()
+
+    assert checkpoints.undo() == f"Removed {f} (created this session)."
+    assert not f.exists()
+
+
+def test_undo_pops_one_mutation_at_a_time(tmp_path):
+    f = tmp_path / "a.py"
+    f.write_text("v1\n", encoding="utf-8")
+    EditFileTool().execute(str(f), "v1", "v2")
+    EditFileTool().execute(str(f), "v2", "v3")
+
+    assert checkpoints.pending() == 2
+    checkpoints.undo()
+    assert f.read_text() == "v2\n"
+    checkpoints.undo()
+    assert f.read_text() == "v1\n"
+
+
+def test_failed_edit_leaves_no_checkpoint(tmp_path):
+    f = tmp_path / "a.py"
+    f.write_text("v1\n", encoding="utf-8")
+    # old_string absent -> error before any write
+    result = EditFileTool().execute(str(f), "missing", "v2")
+    assert result.startswith("Error:")
+    assert checkpoints.pending() == 0
+    assert checkpoints.undo() == "Nothing to undo."

{corecoder-0.4.1 → corecoder-0.4.2}/tests/test_core.py

@@ -1,6 +1,6 @@
 """Tests for core modules: config, context, session, imports."""
 
-import tomllib
+import re
 from pathlib import Path
 from typing import ClassVar
 
@@ -12,8 +12,42 @@ from corecoder.tools import get_tool
 
 
 def test_version():
-    pyproject = tomllib.loads(Path("pyproject.toml").read_text())
-    assert __version__ == pyproject["project"]["version"]
+    # regex instead of tomllib: the latter only exists on 3.11+ and CI runs 3.10
+    m = re.search(r'(?m)^version = "([^"]+)"', Path("pyproject.toml").read_text())
+    assert m is not None
+    assert __version__ == m.group(1)
+
+
+def test_readme_line_counts_are_current():
+    # The LoC numbers are the brand of this repo. If the engine or the
+    # package grows, the README has to move with it, and this test is the
+    # alarm: update the badge and the prose in README.md and README_CN.md.
+    root = Path(__file__).resolve().parent.parent
+    engine_files = [
+        root / "corecoder" / name
+        for name in ("agent.py", "llm.py", "context.py", "session.py")
+    ]
+    engine_files += sorted((root / "corecoder" / "tools").glob("*.py"))
+    package_files = sorted((root / "corecoder").rglob("*.py"))
+
+    def net_lines(path: Path) -> int:
+        return sum(
+            1
+            for line in path.read_text(encoding="utf-8").splitlines()
+            if line.strip() and not line.strip().startswith("#")
+        )
+
+    engine = sum(net_lines(f) for f in engine_files)
+    physical = sum(
+        len(f.read_text(encoding="utf-8").splitlines()) for f in package_files
+    )
+    package_net = sum(net_lines(f) for f in package_files)
+
+    readme = (root / "README.md").read_text(encoding="utf-8")
+    assert f"engine-{engine}_LoC" in readme
+    assert f"{len(package_files)} files" in readme
+    assert f"{physical:,} physical lines" in readme
+    assert f"{package_net:,} net" in readme
 
 
 def test_public_api_exports():