μ-code — Micro Coding Agent for Local LLMs

⚠ Beta Notice: μ-code is in active early development. The tool interface is functional and stable, but CLI options and config flags may refine before v1.0.

Why μ-code?

Frontier API tokens feel practically infinite today, but that won't last forever. As AI dev tools scale, token budgets, strict rate limits, and shrinking free tiers are bound to become standard enterprise policy.

What's more, local models are far more capable than their size suggests — especially with MLX acceleration on Apple Silicon. Even a 3B model is fast enough to breeze through these smaller tasks, so there's no reason to spend a frontier token on them at all.

μ-code was built around a simple split:

• Top-tier frontier models should act as architects. Use their large context windows and strong reasoning to plan, break down feature requests, and map out changes.
• μ-code acts as the local worker. It takes those small, single-file, atomic execution tasks and handles them using fast, open-weight local models.

We're building and battle-testing μ-code today so that when strict token caps hit, your local workflow is already locked in. Zero API costs, zero rate limits, and no context bloat for small file edits.

Install

curl -L https://raw.githubusercontent.com/hrhrprasath/mu-code/main/mu -o /usr/local/bin/mu && chmod +x /usr/local/bin/mu

Requires Node.js >= 18. Make sure /usr/local/bin is in your PATH (it is by default on macOS and most Linux distributions).

Or use the install script to set up the binary and deploy skills to ~/.agents/skills/:

git clone https://github.com/hrhrprasath/mu-code.git
cd mu
./install.sh

Prerequisites

• Node.js >= 18
• ripgrep (rg) — recommended. Used by the model for file search. Install with brew install ripgrep, apt install ripgrep, or see official docs.
• An OpenAI-compatible API running locally (Ollama, llama.cpp, mlx, vLLM).

Quick start

Create ~/.mu-code/config.json:

{
  "model": "llama3.2:3b",
  "ai_base_url": "http://localhost:11434/v1"
}

Then run:

mu -f src/main.go

A short goal is asked at startup — it's pinned into every request so the model never drifts.

Usage

mu [options] [--file <path>]...

Flag	Description
-f, --file <path>	Preload a file into context (repeatable)
-g, --goal <text>	Set session goal directly (skip interactive prompt)
-p, --prompt <text>	Run a single prompt non-interactively and exit
--think	Enable reasoning mode (for Qwen3, deepseek-r1, etc.)
-v, --version	Show version
-h, --help	Show help

Standalone CLI or Sub-Agent

μ-code works both ways — same binary, no separate install:

• Standalone CLI — run mu interactively, or one-shot with -p. You drive it directly like any terminal agent: set a goal, read/edit files, approve diffs.
• Sub-Agent — delegate from a host AI (opencode, Claude Code, Codex CLI, etc.) via the mu-code-delegate Agent Skill. The host does all the reasoning and planning; μ-code executes each atomic step.

Pick whichever fits the moment: drive it yourself for quick edits, or hand it to a bigger model as its local worker.

How it works

μ-code gives the model four tools:

Tool	Purpose
bash_exec	Run shell commands (mainly rg -n to locate lines)
read_file	Read a file, optionally by line range
edit_file	Replace lines by line number
write_file	Write or append a whole file

The loop:

1. Model gets your request + session goal
2. Model calls tools in sequence — search with rg, read specific lines, edit by line number
3. Every edit/write/bash call shows a diff and requires your approval
4. History is aggressively trimmed to fit small context windows

Key design choices:

• One file at a time — no project-wide crawling, no LSP, no symbol index
• Line-number editing — the model never needs to reproduce whitespace from memory. rg finds the line, read_file shows it, edit_file replaces it by number
• Safety by default — every mutation shows a diff and requires approval; auto_approve: true skips the y/N gate but still always shows the diff
• Zero dependencies — only Node.js core modules (fs, path, readline, child_process)
• Built for small models — aggressive context trimming, small tool outputs, one atomic action per turn

Agent Skills — use μ-code as an executor

μ-code ships with two Agent Skills for the architect + worker pattern:

Skill	Purpose
mu-code-delegate	Delegate atomic edits to μ-code. The host AI reasons and plans; μ-code executes.
mu-code-config	One-time setup — creates ~/.mu-code/config.json and verifies the model.

Install them to any AI tool that supports the .agents/skills/ standard (opencode, Claude Code, Pi, Codex CLI, VS Code/Copilot, Cursor, Windsurf):

./install.sh   # prompts where to install skills

Workflow

1. Host AI reasons — searches codebase, plans the change, determines exact file paths and line numbers
2. Host delegates — runs mu -g "<goal>" -p "<precise edit instructions>"
3. μ-code executes — reads files, edits lines, runs bash, shows diffs for approval
4. Host verifies — checks the result, moves to next step

From any AI coding tool

Once skills are deployed to .agents/skills/, host tools will auto-discover them. When you mention μ-code, the tool will follow the skill instructions — keeping all reasoning on its side and only delegating execution to μ-code.

Test Results — architect + worker in action

μ-code was validated with the architect + worker pattern: opencode (deepseek-v4-flash-free) acted as architect and delegated every coding step to μ-code, which ran a local Ollama model. The same MiniKV task was run three times, swapping the local code-generation model. All three runs produced 0 lines written by the architect and passed 19/19 pytest tests.

Metric	ornith:9b	gemma4:12b-mlx	granite4.1:3b
Wall-clock time	18m 24s	≈ 48 min	≈ 20 min
Modules correct on 1st pass	3/5	5/5	3/5
Code bugs generated	2	0	3
Main-model tokens (pure delegation)	~11.5K	~13.6K	~11K
Main-model tokens (incl. fixes)	~11.5K	~17.4K	~20.3K
Main-context savings	~50–65%	~50–60%	~55–65% pure / ~35–50% realized

Key takeaways:

• Bigger models = cleaner code, but slower. gemma4:12b produced all 5 modules right the first time (0 bug-fix rounds) yet was ~2× slower than ornith. granite4.1:3b was fastest but dropped a method, misplaced files, and mangled an edit_file into a literal \n string.
• The architect is the quality gate. Every bug was caught by the architect on read-back — μ-code has no self-correction loop. With small models, use absolute paths + full-file write_file and verify everything.
• Token offload works across models. ~50–65% of main-provider (billed) context is saved by moving codegen to the free local model; every bug-fix round roughly halves the realized savings.
• Privacy is preserved. All code generation ran 100% locally; nothing was uploaded.

Full reports: ornith:9b · gemma4:12b-mlx · granite4.1:3b. Recommendation: use a 10–12B model (e.g. gemma4:12b-mlx) when correctness matters; a 3B model only for trivial one-file tasks.

Configuration

μ-code reads config from ~/.mu-code/config.json. All fields are optional.

{
  "model": "llama3.2:3b",
  "ai_base_url": "http://localhost:11434/v1",
  "num_ctx": 8192,
  "auto_approve": false,
  "think": false,
  "tool_output_char_limit": 3000,
  "max_tool_iters": 12,
  "max_dangerous_per_turn": 6,
  "repeated_error_limit": 3,
  "max_reads_per_turn": 5,
  "context_token_budget": 6000,
  "history_keep_turns": 4,
  "file_token_limit": 4000,
  "max_goal_chars": 300
}

Key	Default	Description
model	(required)	Model name (e.g. llama3.2:3b)
ai_base_url	http://localhost:11434/v1	OpenAI-compatible API endpoint
num_ctx	null	Context window size
auto_approve	false	Skip y/N confirmation gate
think	false	Enable reasoning mode
tool_output_char_limit	3000	Per-tool output cap (chars)
max_tool_iters	12	Max tool calls per turn
max_dangerous_per_turn	6	Max edit/write/bash confirmations per turn
repeated_error_limit	3	Bail out after this many tool errors in a row
max_reads_per_turn	5	Max read_file calls per turn
context_token_budget	6000	Estimated tokens sent per request
history_keep_turns	4	User turns retained in context
file_token_limit	4000	Per-file preload token budget
max_goal_chars	300	Max session goal length

Environment variables override the config file when set. The same keys work in UPPER_CASE (e.g. MODEL, AI_BASE_URL, NUM_CTX, AUTO_APPROVE).

Security: If your ai_base_url includes an API key, restrict the config file with chmod 600 ~/.mu-code/config.json.

Commands

Command	Description
/goal	Show current session goal
/goal <text>	Update session goal
/debug	Show estimated prompt token breakdown
/exit or /quit	Exit
``` ... ```	Multi-line input (paste code blocks)

Design principles

• Small steps, small reads, small edits — one file, one concern, one tool call at a time
• Search with rg only — no LSP, no symbol lookup, no "find references"
• Read only what you need — tight line ranges after rg pinpoints the location
• Skeleton first — for new files, write a minimal skeleton, then fill in with focused edits
• Trust the tool result — never assume, never retry the same failing call blindly
• Never start applications — no servers, watchers, or long-running processes

Limitations

• Single-file operations — no project-wide crawling, refactoring, or multi-file orchestration. One file, one concern, one step at a time.
• No LSP / symbol index — search is rg-only, scoped to specific files or narrow directories.
• Small context windows — designed for local models with 4k–8k context. Not a Cursor / Copilot replacement.
• Line-range editing — the model edits by line number, not by semantic understanding. It never reproduces full files from memory.
• Linux / macOS only — no Windows support currently.
• auto_approve: true gives the model unrestricted file and shell access — the model can read, write, or delete any file your user owns. Use only in sandboxed or trusted environments.

License

Apache 2.0