<div align="center">
  <img src="miii_logo.png" alt="miii" width="160" />
</div>

# miii

**The AI coding agent that runs on your machine. Not theirs.**

[![npm](https://img.shields.io/npm/v/miii-cli)](https://www.npmjs.com/package/miii-cli) [![license](https://img.shields.io/npm/l/miii-cli)](LICENSE)

```bash
npm install -g miii-cli && miii
```

---

Every cloud coding agent does the same thing: it takes your source code, ships it to a server you don't control, charges you per token, and calls it intelligence.

You have a machine on your desk with 32GB of RAM and a GPU that's been idle since you bought it.

Those two facts don't have to coexist.

**miii is the agent layer that belongs on your hardware.** Autonomous. Local. Free. Your code never leaves unless you decide it should.

---

## What it looks like

```
you: fix the token expiry bug in auth middleware

● Reading src/middleware/auth.ts to locate the expiry check.
  Read 142 lines

● Patching line 89 — < should be <=.
  ⚡ Permission Required
  ● update_file src/middleware/auth.ts
     - if (exp < Date.now() / 1000) {
     + if (exp <= Date.now() / 1000) {
  [A] Allow   [D] Deny

● Running tests to verify.
  ✓ 24 passed in 1.2s

Done — off-by-one in token expiry. Sessions now expire on the second boundary, not after.
```

You see the plan. You see the diff. You decide. Then it runs.

---

## Get started

```bash
# Local — free, offline, private (recommended)
ollama pull llama3.2
npm install -g miii-cli
cd your-project && miii

# Anthropic Claude
ANTHROPIC_API_KEY=sk-... miii

# OpenAI-compatible (OpenAI, Groq, Together, LM Studio, vLLM…)
miii → /config provider openai-compat → /config url → /config key
```

**Requirements:** 16 GB RAM minimum for a 7B local model. 32 GB or a dedicated GPU recommended.

---

## What makes it different

### It tells you what it's about to do

Before every tool call, miii narrates in one sentence — what it's doing and why. You see the intention before the action, a permission modal with a live diff, then the result. No silent batches. No surprises.

This isn't just UX polish. It's accountability built into the loop.

### It understands your code, structurally

miii builds a static call graph of your entire codebase — every function, class, and method, and every edge between them. No model. No network. Pure AST parsing.

```bash
/graph build         # 847 symbols, 1203 edges — done in <1s
/graph query "auth"  # auth → verifyToken → decodeJWT → hmacSha256
```

When a structural question comes up, the agent queries this graph first. A 7B model with a call graph reasons about architecture the way a 70B model does without one. Context beats parameters.

### It reads files like a surgeon

Most agents read the whole file and dump every token into context. miii reads a **window**: the imports, a focus region centered on the edit target, the file footer. Cuts land on function boundaries.

A 500-line file costs ~480 tokens — not ~2000. Pass `focus="functionName"` and the window snaps to exactly where the work is.

### It never loses your work

Every file edit is snapshotted before the write happens. If anything goes wrong — bad patch, wrong file, crashed session — press `Esc`. Every file touched in that run is restored to exactly where it was.

Snapshots survive crashes. You can undo after you've closed the terminal.

On top of snapshots, every successful edit auto-commits to a private shadow git repo. You get a full `git log` of every model change — readable, grepp-able, reversible.

```bash
/history    # model edit log as shadow commits
/undo       # revert the last one
```

### It adapts when it fails

When a patch fails — stale text, ambiguous match — most agents retry the exact same call. miii tracks failure count per `(tool, file)` pair. On the second failure it stops and injects:

> "Stop retrying. Re-read the file. Find the exact lines. One minimal change per call."

"Fix this 200-line function" auto-decomposes into "fix line 45 only."

### It sandboxes every shell command

Every `run_command` runs inside an OS-level sandbox. macOS: `sandbox-exec` — reads anywhere, writes only inside your project. Linux: `bwrap` — same boundary, optional network isolation.

The sandbox is defense-in-depth. You still approve every command. The sandbox is what catches the model if you approve something you shouldn't have.

---

## Extend it

**Hooks** — drop an executable at `.miii/hooks/<event>`:

| Event | When it fires | Exit nonzero to |
|---|---|---|
| `session-start` | TUI launches | — |
| `user-prompt` | Before input is processed | Block the prompt |
| `pre-tool` | Before any tool runs | Block the tool |
| `post-tool` | After a tool succeeds | — |

Format-on-save. Secret scanning. Custom approval flows. Audit logs. IDE bridge notifications. Your hooks, your rules.

**Skills** — a Markdown file or an npm package (`miii-skill-<name>`). Drop it in, get a slash command.

```bash
/skills install refactor-ts
/refactor-ts    # now available
```

**MCP** — configure any MCP server. Its tools appear in the agent's tool list automatically. No code changes.

---

## Commands

Type `/` to open the palette. `↑ ↓` to navigate. `Enter` to select.

### Planning

| Command | Action |
|---|---|
| `/plan <topic>` | Think through a goal before touching code |
| `/plan exec <task>` | Write the plan, you confirm, then it executes |
| `/plan:next` | Next concrete steps |
| `/plan:breakdown` | Decompose goal into subtasks |
| `/plan:review` | Critique — what's missing |
| `/plan:done` | Exit planning mode |

### Codebase intelligence

| Command | Action |
|---|---|
| `/graph build` | Build the symbol call graph |
| `/graph query <q>` | Walk callers + callees from a seed |
| `/graph status` | Symbols, edges, age |
| `/index build` | Build the semantic vector index |
| `/index search <q>` | Find code by meaning |
| `/index status` | Chunks, size, age |

Graph understands structure (who calls what). Index understands meaning (what does this do). Use both.

### Code

| Command | Action |
|---|---|
| `/refactor <goal>` | Multi-file refactor with per-file checkpoints |
| `/think <query>` | Deep research over files + web → synthesis |
| `/test [path]` | Run the test suite |
| `/watch` | Watch for file changes, auto-fix failures |

### Design

| Command | Action |
|---|---|
| `/design teach` | 7 brand questions → generates `DESIGN.md` |
| `/design <task>` | Implement UI using `DESIGN.md` as context |

### Git

| Command | Action |
|---|---|
| `/git review` | AI review of the current diff |
| `/git commit <msg>` | Stage all + commit |
| `/git log` | Summarize recent commits |
| `/git diff` | Show + explain the working diff |
| `/history` | Shadow-git log of model edits |
| `/undo` | Revert the last model edit |

### Sessions

| Command | Action |
|---|---|
| `/new` | Fresh session (saves current first) |
| `/compact` | Summarize history, extract facts to memory |
| `/sessions` | List saved sessions |
| `/session <name>` | Switch to or create a session |
| `/clear` | Wipe history in the current session |

### Config & model

| Command | Action |
|---|---|
| `/config` | Open the config picker |
| `/config provider <ollama\|anthropic\|openai-compat>` | Switch provider |
| `/config model <name>` | Set model |
| `/config key <api-key>` | Set API key |
| `/model <name>` | Hot-swap model mid-session, no restart |

---

## Config

`~/.config/miii/config.json` (global) or `.miii.json` (project, overrides global):

```json
{
  "provider": "ollama",
  "model": "llama3.2",
  "baseUrl": "http://localhost:11434",
  "streaming": false,
  "gitContext": true,
  "embedModel": "nomic-embed-text"
}
```

| Field | Default | Description |
|---|---|---|
| `provider` | `ollama` | `ollama` · `anthropic` · `openai-compat` |
| `model` | `llama3.2` | Model name for the chosen provider |
| `baseUrl` | `http://localhost:11434` | Ollama / OpenAI-compatible endpoint |
| `apiKey` | — | Anthropic or OpenAI key (stored `chmod 600`) |
| `streaming` | `false` | Stream tokens as they arrive |
| `gitContext` | `true` | Auto-inject git diff/status for code questions |
| `embedModel` | `nomic-embed-text` | Embedding model for `/index build` |
| `tavilyApiKey` | — | Enables `web_search` / `web_extract` |
| `sandboxShell` | `true` | OS-level shell sandbox |
| `sandboxAllowNetwork` | `false` | Network access inside the sandbox |

**Project instructions** — drop a `MIII.md` in your repo. miii walks from cwd to root and injects every match into the system prompt. Same mechanic as Claude Code's `CLAUDE.md`.

---

## Safety model

Every destructive action requires your approval. You see exactly what will change before it changes.

- **Permission modal** — every write, delete, move, and shell command shows a diff. Allow or Deny.
- **OS sandbox** — shell commands run inside `sandbox-exec` (macOS) or `bwrap` (Linux). Write access bounded to your project + `/tmp`.
- **Path guard** — rejects any path outside cwd, including symlink escapes.
- **Checkpoints** — pre-edit snapshot of every file touched in a run. `Esc` restores all of them instantly.
- **Shadow git** — full model edit history. `/undo` reverts one commit at a time, across sessions.
- **Timeouts** — `run_command` hard-stops at 30s. Output capped at 8000 chars, smart-truncated.
- **API key protection** — keys live at `~/.config/miii/config.json` with `0600` permissions. Warns if a key appears in a project file.

---

## Keyboard shortcuts

| Key | Action |
|---|---|
| `Enter` | Send |
| `Ctrl+J` | Insert newline |
| `↑` / `↓` | Navigate history |
| `Ctrl+A` / `Ctrl+E` | Line start / end |
| `Ctrl+W` | Delete word back |
| `Ctrl+K` | Kill to line end |
| `Ctrl+U` | Clear line |
| `Ctrl+←` / `Ctrl+→` | Jump word |
| `Esc` | Abort + roll back this turn's edits |
| `Ctrl+C` | Exit |

---

## Build from source

```bash
git clone https://github.com/maruakshay/miii-cli
cd miii-cli
npm install && npm run build && npm link
```

```bash
npm run dev    # tsx — no build step needed for dev
npm test       # vitest, 48 tests
```

Node 20.12+. CI runs on Node 20 and 22 for every push and PR.

---

## Architecture

`src/index.ts` mounts an Ink TUI. Submissions hit `useSubmit.ts`, which dispatches slash commands or calls `useRunLoop.ts`. The loop builds context (`src/prompts/SYSTEM_PROMPT.md` + memory + history), streams via `src/llm/stream.ts` (Ollama / Anthropic / OpenAI-compat), parses `<tool_call>` blocks through `src/parser/stream-parser.ts`, gates every write through a permission modal, snapshots files via `src/checkpoints/store.ts`, and executes tools from `src/tools/index.ts`. Context compacts at ~40k chars via `src/tasks/compactor.ts`.

---

### Case Study: Autonomous Local Patch Cycle

**Background**: A security-conscious engineering team refuses to ship source files to remote servers but still needs a cohesive autonomous agent to fix regressions, validate behaviour, and log every action.

**Approach**: miii coordinates the run loop with narration, a windowed read, structural graph queries, gated edits, and snapshots. The agent first answers the developer with a concise plan sentence, then reads the relevant focus window, queries the call graph for the affected function, opens a permission modal showing the diff, snapshots the touched files, and streams the patch to the chosen local provider (Ollama, Anthropic, or OpenAI-compatible). Every edit is gated so the engineer approves before the write, and every run automatically compacts context (via src/tasks/compactor.ts) and records a shadow git commit for traceability.

**Outcome**: The team obtains the same fidelity as a high-end remote agent without leaking code or tokens. Bug fixes complete with explicit permission, tests run automatically, artefacts stay local, and the narrated permission modal plus snapshots makeeach revision auditable and reversible.

MIT · [miii.in](https://www.miii.in) · [@maruakshay](https://github.com/maruakshay)
