Install

Terminal

npm install -g ordewell
ordewell                       # the TUI — chat left, plan right

ordewell with no arguments opens the terminal UI; with a subcommand it is the CLI. npx ordewell works without a global install, and the same package is also published scoped as @ordewell/cli if you prefer that name.

VS Code

code --install-extension ordewell.ordewell

Or search Ordewell in the Extensions view — Marketplace listing. The extension bundles its own core, so it needs nothing from npm.

Requirements

• At least one coding agent — Claude Code, Codex or OpenCode. These are what execute the tasks; see runners.
• No API key up front. A coding agent can be the planner too — see choosing a planner.
• Node.js 20 or newer for the CLI and TUI, on macOS, Linux or Windows. The extension needs only VS Code.
• tmux for the TUI on every platform — it backs each task's live terminal. See platform support.

Your first plan

Describe a goal in plain prose. The planner reads your workspace, asks about anything underspecified, and its final message is the plan.

In the TUI or the VS Code panel, type the goal into the input. The opening screen names the planner and the runners Ordewell found — change either in place with /planner and /runners, or from the settings bar in VS Code. Nothing needs a restart, and nothing needs to be exported first.

Headless, the same loop is two commands:

export AI_PROVIDER="claude-code"        # or codex, or opencode — no API key

ordewell plan --goal "Add rate limiting to the public API"
ordewell run

Nothing runs until you say so. Between plan and run the plan is a file you can rewrite — see editing the plan.

Choosing a planner

Planning and code generation are different workloads, so Ordewell lets you assign them separately. The planner researches and writes the plan; it never writes code.

Without an API key — the default

A coding agent you already hold a subscription for can be the planner. Pick it from /planner in the TUI, the planner bar in VS Code, or by subcommand:

ordewell planner claude-code     # or codex, or opencode
ordewell model set sonnet        # scoped to that agent's own catalog
ordewell planner-effort high     # a variant of the selected model

An agent that isn't installed is greyed out in the picker rather than offered and then failed. Harness planners are read-only by construction — --permission-mode plan, sandbox: read-only, agent: plan — and any permission request is auto-denied and answered, because to these agents an unanswered request is a hang rather than a refusal.

With an API key

Add one from /key in the TUI, or ordewell key set <provider> <key>; a key already in your environment is picked up as-is. Twenty-five providers are recognised, each from its 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, SiliconFlow — and the provider is auto-detected from which one is set. Run ordewell key to list them with their variable names.

Anything else that speaks the OpenAI API works too: set OPENAI_COMPATIBLE_BASE_URL (and a key, if it wants one), which is also how you point Ordewell at a local model server. The default planner model is a budget one — planning does not need your strongest model.

Each settings command pushes to the running server before writing .env, so the change lands on the next plan with no restart.

Editing the plan

The plan is a typed artifact, not an agent's internal state. Every surface can change any of it without a round-trip to the model.

Per-task assignment

Change things in the order runner → model → thinking effort → mode, because each choice constrains the next. Changing the runner is not a field write: the other three re-derive from the new runner's catalog, so a combination that cannot spawn is never saved.

ordewell task-runner 2 opencode
ordewell task-model 3            # lists what that task's runner can spawn
ordewell task-model 3 sonnet
ordewell task-deps 3 1,2

Plan shape

Add tasks, remove them, and rewire dependencies. Removing a task names the tasks it detaches rather than counting them. Dependencies point backwards in display order, so cycles are impossible to create at the edit site.

No surface reorders tasks, and that is deliberate: the orchestrator fans out every task whose dependencies are met, so display order never was the schedule. Dependencies are the lever.

Reprompting

After a plan exists the chat stays conversational. Ask for a change in prose and the planner emits a targeted edit; ask for something structural and it re-emits the whole plan. Completed work survives either. During execution, questions are answered live and structural edits queue to the next batch boundary.

Execution & verdicts

Each AI task spawns a real coding-agent session in a fresh context, handed its predecessors' review reasons and log tails. Independent tasks run in parallel — three at once by default, configurable to five. Manual tasks become checklists for you.

How a task passes

A task completes when its unique completion marker appears in the runner's output. Exit code is retained as diagnostic evidence. The model is never a tie-breaker, and there is no "the agent said it was done" path.

A stuck task can be advanced with /complete, and one marked done by mistake goes back with /uncomplete. Sessions auto-save to .ordewell/sessions/.

Optional review and verify passes

Review mode adds a final plan task that judges the work on spec and standards, for human sign-off. Verify mode adds one that runs the full suite and writes the missing spec checks — still judged by exit code.

Skills

Skills are prompt blocks Ordewell injects, not files it reads from your agent. Toggle them before you plan.

ordewell grill-me on
ordewell prd on
ordewell tdd on

Runners & plugins

Runners are external CLI tools, not internal APIs. Claude Code, Codex and OpenCode ship built-in. Enable several and the planner assigns one per task.

ordewell plan --goal "Refactor auth module" --runner claude-code --runner opencode
ordewell runners codex off

Adding your own

Anything else is a plugin manifest — a JSON file with {{variable}} and {{if …}} templating that describes how to invoke the CLI. No code change, no pull request.

ordewell plugins create my-runner        # scaffolds manifest.json
ordewell plugins install github:user/repo
ordewell plugins list

Surfaces

Four front ends, one core. They differ only in how you name a target — the TUI opens a picker, the CLI takes an argument.

ordewell           # the terminal UI (same as `ordewell tui`)
ordewell plan …    # any subcommand is the CLI instead
ordewell web       # HTTP + WebSocket API on 127.0.0.1:3742

VS Code is the fourth: code --install-extension ordewell.ordewell. The API server is what the CLI, TUI and extension are all clients of, and every other command starts it on demand — it serves JSON, not a browser dashboard.

Every slash command has an ordewell subcommand of the same name, held there by a parity test — so headless automation reaches everything a human can.

Configuration

Run ordewell --help for the full list, or ordewell setup for the interactive wizard. VS Code mirrors everything under ordewell.* settings.

Keys typed into ordewell key set or /key are masked on screen and written to .env, never echoed back.

Platform support

The TUI requires tmux everywhere, not only on Windows — it is what backs each task's live terminal. Install it from your package manager (apt install tmux, brew install tmux) before running ordewell. Everything else runs natively on Windows: the planner, task execution, model discovery and the read-only exploration envelope.

If a runner is greyed out right after you installed it, restart the VS Code window — a GUI-launched extension host holds the PATH it started with.

Architecture

core/    Pure TypeScript, zero UI deps — Session, PlanStore, Planner,
         TaskOrchestrator, VerdictEngine, ModelResolver, ModeResolver,
         RunnerRegistry + manifest template engine
cli/     ordewell: tui, plan, run, status, stop, web, models, setup,
         plugins — plus a pure state + renderer TUI core behind a thin
         raw-mode terminal driver
vscode/  Extension + webview: streaming planner timeline, task cards,
         TTY capture via script(1)
web/     Hono HTTP + WebSocket server (session pool, headless execution)

Every surface consumes one event union over one broadcast seam. The design decisions behind all of this — why the planner is a conversation loop, why verdicts dropped model review, how the exploration envelope is tiered — are written up as architecture decision records.