# CoreCoder

> A minimal, readable Python coding agent inspired by Claude Code that works with any LLM and is built for learning and forking.

CoreCoder is an open-source, MIT-licensed minimal AI coding agent written in pure Python by Yufeng He. It is positioned as the nanoGPT of coding agents: a roughly 1.3k-line engine inside a package of about 2,800 lines, meant to be read end to end and then forked. It was formerly named NanoCoder, and the latest release listed is v0.8.0.

## What It Is

CoreCoder is a terminal coding agent and teaching reference. At its core is a bounded loop that sends the conversation to a model, runs the tools the model requests, feeds the results back, and repeats until the model answers without requesting tools. It ships eight built-in tools: bash, read_file, write_file, edit_file, glob, grep, todo_write, and a sub-agent spawner. It runs in an interactive REPL or in one-shot mode with `-p`, and it can also be imported as a library exporting Agent, LLM, and Config.

## Models and Providers

It speaks the OpenAI-compatible API by default, and switching providers is usually a matter of setting `OPENAI_API_KEY`, `OPENAI_BASE_URL`, and `CORECODER_MODEL`. The README gives examples for OpenAI, DeepSeek, OmniRoute, and local Ollama. An optional LiteLLM backend (`pip install "corecoder[litellm]"`) routes to providers without an OpenAI-compatible endpoint. Reasoning models stream their chain-of-thought, which is shown dimmed and kept out of conversation history.

## Safety and Control Features

Mutating tools such as edit, write, bash, and sub-agent spawning stop for user consent. In the REPL you can allow once, always allow a tool, or deny. In one-shot mode these calls are refused unless `--yes` is passed. Plan mode (`/plan`) makes the agent investigate read-only and present a numbered plan before it is allowed to change anything. Hooks let you run your own shell commands before and after tool calls, and a pre-hook can veto a call with exit code 2.

## Context, Extensibility, and Session Handling

Context is managed in three compaction tiers, at 50%, 70%, and 90% of the window. The edit tool uses unique-match search-and-replace and returns a diff on success. An MCP stdio client loads tools from servers configured in `~/.corecoder/mcp.json`; it supports tools only, not resources or prompts. Sessions can be saved and resumed, `/undo` reverts file changes using persisted checkpoints, and `/tokens` reports token usage and cost estimates.

## Learning Material

The project includes a bilingual (Chinese and English) series of eight source-reading essays that walk through the loop, tools, LLM layer, context handling, sub-agents, CLI, forking, and extensibility. The README says the bash dangerous-command blocking is a regex blacklist, not a security sandbox.

## Features
- Bounded agent loop with parallel tool execution
- Eight built-in tools: bash, read_file, write_file, edit_file, glob, grep, todo_write, sub-agent
- Unique-match search-and-replace edits with diff output
- Three-tier context compaction
- Consent gate for mutating tools
- Plan mode (read-only planning before execution)
- Pre/PostToolUse shell hooks with veto support
- MCP stdio client for external tools
- Session save/resume and /undo checkpoints
- Token and cost tracking
- Interactive REPL and one-shot mode
- Importable Python library
- Works with any OpenAI-compatible provider or LiteLLM backend
- Bilingual source-reading essay series

## Integrations
OpenAI, DeepSeek, Ollama, OmniRoute, OpenRouter, LiteLLM, Model Context Protocol (MCP)

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
0.8.0

## Links
- Website: https://pypi.org/project/corecoder/
- Documentation: https://github.com/he-yufeng/CoreCoder/blob/main/article/00-index_EN.md
- Repository: https://github.com/he-yufeng/CoreCoder
- EveryDev.ai: https://www.everydev.ai/tools/corecoder