https://github.com/microclaw/microcode
https://github.com/microclaw/microcode
Last synced: 18 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/microclaw/microcode
- Owner: microclaw
- License: mit
- Created: 2026-05-12T16:43:08.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-01T03:57:03.000Z (20 days ago)
- Last Synced: 2026-06-01T05:24:09.528Z (20 days ago)
- Language: Rust
- Size: 1.14 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# microcode
**A coding agent that stays out of your way.**
[](https://github.com/microclaw/microcode/releases)
[](LICENSE)
*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
```bash
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
```bash
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
```toml
[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`](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/.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`](USAGE.md) — Day-to-day reference.
- [`docs/architecture.md`](docs/architecture.md) — Module map and data flow.
- [`docs/design-journal.md`](docs/design-journal.md) — Why each decision was made, in order.
- [`docs/providers.md`](docs/providers.md) — Pointing microcode at any LLM endpoint.
- [`docs/tools.md`](docs/tools.md) — Tool catalogue.
- [`DEVELOPMENT.md`](DEVELOPMENT.md) — Build, test, layout, releasing.
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — How to send a patch.
## Releasing
Maintainer flow — single command, gated by a clean tree on `main`:
```bash
./deploy.sh --minor # bumps version, tags, pushes; CI builds + uploads
./deploy.sh --dry-run # preview only
```
[`.github/workflows/release.yml`](.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`](LICENSE).