Minions
Local LLM minions for mechanical code tasks — offload grunt work to your local Ollama models.
The Idea
Think of it like Gru and his Minions: Gru (Claude Code) handles the master plan — architecture, complex logic, decisions. The Minions (local LLMs) handle the repetitive grunt work — adding docstrings to 50 files, type hints across a module.
┌─────────────────────────────────────────────────────────────┐
│ Claude Code (Cloud) │
│ Planning • Strategy • Complex reasoning │
└─────────────────────────────┬───────────────────────────────┘
│ delegates mechanical tasks
▼
┌─────────────────────────────────────────────────────────────┐
│ Minions (Local) │
│ Docstrings • Type hints • Repetitive fixes │
│ Free • Private • On your hardware │
└─────────────────────────────────────────────────────────────┘
Why this split?
| Cloud (Claude Code) | Local (Minions) |
|---|
| Expensive tokens | Free (your GPU) |
| Best for reasoning | Best for grunt work |
| Complex decisions | Mechanical repetition |
| Smart but costly | Cheap and focused |
Use Claude for the hard stuff. Send minions for the rest.
What Minions Can Do
| Task | Works? |
|---|
| Add docstrings | Yes |
| Add type hints | Yes |
| Add comments | Yes |
| Rename variable (simple cases) | Yes |
| Files up to ~500 lines | Yes (32K context) |
| Anything requiring understanding | No |
Be honest: 7b models are limited. Minions handle repetitive mechanical tasks. No reasoning, no logic.
How It Works
Minions use a Generate → Validate → Retry pipeline:
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Generate │ ──▶ │ AST Lint │ ──▶ │ Validate │ ──▶ │ Apply │
│ (minion) │ │ (syntax) │ │ (LLM) │ │ (if ok) │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
│ │
└───── Retry ────┘
(with error)
- Generate: Minion model creates code changes
- AST Lint: Fast syntax check catches obvious errors
- Validate: Second LLM checks task completion & preservation
- Retry: On failure, error is sent back to minion to fix
- Apply: Only after validation passes
Failures are logged to ~/.minions/ for debugging.
Limits
| Constraint | Limit |
|---|
| File size | <500 lines (32K context, configurable) |
| Task type | Mechanical only (no logic, no reasoning) |
Installation
Prerequisites
- Install Ollama:
brew install ollama or ollama.ai
- Pull models:
ollama pull qwen2.5-coder:7b
ollama pull qwen2.5-coder:1.5b # for validation
Install Minions
git clone https://github.com/felixmanojh/minions.git
cd minions
python -m venv .venv
source .venv/bin/activate
pip install -e .
Interactive Setup
minions setup -i
Guides you through model selection and downloads.
Add Skills to Claude Code (Optional)
cp -r skills/* ~/.claude/skills/
Usage
Unified CLI
minions <command> [options]
Polish (Auto-Apply)
Add docstrings, types, comments — validated before applying:
# Add all polish (docstrings + types + headers)
minions polish src/foo.py --task all
# Just docstrings
minions polish src/foo.py --task docstrings
# Multiple files
minions polish src/foo.py src/bar.py --task types
# Dry run (preview without applying)
minions polish src/foo.py --task all --dry-run
# Skip validation (faster, less safe)
minions polish src/foo.py --task all --no-validate
# Use custom linter
minions polish src/foo.py --task all --lint-cmd "ruff check"
# More retries on failure
minions polish src/foo.py --task all --max-retries 3
Sweep (Codebase Scan)
Find and fix files missing documentation:
# Discover what needs work
minions sweep src/ --task docstrings
# Apply fixes to all discovered files
minions sweep src/ --task docstrings --apply
# Full sweep with backups
minions sweep . --task all --apply --backup
Patch (Manual Review)
Generate patches for review before applying:
minions patch "Add TODO comment at top" \
--target src/file.py \
--read src/file.py
# Review and apply
patch -p1 --dry-run < sessions/*.patch
patch -p1 < sessions/*.patch
Swarm (Batch Patch)
Same patch on multiple files in parallel:
