CoreCoder

The nanoGPT of coding agents. A 1.3k-line engine inside 2,735 readable lines of pure Python: understand how a coding agent actually works, then fork your own.

learn from it · fork it · ship something better

中文 | English | Source-reading series · 8 bilingual essays

• Readable end to end. Read the whole engine in an afternoon, with no magic hidden anywhere you can't follow it.
• Hackable. Set a breakpoint on any line, change it, rerun, all on your own machine. It genuinely works, which makes this a living reference rather than a diagram.
• The gaps are the point. It deliberately keeps only the minimal core; what's missing isn't half-finished, it's where you branch off and make it your own.

How it compares

The nanoGPT column is there as a reference point: minimal, readable, but it teaches you to train a GPT. CoreCoder is after the same thing, only the subject is an agent that actually edits code. Sitting it next to Claude Code and aider isn't about competing for their users. CoreCoder is the foundation you stand on while you learn from them and get going; it isn't in the same race.

What this is

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,309 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 25 files: 2,735 physical lines, 2,205 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. 215 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.

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.

This README follows the same arc: the first half helps you read it (the code map, the main loop, eight essays), the second half helps you fork it and points at a few directions worth pushing further.

Run it once first (five minutes before you read)

Before you read the source, get it running on your machine once to build some intuition. It's a foundation meant for forking, so the recommended path is to clone it and install editable, reading and changing as you go:

git clone https://github.com/he-yufeng/CoreCoder
cd CoreCoder
pip install -e .

If you just want to get it running first, pip install corecoder works too.

Give it a model and a key and it goes. It speaks the OpenAI-compatible API by default, and switching providers is usually just two environment variables:

Kimi, Qwen and the like are the same two variables; for providers that don't even offer an OpenAI-compatible endpoint, the optional LiteLLM backend (pip install "corecoder[litellm]") routes to a hundred-plus of them. The third essay goes into this in detail. Thinking models are first-class too: deepseek-reasoner, kimi-k3 and friends stream their chain-of-thought, and CoreCoder shows it dimmed as it works, kept out of the conversation history so providers never see it come back. The key can be exported directly or dropped into a .env at the project root, which is loaded on startup. Then:

Smoke-tested end to end (read the file, edit it, run it, report back) against DeepSeek, Qwen3 and Kimi K2 via a single OpenRouter-compatible endpoint; each completed the full loop. One note for one-shot scripts: -p refuses mutating tools unless you pass --yes, by design.

corecoder                                             # interactive REPL
corecoder -p "add error handling to parse_config()"   # one-shot mode, exits when done

Read it: the code map

Laid out flat, the whole project is this big. Skim it before you clone and you'll know where everything is. This is the most concrete difference from Claude Code's hundreds of thousands of lines: you can read it like the table of contents of a book. Start from the main loop in agent.py; that's the heart of the whole agent.

corecoder/
├── agent.py        agent loop + parallel tool exec       240 lines   ← start here
├── llm.py          streaming client + retry + cost        332 lines
├── context.py      three-tier context compaction          220 lines
├── session.py      save / resume + path-traversal guard    97 lines
├── permissions.py  consent for mutating tools              75 lines
├── hooks.py        Pre/PostToolUse shell hooks             87 lines
├── shell.py        POSIX shell routing (Git Bash on Windows) 61 lines
├── mcp.py          MCP stdio client for external tools    208 lines
├── prompt.py       system prompt                           41 lines
├── cli.py          REPL + slash commands + one-shot       358 lines
├── config.py       env-var config                          55 lines
├── checkpoints.py  /undo snapshot and restore               93 lines
├── 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    99 lines
    ├── grep.py       content search                        93 lines
    ├── glob_tool.py  filename matching                     52 lines
    ├── read.py       file read                             56 lines
    ├── write.py      file write                            46 lines
    ├── todo.py       agent-maintained task checklist       79 lines
    ├── agent.py      sub-agent spawning                    72 lines
    └── base.py       tool base class                       32 lines
examples/
└── plan_hooks_demo.py  offline plan mode + hooks demo (no API key)

Eight tools: bash, read_file, write_file, edit_file, glob, grep, todo_write (a task checklist the agent maintains for itself), and agent (which spawns a sub-agent). Everything else is the CLI shell, config, and packaging wrapped around that engine core. If ~/.corecoder/mcp.json exists, its MCP servers join the eight as extra mcp__* tools; the MCP section below covers it.

A while loop is the whole agent

The whole of an agent fits in one sentence: hand the user's words to the model, run whatever tools it asks for, stuff the results back into the context, ask again, and keep going until it stops asking for tools and gives an answer. In code, that's about a dozen lines:

# corecoder/agent.py · the main loop (trimmed skeleton)
def chat(self, user_input):
    self.messages.append(user_input)

    for _ in range(self.max_rounds):                   # bounded, so it can't run away
        reply = self.llm.chat(self.messages, self.tools)   # ask the model what to do next