# Workstreams

Workstreams help you organize related AI sessions that work on the same set of files and/or are about the same topic.

### **How to use:**

Start any AI session as usual. When you need to branch your work or try a different approach, click the **+** button to add a new session tab.

<figure><img src="/files/PAVbq3TYUKI9KcNeqg0e" alt=""><figcaption></figcaption></figure>

Your single session automatically converts into a workstream containing multiple sessions.

<figure><img src="/files/UKwIZkuu81Y341zwA3NI" alt=""><figcaption></figcaption></figure>

The right panel shows all files modified across all sessions in your workstream, giving you a unified view of changes.

<figure><img src="/files/b8R6bL1iRj7nhAidmofD" alt=""><figcaption></figcaption></figure>

Clicking on that file, you can open the files editor in the Agents mode

<figure><img src="/files/2130W1MWrgrIa5c6oCMT" alt=""><figcaption></figcaption></figure>

Right clicking on the file, you can still open it in Files mode

<figure><img src="/files/hBFQtvUzGxVkm2ixGuPs" alt=""><figcaption></figcaption></figure>

### **Benefits:**

* Keep related work organized without losing context
* Easily compare different approaches to the same problem
* Track all file changes across multiple sessions in one place

### Spawning sibling sessions with `/launch-new-session`

You can ask the agent to spin off another session for a side task without leaving the current one. Run `/launch-new-session` in any session and describe the side task. The agent calls the `spawn_session` MCP tool and a new session is created.

By default the new session is a **sibling**: it joins the caller's workstream, so files-edited, open tabs, and the workstream overview are shared. The original session stays focused on its own thread while the sibling runs in parallel.

If you want the side task fully separated, ask for an isolated session ("isolated bug fix", "fix and commit separately"). The agent passes `isolated: true` to `spawn_session` and the new session is top-level instead of joining the workstream.

* **Sibling (default)**: shares workstream context with the caller. Good for parallel exploration of related work.
* **Isolated**: independent top-level session with no parent. Good for unrelated fixes the agent should commit on its own.
* **Worktree**: combine either mode with a worktree to put the new session on its own git branch. Sibling and worktree are independent options.

You can also launch sibling sessions from the composer's Actions dropdown by configuring an Action with `launch: new-session`. See [AI Actions](/session-management/ai-actions.md) for the config keys.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nimbalyst.com/session-management/workstreams.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.