Persistent memory for Claude Code. Also: loop detection, scope guards, code analysis, and a local LLM for second opinions.
Claude Code forgets everything between sessions and after context compaction. Mini Claude provides:
- Checkpoints - Save task state, auto-restore after compaction
- Mistake memory - Log errors, get warned next time you touch that file
- Decision memory - Log WHY you chose something
- Loop detection - Warns when editing same file 3+ times (death spiral)
- Scope guards - Declare allowed files, prevent over-refactoring
- Impact analysis - See what depends on a file before changing it
- Convention storage - Store project rules, check code against them
Runs locally with Ollama for semantic search and code analysis. No cloud, no API costs.
- Python 3.10+
- Ollama with
qwen2.5-coder:7b - Claude Code (VSCode extension or CLI)
# 1. Install Ollama and pull model
ollama pull qwen2.5-coder:7b
# 2. Clone and install
git clone https://github.com/20alexl/mini_claude.git
cd mini_claude
python -m venv venv
# Linux/Mac
source venv/bin/activate
# Windows (PowerShell)
.\venv\Scripts\Activate.ps1
# Windows (cmd)
venv\Scripts\activate.bat
pip install -e mini_claude/
# 3. Run installer
python install.pyThe installer creates launcher scripts and MCP configuration.
Don't delete the venv folder - VSCode runs Mini Claude from it.
Option 1: Use the installer
python install.py --setup /path/to/your/projectOption 2: Copy manually
- Copy
.mcp.jsonto your project root (required - tells VSCode where the MCP server is) - Copy
CLAUDE.mdto your project root (tells Claude how to use Mini Claude)
Mini Claude automatically tracks without you needing to call tools:
| What | How |
|---|---|
| Edits | Auto-logged after each Edit/Write. Shows "Edit tracked: file.py (edit #3)" |
| Tests | Auto-logged after pytest/npm test. Shows "PASS/FAIL Test tracked" |
| Mistakes | Auto-detected from common error patterns in failed commands |
Parallel LLM requests are automatically queued to prevent GPU contention.
| Tool | Purpose |
|---|---|
session_start |
Load memories, mistakes, checkpoint, last session context |
session_end |
Optional - shows session summary (memories auto-save) |
pre_edit_check |
Check mistakes, loops, scope before editing |
| Tool | Purpose |
|---|---|
memory(remember/search/clusters) |
Store and find discoveries |
work(log_mistake) |
Record error + how to avoid |
work(log_decision) |
Record choice + reasoning |
| Tool | Purpose |
|---|---|
context(checkpoint_save) |
Save task state for compaction survival |
context(checkpoint_restore) |
Restore after compaction |
context(verify_completion) |
Verify task is actually done |
| Tool | Purpose |
|---|---|
scope(declare) |
Set allowed files for task |
scope(check) |
Verify file is in scope |
loop(check) |
Check if editing too much |
| Tool | Purpose |
|---|---|
impact_analyze |
What depends on this file |
deps_map |
Map imports/dependencies |
scout_search |
Semantic codebase search (reads actual code) |
scout_analyze |
Analyze code snippet with LLM |
file_summarize |
Quick file purpose summary |
code_quality_check |
Detect AI slop |
audit_batch |
Audit multiple files |
find_similar_issues |
Find bug patterns |
| Tool | Purpose |
|---|---|
convention(add) |
Store project rule |
convention(check) |
Check code against rules |
code_pattern_check |
Check against conventions with LLM |
| Tool | Purpose |
|---|---|
output(validate_code) |
Check for silent failures |
# Different model
export MINI_CLAUDE_MODEL="qwen2.5-coder:14b"
# Remote Ollama
export MINI_CLAUDE_OLLAMA_URL="http://192.168.1.100:11434"- Check Ollama is running:
ollama list - Restart VSCode
- Check Claude Code → MCP Servers status
ollama serve
ollama pull qwen2.5-coder:7bClaude Code
│
├── MCP Server (Mini Claude)
│ │
│ └── ~/.mini_claude/ (state files)
│
└── Ollama (local LLM)
State is stored in ~/.mini_claude/ per project.
Report bugs or request features: https://github.com/20alexl/mini_claude/issues
MIT
