felixmanojh-minions

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)

1. Generate: Minion model creates code changes
2. AST Lint: Fast syntax check catches obvious errors
3. Validate: Second LLM checks task completion & preservation
4. Retry: On failure, error is sent back to minion to fix
5. 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

1. Install Ollama: brew install ollama or ollama.ai
2. 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: