A lightweight Python implementation of Claude Code for the community — a terminal-based AI coding assistant that runs an agentic tool loop via the Anthropic API.
- Interactive REPL with command history
- Streaming responses — text appears as it is generated
- Agentic tool loop — multiple tool calls per turn
- 5 built-in tools: file read, file edit, glob, grep, bash
- Permission system — reads auto-approved, writes/bash ask for confirmation
- Python 3.11+
- Anthropic API key
cd /path/to/cc-mini
pip install -e ".[dev]"export ANTHROPIC_API_KEY=sk-ant-...Custom API base URL (useful for proxies or compatible endpoints):
export ANTHROPIC_BASE_URL=https://your-gateway.example.comOptional environment variables for runtime defaults:
export CC_MINI_MODEL=claude-sonnet-4-5
export CC_MINI_MAX_TOKENS=64000cc-minicc-mini type 'exit' or Ctrl+C to quit
> list all python files in this project
↳ Glob(**/*.py) ✓
Here are all the .py files...
> read engine.py and explain how the tool loop works
↳ Read(src/core/engine.py) ✓
The submit() method implements an agentic loop...
Type exit or press Ctrl+C to quit.
cc-mini "what tests exist in this project?"Use -p to print the response and exit:
cc-mini -p "summarize this codebase in 3 bullets"Pipe input:
echo "what does engine.py do?" | cc-mini -pSkip permission prompts for all tools (use with care):
cc-mini --auto-approvecc-mini \
--base-url https://your-gateway.example.com \
--api-key sk-ant-... \
--model claude-sonnet-4max_tokens follows the selected model by default. Override when you need a tighter cap:
cc-mini --model claude-3-5-haiku --max-tokens 2048Config files are loaded in this order:
~/.config/cc-mini/config.toml.cc-mini.tomlin the current working directory
The project-local file overrides the home config. Point to a specific file with --config.
Example:
[anthropic]
api_key = "sk-ant-..."
base_url = "https://your-gateway.example.com"
model = "claude-sonnet-4"Top-level keys are also supported:
api_key = "sk-ant-..."
base_url = "https://your-gateway.example.com"
model = "claude-3-7-sonnet"
max_tokens = 64000| Tool | Name | Permission |
|---|---|---|
| Read file | Read |
auto-approved |
| Find files | Glob |
auto-approved |
| Search content | Grep |
auto-approved |
| Edit file | Edit |
requires confirmation |
| Run command | Bash |
requires confirmation |
When the assistant wants to run a write or bash tool, you'll see:
Permission required: Bash
command: pytest tests/ -v
Allow? [y]es / [n]o / [a]lways:
y— allow oncen— denya— always allow this tool for the rest of the session
cc-mini includes Buddy, a Tamagotchi-style AI companion that lives in your terminal. Each user gets a unique pet determined by a seeded PRNG — same user always gets the same species, rarity, and stats.
> /buddy # Hatch your companion (first time)
> /buddy # Show companion card (after hatching)
> /buddy pet # Pet your companion
> /buddy mute # Mute companion reactions
> /buddy unmute # Unmute reactions
- 18 species: duck, goose, blob, cat, dragon, octopus, owl, penguin, turtle, snail, ghost, axolotl, capybara, cactus, robot, rabbit, mushroom, chonk
- 5 rarities: Common (60%), Uncommon (25%), Rare (10%), Epic (4%), Legendary (1%) — plus 1% shiny chance
- 5 stats (0–100): Debugging, Patience, Chaos, Wisdom, Snark — these shape how your companion talks
- ASCII sprite with idle animation (blinking, fidgeting) displayed in the terminal toolbar
- Automatic reactions: after each Claude response, your companion comments in a speech bubble
- Direct conversation: address your companion by name and it replies directly (with conversation memory)
> help me fix this bug
Found the issue — off-by-one error in the loop...
(×>) Glitch Honker: 又是越界，经典。
> Glitch 你觉得这代码怎么样？
(×>) Glitch Honker: 嘎，能跑就行，别问我这种哲学问题。
The companion's personality is generated by Claude on first hatch and persists permanently. Stats influence behavior: high Snark = sarcastic, high Patience = supportive, high Chaos = unpredictable.
src/core/
├── main.py # CLI entry point + REPL
├── engine.py # Streaming API loop + tool execution
├── context.py # System prompt builder (git status, date)
├── permissions.py # Permission checker
├── _keylistener.py # Esc/Ctrl+C detection
├── tools/
│ ├── base.py # Tool ABC + ToolResult
│ ├── file_read.py
│ ├── file_edit.py
│ ├── file_write.py
│ ├── glob_tool.py
│ ├── grep_tool.py
│ └── bash.py
└── buddy/
├── types.py # Data model: species, rarity, stats
├── companion.py # Mulberry32 PRNG + deterministic generation
├── sprites.py # ASCII art for 18 species (3 frames each)
├── animator.py # Real-time tick-based animation engine
├── render.py # Rich terminal rendering (cards, bubbles)
├── commands.py # /buddy command handler
├── observer.py # Post-response reaction generator
├── prompt.py # System prompt integration
└── storage.py # JSON persistence
pytest tests/ -v- Place a
CLAUDE.mdfile in your project root — it will be included in the system prompt automatically - Use
--auto-approvewhen running non-interactively or for trusted tasks - The REPL keeps conversation history within a session; each new run starts fresh
- Type
/buddyto hatch your AI companion — it watches your coding sessions and comments from the sideline