mini_claude

Mini Claude runs locally and provides persistent memory and tooling to reason about Claude Code projects. It integrates with Ollama for semantic search and code analysis, and exposes tools for session management, memory and work tracking, scope and loop protection, and code conventions. You can start a server instance per project and use the included MCP setup to wire it into your editor or developer workflow. The server tracks edits, tests, and mistakes automatically and uses a local LLM to provide second opinions and analysis without cloud calls.

To use the server and its tools, first ensure Ollama is running and the required model is available. Then start the Mini Claude MCP server via your normal MCP launcher (as configured in your project’s MCP setup). Within VSCode, you can rely on the installed launcher scripts to initialize sessions, load memories, and perform checks before editing. The toolset includes session_start and session_end for lifecycle management, memory and work tools for recording discoveries and mistakes, and a constellation of context protection and code analysis tools to keep changes aligned with project conventions and dependencies. In practice, you can run pre_edit_check before making edits, use impact_analyze and scout_search for code understanding, and apply convention(add)/convention(check) to ensure your code adheres to project rules. The architecture keeps state under ~/.mini_claude/ per project, so you can switch between tasks without losing memory between edits.

Prerequisites:

• Python 3.10+
• Ollama installed and running
• Claude Code (VSCode extension or CLI)

Steps:

# 1. Install Ollama and pull the model
ollama pull qwen2.5-coder:7b

# 2. Clone the repository and set up a Python environment
git clone https://github.com/20alexl/mini_claude.git
cd mini_claude
python -m venv venv

# Linux/macOS
source venv/bin/activate

# Windows (PowerShell)
.
venv\Scripts\Activate.ps1
# Windows (cmd)
venv\Scripts\activate.bat

# 3. Install the package in editable mode (per the README)
pip install -e mini_claude/

# 4. Run the installer to create MCP configuration and launchers
python install.py

The installer creates launcher scripts and the MCP configuration. Do not delete the venv folder since VSCode runs Mini Claude from it.

Configuration hints:

• If you want per-project setup, you can run the installer’s per-project flow or copy the .mcp.json and CLAUDE.md into your project as described in the README. The per-project setup ensures the MCP server location is known to your editor.

Tips and common issues:

• Ensure Ollama is running before starting Mini Claude. Use ollama list to verify; if needed, start Ollama with ollama serve and pull the model again with ollama pull qwen2.5-coder:7b.
• The state for each project is stored under ~/.mini_claude/. This keeps memories and checkpoints project-scoped.
• If you modify project files outside the editor, the auto-tracking features will still record edits after the next save.
• When configuring per-project settings, use the installer option or manually copy .mcp.json and CLAUDE.md to your project root to wire up MCP with VSCode.
• If you encounter connection issues, verify that MINI_CLAUDE_OLLAMA_URL points to the running Ollama instance and that the model is accessible.
• Use the pre_edit_check tool to catch issues such as loops, scope violations, or misconfigurations before applying edits.