CoreCoder
A small, runnable Python coding-agent core built to read, modify, and fork.
- Source repo
- he-yufeng/CoreCoder
- Stars
- ★ 1.9k
- Last updated
- 2d ago
- License
- MIT
- Primary language
- Python
- FA score
- 59/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A Python developer learning how a coding agent works can read
agent.py, set breakpoints, and change the loop locally. - Not a fit if
- Teams running untrusted code that need real isolation: bash safety is only a regex blacklist
- Users needing MCP resources/prompts or RAG retrieval: both are explicitly absent
- Source review
- 59/100 · Major gaps
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
LLMand callAgent.chat().
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/CoreCoder
cd CoreCoder
pip 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").
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 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.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| CoreCoder This agent | 59 · Major gaps | CLIFree + model costs | ★ 1.9k | 2d ago | Python | OpenAI API |
| Kode CLI | 44 · Major gaps | CLIFree + model costs | ★ 5.2k | 3d ago | TypeScript | OpenAI API · Claude API |
| fx Coding Agent | 63 · Some gaps | CLIFree + model costs | ★ 3.8k | today | Zig | ChatGPT · Codex · OpenAI API |
| DevSpace | 50 · Major gaps | CLIFree + model costs | ★ 5.4k | 4d ago | TypeScript | ChatGPT |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: minimal toolset, bash dangerous-command gate, sub-agents deprived of recursive tool, session path traversal protection, transparent cost tracking. Deductions: weak user confirmation (only interactive REPL, not one-shot), sensitive data (API keys) only via env vars and .env, no encryption or prompts, dependencies not pinned, rollback relies on git, no built-in undo.
Evidence shows: clear code structure, modular design, tests cover core functionality, CI matrix across platforms and versions. Deductions: dependencies not pinned, potential unavailability due to upstream changes, failure messages exist but not fully assessed.
Evidence shows: targets developers, supports multiple LLM providers, extensible tools, flexible env-var configuration. Deductions: no explicit resource limits or extreme environment adaptation, trigger precision depends on model behavior, no detailed boundary documentation.
Evidence shows: clear README structure, detailed install instructions, stable naming (renamed but redirects), examples and FAQ, known limitations explicit, MIT license, clear maintenance responsibility. Deductions: missing changelog, only version number.
Evidence shows: output is code edits and reports, directly usable, marginal value in teaching and customizability, high cost-benefit (free open source). Deductions: no evidence of actual run results, only static analysis.
Evidence shows: README claims align with code, tests verify some functionality, articles claim based on code. Deductions: lack of external corroboration, some claims (e.g., '86 tests all green') not verified in static review.
- API keys are managed only via environment variables or .env files, with no encrypted storage or security prompts; users must ensure key security themselves.
- The bash tool's dangerous-command gate is only a regex blacklist, not a security sandbox; additional isolation is needed for untrusted input.
- Dependencies are not pinned, which may cause compatibility issues due to upstream updates; pinning versions is recommended.
- One-shot mode (-p) has no user confirmation mechanism, which may execute dangerous operations; use with caution.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
v0.8.0 Undo and consent now survive restarts. /undo checkpoints serialize to ~/.corecoder/checkpoints.json (base64 payloads, tmp-file swap so a crash can't truncate the file) and reload lazily on first use, and "always allow" grants persist in ~/.corecoder/permissions.json. One-shot -p mode stays pure and still refuses mutating tools. Also in this release: - Test coverage for the REPL slash-command dispatch. - Docs pinned to the code: hook examples, test counts, and line counts are swept by an alarm so they can't drift. 中文说明 …View on GitHub ↗ -
Release notes excerpt
Twenty-three commits since v0.6.0, still in the distilled spirit of the project: - Thinking models show their work (745ff65): deepseek-reasoner, kimi-k2-thinking and friends stream reasoning_content next to the answer. CoreCoder now surfaces it as it arrives instead of dropping it, and keeps it out of the reply and the history so context stays clean. …View on GitHub ↗ -
v0.6.0 CoreCoder v0.6.0: MCP, hooks, plan mode
Release notes excerpt
Four increments since v0.5.0, all in the distilled spirit of the project: - Engine trim (7f323e7): the core loop got leaner without losing behavior. - Pre/PostToolUse hooks (d503117): user shell commands around tool calls, configured in ~/.corecoder/hooks.json. - MCP stdio client (2dfd156): external tools join the agent from ~/.corecoder/mcp.json. Newline-delimited JSON-RPC over subprocess pipes, handshake and crash isolation included. MCP tools flow through the v0.5.0 consent gate and the new hooks like the built-ins. …View on GitHub ↗
FAQ
Which models can it use?
corecoder[litellm] installation for a LiteLLM backend.Can it change files on my machine?
write_file and edit_file can modify local files, and bash can execute shell commands. Run it only in a local working directory you are prepared to let it operate on.How are model costs controlled?
/tokens to see token usage and an estimated cost. The documented implementation does not provide a hard budget or automatic stop when a budget is exceeded.