Phase-gated orchestration for agent tasks
npm install @weldr/runr> Autopilot for AI-driven dev work: run tasks end-to-end, and when something breaks, stop cleanly with the next 3 best actions.
``bash
npm install -g @weldr/runr
runr init --demo
cd runr-demo
npm install
The demo creates a self-contained TypeScript project with three tasks: success, a failure that stops with next actions (then
), and a scope guard stop.Runr is language-agnostic. The demo is JS/TS because it's the fastest proof. Other languages work by swapping verification commands (e.g.,
pytest -q for Python, go test ./... for Go).---
In your own repo
`bash
npm install -g @weldr/runr
runr init --pack soloStart work
runr run --task .runr/tasks/example-task.mdIf it stops, do the obvious next thing
runr continueInspect what happened
runr report latest
`What happens when it fails
Runr doesn't "keep going and hope." It stops with receipts and 3 next actions you can trust:
- continue — auto-fix what's safe, then resume
- report — open the run receipt: diffs + logs + timeline
- intervene — record manual fixes so they don't become black holes
That's the whole UX: keep momentum, keep receipts, never lose your place.
The mental model
- Autopilot: run work in milestones with phase gates (plan → implement → verify → review)
- Recovery: save checkpoints so you can resume from the last verified state
- Runs: capture diffs, verification logs, and interventions automatically
Quick links
- Why Runr?
- Hybrid Workflow
- CLI Reference
- Configuration
---
How it works
Runr orchestrates AI workers through phase gates with checkpoints:
PLAN → IMPLEMENT → VERIFY → REVIEW → CHECKPOINT → done
↑___________| (retry if verification fails)
- Phase gates: the agent can't skip verification or claim false success
- Checkpoints: verified milestones are saved as git commits
- Stop handoffs: structured diagnostics with next actions
- Scope guards: files outside scope are protected
> Status: v0.7.x — Hybrid workflow with provenance tracking. Early, opinionated, evolving.
---
Try it: Hello World
bash
cd dogfood/hello-world
npm install
runr run --task .runr/tasks/add-farewell.md --worktree
`Complete walkthrough in dogfood/hello-world/README.md.
---
Meta-Agent Mode
The easiest way to use Runr: one command, zero ceremony.
Best for: longer tasks, multiple milestones, and hands-off recovery.
Runr works as a reliable execution backend for meta-agents (Claude Code, Codex CLI). The meta-agent operates Runr for you — handling runs, interpreting failures, and resuming from checkpoints.
bash
Initialize with Claude Code integration
runr init --pack solo --with-claudeLaunch meta-agent with workflow context
runr meta
`The agent will automatically:
- Follow workflow rules from
- Use safety playbooks from
- Have , /runr-submit, /runr-resume slash commands availableTip: start from a clean tree.
runr meta blocks if you have uncommitted changes.---
Direct CLI Usage
Tip: start from a clean tree (commit or stash first).
`bash
Install
npm install -g @weldr/runrInitialize
cd /your/project
runr init --pack soloRun a task
runr run --task .runr/tasks/example-feature.md --worktreeSubmit verified checkpoint
runr submit --to dev
`---
Configuration
Create
:`json
{
"agent": { "name": "my-project", "version": "1" },
"scope": {
"allowlist": ["src/", "tests/"],
"denylist": ["node_modules/**"],
"presets": ["vitest", "typescript"]
},
"verification": {
"tier0": ["npm run typecheck"],
"tier1": ["npm test"],
"tier2": ["npm run build"]
}
}
`Tiers run from fast → slow. Keep
as a quick sanity check.$3
Don't write patterns by hand:
`json
{
"scope": {
"presets": ["nextjs", "vitest", "drizzle", "tailwind"]
}
}
`Available:
, react, drizzle, prisma, vitest, jest, playwright, typescript, tailwind, eslint, env---
CLI Reference
| Command | What it does |
|---------|--------------|
|
| Show status and next actions |
| runr run --task | Start a task |
| runr continue | Do the next obvious thing |
| runr report | View run receipt: diffs, logs, timeline |
| runr resume | Resume from checkpoint |
| runr intervene | Record manual work |
| runr submit | Submit verified checkpoint |
| runr meta | Launch meta-agent with workflow context |
| runr init | Initialize Runr in a repo |
| runr runs bundle | Generate evidence bundle |
| runr tools doctor | Check environment health |---
Task Files
Tasks are markdown files:
`markdown
Add user authentication
Goal
OAuth2 login with Google.Requirements
- Session management
- Protected routes
- Logout functionalitySuccess Criteria
- Users can log in with Google
- Session persists across refreshes
`---
Stop Reasons
When Runr stops, it tells you why:
| Reason | What happened |
|--------|---------------|
|
| Task finished. Ship it. |
| verification_failed_max_retries | Tests failed too many times |
| guard_violation | Touched files outside scope |
| review_loop_detected | Reviewer kept requesting same changes |
| time_budget_exceeded | Ran out of time |Every stop produces structured diagnostics with next actions.
---
Philosophy
This isn't magic. Runs fail. The goal is understandable, resumable failure.
This isn't a chatbot. Task in, code out.
This isn't a code generator. It orchestrates generators.
Agents lie. Logs don't. If it can't prove it, it didn't do it.
---
Development
`bash
npm run build # compile
npm test # run tests
npm run dev -- run --task task.md # run from source
``See CONTRIBUTING.md.
Apache 2.0 — See LICENSE.
---
Shipping beats rerunning the same milestone twice.