cc-mini: A 1000-Line Python Harness for Building Your Own Coding Agent
Ultra-light Harness scaffolding for AI agents, a mini version of claude code
At a glance
- What is it?
- cc-mini is a minimal reimplementation of the Claude Code agent harness in roughly 1000 lines of Python, with nine built-in tools, a permission system, and an extendable skills directory. It is best understood as a teaching scaffold and a base to fork, not as a finished product, and its licence status is unstated in the repository metadata.
- Who is it for?
- Adopt cc-mini if you want to read and modify the entire agent loop yourself, or if you want a small base for a custom skill such as the citorigin example in the docs. Do not adopt it if you need a supported product with a declared licence and release history, since the repository shows no releases and no licence file.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository last received commits 98 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap cc-mini is trying to fill: an agent loop you can read in one sitting
Most coding agents ship as products. You install a binary, point it at a repository, and the loop that decides which file to read, which command to run, and when to stop is hidden inside a compiled artifact or a large codebase. cc-mini takes the opposite position. Its README states that the entire core is about 1000 lines of Python, and the repository layout supports that claim: the src/core directory holds engine.py for the streaming API loop and tool execution, llm.py for the Anthropic and OpenAI clients, config.py, context.py, tool.py, permissions.py, and session.py. That is the whole harness. Everything else is either a tool implementation under src/tools or a pluggable capability under src/features.
The intended audience is narrow and specific. This is for engineers who want to understand how an agentic tool loop actually works, or who want to fork a small base and add their own behaviour without negotiating with a large upstream project. The README describes the project as built to extend and positions it as coming from Claude Code, meaning it reimplements patterns from that tool rather than wrapping it. If your goal is to get work done today with a polished assistant, cc-mini is not aimed at you. If your goal is to own the loop, it is.
How the tool loop works: streaming, tool calls, and a permission check in between
The mechanism visible in the repository is a standard agentic loop. The engine streams from the LLM, and when the model emits a tool call, the harness executes the matching tool and feeds the result back, repeating until the model stops requesting tools. The README describes this as Claude calling tools autonomously until the task is complete, and the first-session demo shows the shape of it: a Glob call for **/*.py, then a Read call on src/core/engine.py, with a check mark after each.
Nine tools ship in the box. Read, Glob, Grep, AskUser, EnterPlanMode, and ExitPlanMode are auto-approved. Edit, Write, and Bash require confirmation. That split is the permission model, and it is mode-aware: the README says reads are auto-approved while writes and bash ask for confirmation, and that plan mode has its own permission isolation. Plan mode is worth noting because it changes the data flow rather than just the prompt. Entering plan mode lets parallel subagents explore the codebase before implementation, and those subagents are read-only. The Agent tool that launches them is also used by coordinator mode, which adds Agent, SendMessage, and TaskStop for background workers doing parallel research and implementation.
Two more pieces sit around the loop. Session persistence auto-saves conversations to ~/.config/cc-mini/sessions/ and /resume brings them back. Context compression auto-compacts when the conversation approaches token limits, and /compact triggers it manually. The KAIROS memory feature, documented separately, adds cross-session memory with auto-consolidation under ~/.config/cc-mini/memory/. None of these are unusual designs. The point is that they are all visible, in files you can open, which is the entire value proposition.
Getting it running: install, provider config, and the environment variables that matter
The README gives two install paths. The recommended one is a one-line script: curl -fsSL https://raw.githubusercontent.com/e10nMa2k/cc-mini/main/install.sh | bash. The manual path is git clone https://github.com/e10nMa2k/cc-mini.git, then cd cc-mini, then pip install -e ".[dev]". Requirements are Python 3.10 or newer, with 3.11 recommended, plus an API key.
Provider selection is where the configuration has a real trap, and the README flags it directly. For Anthropic you export ANTHROPIC_API_KEY. For anything else you set CC_MINI_PROVIDER=openai, and the README is explicit that this is a protocol type, not a vendor name. Azure AI Foundry and other OpenAI-compatible gateways still use openai; setting the provider to foundry or bedrock will not work. Alongside that you set OPENAI_API_KEY and OPENAI_BASE_URL, and optionally CC_MINI_MODEL, whose default the README gives as gpt-5.1-codex.
Running it is a single command with flags. cc-mini starts the interactive REPL, cc-mini "what tests exist?" sends a one-shot prompt, -p prints and exits, --auto-approve skips permission prompts, --resume 1 continues a previous session, and --coordinator starts coordinator mode. Configuration is layered: CLI flags, environment variables, and a project-level .cc-mini.toml. Skills live in ~/.cc-mini/skills/ for user scope and {cwd}/.cc-mini/skills/ for project scope, which is how the /review, /commit, /test, and /simplify commands are defined. The docs/examples/citorigin directory shows a project-specific custom skill if you want a worked example before writing your own.
The Buddy feature and what it signals about the project's priorities
The README leads its feature list with an announcement: Buddy, an AI companion with custom sprites that lives in the terminal, hatched with /buddy and supporting custom ASCII species. The demo output shows a shiny legendary duck named Glitch Quack with mood stats rendered as bar charts. There is a full docs/buddy.md and a companion.json under ~/.config/cc-mini/.
This is a deliberate choice, and it is worth being direct about what it means. A project that promotes a Tamagotchi pet above its permission system is signalling that it is a personal exploration, not an infrastructure component. That is not a criticism of the code. It is a signal about maintenance expectations. If you fork cc-mini for a team, you should expect to remove or ignore features like this, and you should not read their presence as evidence of instability in the core loop. The two are separate: Buddy lives under src/features and companion state, while the engine, tools, and permissions live under src/core and src/tools. The risk is not technical coupling. The risk is that the project's stated direction and your use case may diverge, and you will be maintaining the fork yourself.
Where the README leaves you exposed: licence, releases, and sandbox portability
Three gaps matter before you build on this. First, the licence is unknown. The repository metadata supplied here lists no licence, and the README does not name one. Without a licence file, the default position under copyright is that you have no granted rights to redistribute or modify, regardless of what the code is published for. That is a legal question, not a technical one, and I am not giving legal advice, but it is a concrete blocker for commercial or internal redistribution until you check the repository directly. Second, there are no releases. The README references features from unreleased Claude Code, and the project itself has no tagged versions, so upgrades mean pulling from main. There is no changelog to read and no version to pin.
Third, the sandbox feature depends on Bubblewrap for bash isolation, per the README's link to docs/sandbox.md. Bubblewrap is a Linux tool. On macOS or Windows, that isolation path is not available in the same form, and the README does not describe a fallback. If you are running cc-mini on a laptop outside Linux and relying on the sandbox for safety, you need to confirm what actually happens, because the material here does not say. The permission prompts on Edit, Write, and Bash still apply, but a prompt is a human check, not an isolation boundary.
cc-mini against Aider: two different answers to the same question
The obvious comparison is Aider, which is also a Python coding agent you run in the terminal. The difference is in what each treats as the fixed point. Aider's approach centres on repository mapping and git-integrated edits: it builds a map of your codebase, applies changes, and commits them, with the editing format and the repo map as the load-bearing parts. cc-mini's approach centres on the harness itself. It gives you a streaming loop, a tool protocol in src/core/tool.py with a base Tool and ToolResult, and a permissions checker, and it expects you to supply the rest through tools and skills.
In practice that means Aider is a tool you adopt and configure, while cc-mini is a codebase you fork and modify. Aider has releases and a licence you can read; cc-mini has neither at the time of writing. Aider's value is in its editing accuracy and git workflow; cc-mini's value is that you can open engine.py and change how the loop behaves. If you want to add a tool that queries your internal ticketing system, cc-mini's one-file-per-tool layout under src/tools makes that straightforward. If you want an agent that reliably edits a large Python codebase today, Aider is the more finished instrument. Neither is a substitute for the other, and the choice depends on whether your problem is the agent's behaviour or the agent's plumbing.
Maintenance cost and the upgrade path you are actually signing up for
Because there are no releases, upgrades are git pulls from main against a tree you have probably modified. The core is small enough that merge conflicts in src/core/engine.py are readable rather than archaeological, which is the main practical benefit of the 1000-line claim. But every pull is a potential conflict, and there is no version number to reason about.
Installation writes to two locations. Source code lives under ~/.cc-mini/, and state lives under ~/.config/cc-mini/: sessions, memory, plans, history, and companion.json. User skills under ~/.cc-mini/skills/ and project skills under {cwd}/.cc-mini/skills/ are yours and will survive upstream changes, which makes skills the safer extension point than patching core files. If you do modify core, the TOML config at .cc-mini.toml and the environment variables give you a way to keep behaviour differences out of the code where possible.
The cost you should price in is not the code. It is the absence of a licence and the absence of tags. Both are cheap to resolve and both are currently unresolved. Check the repository for a LICENSE file before you invest, and decide whether you are comfortable tracking main.
Editorial conclusion
Adopt cc-mini if you want to read and modify the entire agent loop yourself, or if you want a small base for a custom skill such as the citorigin example in the docs. Do not adopt it if you need a supported product with a declared licence and release history, since the repository shows no releases and no licence file. Before installing, verify the licence in the GitHub repository itself, since the metadata here lists it as unknown, and read install.sh before piping it to bash.
Community notes