CoreCoder CLI
A teaching terminal coding agent in Python, built as a "nanoGPT for agents": read it, take it apart and fork it
- 1,864 ★ on the repository
- Last commit
Broad access
Why this level
- The agent writes and edits files and runs shell commands, and an "always allow" decision persists between runs
- `--yes` in `-p` mode approves all mutating calls up front, and hooks run your commands around every call
Install
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/corecoderDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent writes and edits files and runs shell commands, and an "always allow" decision persists between runs
- `--yes` in `-p` mode approves all mutating calls up front, and hooks run your commands around every call
This is third-party code. Review the repository files before installing.
What it does
CoreCoder is a compact terminal coding agent in the manner of Claude Code, written in Python. The author pitches it as a "nanoGPT for agents": an engine a little over a thousand lines long that you can read in an evening, set a breakpoint on any line and rewrite for yourself. The code ships with a series of eight bilingual essays that walk through the loop, tools, context and sub-agents using the code itself. The agent reads and writes files, runs shell commands, searches the project, keeps a task list and spawns sub-agents. There are eight tools: bash, read_file, write_file, edit_file, glob, grep, todo_write and agent. A file edit replaces the single matching snippet and does not use line numbers. Context is compacted in three tiers: long outputs are trimmed first, old turns are then summarized and an emergency compaction comes last. The model is set through environment variables: DeepSeek, local Ollama and other OpenAI-compatible providers work, and an optional LiteLLM backend covers the rest. The REPL has `/plan`, `/undo`, `/diff` and `/tokens` commands, hooks around tool calls and MCP server support.
Who it is for. For developers who want to understand how a coding agent like Claude Code works, and for those who need a small base to build their own agent.
Good fit when
- You want to study how an agent works from real code and a series of essays
- You need a base to fork: add your own tool on top of a 32-line base class, change the system prompt or the model
- You need a simple terminal agent with DeepSeek, Qwen, Kimi or local Ollama through a single API address
- You want to embed an agent in your own program as a library: Agent, LLM and Config are exported from the package
Not a fit when
- You need a daily tool for a large team: the project is for learning and is not meant to replace Claude Code
- You work with untrusted input: the agent has no sandbox
- You need retrieval-based search over a big repository or a hard spending cap: the project has neither
- You need MCP resources and prompts: the client in mcp.py supports tools only
Example request
Run corecoder in /plan mode, find every TODO in the project, propose an edit plan and after my approve fix the first threeLimitations
- Python 3.10 or newer and a model provider key are required. OpenAI and Anthropic APIs are unavailable from Russia, so check your provider before installing.
- Dangerous bash commands are blocked by a plain list of regular expressions. It guards against slips and does not replace isolation.
- Model request retries use exponential backoff only; there is no fallback model and no hard spending cap.
- Sub-agents run synchronously and there is no RAG search over large repositories.
- The license is MIT.
How to disable. Remove the package with `pip uninstall corecoder`. Sessions, permissions, settings and the MCP server list live in ~/.corecoder; delete the folder if you no longer need them.
FAQ
How do I install CoreCoder and run it with DeepSeek?
Run `pip install corecoder`, then set OPENAI_API_KEY, `OPENAI_BASE_URL=https://api.deepseek.com` and `CORECODER_MODEL=deepseek-chat`. The corecoder command opens interactive mode, and `corecoder -p "task"` runs one task and exits.
How is CoreCoder different from Claude Code and aider?
Claude Code is closed and large, and aider takes tens of thousands of lines of Python. CoreCoder keeps only a minimal core that reads in an evening and is built for study and forking.
How does CoreCoder protect files and commands?
Reads and searches run at once. Writes, edits, bash and sub-agent spawning ask for consent first: once, always for that tool, or deny. An "always" decision is kept in ~/.corecoder/permissions.json.
Can I connect MCP servers to CoreCoder?
Yes. Put mcp.json in ~/.corecoder in the same format as Claude Code, and the server tools appear as mcp__<server>__<tool>. Each call goes through the consent prompt.
What does /plan mode do in CoreCoder?
While it is on, every mutating call is refused and the agent investigates read-only and proposes a numbered plan. After you say approve or toggle `/plan` again, control returns and the agent makes the edits.
Discussion
No questions or reviews yet.
Related
CLI toolsOpen-source personal AI assistant on your own machine: answers in Telegram, Slack, Discord and WhatsApp, extended with skills and plugins
An engineering system for coding agents: 68 agents, 292 skills, hooks, memory, rules and the AgentShield security scanner
DeepSeek Harness is an open-source AI agent from DeepSeek where every feature is a plugin. It runs in the browser, on macOS and on Windows.
A self-improving agent from Nous Research with a TUI, messaging gateway, cron jobs and skills it writes itself
An open source coding agent for the terminal and desktop with build and plan modes
Ollama runs open models on your own machine and serves them to agents through a local API compatible with OpenAI and Anthropic.
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| CoreCoder (this entry) | no | 1,864 | |
| CodeAgent | no | 1,026 | also a Python terminal agent in the manner of Claude Code, but with no essay walk through the code |
| Pi | no | 117,254 | a minimal TypeScript terminal agent extended with skills and packages, with no teaching walkthrough of the code |
README in short
The documentation is laid out as a read-then-fork path: a five-minute start, a per-file code map with line counts, a walkthrough of the main loop and ideas for forks.