Switch agents mid-session

How to swap the AI agent on a running spec task, what happens to your conversation history, and how uncommitted work is preserved.

When a spec task is in progress, you can switch to a different agent from the chat panel without losing context. The new agent receives the full conversation history from the previous one.

Why switch mid-session

Common reasons:

• Move from one code agent runtime to another (for example, Claude Code to Qwen Code)
• Test how a different agent app, with its own skills and prompt, approaches the same codebase

If all you want is a different model, or more reasoning, or a bigger machine, you don't need to switch agents at all — change the task's execution settings instead, and keep the session you're in.

Change how one task runs

The execution controls sit beside the task, both on the new-task form and on an existing task, and change only that task. The agent app they point at is left untouched, so other tasks using it are unaffected.

Two things are worth knowing before you reach for these:

• Change one setting at a time. The API accepts exactly one execution change per request, so the UI applies them one by one rather than as a batch.
• A sandbox resize applies to the running sandbox. If the task already has a sandbox up, Helix resizes it in place rather than waiting for the next run. If the resize can't be applied the change is refused and nothing is left half-done.

You need permission to update the project the task belongs to.

How to switch

In the chat panel header, open the agent dropdown. It lists every available agent app. Pick a different one — a confirm dialog appears naming both the current and target agents:

Switch agent? Current: "Claude Opus" (claude_code, claude-opus-4-6) New: "Sonnet Agent" (claude_code, claude-sonnet-4-6)

Click Fork to proceed, or Cancel to stay on the current agent.

What happens to uncommitted work

Before the switch completes, Helix checks whether the parent agent's working tree has uncommitted files or unpushed commits.

If the working tree is clean, the fork proceeds silently.

If there are uncommitted files, the modal lists them and offers a checkbox: "Commit and push these changes to feature/000XXX-… before forking." The checkbox is on by default. Leave it checked to have Helix commit and push the in-progress files to your spec task's feature branch. Uncheck it if you want to abandon the changes — the new agent starts from the last pushed commit.

The auto-generated commit message follows the conventional commits format:

chore(fork): pre-fork checkpoint before switching to <runtime>

If changes can't be saved automatically — for example, if there is no spec task attached to the session, or the working tree is on a protected branch with no valid push target — the modal shows a red warning and hides the Fork button. Fix the git state from the agent's terminal and try again.

The child session

After the fork:

• A fork divider marks the point in the chat where the switch happened. Above it is the conversation history from the parent, rendered as read-only chat bubbles. Below it is the new agent's thread.
• The new agent sends a short warm-up acknowledgment automatically — no first message needed from you. It confirms it has reviewed the prior conversation and is ready to continue.
• A "Forked from ..." badge in the chat header links back to the parent session if you want to review the original conversation.

The child session inherits the parent's full configuration: active tools, RAG settings, fine-tuned model weights, and app configuration.

The parent session

The parent session is paused once the fork completes. It still shows the full prior conversation but no longer accepts new messages. A banner at the top links to the active child session.

If you visit the spec task board, it automatically points to the child session — clicking into the task takes you directly to the active agent, not the paused parent.

Fork of a fork

You can fork a forked session. The grandchild inherits the full conversation ancestry — the entire prior chain appears as read-only historical context above the divider, not just the immediate parent's turns.

Limitations

• Switching is one-way. A paused parent session cannot be resumed; the fork creates a new branch of the conversation.
• The fork dropdown is disabled on already-paused sessions. Fork from the active descendant, not from a frozen checkpoint.
• For sessions without an attached spec task, uncommitted changes cannot be saved automatically. The Fork button is blocked if the working tree is dirty and there is no viable push target.