CoreCoder

CoreCoder is an open-source, MIT-licensed minimal AI coding agent written in pure Python by Yufeng He. It is positioned as the nanoGPT of coding agents: a roughly 1.3k-line engine inside a package of about 2,800 lines, meant to be read end to end and then forked. It was formerly named NanoCoder, and the latest release listed is v0.8.0.

What It Is

CoreCoder is a terminal coding agent and teaching reference. At its core is a bounded loop that sends the conversation to a model, runs the tools the model requests, feeds the results back, and repeats until the model answers without requesting tools. It ships eight built-in tools: bash, read_file, write_file, edit_file, glob, grep, todo_write, and a sub-agent spawner. It runs in an interactive REPL or in one-shot mode with -p, and it can also be imported as a library exporting Agent, LLM, and Config.

Models and Providers

It speaks the OpenAI-compatible API by default, and switching providers is usually a matter of setting OPENAI_API_KEY, OPENAI_BASE_URL, and CORECODER_MODEL. The README gives examples for OpenAI, DeepSeek, OmniRoute, and local Ollama. An optional LiteLLM backend (pip install "corecoder[litellm]") routes to providers without an OpenAI-compatible endpoint. Reasoning models stream their chain-of-thought, which is shown dimmed and kept out of conversation history.

Safety and Control Features

Mutating tools such as edit, write, bash, and sub-agent spawning stop for user consent. In the REPL you can allow once, always allow a tool, or deny. In one-shot mode these calls are refused unless --yes is passed. Plan mode (/plan) makes the agent investigate read-only and present a numbered plan before it is allowed to change anything. Hooks let you run your own shell commands before and after tool calls, and a pre-hook can veto a call with exit code 2.

Context, Extensibility, and Session Handling

Context is managed in three compaction tiers, at 50%, 70%, and 90% of the window. The edit tool uses unique-match search-and-replace and returns a diff on success. An MCP stdio client loads tools from servers configured in ~/.corecoder/mcp.json; it supports tools only, not resources or prompts. Sessions can be saved and resumed, /undo reverts file changes using persisted checkpoints, and /tokens reports token usage and cost estimates.

Learning Material

The project includes a bilingual (Chinese and English) series of eight source-reading essays that walk through the loop, tools, LLM layer, context handling, sub-agents, CLI, forking, and extensibility. The README says the bash dangerous-command blocking is a regex blacklist, not a security sandbox.