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, or open the 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 run the tasks; see runners.
• No API key up front. A coding agent can be the planner too; see choosing a planner.
• Node.js 20.3 or newer for the CLI and TUI, on macOS, Linux or Windows. The extension needs only VS Code.
• git for task isolation. Without a git repository Ordewell still works, and every task runs directly in your folder; see isolation.

Your first plan

Describe a goal in plain prose. The planner reads your workspace, asks about anything underspecified, and then hands you 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, and in a git repository the repositories and branches code tasks will run on. Change the planner and runners in place with /planner and /runners, or from the Settings panel 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 yours to rewrite; see editing the plan. To skip review, turn autorun on in /settings; each plan then starts as soon as the planner submits it. See run settings.

Choosing a planner

Planning and writing code 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. /planner walks harness › model › effort in one flow, in the TUI and in VS Code. From a shell, the same steps have their own headless commands:

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. Agent planners are started read only (Claude Code with its edit and shell tools withheld, Codex in a read-only sandbox, OpenCode on its plan agent), and any permission request is 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 it is. 25 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 and SiliconFlow. The provider is detected from whichever 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, because planning does not need your strongest model.

Each planner, model and effort 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 going back to the model.

Assigning each task

Change things in the order runner → model → thinking effort → mode, because each choice constrains the next. Changing the runner is not a simple field write: the other three are worked out again from the new runner's catalog, so a combination that cannot start is never saved.

ordewell task-runner 2 opencode
ordewell task-model 3            # lists what that task's runner can start
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 a cycle cannot be created 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 makes a targeted edit; ask for something structural and it writes the whole plan again. Completed work survives either. An edit now applies as the call answers: the change is committed, saved and on every surface while the planner is still replying, each call a batch applied whole or not at all, and a change stays even if the reply is then stopped or fails, never sent a second time to be made twice. While tasks run, edits apply at once to tasks that have not started and are refused, with a reason, for a running or finished one; a whole new plan is refused while tasks run.

Rewind, fork and compact

The planner conversation can be steered too, and none of this touches your tasks or your code.

• /rewind copies the conversation up to just before a message you pick into a new session, and hands that message back so you can edit and resend it. The original session is kept whole, so /sessions gets you back.
• /fork carries on in a copy of the conversation and its tasks, leaving the original as it was.
• /compact condenses the planner's live context into a summary it writes, keeping the last two exchanges word for word. Nothing is removed: the transcript keeps every message, on disk and on screen, /rewind still reaches past the summary, and a failed or stopped compaction changes nothing. A second /compact condenses the first summary and what followed it, never the messages it already stands for.
• Automatic compaction (an API planner) budgets every call before it is sent: past 90% of the model's known window, older tool output is pruned to stubs and the older conversation is condensed into a checkpoint, announced in the turn. A model whose window no catalog states is sent whole and compacts nothing ahead of a call.
• A call that still cannot fit pauses the planner instead of failing the turn: its input is held, nothing runs twice, and tasks keep going. Retry compaction, as /compact retry in the TUI, ordewell compact retry, or the bar above the composer in VS Code, opens the held turn again and tries to condense and carry it on. /stop drops the turn; a turn whose calls already changed something is never restarted from scratch.

On the command line they are ordewell rewind [n], ordewell fork, ordewell compact and ordewell compact retry. Automatic compaction is a settings-file switch, plannerAutoCompaction, on until you turn it off; no settings panel offers it, and /compact works either way.

Execution & verdicts

Each AI task starts a real coding agent session in a fresh context, handed the handoffs of the tasks it depends on. Independent tasks run in parallel, five at once by default; change that in /settings, even mid-run (see run settings).

Kinds of task

• Change tasks edit code, each on its own branch; see isolation.
• Read-only tasks: a review, an audit, an analysis whose deliverable is its report. Ordewell defines them the same on every runner: the task keeps its runner's own read tools, its only shell is Ordewell's own command tool, and what the command rules would ask about or refuse runs sealed instead, with the workspace read-only, the task's own worktree writable, no network, no home directory, and nobody asked. That is what lets it run the test suite or try a fix. Its runner's own write and shell tools are withheld, its web reads go through Ordewell's fetch and web_search, and it lands nothing: the worktree is thrown away when it ends, and the result is its report, or the patch it saved of its worktree.
• Research tasks are read-only tasks whose report is addressed to the planner. When one ends, passed or not, the planner wakes with the report at every supervisor level, Off included; see below.
• Script tasks have no runner and no model. Their body is a list of commands, run in order with no shell and stopping at the first that fails, or one script for the planner's own interpreter. Ordewell runs it itself where it runs an ops task: at the workspace root, behind a merge gate when it depends on change tasks, and never during Merge all. Ten minutes is the time limit unless the task sets another. Only the planner writes the body, and the consent is to it as written: the approval card shows the exact commands or script, the effect allowlist can pre-approve one, and an edited body needs consent again.
• Ops tasks (a deploy, a cloud CLI call, a push) change no repository files and run in your own checkout. One that depends on change tasks waits until their work is merged into your branch. Flip a task with /task-ops, or O in the TUI.
• Manual tasks become checklists for you.

How a task passes

A task completes when its runner reports it done: a task_complete call to Ordewell's own tool server, bound to that attempt. Exit code is kept as diagnostic evidence. The model is never a tie breaker, and there is no "the agent said it was done" path. The one exception is a script task: it has no runner to make the call, so its exit status is handed to the verdict engine in place of one. A running task shows Completion received the moment the report lands, while the attempt winds down; what passes and what lands is decided after that.

A stuck task can be advanced with /complete, and one marked done by mistake goes back with /uncomplete. /skip gives up on a failed, blocked or waiting task without landing anything it did; its dependents go ahead without it. A failed task blocks only its dependents, and retrying it or skipping it continues them. Sessions save themselves to .ordewell/sessions/.

Check-and-fix loops

An "until it passes" goal is a loop, declared on the task that judges the work. That task names a body, the tasks that fix what it finds, and Ordewell runs the rounds itself: the check runs; while it fails with rounds left, the body runs on the latest landed work, each fix given the check's latest report, and then the check runs again. Three rounds unless the plan sets another, at most ten.

• A pass ends the loop. Body tasks that never ran end skipped as not needed, and the check's dependents go on.
• Between rounds the check is not a failure. It blocks none of its dependents, wakes no supervisor and does not end the run; the surfaces show it as fixing, round 2 of 3, rather than failed.
• Out of rounds, it fails once. The check ends failed, body tasks that have not run are skipped, its dependents are blocked, and the supervisor hears one event saying how many rounds it ran.
• A body task that fails stops the loop until it is retried and passes. Retrying the check starts a new set of rounds.

The plan's approval covers a loop's rounds: a fix approved once runs every round without asking again, and a script task's consent is to its body as written. A loop can also be a script task checked by another script, a migration followed by the schema test, say. The planner plans one only when the goal says "until it passes" or names a gate worth checking independently; routine tests and self-review stay inside the implementation tasks, and tests that already exist never become a loop.

A loop is not the supervisor adding rounds by re-planning: it is a declaration in the plan, so the rounds run at every supervisor level, Off included, they spend no planner turn, and the supervisor hears about the loop once, at the end.

Research tasks

A long investigation used to be a long planner turn, with the conversation held shut while it ran. Now the planner marks the piece that must decide something as a research task, a read-only task with a self-contained brief, and the conversation stays yours. When the task ends, passed or not, its report opens a planner turn at every supervisor level, Off included: the planner asked for that report, so supervision is not the question.

The planner decides how many research tasks a message starts, and may start more from a report turn, so a report, then new research, then its report can carry on with no message from you. There is no fixed budget for a message; the bounds are the planner's judgement, the run's Parallel limit they share with every other task, and your Stop. A research task starts without asking (nothing it does lands), and remains a row in the plan with its log, usage and stop like any task. The planner keeps brief lookups in its own turn; evidence a later task will act on is an ordinary read-only task that task depends on, so the findings reach it in its handoff instead of being re-typed.

Working with a running task

• Open it with Enter on its row or /open <id> to read its log live and type to it. A message waits for the runner's current step; ctrl-s (Ctrl+Enter in VS Code) sends it now. ctrl-x stops the runner's turn.
• Its runner's own commands work in the task's chat: / completes the commands and skills the runner reported, and /compact is the runner's own compaction.
• A checkpoint or tool request makes the task wait for you. Type directions and press Enter, or ctrl-y to approve as is; from anywhere, /checkpoint <id> approve|reject.
• A usage limit pauses the task until the reset the runner names (Claude Code and Codex do), then it resumes in the same session. r or Resume now resumes it early.
• A finished task can be picked up again in its saved session with /continue <id> <message>.

Every attempt records its tokens, reported cost and wall time per model, shown in the task view and by ordewell status. If an agent stops to ask something Ordewell must not answer for it, such as Claude Code's folder trust prompt, the task says it is waiting for you and where to answer, instead of looking busy forever. What the footers draw from those records, and the account windows beside them, is under usage & account limits.

Usage & account limits

Two different measures sit in one compact footer, in the same order on every surface: the context meter first, then the selected account's own windows, then the cost the runner reported. In VS Code the planner's row carries a Planner prefix, so it reads Planner ctx 61k (6%); a task log draws the same meter without it. Window shares read like 5h 24% used · Weekly 61% used.

The account windows are the runner's own, not Ordewell's estimate. Ordewell asks each installed runner's account the way that runner's own clients do, on a short-lived process that starts no model and no turn: Codex over its app-server for the ChatGPT plan's five-hour and weekly windows; Claude Code over its usage request; and OpenCode Go with no process at all, reading the one login OpenCode would pay for a Go model with from OpenCode's own store and asking only OpenCode's fixed quota addresses. A workspace that sets its own CLAUDE_CONFIG_DIR or CODEX_HOME gets the account it chooses, because the reads run with the workspace's environment.

The planner footer shows only the account of the planner you selected, and OpenCode Go only while a opencode-go/… model is selected, since Go's limits meter those models and nothing else OpenCode runs. A task log shows only its own runner's, live whichever attempt is on screen. A window's reset time, the plan name and when the read was taken are in the row's hover, not the row.

The numbers stay honest by omission. A read that fails keeps the last good one, marked (stale); an account that is signed out, unsupported or not installed draws nothing; a service throttling the read is a failed read, never a full window; and a percentage is shown only as reported, so an unknown share is not a zero. Nothing here is saved with a plan, restored after a reload, summed into the usage ledger, or used to pause work: a usage-limit pause comes from the runner's own message, described under working with a running task.

Automatic compaction is a planner measure, not an account one; see rewind, fork and compact.

Run settings

How a run starts, is watched and merges is yours, not the plan's. /settings walks them all in one panel in the TUI; in VS Code they are the Run block of the chat's Settings panel. The headless CLI keeps one command per value for scripts; the TUI and VS Code set them in the panel.

Two values are not rows in the panels, and are set only from a shell or by editing the settings file: the supervisor's wake-up read budget (ordewell supervisor reads <n>), how many reads one wake-up may make, 12 by default, and the Planned-with line (ordewell trailer off), described under the Planned-with line. Everything else in this table has its row in both panels.

A change applies at once to the session you make it in, and to other sessions from their next run. Parallel is kept in .env; the rest machine-wide in ~/.ordewell/settings.json. Only you change them: no planner tool can, and the panel never reaches the planner. Choosing Act or turning autorun on asks you to confirm first. The TUI's status row and VS Code's plan bar show the current values.

Headless, the same values:

ordewell auto guarded
ordewell supervisor act          # or: supervisor retries 3, supervisor reads 20
ordewell automerge on
ordewell autorun on
ordewell parallel 8
ordewell trailer off             # set only here or in settings.json

The supervisor

A research task's report is not a wake-up: the planner asked for that report, so it arrives at every level, Off included. The level decides what happens to the run's own events:

• Off: the planner speaks only when you write.
• Watch (default): it wakes on a failure, a task waiting for you, an idle task, a landing conflict, a stopped automatic merge, a usage-limit pause, a loop that ran out of rounds, or the end of the run, reads what it needs and writes you a note.
• Act: it may also run, stop, retry and skip tasks, message runners, deny approvals, edit the plan and merge, without asking.

It decides what to do next, never whether a task passed, and it can deny a runner's request but never allow one. Each wake-up is a planner turn, so it uses the planner's usage. Guards keep Act from looping: an identical retry is refused, and more than six wake-ups in 30 minutes with no task passing drops the run to Watch.

Isolation & handoff

In a git repository, every AI task runs in its own worktree on its own branch, not in your checkout. Tasks that edit the same files can run side by side without overwriting each other, and nothing reaches the branch you have checked out until you ask for it.

The opening screen shows the shape of that before anything runs: the repositories and branches code tasks will run on, whether a tree has uncommitted changes to tracked files, and what tasks share live. The TUI's first frame and VS Code's empty state draw the same notice. It is a read, not a start: no session is opened, nothing is created, and it is read again when you return to the window or change the configuration; the base branch is read again when a run starts.

How work lands

A task that passes is committed and merged into one integration branch for the run, lowest plan number first. Its dependents only start once its work is on that branch, so they build on the real result rather than on a guess.

Worktrees link your node_modules, .env files and agent config from the checkout. Your own workspace packages resolve to the worktree's code, everything else to the shared install. If a project needs something else prepared, set worktreeSetupCommand.

The Planned-with line

The merge commits Ordewell makes end with one line, a git trailer: Planned-with: Ordewell. It is on by default, and it is not a row in the settings panels: turn it off with ordewell trailer off, or with "plannedWithTrailer": false in the settings file. Commits a coding agent made itself are not touched.

When a merge conflicts

The task first gets a chance to repair it: it runs again in its kept worktree, on its own runner, model and mode, and is asked to merge the latest integration branch in so both sides' intent survives. The repair only counts if its branch really contains that work, no conflict markers are left, and the normal landing then goes through cleanly.

If it does not, the task waits for you with the conflicting files named. Resolve it by hand and mark it complete, retry it, or add a task that resolves it. A failed repair never halts the run and never overturns the task's own pass. conflictRepairAttempts sets how many tries a task gets (2 by default, 0 to turn repair off).

The handoff

At the end of a run you decide what happens to it:

ordewell handoff review          # the run's diff
ordewell handoff merge           # onto your checked out branch
ordewell handoff discard         # throw the run away
ordewell handoff cleanup         # remove worktrees and task branches, keep the run's branch

/handoff in the TUI and the handoff card in VS Code offer the same four. After a merge that takes everything, the run's worktrees and branches are cleared away.

You don't have to wait for the end: whenever landed work is not on your branch yet, the TUI's plan pane counts it (/handoff merge) and VS Code shows a Merge all button. With merge automatically on in /settings, Ordewell does this for you at each merge gate and at the end of the run. A Merge all asked for after the run's own merge has already taken everything answers that there is nothing left to merge.

Uncommitted changes to tracked files hold a run back until you stash them or choose to run without isolation: ordewell run --stash or ordewell run --without-isolation.

A folder of repositories

Open a folder that holds several independent repositories and each task gets a workspace laid out like the folder: a worktree of every repository at its usual path, all on one branch name, so relative paths between them keep working. A task lands in every repository it changed or in none. Merge all works the same way: every repository merges, or none does and you are told which one stopped it and why.

Repositories directly inside the folder are found on their own. List others, or pick a subset, with workspaceRepos. Loose files beside the repositories are shared live with every task, and the planner is told about them so it does not have two tasks editing one at the same time.

Skills

A skill is a folder with a SKILL.md file in the open Agent Skills format: a short description, then instructions. A planner skill guides the planning conversation; a task skill guides the agent working on one task. Keep your own in ~/.ordewell/skills/, or in a workspace's .ordewell/skills/, which is committed so your team shares it.

Type /name anywhere in a message to the planner. Your text is sent as you wrote it, with the skill's instructions beside it. These come built in:

The planner attaches task skills to the tasks that need them, and Ordewell puts their text into the task's prompt when it starts, on every runner. In VS Code they are chips on each task card; in the TUI press K on a task. From a shell:

ordewell skills                     # every skill this workspace sees
ordewell task-skills a1b2 tdd       # attach a task skill to a task

The full guide to writing skills is in docs/skills.md.

The grilling, spec and architecture workflows are adapted from Matt Pocock's skills.

Runners

Runners are external command line 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

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. The exceptions are TUI-only commands such as /mouse, and /settings, whose rows have their own headless commands: ordewell auto, supervisor, automerge, autorun and parallel. /planner walks the same steps as ordewell planner, ordewell model and ordewell planner-effort.

Configuration

Run ordewell --help for the full list, or ordewell setup for the interactive wizard. VS Code mirrors everything under ordewell.* settings. Supervisor, merging and autorun are not environment variables; see run settings. Automatic compaction is not one either: it is "plannerAutoCompaction": false in the settings file, on until turned off, and no panel offers it.

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

Each project's own environment

However Ordewell was started (a desktop launcher, another directory, a server already running for a different project), the planner and every task's agent get the project's own variables. They come from its .envrc when direnv is installed and you have allowed it, then from an untracked .ordewell/env file of KEY=value lines, which wins.

That makes it easy to give a project its own Claude Code account: put a CLAUDE_CONFIG_DIR in either file. A blocked .envrc, an .ordewell/env that git tracks, and variables that change how processes load (PATH, NODE_OPTIONS, LD_PRELOAD and friends) are never applied, and you are told once per run. ORDEWELL_DIRENV=false leaves direnv out.

Version check

The CLI and the VS Code extension check for a new release once a day. The request to ordewell.ai carries the version you run and a random install ID, replaced every 30 days. The ID is kept in ~/.ordewell/version-check.json and shared by both surfaces. Nothing else about you or your work is sent. Like any server, it sees your IP address. The CLI may show a one-line update notice; the Marketplace handles extension updates.

On the first start, Ordewell shows a one-time notice and sends nothing. The first check happens on a later start. If it cannot record the notice, it shows no notice and sends nothing; a check that cannot write its state does not send a request either.

To turn it off, set ORDEWELL_NO_VERSION_CHECK=1 or DO_NOT_TRACK=1. Turning off VS Code's telemetry stops it for the extension too. While disabled, the check sends no request and writes no install ID.

What is sent, what is kept and how long for is under Privacy.

Privacy

Ordewell runs on your machine. Your code, prompts, plans, task output and credentials stay on your machine or in the runner accounts you already use. Nothing you build is uploaded to ordewell.ai.

The version check

The daily version check is the only request Ordewell sends on its own: your version and a random install ID, described under Version check. The ID derives from nothing on your machine and is replaced every 30 days. The request carries no cookie, file names or account details, though ordewell.ai sees your IP address. Every other request Ordewell makes is one you, your planner or a task asked for.

Before the first request, Ordewell shows a notice and sends nothing. ORDEWELL_NO_VERSION_CHECK=1 or DO_NOT_TRACK=1 turns the check off before anything is written: no notice, no install ID, no request. The VS Code extension also follows VS Code's telemetry setting.

What the counts hold

Each check writes the day, the version and a SHA-256 hash of the install ID to Cloudflare Analytics Engine, which keeps it for three months. The IP address is not written to that dataset. Cloudflare hosts ordewell.ai and this site and processes those requests on Ordewell's behalf.

This website

The site uses Cloudflare Web Analytics for cookieless page counts. No advertising or cross site trackers run here.

Platform support

No tmux needed. Every runner is driven through its own protocol. The CLI and VS Code extension run natively on Windows. The terminal UI has not been verified natively; use WSL for it.

If a runner is greyed out right after you installed it, restart the VS Code window. An extension host launched from the desktop holds on to the PATH it started with.

Most Windows support is tested on Linux through platform seams. On a Windows host, only npm-installed runner launches have been measured; a full run from goal to merge has not been watched end to end. Whether Codex's read-only sandbox is enforced and %VAR% expansion on the cmd.exe shim route remain open. The planner's shell has no OS sandbox on Windows and relies on its command rules alone. See troubleshooting and Windows support.

Architecture

core/    Pure TypeScript, zero UI deps: Session, PlanStore, Planner,
         TaskOrchestrator, VerdictEngine, ModelResolver, ModeResolver,
         RunnerRegistry
cli/     ordewell: tui, plan, run, status, stop, web, models, setup,
         skills, 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, how a folder of repositories is isolated) are written up as architecture decision records.