microcode

A coding agent that stays out of your way.

Silent inside your project. Asks only when leaving it. Runs cargo check after every edit.

---

Note

This is a test/experimental project. It is not actively maintained, and there are no plans to continue development for the foreseeable future. Feel free to explore the code, but don't expect updates, fixes, or support.

---

Install

curl -fsSL https://raw.githubusercontent.com/microclaw/microcode/main/install.sh | bash

That detects your OS/arch, pulls the latest release binary from GitHub, and drops it in ~/.local/bin (or /usr/local/bin if writable). Re-run any time to upgrade.

Or from source: cargo install --path .

30-second tour

cd path/to/your/rust/project
microcode init                                # one-time: writes .microcode/config.toml + MICROCODE.md
microcode                                     # interactive — runs setup wizard if no API key yet
microcode run "fix every clippy warning"      # one-shot
microcode -y run "rewrite the auth module"    # fully unattended (--skip-permission)

First run with no API key drops you into a wizard:

[1] Anthropic (Claude)        — direct API
[2] OpenAI                    — direct API
[3] OpenAI-compatible         — Together / Fireworks / OpenRouter / DeepSeek / ...
[4] Local (no API key)        — Ollama / vLLM / LM Studio

Pick one, paste your key (or skip for local models), and you're chatting.

Why microcode

Most coding agents prompt you on every mutating call. That makes sense for a foreign agent visiting your machine — but microcode is yours, running in your project. So it shouldn't ask twice.

Three opinionated bets, none of which are individually new, but which together feel different:

1. Permission by location, not by every call

Operation	Inside the project	Outside the project	With --skip-permission
read / ls / glob / grep	silent	silent	silent
write / edit	silent	prompts	silent
bash (cwd-scoped)	silent (subject to deny patterns)	n/a	silent

Hard deny patterns (bash:sudo *, bash:rm -rf /*) always win. The result: zero prompts during normal work, one prompt the moment something would touch a path outside your project root.

2. The Rust compiler is in the loop

Every write / edit on a .rs file automatically triggers cargo check --message-format=json -q. The diagnostics get appended to the same tool result the model just received — not at some later "now run tests" turn. The model never gets to forget it broke the build.

✓ edit src/auth.rs (1 replacement)

--- cargo verifier ---
cargo check FAILED (1.4s, 2 error(s))
  error: cannot find function `frobnicate` in this scope [src/auth.rs:42:5]
  error: mismatched types [src/auth.rs:18:9]

The system prompt tells the model: do not declare a task done while the verifier shows errors. Empirically, this kills the most common failure mode of every other agent — silently leaving a syntax error and continuing.

3. Bring your own model

[provider]
kind = "openai"
base_url = "http://localhost:11434/v1"   # Ollama — no auth needed
model    = "qwen3-coder:30b"

Anthropic + any OpenAI-compatible endpoint: OpenAI, OpenRouter, DeepSeek, Together, Fireworks, Groq, Ollama, vLLM, LM Studio. See docs/providers.md for cookbook entries.

Features

• Streaming responses. Text deltas render token-by-token.
• Cargo verifier hook — automatic on every .rs edit.
• Optional cargo test hook — opt-in, runs after N edits or on /test.
• /cost — live USD estimate using a built-in price table (override per-model).
• /fork, /switch, /branches — cheap in-memory conversation forks.
• MCP integration — any stdio MCP server, namespaced as mcp__server__tool.
• Per-session journal — .microcode/journal/<timestamp>.md, auditable.
• Project context — MICROCODE.md auto-injected into the system prompt.
• One static binary — ~6 MB, ~50 ms cold start, 9 runtime crates.

How it differs

	Claude Code	Codex CLI	Aider	microcode
Provider(s)	Anthropic	OpenAI	many	Anthropic + any OpenAI-compatible
Compiler in the loop	model decides	model decides	model decides	automatic for .rs edits
Default friction	per-call confirms	sandbox + approval	--yes flag	silent in-cwd, ask only on escape
MCP	yes	partial	no	yes (stdio)
Footprint	~390 MB	~140 MB	~80 MB	~30 MB

The trade is honest: microcode does less. It does what it does with more visible feedback.

Documentation

• USAGE.md — Day-to-day reference.
• docs/architecture.md — Module map and data flow.
• docs/design-journal.md — Why each decision was made, in order.
• docs/providers.md — Pointing microcode at any LLM endpoint.
• docs/tools.md — Tool catalogue.
• DEVELOPMENT.md — Build, test, layout, releasing.
• CONTRIBUTING.md — How to send a patch.

Releasing

Maintainer flow — single command, gated by a clean tree on main:

./deploy.sh --minor      # bumps version, tags, pushes; CI builds + uploads
./deploy.sh --dry-run    # preview only

.github/workflows/release.yml builds for aarch64-apple-darwin, x86_64-apple-darwin, x86_64-unknown-linux-gnu, and aarch64-unknown-linux-gnu on every v* tag, then attaches .tar.gz + .sha256 per target to the GitHub release.

License

MIT. See LICENSE.