Choosing your mode

Warpforge gives you three ways to start work: Single agent, Orchestrator and Factory. Picking the right one is most of the difference between an agent that saves you an afternoon and one that burns your quota producing a diff you throw away.

You don’t have to guess which is which: the composer draws what pressing Start will actually do — a strip of blocks showing the shape of the run. For Factory that’s the selected template’s real stages and round limit, not a stock illustration. For an orchestrator it’s explicitly an example, staffed from your own enabled harnesses, because the lead decides the split once it has read the prompt.

The short version:

Start with a single agent

A regular task is one agent in one conversation. It still gets the runtime tools, memory, and create_task — so “single” is not “limited,” it’s undivided.

Reach for it when:

• The work is one coherent change, however large — a feature, a refactor, a bug hunt.
• You want to steer as it goes. A conversation you’re watching beats a pipeline you’re waiting on.
• You don’t yet know the shape of the problem. Exploration is a conversation, not a plan.

This is the right answer far more often than it feels like it should be. Delegation has real overhead: the lead has to describe the work well enough for an agent with none of its context to do it. For a change one agent could have made directly, that description costs more than it saves.

Add an advisor to a single session

A single session can bring a second opinion along without turning into a pipeline. In New Task, turn on Advisor and pick its harness and model — usually the other one: Claude Code does the work and Codex advises, or the reverse, or a fast model works while a stronger one advises.

The agent doing the work gets one extra tool, ask_advisor, and is told to use it at three moments: before a big design decision, when it’s stuck after a couple of failed attempts, and before it declares the task done. It asks, the advisor answers, and the working agent decides what to do with the answer.

The advisor knows the task, not just the diff. A reviewer that only sees a diff can’t tell whether the change does what you asked. The advisor gets your opening message as the goal, and every question comes with what happened since the last one: your recent messages, the working agent’s recent messages, and the changed files — a few kilobytes, never the whole transcript. It works in the task’s own checkout, so it can open any file or run git diff itself. And it’s one conversation for the whole task, so it remembers what it said before.

It can’t change anything. Its requests to edit files or run commands are denied automatically, its harness is switched to read-only where it has such a mode (Codex’s read-only mode, Claude Code’s plan mode), and its Warpforge tools are the ones that only read.

Where you see it. Each consultation appears in the chat as a collapsed Asked advisor block — expand it for the question and the answer. The advisor’s own conversation stays out of your sidebar; open it from the block when you want to see how it got there. The task header shows which advisor the task has.

Reach for it when:

• One agent should do the work, but a decision in it deserves a second look.
• You want another model family’s view. Different models get different things wrong.
• You’d reach for a review pipeline, except the change is small enough that one pass of advice is enough.

Limits:

• Single sessions only — not orchestrators or pipelines.
• Three questions per turn of the working agent; a fourth is refused until its next turn.
• An answer that takes longer than 15 minutes is given up on, and the working agent carries on without it.
• If the advisor’s account is known to be out of quota, the question is refused rather than left to fail.
• It’s advice. Nothing checks that the working agent follows it.

Use an orchestrator when the work genuinely splits

Enabling Orchestrator turns the agent into a lead with 11 extra tools: it can spawn_agent, follow up with message_agent, and drain results with read_inbox — while you keep talking to it.

Reach for it when at least one is true:

• The parts are independent. Three endpoints, three files, three services — work that won’t collide.
• Different pieces want different harnesses. This is the one thing nothing else does: a Claude Code lead can put a Codex sub-agent on one piece and an opencode sub-agent on another, in the same task, and reconcile their results.
• The task is bigger than one context window. The lead spends its context coordinating; each sub-agent gets a fresh one for its own slice.

Don’t reach for it when:

• The parts touch the same code. Parallel agents editing one file is a merge conflict you asked for.
• You could have described the whole thing to one agent in a sentence. If the delegation prompt is longer than the change, delegate nothing.

Use Factory when review is the point

Factory runs a pipeline of fixed stages — plan? → implement → verify? → review ⇄ fix — and Warpforge drives the transitions, not a manager model deciding what to do next. Each stage is its own agent session with its own model, and review rounds repeat until approval or a configured limit.

Choose Factory in New Task, or start it from a backlog item — or from many at once. You pick the workflow template, whether an agent tests the change in the running app, where it runs, and whether it ends in a draft pull request.

Reach for it when:

• You want a second opinion by construction. The reviewer is a different session — often a different model — that did not write the code and is told not to edit files.
• The work is repeatable. Workflow templates are versioned YAML in .warpforge/workflows/, so the process travels with the repo instead of living in one person’s habits. Three ship with Warpforge; writing your own is a file, not a fork.
• The change is risky enough to be worth several times the cost. Which brings us to the tradeoff.

Commit or not is your choice. With Open a draft PR when done off, a finished Factory task commits nothing: it lands in Needs review with its chats, timeline, and diff intact. With it on, Warpforge commits the change on a fresh branch and opens a draft pull request for a person to review — it never merges. Either way it never loops forever: when it exhausts its review rounds with findings open, it stops and asks. See The Factory for everything the mode does.

Combining them

These aren’t exclusive. An orchestrator can spawn_workflow, so a lead handling a large feature can send the one risky piece through a full review pipeline while dispatching the routine parts as plain sub-agents.

That’s usually the shape of a big task done well: one lead, mostly single sub-agents, a pipeline where it matters.

A decision table

See also

• Agent tools (MCP) — exactly which tools each mode gets
• Orchestration and workflows — how delegation and pipelines work
• The Factory — everything Factory mode does, from the backlog to the draft pull request
• Tasks and backlog — where the work comes from in the first place