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
- 6 built-in tools: file read, file edit, file write, 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 |
| Write file | Write |
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: Off-by-one again, classic.
> Glitch what do you think of this code?
(×>) Glitch Honker: If it runs, don't ask me philosophical questions.
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.
The assistant can remember information across sessions, and automatically consolidate memories over time.
Slash commands:
| Command | Description |
|---|---|
/remember <text> |
Save a note to the daily log |
/memory |
Show current memory index |
/dream |
Manually consolidate daily logs into organized topic files |
Auto-dream runs automatically after a turn when ≥ 24 hours and ≥ 5 new sessions have passed since the last consolidation. Configurable via --dream-interval, --dream-min-sessions, or --no-auto-dream.
Try it out:
# 1. Save some notes and manually consolidate
cc-mini --auto-approve
> /remember I prefer Python over JavaScript
> /remember Our project uses gRPC + PostgreSQL
> /dream # reads daily logs, creates topic files + MEMORY.md
> /memory # verify the memory index
# 2. Start a new session — the model should recall your preferences
cc-mini
> What do you know about my preferences?
# 3. Test auto-dream (default: 24h + 5 sessions, use flags to lower for testing)
# First, accumulate a few sessions:
for i in $(seq 1 3); do cc-mini "session $i"; done
# Then start with lowered thresholds:
cc-mini --dream-interval 0 --dream-min-sessions 1 --auto-approve
> hello
# Auto-dream triggers after the responseData is stored in ~/.mini-claude/ (memory in memory/, sessions in sessions/).
src/core/
├── main.py # CLI entry point + REPL
├── engine.py # Streaming API loop + tool execution
├── context.py # System prompt builder (git status, date, memory)
├── config.py # Configuration (CLI, env, TOML)
├── memory.py # KAIROS memory system (logs, dream, sessions)
├── commands.py # Slash command system
├── compact.py # Context window compaction
├── session.py # Session persistence (JSONL)
├── 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 - Use
/historyto list past sessions,/resumeto continue one - Memories persist across sessions in
~/.mini-claude/memory/; run/dreamto consolidate - Type
/buddyto hatch your AI companion — it watches your coding sessions and comments from the sideline