he-yufeng/CoreCoder

CoreCoder – a tiny, readable coding‑agent engine

What it is – CoreCoder is a 2,800‑line pure‑Python implementation of a code‑editing AI agent. It strips the idea of a “coding assistant” down to its essentials: a while loop that sends the user’s prompt to an LLM, lets the model call a handful of tools (file read/write, shell, grep, etc.), feeds the tool results back into the conversation, and repeats until the model returns a final answer. All of this is written to be readable in an afternoon and easy to fork.

Why it matters – Most commercial agents (Claude Code, Cursor, etc.) hide their core logic behind hundreds of thousands of lines of closed code. CoreCoder exposes the whole pipeline – model wrapper, cost tracking, three‑tier context compaction, parallel tool execution, sub‑agent spawning, permission prompts, and a REPL – in a single, well‑commented codebase. This makes it a practical reference for anyone who wants to understand how a real‑world coding agent works or build their own customized version.

Key components

• agent.py – the main loop (≈240 LOC) that drives the conversation.
• llm.py – streaming OpenAI‑compatible client, retry logic, and token‑cost accounting.
• context.py – three‑tier context trimming (mechanical cut, model‑summarize, aggressive truncation).
• tools/ – eight built‑in tools (bash, read_file, write_file, edit_file, glob, grep, todo_write, agent) plus optional MCP extensions.
• cli.py – interactive REPL with slash commands (/model, /plan, /undo, /tokens, …).
• hooks.py, permissions.py, checkpoints.py – safety gates, consent handling, and undo support.

How to try it

# Clone and install in editable mode
git clone https://github.com/he-yufeng/CoreCoder
cd CoreCoder
pip install -e .

# Or just install the released package
pip install corecoder

# Set your LLM credentials (example for OpenAI)
export OPENAI_API_KEY=sk-...
# optional: pick a model
export CORECODER_MODEL=gpt-5.5   # default

# Run the interactive REPL
corecoder

# One‑shot usage (adds error handling to a function and exits)
corecoder -p "add error handling to parse_config()"

The REPL will ask for consent before any mutating tool (write_file, edit_file, bash, sub‑agent) runs, unless you start it with --yes.

Extending / forking

1. Swap models – just change the CORECODER_MODEL env var or pass a custom LLM instance.
2. Add a tool – create a new file in tools/ inheriting from tools/base.py, implement run(), and register it in agent.py.
3. Edit the system prompt – modify prompt.py (41 LOC) to change the agent’s personality or instructions.
4. Embed as a library –

   from corecoder import Agent, LLM
   llm = LLM(model="deepseek-chat", api_key="sk-…")
   print(Agent(llm=llm).chat("list all TODO comments in this repo"))
   

5. Explore the essays – the repository includes an eight‑part bilingual “source‑reading series” that walks through each subsystem line‑by‑line.

Who should look at it –

• Researchers or engineers who want a concrete, open‑source reference for building or studying coding agents.
• Developers interested in customizing toolsets, adding RAG, or integrating the engine into larger IDE‑like products.
• Educators teaching LLM‑driven agents; the minimal codebase is ideal for classroom demos.

---

CoreCoder is a fully functional, test‑covered (227 tests) Python package that demonstrates how a coding assistant works from end‑to‑end while remaining small enough to read, modify, and extend.