CoreCoder
A small, runnable Python coding-agent core built to read, modify, and fork.
Per-dimension scores and reasoning
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.
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().
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/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").
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.
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.