An agent is who runs a task: its instructions, how it picks a model, the tools it may use, whether it is read only, and where it works. Assign work to an agent and Stave makes the task — in a new worktree or in the current workspace — and starts it. Every later turn of that task runs as the same version of the agent. An agent can also be a subagent: an agent another agent calls for one piece of its work, inside its turn or as a delegated task.
Saving an agent starts nothing and grants nothing. Each assignment records its own start. A task that runs as an Agent runs autonomously: no routine approval prompts. Claude asks when its native Auto classifier hands an action to you or is unavailable. In an agent run with Auto permission, Codex hands approvals to its native auto-review when the runtime supports it, and otherwise never asks, as before. Guardrails (all on by default, each one can be turned off) also ask. A read-only Agent stays read only. Delegated Agents use the delegation policy resolved by the host and never get more autonomy than the task that delegated them.
Run overview → Run details shows the Agent version captured for that turn, the permission source and whether instruction delivery was confirmed. The run's model remains the provider's reported model. Older turns without Agent evidence stay unspecified. History marks a saved version Assigned when an assignment references it; that label does not count completed turns.
- You keep explaining the same role to a model: "review this commit, change nothing", "implement in a fresh worktree and verify".
- You want the same role on Claude, Codex, Cursor, Kiro or OpenCode without rewriting it.
- Your repository already has agent files for a coding agent and you want to use them from Stave.
For a sequence of stages, give the agent a workflow. For a one-off prompt, use a macro.
Open the Agents surface from the sidebar, the command palette
(Open Agents), or Cmd/Ctrl+K then G. It has three tabs: Agents,
My standards and Performance, which compares ended agent runs across
workspaces (see Agent performance and task outputs).
- Open Agents in the sidebar and stay on the Agents tab.
- Press New agent and say what it should do in one line, then Draft agent. Review the draft in the editor and save it. You can also start blank or copy an existing agent, or Duplicate any agent to edit a copy.
- Press Assign… in the agent's header. Kickoff opens with the agent preselected as the worker.
- Describe the work as the kickoff source, then Assign (or leave the first task ready without starting).
- Open task to follow it. The task's Flow panel shows what was assigned, its stages and the tasks it delegated.
- Issues: a ticket's context menu, or the detail pane's ⋯ menu, has Assign to agent. The ticket's key, title and link become the kickoff source. The ticket's own assignee does not change.
- Composer: type
!assignin any task's composer, including a new one. The rest of the draft becomes the kickoff source. The agent works in its own task. - Command palette: Assign to an agent… opens the composer's selector on Agents when a task is open, and Kickoff otherwise.
All of these open Kickoff with Who set. On the first screen, choose Me or an agent; with an agent, Assign beside Resolve source starts the work right away, from the source as Skip AI reads it. On the review screen, Who and Where set the worker and the new worktree and its base; the agent's workflow decides the stages.
Assign on either screen is the same start; the first one only skips the review. Where starts on New workspace for every agent, including Lead. Choose Current workspace to add a new task where you are, with no worktree. This kickoff choice is independent of the agent's saved workspace preference, which still applies to delegation. Selecting the same agent for another kickoff creates a separate assigned task; it does not reuse or replace its existing task. The task records its agent, then its first turn is sent like any composer turn: your sandbox, deny lists, credential lists, network setting, trusted tools and Stave Auto apply, and the turn runs autonomously, exactly like every later turn. Kickoff shows where it runs as Agent settings: provider · model · permission.
- Custom, From repository and Built-in agents, with search. Each row shows an avatar: a rounded square in the agent's colour with its icon, or its initials when it has none. Drag the list's edge to make it wider or narrower (240–480px, never so wide the detail drops under 512px); double-click the edge to return to the default 288px. Stave keeps the width between sessions.
- New agent: describe the job in What should it do? and press Draft agent. The Utility inference model (Settings → Background AI) drafts the name, Use when, instructions, permission, where it works and a colour; a reviewer or researcher is kept read only. The editor opens with the draft. Start blank (Auto model, Auto permission, a new worktree, usable as a main agent) and Or copy an existing agent (any built-in or repository agent) skip the model. A copy keeps the original's colour and icon. Nothing is saved until you save the editor; Cancel discards the draft. The command palette's New agent and the empty state open the same dialog.
- Profile header: the avatar, the name, Use when, and chips for source, model, permission and where the agent works.
- As a main agent: per provider, whether the instructions and tool limits are Enforced, Asked in instructions (stated to the model, not enforced), or Not available.
- Duplicate, Archive, Restore and Delete. Built-in and repository agents are read only; an update never overwrites your copy. Archiving stops new assignments only.
- Activity, under the header: how many assignments the agent has, how
many of its tasks are running or need you, how many couldn't start, when it
was last used, and Work — its assignments with their state (Preparing,
Started, Couldn't start or Interrupted) and a filter. While the
agent runs a task (or for half an hour after the run ends) the row shows the
run's state and where it stands (
Cause 2/3, orPlan 3/5for a one-stage run); click a row to open its task. - Settings and History tabs. History is covered below.
A custom agent's editor shows what most agents need and keeps the rest out of the way:
- Profile: name, colour, icon and Use when. Icon opens a grid of icons with a search field; Initials in the same grid goes back to the agent's initials. Colour and icon are independent, so changing one keeps the other. A change to either is recorded in History as Colour and icon.
- Instructions: what the agent does on every task.
- Workflow: the stages its runs follow (see below).
- How it runs: the model (Auto-routing with an optional task class and an optional preferred provider, or a Fixed provider, pinned model and effort), the permission, and where it works.
- Advanced (collapsed): Don't use when, skills, allowed and denied tools, max turns, concurrency, what it is usable as, and its report sections.
A field that fails a rule shows the reason inline (for example, a read-only agent cannot take a new worktree, and a tool cannot be both allowed and denied). A save blocked by an Advanced field opens Advanced.
Every save that changes how a custom agent behaves keeps the version it replaced; the last 10 are listed newest first. Each row names the fields that differ from the agent now and shows Ran when a task used that exact version. Restore saves the old version as the current agent, so the version it replaces joins History and a restore can itself be undone. Archiving and concurrency changes are not new versions.
When you correct a custom agent in one of its tasks (you write again after it answered), Stave asks the Utility inference model once whether the agent's instructions should change so the correction is not needed next time. If so, a suggestion appears on the agent's page with the change in one sentence:
- Apply saves the suggested instructions like an edit, so the previous instructions stay in History.
- Edit lets you change the suggested instructions before applying them.
- Dismiss drops the suggestion.
Learning is on for new custom agents; turn Learn from my corrections off on an agent's page to stop it. Each corrected task uses at most one request, and an agent keeps at most three open suggestions. Only the task's messages from you and the agent are sent — no tool output, attachments or secrets — and the request runs read only. A suggestion written against instructions you have since changed says so; applying it replaces them. Built-in and repository agents do not learn.
An agent's Workflow is the ordered stages a run of it follows. Without stages, a run is one stage that plans its own steps — Implementer, Researcher, Reviewer and Lead work this way. Debugger (Reproduce → Cause → Fix), UI Polisher (Reproduce → Fix → Report) and Shipper (Validate → Open draft PR → Watch checks → Ready for review) come with a workflow.
- Add stage: an AI stage (blank or from a template) with an instruction and Done when, optionally done by another agent and pinned to a commit; or a Stave action: Open draft PR, Watch checks, Ready for review or Run script. Drag a stage, or use Alt+arrow keys, to reorder it.
- Check in with me (with two or more stages): Only when stuck (default), Before publishing or Every stage. A stage's hand toggle makes that one stage ask, or not.
- Review before done (an agent that edits files and has no stages): When behavior changes (default), Always or Off. When it is on, a run commits its verified changes and the Reviewer checks the assignment's result (on the other provider when it can). Research and answers are reviewed through their conclusions, sources and artifacts without an empty commit. Work → Review → Fix review findings remains the sequence. If the independent review reports no findings, the workspace is unchanged and no required checks or sign-off remain, Stave skips the final repair stage and records why. Under When behavior changes, wording, formatting and comments receive a brief correctness check. Lead is Off: it asks for reviews of the parts it hands out. A delegated helper's run is never reviewed this way; the run that called it decides. The workspace check, when there is one, gates the fix stage.
- Each AI stage reports when it is done; the run card and the Task panel's Progress show the stages only when there is more than one.
- A saved Agent's delegated task defaults to supervised completion: its frozen workflow runs with stage reports and bounded continuation, retaining delegated permissions and the selected model. Explicit one-turn consultations and detached work retain their existing lifecycles. In-turn subagents receive AI stages as instructions and remain scoped to the parent's turn.
- Exported agent files leave the workflow and a set review choice out and say so.
Delete removes a custom agent from your settings, with its History and suggestions. Past assignments keep their own snapshot, so an agent's history still shows its name after it is gone. If another agent's workflow stage still names the agent, deletion is blocked and the dialog lists where — Archive instead, or remove those references first. Running or waiting tasks are shown for context but do not block: they keep the version they started with and finish on their own.
An agent's avatar also appears next to its work in the sidebar (with a status dot — a green dot for running, an amber dot when it needs you), in the Kickoff Who picker, on the Fleet task badge, and on the assignment node of a task's Flow panel, and in the composer's agent control and selector. Each built-in agent has its own icon and colour, chosen so agents whose initials look alike (Reviewer and Researcher, for one) never share either. A repository agent gets a stable colour derived from its id and shows its initials; a custom agent's colour and icon are chosen in its Profile section, and one with no icon shows its initials.
The composer's selector (Alt+P) always has two sections and one search box:
Models (the providers and Stave Auto) and Agents (every active agent
that can run a task). Typing in the search also lists the agents that match.
What you pick decides how the task runs:
- A model is Chat. The model runs the task with the task's own permissions, as it always did. If an agent was running the task, picking a model ends it and its run. Later turns tell the model the agent was released and its role and limits no longer apply (Claude's system prompt, Codex's developer instructions, once per session in the prompt on Cursor, Kiro and OpenCode), because a resumed session still remembers the agent's instructions.
- An agent is Agent mode. The agent runs the task from the next turn and picks its own model: Stave Auto routes every turn, using the agent's task class as its starting point. An agent with a fixed model uses it as its default instead. The selector does not move to a model. With Stave Auto turned off, the agent runs on the model the task already has.
- A pin binds the agent's turns to one model. In Agent mode the button
has two segments, the agent and its model:
Implementer | Auto · Balanced. While Stave Auto routes the agent's turns, the segment shows no effort (Auto chooses it on every turn) and opens on Stave Auto, where the preference (Balanced, Cost-saver, Quality-first) changes without ending the agent. Each provider tab is headed Auto — Implementer chooses (checked). Pick a model there and the segment reads Pinned · Opus 5 with its effort; the first row becomes Back to Auto, and picking a preference on the Stave Auto tab also lifts the pin. A pin never ends the agent. Per turn the order is: pin, then the agent's fixed model, then Stave Auto. An agent fixed to a provider without a model runs on that provider's default model; any other model of the provider is a pin. - The first send in Agent mode reads Assign; later sends read Send.
- A choice applies from the next turn. Earlier turns keep the agent they ran as, and each agent's History counts the turns it ran. Choosing another agent is locked while a turn runs or waits for an answer, and a switch to an agent with a wider permission asks first. Switching agents ends the run the previous agent started.
- A task that runs as an agent calls other agents itself, as subagents.
A custom agent's Usable as chooses where it can be used: Main agent (Assign / Kickoff), Subagent in a turn (called inside a lead agent's turn) and Subagent as a task (a delegated task). Duplicate the built-in Reviewer and turn on Main agent to start work with it directly.
Every turn of a task that runs as an agent registers the agents it may call
as its in-turn subagents: its Can call list, or every agent usable as a
subagent in a turn when the list is open, at most eight. Claude calls them with
the Agent tool, under the lead's permissions; Codex starts them with
spawn_agent from the instructions Stave hands it. Either way they run one
level deep and their answers come back into the turn.
Can call, under Advanced, limits which agents a task running as this agent may delegate to. Any agent (the default) sets no limit. Only these agents offers every active agent usable as a delegated task; checking none means the agent delegates to no one. A delegation to an agent outside the list is refused with the names it may call. Exported agent files leave Can call out.
My standards, its own tab on the Agents surface, holds your own rules for every agent you run — how you want code written, reviewed or reported. Turned on, they are added after each agent's instructions when you assign work, delegate to an agent or it runs as a subagent. A task keeps the standards it started with; What it received lists them as a source. They stay in your settings and are never written into an exported agent file.
Export in an agent's details shows the Claude or Codex agent file the agent becomes and the path it goes to. Write to repository writes it into the open workspace; when a file is already at that path, a second Replace press is needed. The file never carries a permission above the provider's default — an Auto agent is written without one — and fields the format has no place for are listed under Not in the file. Commit the file to share the agent with the team.
Stave lists the agent files the open workspace already keeps for coding agents:
| Folder | Files |
|---|---|
| .claude/agents | Markdown files, including subfolders |
| .codex/agents | TOML files |
| .kiro/agents | JSON and Markdown files |
| .cursor/agents | Markdown files |
| .github, agents folder | Files ending in .agent.md |
Files are read, never written. Use the reload button next to search after editing a file. A repository agent's details show Read from the file: each field that was Not imported (it would run commands or skip approvals), Left out (Stave has no place for it) or Changed.
When a file has no permission setting, a tool list without file-editing tools makes it Read only; otherwise it starts as Guided, never Auto.
A file that could not be read, or whose agent has the same id as a custom or built-in agent, is listed under agent files were not used with the reason. A repository file never replaces an agent you made or a built-in one; rename the agent in the file to use it. Duplicate a repository agent to edit a copy.
The Progress tab of the right rail's Task panel shows one task's flow while the task has no agent run; once it has one, the agent run takes that place. Every task has a base flow, drawn from records that already exist:
- Request — the first message that opened the task.
- Plan — the latest plan or todo list the provider reported, with how many items are done; Timeline lists each item.
- Changes — the files changed, with the added and removed line totals.
- Verification — the structured result of the project's checks (pass, warn or fail) with how many ran. It reads the recorded result only and never guesses a pass or fail from a command's output.
- Pull request — the workspace's pull request, its status and its checks, once one exists.
A Waiting for approval or Waiting for your answer step appears whenever the task is waiting on you. A task with no messages yet says it is waiting for the first message.
When a task is assigned to an agent, the assignment heads the flow, and the task's delegated tasks follow the base steps as nodes of their own. Timeline lists when a node started, was asked for changes, retried and ended. The flow only reads the records that already exist; it changes nothing.
For a task assigned to an agent, What it received lists the version of the agent the task runs (a short content hash), each instruction source that went in, and how firmly the instructions, tool limits, model and permission are held on that provider. If the agent was edited after the task started, the flow says so: later turns keep the version used, and assigning again uses the edit. A change of colour or icon alone is not counted as an edit, since it does not change what the agent does.
A task that runs as an agent shows the agent's name, and typing the name in Fleet's search finds its tasks.
| Setting | Values | Notes |
|---|---|---|
| Works in | New worktree, Current workspace | New worktree uses Kickoff's branch (Assign on the first screen takes the one Skip AI proposes); Current workspace adds a task where you are |
| Permission | Read only, or full access (saved as Manual, Guided or Auto) | Read only keeps every turn in the read-only posture and works in the current workspace; any other value runs autonomously |
| Model | Auto-routing, or a fixed provider, model and effort | With Stave Auto on, the task stays on Auto and every turn is routed, with the agent's task class as the fallback; with it off, your routing rules pick one model and effort for the task when it starts |
| Usable as | Main agent, Subagent in a turn, Subagent as a task | Built-in subagents (Scout, Sweep, …) are usable only in a turn |
-
The task and its prompt are saved, and the agent recorded, before the first send. If the send cannot start, the prompt stays ready in the composer; if it cannot be confirmed, check the task before sending again. Kickoff never sends twice on its own.
-
Assignments from earlier versions that were cut off while preparing show Interrupted with what they had made. They are never started again on their own.
-
Cursor, Kiro and OpenCode receive the agent's instructions at the top of the first message — or of the next message after the task starts as, or switches to, an agent from Kickoff, an agent run or the composer. Claude and Codex receive them on their instruction channel with every turn.
-
A task that runs as an Agent is autonomous. Every turn of the task — the first and each later one — removes routine approval prompts and changes nothing else: your sandbox, deny lists, credential lists and network setting stay as you set them. Claude's native Auto classifier can hand an action to you when it cannot decide or Auto is unavailable; the Agent Run waits for that approval. Saved Manual and Guided agents now run like Auto; only Read only limits a turn. This holds in agent runs too: an Auto agent's runs use the provider's classifier (Claude auto mode, Codex auto-review when available); every other permission runs on your own provider settings, and Read only stays read only.
Agent Claude Codex Cursor Kiro OpenCode Read only Don't Ask, edit tools off, read-only sandbox Read-only files, never asks, network off Ask mode, Manual Manual, told not to edit Stave read-only agent: asks before every tool, edit tools and subagents off Any other Native Auto (Bypass, Plan and Don't Ask stay as you chose); Stave answers what Claude still hands over Never asks, or in an Auto agent's run, Codex auto-review when available; at least workspace files, or your full access Your settings Your settings Your settings The only interrupts left are the Agent-mode guardrails (all on by default; turn each off in Settings) — a write outside the task's repository, a protected credential path or variable, an irreversible remote action (force-pushing a default or protected branch, deleting remote branches, tags, releases or repositories, publishing,
sudo) — and the agent's own questions. See Provider Sandbox And Approval. Kiro has no read-only mode, so a read-only agent there asks before every tool and is only told not to edit; the Agents tab shows this as Asked in instructions. OpenCode runs a read-only agent as an OpenCode agent Stave defines under a new random name each turn (stave-read-only-<random>), so your OpenCode config cannot override its rules: file edit tools are removed, subagents are off and every other tool asks, so the limit is enforced; a shell command you approve can still write. On OpenCode 2.x the agent also removes the code-modeexecutetool, which cannot ask first, so a read-only agent there cannot use Stave Local MCP tools. Read only covers the repository, not Stave's own records of the work: a read-only agent can still add workspace notes, todos, links and custom fields, write a plan file withstave_write_plan_file, and report or block its stage. Clearing or removing what you wrote, repository memory and schedules stay off. -
Tool limits are enforced where the provider supports them (for example, a Claude main agent's denied tools) and stated in the instructions elsewhere.
-
Where an assigned task runs:
Agent model Runs on override Stave Auto First turn and later turns Fixed — either The agent's provider, model and effort Auto-routing A provider either Your model for that provider, never re-routed Auto-routing Auto-routing On Auto, routed on every turn Auto-routing Auto-routing Off One route from your rules for the agent's task class, kept for the task When Auto routes the task, a confident classification decides the task class. The agent's task class fills in when the intent is unclear or classification is unavailable, and a safety escalation always wins.
An Auto-routing agent may prefer Claude, Codex, or The other provider (the one the delegating task is not on). The preference leads the provider order only at a task boundary, the task's first turn or a delegation, and a rule that names a provider outranks it. The built-in Reviewer prefers the other provider, the same default the Review button offers; when that provider's CLI is not installed, the delegation stays on the delegating task's provider. The preference is not written to exported Markdown or TOML agent files and is listed among the fields left out.
Every Agent run on a Claude or Codex task starts with team limits; there is nothing to turn on. The Run panel's Team limits section shows them.
- Shared turns. The Agent's max turns (30 by default, up to 100) are the whole team's: the run's own turns, the turns of the helper Agents it calls and your replies in a stage all count, and a turn that fails to start still counts. When they run out the run halts with Limit reached; Extend adds turns, and the shared budget grows with them. While helpers work, one turn stays reserved so the run can integrate their results.
- Helper Agents. A run can have 3 helper Agents working at once and call 8 in total. Change both in Settings → Providers → Delegated tasks; a run keeps the numbers it started with. These count saved Agents that work to completion (supervised delegations). One-turn and detached helpers, and in-turn native subagents, do not draw on the shared turns.
- Model and effort. An Agent whose model is Auto may change model or effort as the work needs it. A step-up to a stronger model or more effort happens as soon as the work needs it; other changes are limited to two per run, with two turns between them, and your replies in a stage count as turns. A Fixed Agent model, or a model or effort pinned in the composer when the run starts, never changes on its own; a composer pin replaces a fixed model on the Agent's own provider, and a pin on another provider is refused at start.
- Your choice wins. Pin a model or effort in the composer when you reply, and the reply and the turns after it run on it, over the run's route, its proposals and its start pins, until you switch the composer back to Auto; then a model or effort the run fixed at start comes back, and otherwise the run adapts from where it is. The run keeps its provider, account and permissions, and refuses a pin that this provider or account cannot run. When you ask for a model or effort in words, the Agent proposes it as your request: it takes effect on the stage's next turn, including your next reply, without waiting for the change limit or cooldown, within the run's pins and eligible models. The Agent can also propose a justified change itself, including while its stage is blocked.
- Providers. The run stays on the provider and account it started on. A helper Agent runs on its own provider, so a Reviewer can review Claude's work on Codex, unless the run's model is pinned; then helpers stay on the run's provider too. Helpers cannot call further helpers.
After helpers settle, the run integrates their results and reports its acceptance criteria; a report written before they finished is not enough. Reported billing is separate from these limits; an unknown cost stays unknown.
Runs that started on Stave 0.27.0 with the composer's former Auto adjust option keep the limits they started with: 30 shared turns, 2 helpers at once, 4 in total, helpers on the run's provider, and no in-turn native subagents.
Saved file paths can accompany a supervised assignment, including image paths. Save editor changes first: the Run reads the on-disk files. Inline image payloads and explicitly attached task or Information panel context are captured once when the Run starts and retained through retries, continuations, and app restarts. Later changes to an attached task do not replace that captured context. An idle queued assignment starts supervision with its captured routing intent. No live cost or quality improvement is guaranteed by these containment limits.
- Stave reads at most 50 agent files per repository.
- Export writes Claude and Codex agent files only.
- Hooks, inline MCP servers and approval-skipping modes in agent files are never imported.
- A worktree is a separate checkout, not a sandbox.
- Running tasks as agents is experimental.
- Agent runs and their stages and Playbooks (retired)
- Delegated tasks
- Auto-routing
- Fleet Action Required
Agent instructions for a prompt-channel provider stay pending when the first turn is blocked, cancelled before execution, or fails during provider startup. They are included in both the plain prompt and canonical conversation input, and consumed after the primary provider responds or starts a tool or decision. A delayed turn cannot consume instructions recorded for a newer agent.