Review what the AI plans to do before it touches your code. Then prove it did it.
RunWield is a coding harness that makes the agent slow down at the moments that matter. It sorts your request by risk, writes a plan you actually review when the blast radius is real, executes it through specialized roles, and refuses to call the work done until CI and a separate reviewer agree it matches the plan you approved.
ideate -> plan -> execute -> record -> use records to plan better
Install · How it works · Documentation
curl -fsSL https://raw.githubusercontent.com/gandazgul/runwield/main/install.sh | bashThen, from your project root:
wldFirst run asks you to connect a model — a subscription login or your own API key. RunWield works with any provider. Then
run /init once to let it explore the repo and build project context, and just say what you want:
> fix the failing parser test
macOS and Linux, installs to ~/.local/bin, no root required.
For full setup: model provider auth, runtime helpers, running from source, etc check out the Quickstart Guide.
I'm looking for five developers to try RunWield on one real, non-trivial change. I'll personally help you get running, fix anything that blocks you within a day, and give you a direct say in the roadmap. Try it with me →
Most coding harnesses optimize for getting an agent typing as fast as possible. Chat, and hope.
So the expensive part is never the typing. It's the moment you're staring at a 40-file diff, trying to reverse-engineer what the model thought it was building, and deciding whether to spend an hour reviewing it or an afternoon redoing it. You never got to say "no, not like that" while it was still cheap. And when you finally merge, everything you learned along the way evaporates — the next session starts from zero and makes a version of the same mistake.
1. You review intent, not just diffs. For anything non-trivial, a Planner agent writes a plan before an Engineer writes code. You review it in a real browser UI — inline comments, revisions, approval — not by squinting at a wall of chat. Redirecting a plan costs a sentence. Redirecting a finished branch costs a day.
2. Ceremony scales with risk. Every request is triaged into one of six intents, and only the expensive ones get the expensive treatment:
| Your request | What happens |
|---|---|
| "how does auth work here?" | Inquiry — Guide just answers. No plan, no ceremony. |
| "should we move to event sourcing?" | Ideation — Ideator researches, interviews you, produces a PRD. |
| "bump the deps and update the lockfile" | Operation — Operator does it directly. No code implementation. |
| "fix the failing parser test" | Quick fix — Engineer implements, then CI has to pass. |
| "add SSO to the admin panel" | Planned Change — bug, feature, or refactor. Planner writes a plan → you approve → Engineer executes → full validation. |
| "migrate the billing system" | Project — Architect designs an Epic, Slicer decomposes it with you into shippable Planned Changes. |
How much ceremony the work gets is tracked separately from what kind of work it is. A gnarly bug that needs a real plan is still recorded as a bug fix, not quietly relabeled a feature.
3. "Done" is proven, not asserted. This is the part most harnesses skip. When an Engineer says it's finished, RunWield doesn't believe it:
- Mechanical validation runs your project's real CI. Failures go back to the Engineer for bounded repair attempts, not an apology.
- Semantic review then runs in narrowing rounds — two full plan-vs-diff reviews, then verification-only passes. Findings are tracked in a Review Issue Ledger across rounds and repaired by a separate agent working in fresh context, so nothing gets rationalized away by the model that wrote it.
- Merge proof. Plan work runs in a linked git worktree, and the plan is only marked
verifiedafter Git itself confirms the sealed implementation commit reached your target branch. Not because an agent said so.
4. Your project remembers. Every finished plan produces a Work Record — what changed, why, what was rejected along the way. Combined with searchable project memory, PRDs, and ADRs, the next planning session starts from what you already learned instead of from an empty context window.
You type wld "add rate limiting to the public API". Then:
- Router classifies it as a Planned Change and hands off to Planner.
- Planner investigates the repo and writes a plan to
plans/. - You review it in the browser — comment, request changes, approve. Iterate as many times as you want. Nothing has touched your code yet.
- Engineer executes the approved plan in an isolated git worktree.
- CI runs. Failures get bounded repair attempts.
- Reviewer compares the final diff against the plan you approved, over multiple narrowing rounds, with findings carried in a ledger until they're resolved.
- Merge-back is verified by Git, and the plan flips to
verified. - A Manual QA checklist and a Work Record are generated automatically, so the reasoning survives the PR.
Every one of those steps is a place you can interrupt, redirect, or stop. That's the whole idea.
Yes, if you work on codebases where a bad change is expensive, you want to steer before code exists instead of after, and you're tired of "done!" meaning "the model stopped typing."
Probably not, if most of your work is quick one-shot edits. RunWield would be more ceremony than you need — Pi or another lightweight harness will be faster and you'll be happier.
I'm looking for five developers to run RunWield on one real, non-trivial change — not a toy repo, not a demo.
In exchange: I'll personally help you get set up, fix whatever blocks you, and you get a direct line into what gets built next.
RunWield is built on Pi and ships as a single compiled binary.
- CLI + TUI — Deno, pure JavaScript with JSDoc typing -> Moving to TypeScript.
- Plan review — a browser UI powered by Plannotator.
- Code intelligence — Cymbal.
- Memory — Mnemosyne for project and global memory.
- Workspace UI — Astro + React, local-first (binds to
127.0.0.1with a per-server token by default). - Extensible — layered agent definitions, prompt templates, skills, and themes, overridable per project or per user.
- ACP-compatible, so external clients can drive sessions.
The agent roster:
| Agent | Purpose |
|---|---|
| Router | Default triage. Classifies the request and routes it. |
| Guide | Answers questions and explains the codebase. Cites your durable artifacts instead of making things up. |
| Ideator | Researches and sharpens fuzzy ideas into a PRD. (Inspired by Grill Me from Matt Pocock) |
| Operator | Direct repository and environment work, no code implementation. |
| Planner | Writes reviewable plans for Planned Changes. |
| Architect | Designs larger projects as Epics. |
| Slicer | Decomposes an approved Epic into shippable child Planned Changes. |
| Engineer | Implements approved plans and bounded quick fixes. |
| Frontend Engineer | Implements browser UI work, autonomously or via pair programming checkpoints. |
| Reviewer | Compares the final diff against the original plan. |
| Recorder | Writes the durable Work Record after completion. |
Everything RunWield owns lives under ~/.wld/ (sessions, settings, global instructions, overrides). Everything about
your project stays in your repo as plain markdown: plans/, .wld/, CONTEXT.md. No lock-in, no database, all
greppable.
Documentation: full docs index · usage · plans and workflows · settings · customization · collaboration · troubleshooting
deno task cli "your request" # run from source
deno task ci # check, lint, format, tests
deno task compile # build the binaryBranch, keep changes focused, run deno task ci, and open a PR with a summary and validation notes. The codebase is
mostly pure JavaScript with JSDoc typing -> moving to TypeScript. See contributing and
RELEASING.md.
RunWield is source-available and free to use, but it is not open source yet.
You may install, run, inspect, and use RunWield for personal, internal, or commercial work. You may also submit issues and pull requests.
You may not distribute modified versions, publish derivative works, rebrand RunWield, or offer it as a competing product or service without prior written permission.
RunWield includes third-party dependencies, including Pi and Plannotator-related packages, which remain under their own license terms.
See LICENSE.