Subshell Docs

Helper lifecycle

Clean up helper sessions created during agent coordination.

Creation and visibility

A subshell created with a pane's own token is marked as cross-agent communication. It appears beneath the subshell that created it in the sidebar and starts with its notification bell off. Workspace subshells are grouped by machine; a helper stays beneath its creator even when it runs on another machine. Selecting the helper opens it as a workspace tab. Helper rows can't be dragged independently or moved to another workspace; they stay with their parent.

Helpers appear only beneath their parent, never as standalone entries in the sidebar or subshell dashboard. A helper whose creator's row is gone drops from the tree but stays available through MCP for cleanup. Removing or closing a parent doesn't close its helpers.

That classification remains even if the owner changes its notification preference later. It records how the helper was created.

Finish the exchange

  1. Confirm the helper's result has been collected.
  2. Record any output you need to keep.
  3. Call delete_subshell to remove the completed temporary helper and its captured history.
  4. If you need to retain its history, use terminate_subshell instead. This stops the process but leaves the session record and sidebar entry.

The agent that opens a helper is responsible for cleaning it up. Don't assume an idle prompt or completed task removes the session right away. A helper you forget doesn't linger forever, though: a server sweep retires a cross-agent session about half an hour after its pane has died. A helper you terminated to keep its history, and a helper whose pane is still running, are left in place, so collect and delete when the exchange is done rather than waiting on the sweep.

Exited helpers

A helper process can exit while its record still shows status: "running" with alive: false. You can't send input to an exited process. When authorized, use restart_subshell to restart it with the same ID.

Restart can accept a new prompt. Inspect promptDelivered afterward rather than assuming the text was accepted.

Self restart

Restarting your own subshell terminates the process making the request. Don't use self-restart as a way to refresh tools during an active task.

Deletion is owner-only and removes captured history. Retained terminated logs remain subject to the server's retention policy.

Next steps

Read Session lifecycle and MCP tool reference.

Edit on GitHub

Last updated on

On this page