CoreCoder
A small, runnable Python coding-agent core built to read, modify, and fork.
What does this agent do, and when should you use it?
CoreCoder is a roughly 1,081-line pure-Python command-line coding agent intended for learning and adapting the core mechanics of coding agents. Its Agent loop sends user input to a model, runs requested tools in parallel, adds their results to context, and repeats until the model returns a text answer or the round limit is reached. The project includes an interactive REPL, one-shot prompts, session save and resume, context compaction, token and cost reporting, and importable `Agent`, `LLM`, and `Config` classes. Because it reads and writes local files and executes shell commands, it is suited to controlled local repositories rather than isolated production execution.
Run corecoder for the REPL or corecoder -p "..." for a one-shot task. Agent.chat() appends the user input to message history, calls LLM.chat(), executes any requested tools in parallel, appends results, and continues the loop. Its seven built-in tools are bash, read_file, write_file, edit_file, glob, grep, and agent: they search names and contents, read and write files, replace uniquely matched text and return a diff, execute shell commands, and spawn a sub-agent that cannot recursively spawn more sub-agents. context.py applies three levels of context compaction, session.py saves and resumes sessions, and /tokens reports token usage and estimated cost.
- A Python developer learning how a coding agent works can read `agent.py`, set breakpoints, and change the loop locally.
- A developer working in a small local repository can ask the agent to find TODOs, edit a function, and run a command to check the result.
- An engineer building a custom coding workflow can add a test, LSP, or web-access tool by implementing a tool against `tools/base.py`.
- An individual using DeepSeek, Ollama, or another OpenAI-compatible endpoint can switch model settings with environment variables.
- A developer embedding task-oriented code operations in another Python program can instantiate `LLM` and call `Agent.chat()`.
What are this agent's strengths and limitations?
- The approximately 1,081-line pure-Python engine exposes the agent loop, model interface, context handling, tools, and sessions in code small enough to inspect directly.
- Built-in file reading, writing, search, globbing, unique-match editing, shell execution, and sub-agents support a complete local code-operation loop.
- It supports OpenAI-compatible APIs and tracks token use and estimated cost; an optional LiteLLM backend extends provider access.
- Its context handling progressively trims tool output, summarizes older turns, and performs an emergency compaction instead of relying on one blunt cutoff.
- The bash safety mechanism is a regex blacklist, not a security sandbox; the documentation calls for seccomp or container isolation when handling untrusted input.
- Retries use exponential backoff only; there is no fallback-model chain or hard spending cap.
- Sub-agents use synchronous execution, truncate output beyond 5,000 characters, and cannot spawn further sub-agents.
- MCP and RAG are explicitly absent, so retrieval-based code location for large repositories requires custom work.
How do you install or deploy this agent?
Requires Python 3.10+ and working model credentials. Clone and install with:git clone https://github.com/he-yufeng/CoreCodercd CoreCoderpip install -e .
Alternatively, run pip install corecoder. The default OpenAI setup requires OPENAI_API_KEY=sk-.... A documented DeepSeek example is OPENAI_API_KEY=sk-... OPENAI_BASE_URL=https://api.deepseek.com CORECODER_MODEL=deepseek-chat; a local Ollama example is OPENAI_API_KEY=ollama OPENAI_BASE_URL=http://localhost:11434/v1 CORECODER_MODEL=qwen2.5-coder. A .env file at the project root is loaded at startup.
How do you use this agent?
Start the interactive mode with corecoder. For a task that exits when complete, run corecoder -p "add error handling to parse_config()". In the REPL, /model <name> changes the model, /compact compacts context, /tokens shows usage, /diff shows session changes, and /save plus /sessions manage sessions. As a library, create LLM(model="deepseek-chat", api_key="sk-...", base_url="https://api.deepseek.com"), then call Agent(llm=llm).chat("find every TODO comment in this project and list them").
How does this agent compare with similar options?
CoreCoder positions itself as a minimal coding-agent foundation to read and fork, not as a production replacement for Claude Code or aider. Unlike Claude Code, its implementation can be read and changed locally; compared with aider, it is much smaller in scope. It takes inspiration from nanoGPT's teaching-oriented minimalism, but applies that approach to an agent that edits code rather than GPT training.