μ-code

Micro Coding Agent for Local LLMs

Single-file Node.js CLI • Zero dependencies • GitHub →

⚠ Beta — In active early development. The tool interface is 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 models act as architects, using their large context windows and strong reasoning to plan and map out changes; μ-code acts as the local worker, handling small, single-file, atomic tasks with 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.

      

        

          
Architect + Worker

          
Top-tier models plan and reason. μ-code executes atomic edits locally with fast open-weight models.

        

        

          
Zero Dependencies

          
Only Node.js core — no npm, no binaries beyond ripgrep. Runs anywhere Node 18+ does.

        

        

          
Future-Proof

          
Built for when token budgets tighten. Your local workflow is ready — no API fees, no rate limits.

        

      

    


    


    

      
Two Ways to Run

      
The same binary works standalone or as a delegated sub-agent.

      

        

          
Standalone CLI

          
Run mu interactively or one-shot with -p. You drive it directly — set goals, read/edit files, approve diffs.

        

        

          
Sub-Agent

          
Delegate from a host AI (opencode, Claude Code, Codex CLI) via the mu-code-delegate skill. Host reasons and plans; μ-code executes.

        

      

    


    


    

      
How It Works

      
μ-code gives the model four tools. Every mutation shows a diff and requires approval.

      

        

          
bash_exec

          
Shell commands — mainly rg -n to locate lines. 30s timeout, 10MB buffer.

        

        

          
read_file

          
Read text files by line range. Binary detection built in.

        

        

          
edit_file

          
Replace lines by number. LCS diff before approval. Never reproduces full files.

        

        

          
write_file

          
Write or append content. Creates directories automatically.

        

      

    


    


    

      
Agent Skills — Delegate to μ-code

      
Standard Agent Skills for the architect + worker pattern. Your host AI reasons; μ-code executes.

      

        

          
mu-code-delegateDelegate atomic edits. Host reasons, μ-code executes.

          
mu-code-configOne-time setup of ~/.mu-code/config.json.

        

      

      

        
Install to any tool supporting .agents/skills/:

  opencode · Claude Code · Pi · Codex CLI
  VS Code/Copilot · Cursor · Windsurf

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

Workflow:
  1. Host AI reasons — searches, plans, finds line numbers
  2. Host delegates — runs mu -g "goal" -p "instructions"
  3. μ-code executes — reads, edits, shows diffs
  4. Host verifies — checks result, moves to next step

      

    


    


    

      
Validated in Action

      
Architect + worker benchmarked on the same MiniKV task with three local models — 19/19 pytest tests pass, 0 lines written by the architect.

      

        

          
ornith:9b18m 24s · 2 bugs · ~50–65% token savings

          
gemma4:12b-mlx≈48 min · 0 bugs, clean 1st pass · ~50–60%

          
granite4.1:3b≈20 min · 3 bugs · ~55–65% pure / ~35–50% realized

        

      

      
Bigger models write cleaner code, but slower. μ-code offloads ~50–65% of billed main-context tokens — 100% locally.

    


    


    

      
Install

      

        

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

      

    


    

      
Quick Start

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

      

        

        
{
  "model": "llama3.2:3b",
  "ai_base_url": "http://localhost:11434/v1",
  "num_ctx": 8192,
  "auto_approve": false,
  "think": false
}

      

      
Then run mu -f src/main.go.

    


    


    

      
In-Session Commands

      

        

          
/goalShow current session goal

          
/goal <text>Update session goal

          
/debugShow estimated prompt token breakdown

          
/exit / /quitExit

          
```Multi-line input

        

      

    


    


    

      
Design Principles

      

        
Small Steps
One file, one concern, one tool call at a time.

        
Search with rg
No LSP or symbol index — just ripgrep.

        
Read What You Need
Tight line ranges after rg pinpoints the location.

        
Skeleton First
Write a skeleton, then fill in with edits.

        
Trust the Result
Never assume, never retry a failing call blindly.

        
No Long Tasks
No servers, watchers, or background processes.

      

    


    


    

      
Limitations

      

        
Single-File Ops
No project-wide crawling or multi-file orchestration.

        
Small Context
Designed for local models with 4k–8k context.

        
No LSP
Search is rg-only. No find-references or definitions.

        
macOS / Linux
No Windows support currently.