Mini Claude

1# Mini Claude
2 
3Persistent memory for Claude Code. Also: loop detection, scope guards, code analysis, and a local LLM for second opinions.
4 
5## What It Does
6 
7Claude Code forgets everything between sessions and after context compaction. Mini Claude provides:
8 
9- **Checkpoints** - Save task state, auto-restore after compaction
10- **Mistake memory** - Log errors, get warned next time you touch that file
11- **Decision memory** - Log WHY you chose something
12- **Loop detection** - Warns when editing same file 3+ times (death spiral)
13- **Scope guards** - Declare allowed files, prevent over-refactoring
14- **Impact analysis** - See what depends on a file before changing it
15- **Convention storage** - Store project rules, check code against them
16 
17Runs locally with Ollama for semantic search and code analysis. No cloud, no API costs.
18 
19## Install
20 
21### Requirements
22 
23- Python 3.10+
24- [Ollama](https://ollama.ai) with `qwen2.5-coder:7b`
25- Claude Code (VSCode extension or CLI)
26 
27### Steps
28 
29```bash
30# 1. Install Ollama and pull model
31ollama pull qwen2.5-coder:7b
32 
33# 2. Clone and install
34git clone https://github.com/20alexl/mini_claude.git
35cd mini_claude
36python -m venv venv
37 
38# Linux/Mac
39source venv/bin/activate
40 
41# Windows (PowerShell)
42.\venv\Scripts\Activate.ps1
43# Windows (cmd)
44venv\Scripts\activate.bat
45 
46pip install -e mini_claude/
47 
48# 3. Run installer
49python install.py
50```
51 
52The installer creates launcher scripts and MCP configuration.
53 
54**Don't delete the venv folder** - VSCode runs Mini Claude from it.
55 
56## Setup Per Project
57 
58**Option 1: Use the installer**
59```bash
60python install.py --setup /path/to/your/project
61```
62 
63**Option 2: Copy manually**
64- Copy `.mcp.json` to your project root (required - tells VSCode where the MCP server is)
65- Copy [`CLAUDE.md`](CLAUDE.md) to your project root (tells Claude how to use Mini Claude)
66 
67## Auto-Tracking
68 
69Mini Claude automatically tracks without you needing to call tools:
70 
71| What | How |
72|------|---------|
73| **Edits** | Auto-logged after each Edit/Write. Shows "Edit tracked: file.py (edit #3)" |
74| **Tests** | Auto-logged after pytest/npm test. Shows "PASS/FAIL Test tracked" |
75| **Mistakes** | Auto-detected from common error patterns in failed commands |
76 
77Parallel LLM requests are automatically queued to prevent GPU contention.
78 
79## Tools
80 
81### Session Management
82 
83| Tool | Purpose |
84|------|---------|
85| `session_start` | Load memories, mistakes, checkpoint, last session context |
86| `session_end` | Optional - shows session summary (memories auto-save) |
87| `pre_edit_check` | Check mistakes, loops, scope before editing |
88 
89### Memory & Work Tracking
90 
91| Tool | Purpose |
92|------|---------|
93| `memory(remember/search/clusters)` | Store and find discoveries |
94| `work(log_mistake)` | Record error + how to avoid |
95| `work(log_decision)` | Record choice + reasoning |
96 
97### Context Protection
98 
99| Tool | Purpose |
100|------|---------|
101| `context(checkpoint_save)` | Save task state for compaction survival |
102| `context(checkpoint_restore)` | Restore after compaction |
103| `context(verify_completion)` | Verify task is actually done |
104 
105### Scope & Loop Detection
106 
107| Tool | Purpose |
108|------|---------|
109| `scope(declare)` | Set allowed files for task |
110| `scope(check)` | Verify file is in scope |
111| `loop(check)` | Check if editing too much |
112 
113### Code Analysis
114 
115| Tool | Purpose |
116|------|---------|
117| `impact_analyze` | What depends on this file |
118| `deps_map` | Map imports/dependencies |
119| `scout_search` | Semantic codebase search (reads actual code) |
120| `scout_analyze` | Analyze code snippet with LLM |
121| `file_summarize` | Quick file purpose summary |
122| `code_quality_check` | Detect AI slop |
123| `audit_batch` | Audit multiple files |
124| `find_similar_issues` | Find bug patterns |
125 
126### Conventions
127 
128| Tool | Purpose |
129|------|---------|
130| `convention(add)` | Store project rule |
131| `convention(check)` | Check code against rules |
132| `code_pattern_check` | Check against conventions with LLM |
133 
134### Validation
135 
136| Tool | Purpose |
137|------|---------|
138| `output(validate_code)` | Check for silent failures |
139 
140## Configuration
141 
142```bash
143# Different model
144export MINI_CLAUDE_MODEL="qwen2.5-coder:14b"
145 
146# Remote Ollama
147export MINI_CLAUDE_OLLAMA_URL="http://192.168.1.100:11434"
148```
149 
150## Troubleshooting
151 
152### MCP Server Not Connecting
153 
1541. Check Ollama is running: `ollama list`
1552. Restart VSCode
1563. Check Claude Code → MCP Servers status
157 
158### Ollama Not Running
159 
160```bash
161ollama serve
162ollama pull qwen2.5-coder:7b
163```
164 
165## Architecture
166 
167```text
168Claude Code
169    │
170    ├── MCP Server (Mini Claude)
171    │       │
172    │       └── ~/.mini_claude/ (state files)
173    │
174    └── Ollama (local LLM)
175```
176 
177State is stored in `~/.mini_claude/` per project.
178 
179## Issues
180 
181Report bugs or request features: https://github.com/20alexl/mini_claude/issues
182 
183## License
184 
185MIT
186