Subagents and workflows

Subagents let the model hand a task to a separate agent that works in the background; workflows let it run a script that fans work out to many of them at once.

Turn them on

Open More options → Conversation settings, or press ⌘⇧, (CtrlShift, on Windows).
On the Tools page, in the Agent orchestration group, turn on Subagent (agent_spawn) and Workflow (workflow).

The built-in mework preset has both on.

Subagents

When the model calls agent_spawn, Mework starts a child agent in the background and the model's turn carries on. A child is one-shot: once started, nothing can message or redirect it.

A child sees only its task, unless the model attaches a copy of this conversation or its role has a conversation template. It has the conversation's workspaces and tools (or its role's), except agent_spawn, workflow, ask_user, fork and the plan and handoff tools. Its system prompt ends with the subagent.addendum text, which you can edit in Prompt profiles.

A subagent has no round or time limit. It works until it gives its final reply or you stop it, and only that reply is capped: anything past 64 KiB is cut off.

How many run at once

A conversation runs up to 8 background tasks at once, counting subagents, workflow runs and background commands together. While 8 are running, starting another is refused until one of them finishes. The one exception is a command that reaches its timeout: it still moves to the background, even past the limit. A finished task frees its slot right away, whether or not its result has been collected.

Approval

Under Manual, each new subagent and each workflow run asks for approval. Under Accept edits only workflow runs ask, and under Full access neither does. Every tool call a child or workflow step makes is then checked under the conversation's security level.

How results come back

The model gets a child's final reply when it waits with task_wait, or otherwise between rounds, as a Delivered a background result card. If the conversation is idle when a task ends, however it ended, the agent starts a new turn right away to read the result, whether or not the conversation is on screen; the conversation's row in the sidebar shows it working.

Agent roles

A role is a named setup of model, reasoning effort, tools, skills, MCP servers, hooks, web backends and opening history. The main agent picks a role by name for a subagent or workflow step, and never sees or changes the model behind it.

Roles are on Conversation settings → Agent roles, and on the same page of a preset's settings. They are saved with the conversation and copied from its preset; there are no role files. No model on a role means its model cannot be found, for example because its provider is off; the role is hidden from the main agent until the model is back.

Allow role-less subagents, below the list, is off by default. While it is off and a usable role exists, every subagent and workflow step must name a role.

The role window

Role settings: Role name is what the main agent picks, and Subagent description tells it when to. Execution model and Reasoning effort follow the conversation by default.
Tools: follows the conversation's tools until you change a row; then the role keeps its own list.
Advanced tools: the role's web search and fetch backends and their result settings.
Skills, MCP and Hooks: the same lists as the conversation's own pages. Each follows the conversation's selection until you change a row; then the role keeps its own. A role that picks its own MCP servers gets all of their tools, whatever its Tools list says. How skills and MCP schemas reach the model follows the conversation's Load skills on demand and Tool discovery. A subagent runs only hooks before and after a tool call, on a permission request and on instructions loaded.
Conversation template: the child's opening history. If its user messages hold exactly one {input}, the task replaces it; otherwise the task is added as the last user message. Workflow steps do not use it.

A role's settings are not part of the conversation's prompt cache, so nothing on these pages is locked: a change applies to the next subagent the conversation calls. The one wait is for a hook the role picked after the turn began: the turn's hook confirmation lists the roles' hooks, so a new one runs once the next turn has confirmed it. At Full access nothing needs confirming.

Turning a role off, changing its model, renaming or deleting it stops any child running as that role.

Built-in roles

The mework preset has four roles with medium reasoning effort and the conversation's tools: Opus (claude-opus-5-5) and Sonnet (claude-sonnet-5-5) on Claude Agent, and Sol (gpt-6.1-sol) and Luna (gpt-6-luna) on OpenAI Codex. Allow role-less subagents is off. Sol and Luna show No model until you sign in to Codex and fetch its models.

Workflows

A workflow is a JavaScript script the model writes. Each agent() call starts a step: a subagent with no history. The workflow call returns at once, and the run continues in the background as one task.

The script starts with export const meta = { name, description } and can use:

agent(prompt, opts): starts a step and resolves to its final text (its validated value with schema), or null if it failed or was skipped. Options include agentType (a role name, which also sets the step's model) and isolation: "worktree".
parallel(thunks) runs steps together; pipeline(items, ...stages) sends each item through the stages on its own.
phase(title) groups steps in the run panel, log(message) writes to the run log, and the script's return value is the run's result.

A run has 30 minutes to finish, counted from when it starts running; time its approval card waits for you does not count. Up to 16 steps run at once, depending on your CPU. Steps have no time limit of their own and are never retried automatically. Mework never ends a step for being quiet: a model that reasons privately can send nothing for many minutes.

In the run panel, Skip {label} ends a running step and its agent() call resolves to null; Retry {label} stops the step and starts it again from scratch, and the script gets the new attempt's result. To re-run a run that failed, was stopped or had steps skipped, ask the agent to resume it. Unchanged steps replay instantly as Cached; from the first changed, failed or skipped step on, every step runs again.

Worktree isolation

isolation: "worktree" gives a step its own Git worktree, so parallel steps can edit files without colliding. It works on this computer, WSL and SSH machines alike: the worktree is created at <repo>/.mework/worktrees/<run-id>/ws<N> on the workspace's machine, on a new branch from HEAD. The workspace must be the repository's root.

When the run ends, a worktree with no changes and no new commits is removed. Any other is kept, and the run log gives its path and branch for you to merge or delete.

Note A worktree starts from your last commit. Uncommitted changes in your workspace are not in it.

The Tasks pane

Open it from More options → Tasks, or click the running-task count below a turn in progress. It lists the conversation's subagents, workflow runs, shell commands, terminals, dev servers and preview pages; ended tasks move to a collapsible Finished section.

Click a subagent row, or its Spawned subagent card on the timeline, to read its transcript.
Click a workflow row for its run panel: a tile per step, the Run log, and Skip {label} and Retry {label} on every running step for as long as the run is going.

To have the local model also title and explain subagent and workflow-step rows, turn on Also for subagents under Local model.

Background shell commands

A shell command runs in the background when the model asks for it, and its approval card marks it [Background], whatever the shell. A foreground command still running at its timeout (2 minutes by default) also moves to the background and keeps running, whether the main agent, a subagent or a workflow step ran it, and even when 8 tasks are already running. A subagent or workflow step can start background commands too. They report to the subagent or step that started them: it waits for them with task_wait or gets their results between its rounds, and any still running when it gives its final reply are stopped.

Stopping a task

Stop a task with the square button on its row, or a run with Stop the workflow. Only you can stop tasks; the model has no tool for it.

Stop generating ends only the current turn: background tasks keep running until you stop each one or delete the conversation. While subagents or workflows run, auto-compact cannot hand the conversation off.

Quitting and restarting

Closing the window hides Mework to the menu bar or system tray, and tasks keep running. To stop everything, choose Quit Mework from that menu.

Note Quitting Mework, or a crash, ends every subagent, workflow run and background command, with the processes they started.

On the next launch:

A subagent that had written its final reply delivers it as a completed result, without starting a turn of its own.
A subagent that was still working is reported to the model as lost right away.
A workflow run picks up again right away, without your opening its conversation. Finished steps are reused, and only the unfinished ones run again.
A background command stays in the list, marked failed, and is not run again.