Retrieved article excerpt
Open article · Retrieved 2026-09-15T14:22:28.168445+00:00
Ordewell
**Turn one goal into an ordered plan of coding-agent tasks — each with its own runner, model and mode — then execute and verify it.**
[**Website**](https://ordewell.ai) ·
[Docs](https://ordewell.ai/docs.html)
[License: Apache-2.0](https://github.com/ordewell/ordewell/blob/main/LICENSE)
[npm](https://www.npmjs.com/package/@ordewell/cli)
[CI](https://github.com/ordewell/ordewell/actions/workflows/ci.yml)
[GitHub stars](https://github.com/ordewell/ordewell/stargazers)
[Ordewell's terminal UI: a goal is typed, the planner reads the repo and refuses a write, it asks whether the limiter should reuse the existing Redis client, then commits a seven-task plan — each task showing its runner, model, thinking effort and mode — and executes it to 7/7 complete.](https://github.com/ordewell/ordewell/blob/main/assets/readme/hero-plan-to-run.gif)
---
## What this is
- **A plan you can rewrite before a token is spent.** The plan is a typed artifact, not an agent's internal state: every task carries a runner, model, thinking effort and mode, and you can change any of them, add and remove tasks, and rewire dependencies — without losing completed work or round-tripping the AI.
- **The right model per task, chosen in the open.** The planner makes one portfolio decision across the whole plan — a security refactor and a README update do not deserve the same model — and shows you every assignment before anything runs ([why a separate planner?](https://github.com/ordewell/ordewell/blob/main/docs/why-a-separate-planner.md)).
- **Verdicts from evidence, not opinion.** A task completes only when its unique completion marker appears in the runner's output; exit code is retained as diagnostic evidence. The model is never the tie-breaker. Stuck tasks can be advanced with *Mark complete*, and a task marked done by mistake goes back with *Mark not done*.
- **A planner that talks back.** Planning is one continuous chat: it researches your repo read-only, asks when your goal is vague, and its final message *is* the plan ([ADR-0002](https://github.com/ordewell/ordewell/blob/main/docs/adr/0002-planner-as-conversation-loop.md)). Reads run in parallel; anything reaching outside the workspace asks once; commands that would write are refused outright ([ADR-0008](https://github.com/ordewell/ordewell/blob/main/docs/adr/0008-planner-exploration-envelope.md)).
- **No extra API key required.** Claude Code, Codex, or OpenCode can *be* the planner, strictly read-only, on the subscription you already hold for the runners ([ADR-0009](https://github.com/ordewell/ordewell/blob/main/docs/adr/0009-coding-agents-as-planners.md)).
- **Multi-runner by design.** Enable several and the planner assigns one per task. Claude Code, Codex and OpenCode ship built-in; anything else — Aider, your own CLI — is a plugin manifest, not a code change.
---
## Quick Start
Node.js ≥ 20 on macOS, Linux or Windows. The TUI also needs **tmux** — see
Platform support below.
```
npm install -g ordewell
ordewell # the TUI — chat on the left, plan on the right
```
That's it. First run asks for a planner and a runner, set from inside
(`/planner`, `/runners`, `/key`) — no restart, no API key required up front.
`npx ordewell` works the same without a global install; the package also
ships scoped as `@ordewell/cli`.
For VS Code instead, install the extension — it carries its own core, so
there is nothing to install from npm:
```
code --install-extension ordewell.ordewell
```
Or search **Ordewell** in the Extensions view.
Building from source:
`git clone https://github.com/ordewell/ordewell.git && cd ordewell && npm install && npm run build && npm link -w packages/cli`
— see [CONTRIBUTING.md](https://github.com/ordewell/ordewell/blob/main/CONTRIBUTING.md).
### Scriptable / headless
Every slash command is also a subcommand — set the planner and runner by env
var to skip the TUI entirely.
**Already run Claude Code, Codex, or OpenCode?** No separate API key — it
runs on the subscription you already hold:
```
export AI_PROVIDER="claude-code" # or codex, opencode
ordewell plan --goal "Add rate limiting to the public API" && ordewell run
```
Mutation always stays with the runners; the planner agent only explores and
reasons. Same toggles apply from a UI: `/planner`, `/model`,
`/planner-effort`, or the planner bar in VS Code.
**Prefer an API key?** Twenty-five providers are recognised via their own
`*_API_KEY` — OpenRouter, Anthropic, OpenAI, Gemini, xAI, Groq, DeepSeek,
Mistral, Together, Fireworks, Perplexity, Cerebras, DeepInfra, Cohere,
Novita, Kimi, Zhipu, Qwen, Doubao, Hunyuan, Baichuan, MiniMax, Yi, StepFun
and SiliconFlow. Run `ordewell key` for variable names, or point
`OPENAI_COMPATIBLE_BASE_URL` at anything else, including a local model
server.
```
export OPENROUTER_API_KEY="sk-or-..."
ordewell plan --goal "Add rate limiting to the public API" && ordewell run
```
---
## Three surfaces, one core
### VS Code
A streaming timeline: live thinking, each research step with its outcome, and task cards you expand for the runner's own output. Retarget a task's runner and its model and mode re-derive in place. The whole loop is below, under **The VS Code loop, end to end**.
### Terminal UI
[Ordewell's terminal UI split between the planner conversation on the left and a plan pane on the right showing seven tasks with per-task runner, model, effort and mode.](https://github.com/ordewell/ordewell/blob/main/assets/readme/tui-plan-pane.png)
Everything the extension does, over SSH. `tab` swaps chat and plan pane; single keys drive the plan (`f` start, `E` run all, `m` toggle done, `R` runner, `o` model). `/help` lists the rest.
### CLI
```
$ ordewell plan --goal "Add rate limiting to the public API"
Generating plan for: "Add rate limiting to the public API"...
✓ list_dir src → D middleware F router.ts F auth.ts
✓ grep X-RateLimit → no matches in 6 files
Question: should limits apply per API key, or per client IP?
My recommendation: per key — auth() already threads the key through req.ctx.
> per key, with an IP fallback for anonymous routes
Plan: 4 tasks (3 AI, 1 Manual) — claude-code, opencode
Session: session-1751600000000
1. [ AI] Add a token-bucket limiter in src/middleware/rateLimit.ts (Claude Sonnet 4.5 · Claude Code)
2. [ AI] Wire the limiter into route registration (Claude Haiku 4.5 · Claude Code)
3. [ AI] Return RFC 6585 429s with Retry-After (DeepSeek V4 Flash · Opencode)
4. [MAN] Document the limit headers in the OpenAPI spec
[MAN] = manual step — run `ordewell tui` to work through it
Run 'ordewell run' to execute, 'ordewell status' to inspect, or 'ordewell tui' for the full UI.
$ ordewell run
Executing plan...
✓ #a1b2 completed — PASS: Verified: completion marker detected in agent output. Task c
⟳ #c3d4 in_progress
[2/Wire the limiter into route registration] Started: claude-code / claude-haiku-4-5
Done. 4 completed, 0 failed, 0 blocked.
```
Every slash command is also an `ordewell` subcommand, so nothing is UI-only and headless automation reaches everything a human can.
---
## How it works
1. **Describe a goal** in plain prose.
2. **The planner researches** your workspace read-only and interleaves questions with research in one persistent conversation ([ADR-0008](https://github.com/ordewell/ordewell/blob/main/docs/adr/0008-planner-exploration-envelope.md)).
3. **A plan appears** — ordered tasks, each with a runner, model, thinking effort and mode. Edit anything inline, or reprompt to reshape the whole plan without losing completed work.
4. **Execution** spawns a real coding-agent session per AI task, respecting the dependency graph and handing each task its predecessors' results. Manual tasks become checklists.
5. **The VerdictEngine** completes a task only once its marker appears; an exit without one fails visibly. Sessions auto-save to `.ordewell/sessions/`.
---
**Usage examples** — planning, editing, multi-runner, plugins
**Plan, edit, execute**
```
# The planner researches the repo and converses if the goal is underspecified
ordewell plan --goal "Migrate the config loader from JSON to TOML"
# Reassign before running — runner first, since it re-derives model, effort and mode
ordewell task-runner 2 opencode
ordewell task-deps 3 1,2
# Execute; independent tasks run in parallel (default: 3 concurrent sessions)
ordewell run
# Inspect any session later
ordewell status --session-id session-1751600000000
```
The surfaces differ only in how you name a target: the TUI opens a picker, the CLI takes an argument — and omitting the argument prints the same options the picker would have shown.
```
ordewell task-model 3 # lists the models that task's runner can spawn
ordewell task-model 3 sonnet # picks one
```
**Configure without an editor**
```
ordewell planner claude-code # plan on a coding agent's subscription — no API key
ordewell model set sonnet # scoped to that agent's own catalog
ordewell planner-effort high # a variant of the selected model
ordewell key set openrouter sk-… # stored in .env, never echoed back
ordewell runners codex off
```
Each pushes to the running server *before* writing `.env`, so the change lands on the next plan with no restart — and a refused connection cannot leave the file holding a setting the daemon never saw.
**Deep-interview planning with a PRD**
```
ordewell grilling on # planner interrogates your goal before outlining (min. 3 probing questions)
ordewell prd on # planner previews, then writes a full PRD to .scratch/<slug>/PRD.md
ordewell tdd on # tasks are augmented with red-green-refactor instructions
ordewell plan --goal "Real-time collaborative editing"
# → the planner grills you in chat, drafts the PRD, waits for your OK,
# then commits the plan as its final message
```
**Multi-runner plans and custom runners**
```
# Pass --runner repeatedly to build a runner set; the planner assigns one per task
ordewell plan --goal "Refactor auth module" --runner claude-code --runner opencode
# Bring your own CLI agent via a plugin manifest
ordewell plugins create my-runner # scaffolds manifest.json
ordewell plugins install github:user/repo
ordewell plugins list
```
Remote plugin installs accept `https://` repositories on GitHub, GitLab,
Bitbucket and Codeberg; anything else must be cloned yourself and installed from
its local directory.
**The other two front ends**
```
ordewell # full-screen terminal UI — same as `ordewell tui`
ordewell web --daemon # the local API server, in the background
```
`ordewell web` starts the HTTP + WebSocket API on `127.0.0.1:3742` that the CLI and TUI are clients of — every other command starts it for you on demand. It serves JSON, not a web page; there is no browser dashboard yet.
For VS Code, install the extension and open the Ordewell panel — see Quick Start.
| Area | Commands |
| --- | --- |
| Planning | type a goal, `/approve`, `/run`, `/stop` |
| Tasks | `/add-task`, `/remove-task`, `/complete`, `/uncomplete`, `/skip`, `/retry`, `/cancel`, `/force-start` |
| Skills | `/grilling`, `/tdd`, `/prd`, `/verify` |
| Models | `/model`, `/key`, `/allowlist`, `/runners`, `/auto`, `/refresh` |
| Sessions | `/sessions`, `/new`, `/save`, `/load`, `/delete` — a loaded session is adopted by the server, so its plan stays executable |
| System | `/help`, `/mouse`, `/quit` |
API keys typed into `/key` are masked on screen and written to your `.env`.
The mouse wheel scrolls whichever pane the pointer is over — transcript or plan
— regardless of which one has keyboard focus, and `pgup`/`pgdn` scroll the
focused one. Capturing the mouse for the wheel is what disables the terminal's
own drag-to-select, so `/mouse off` hands it back when you need to copy text out
(remembered via `ORDEWELL_TUI_MOUSE` in your `.env`, and `ORDEWELL_TUI_MOUSE=false`
in the environment turns it off everywhere).
A task's own terminal is