Subagents

Subagents let fx delegate independent work to another agent. Each subagent has a name and its own conversation, works in the same workspace, and reports back to the agent that started it.

Ask fx to delegate work that can run independently:

Have a subagent review the parser tests and report missing cases.
It should not edit files. Meanwhile, investigate the parse error.

Start a subagent and send it messages

The main agent starts a subagent by sending a message to a new name, and continues it by sending more messages to that name:

Start a subagent named reviewer to check the parser tests.
Ask reviewer whether the new test covers the missing case.

Sending a message doesn't wait for an answer. The main agent keeps working, or ends its turn, while the subagent works on its own. It can also wait for the next report, or check what each subagent is doing.

Subagents belong to the current fx session and remain available when you resume it. Their conversations do not appear separately in fx sessions or the fx -r session picker. fx sessions --live lists each running session's subagents below it, and fx session <session-id>/<name> reads one; see See what's running. A subagent that an earlier version of fx started for a single task can't take messages.

Reports

When a subagent's work ends, its report goes to the agent that started it, as that agent's next message:

  • If the main agent is working, the report joins its turn at the next step.
  • If the main agent is idle, the report starts its next turn. The main agent can pick up a subagent's result without a new prompt from you.
  • In an editor connected over ACP, a report always starts the main agent's next turn.

In the terminal, each report shows as a row in the main agent's conversation that names the subagent and how its work ended, such as reviewer finished. A message a subagent sends the main agent shows as Message from reviewer. When the work failed or was interrupted, the row says so, such as reviewer failed. Press ctrl+o to read the full text. fx marks reports and messages as the subagent's output, not as your instructions.

A report also says when you started the turn yourself on the subagent's screen, and why its work was cancelled: you stopped it, or fx quit. A message the subagent sends during a turn you started says so too.

A message also carries the lines you typed on the subagent's screen in the turn that sent it, up to the last eight. When you ask a subagent to tell the main agent something, the main agent sees your own words next to the subagent's.

A subagent reports when the work it was given ends, whether it finished, failed, or was cancelled. To hear from it more or less often, say so when you start it:

TimingThe subagent reports
When its work ends (default)When the work the main agent gave it ends
After every turnAfter each of its turns, including turns you start on its screen
NeverOnly when its work fails, or fx crashes before it finishes
Start a subagent named watcher that reports after every turn.

If fx quits or stops before a report reaches the main agent, fx delivers the report when you resume the session. Work that quitting cut short is reported as cancelled, so after you resume, the main agent can start a turn on its own to handle it.

Keep or close subagents

A subagent keeps its conversation until it is closed, and fx never closes one on its own. The main agent decides which subagents to keep, the way a lead manages a team:

  • At the start of each turn, it sees a list of its subagents: what each one is doing, how its last work ended, and what it's for. What a subagent is for comes from the first line of the instructions or the first task the main agent gave it.
  • When it starts a new subagent, it's told which others are idle and what each is for. Each report says that its subagent is idle now.
  • It gives related work to the subagent that already has the context, keeps one while more related work is likely, and closes one whose work is done.
  • When it can't tell which subagents you still need, it asks you with a suggestion for each, such as when its list grows or the task ends.

To decide yourself, tell the main agent which subagents to keep or close, or close one yourself.

While a subagent works

You can send a working subagent more instructions through the main agent:

Tell reviewer to include invalid UTF-8 input in its review.

A working subagent reads a new message at its next step, such as after the tool it is running finishes. When the turn can't take it, the message waits, and every message still waiting when the turn ends goes into the subagent's next turn together. The main agent can change a subagent's saved instructions only while it is idle.

Up to 64 messages from other agents can wait for one subagent. The main agent is told when a message doesn't fit.

When the main agent checks what its subagents are doing, a working subagent's status names the tool call it is in and how long that call has run, such as in Waiting for npm test for 4m12s.

When a command that a subagent waits on prints nothing for 2 minutes, fx sends the main agent a message from that subagent:

fx: my command `npm test` has had no output for 2m5s. It may still be working, or it may be hung. Message me to check on it, or stop me.

The message reaches the main agent like any other message from the subagent, so a main agent that waits for a report learns about the quiet command before the subagent's work ends. It can message the subagent to check on the command, or stop the subagent. fx sends one message each time the command goes quiet, and doesn't stop the command itself; see Background commands. In the message and the status, fx shows secrets it recognizes in the command, such as OPENAI_API_KEY= values and bearer tokens, as [redacted].

Ask the main agent to stop a subagent to end its turn. The stop drops the messages waiting for its next turn and the ones its turn hasn't read yet, and the main agent is told how many. A stop the main agent makes sends no report, since the main agent already knows. A message the main agent sends after a stop, even in the same reply, waits and starts the subagent's next turn, so you can redirect a subagent in one request:

Stop reviewer and have it review auth.zig instead.

To remove a subagent the main agent no longer needs, ask the main agent to close it, or close it yourself.

Switch to a subagent

Press down with nothing typed, or ctrl+x at any time, to open the agent list. Each subagent's row sits under its instance's row, titled from its first task. While a subagent is in a tool call, its state shows how long the call has run, such as working 4m12s. Move the highlight to its row with up and down. fx shows each agent as the highlight reaches it: it clears the screen and prints that agent's conversation in place. Press enter to stay on it and type to it, and the footer names the subagent on screen, such as reviewer · done ↓. Press esc to go back to the agent the list opened on.

Agents off screen keep working, so switching to one shows its output so far, still streaming.

On a subagent's screen:

  • What you type goes to that subagent as your message. Its reply stays in its own conversation. The main agent sees that turn only if the subagent reports after every turn, or if the turn fails.
  • Press esc twice to stop its turn. When it was working on something from the main agent, the main agent's messages it hasn't read yet are dropped, and the main agent is told how many.
  • An image or $skill you send while it works ends its turn so that your prompt runs next. The work the main agent gave it counts as done.
  • Its approvals and questions appear there.
  • A change to its model, reasoning effort, fast mode, or permission mode applies to that subagent only.
  • /resume, /new, /fork, /clear, /reset, and /close aren't available. Switch back to its instance's screen to use them.

When a subagent asks for approval or asks a question while it isn't on screen, the prompt also appears on the screen of its instance, titled with the subagent's name. With one instance, that's the main screen. When several of its subagents wait, the oldest prompt shows first. The prompt moves back when you switch to the subagent.

While any agent that isn't on screen waits for you, the footer shows a note such as reviewer needs approval · main ↓, or reviewer needs you · main ↓ when its request needs you to continue it, such as when it's out of credits. Otherwise, while subagents that aren't on screen are working, the footer counts them, such as 1 subagent working · main ↓.

After you resume a session, switching to a subagent shows its saved conversation before it runs again.

In the agent list, each instance is followed by its own subagents. Closing an instance with /close stops its subagents without a report. Reports they already owed stay in that session, and arrive if you reopen it with fx --resume.

Start another conversation

Starting another conversation with /new, /clear, /reset, /resume, or /fork stops the work your subagents are running in the current one. That work ends as cancelled, without a report, and the new conversation says how many tasks were stopped. The subagents stay in the conversation you left, with their history. Resume it to find them in the agent list and give them more work. Reports they already owed arrive when you resume it. /fork can also copy them into the fork.

Close a subagent

Closing a subagent stops it and removes it for good. To close one yourself, open the agent list, move the highlight to its row, and press delete (backspace). The footer asks you to press delete again, and any other key keeps the subagent.

When you close a subagent:

  • Its turn stops, and the messages waiting for it are dropped.
  • It leaves the agent list, with the subagents it started, and doesn't come back when you resume the session.
  • If it was on screen, fx shows the agent on the row above it in the agent list. This is also what happens when the main agent closes the subagent you're looking at.
  • If it was working on something from the main agent, the main agent is told that you closed it.

The main agent can close a subagent too, and that close sends no report. A later message to a closed subagent's name starts a new subagent.

Use an agent profile

An agent profile saves what a subagent can use: its tools, MCP servers, permission mode, model, reasoning effort, and instructions. fx tells the main agent which profiles exist, and the main agent names one when a task needs it. Otherwise it starts the subagent without a profile. To choose one yourself, name it in your prompt:

Have a subagent in the reviewer profile check the new tests.

Whatever its profile, fx tells each subagent its name and which agent started it. On a subagent's screen, you can ask it to tell the main agent something, and it sends the main agent a message.

Choose a model

You can choose a different model and reasoning effort for each subagent. This lets you use a stronger model to plan and review, then delegate implementation to a lower-cost model.

For example, keep GPT-6 Astra in the main conversation and ask:

Have a subagent use Kimi K3 to implement this plan.
Return the changes and test results for review.

Subagents use the model and reasoning effort of the agent that starts them unless you choose others when creating them, or their profile sets them. A subagent keeps that selection for later messages. When you name a model, the main agent can run fx models ls --json to look up the exact ID, so a short name such as Kimi K3 resolves to the catalog's spelling instead of a guess. See Models.

Ultrafast inheritance

New subagents inherit the parent turn's Ultrafast request. Their model must also advertise Ultrafast pricing through AI Gateway; choosing another model does not bypass that check.

A subagent retains its saved preference when resumed. An explicit child disable remains off, and a parent with Ultrafast off prevents a saved child opt-in from enabling it. Turn the parent off with /ultrafast off, --no-ultrafast, or FX_ULTRAFAST=0 before delegating without the tier.

Subagent requests are billed separately and can also incur the higher Ultrafast prices. See Usage and costs.

Access

A subagent starts in fx's main profile unless it's given another. main sets nothing, so the subagent has the tools and MCP servers of the agent that started it and runs in its permission mode. It follows that mode as it changes, so switching an instance between ask and auto reaches its subagents at their next tool call. In another profile, it gets what that profile sets instead. A mode you choose on a subagent's own screen wins over both.

With several instances open, a subagent's "don't ask again" approvals belong to the instance at the top of its tree.

A subagent can start subagents of its own unless its profile leaves out the subagent tool. Its subagents report to it, not to the main agent, and don't get the subagent tool themselves, so subagents nest two levels deep. If several subagents edit files, give each one a separate area to avoid conflicting changes.