docs/src/session-branching.md

Rama main · réplica de lectura del repositorio original.

# Session Branching

Session branching (forking) lets you create an independent copy of a
conversation at any point. The new session diverges without affecting the
original — useful for exploring alternative approaches, running "what if"
scenarios, or preserving a checkpoint before a risky prompt.

## /fork Command

The quickest way to fork — type in the chat input or on any channel:

```
/fork                    # fork with auto-generated label
/fork experiment-a       # fork with a custom label
```

Available in the web UI, Telegram, Discord, Slack, Matrix, and all other
channels. See [Slash Commands](commands.md) for the full list.

## Forking from the UI

There are three ways to fork a session:

- **`/fork` command** — type `/fork [label]` in the chat input.
- **Chat header** — click the **Fork** button in the header bar (next to
  Delete). This is visible for every session except cron sessions.
- **Sidebar** — hover over a session in the sidebar and click the fork icon
  that appears in the action buttons.

All three create a new session that copies all messages from the current one and
immediately switch you to it.

Forked sessions appear **indented** under their parent in the sidebar, with a
branch icon to distinguish them from top-level sessions. The metadata line
shows `fork@N` where N is the message index at which the fork occurred.

## Agent Tool

The agent can also fork programmatically using the `branch_session` tool:

```json
{
  "fork_point": 5,
  "label": "explore-alternative"
}
```

- **`label`** — label for the new session (required).
- **`fork_point`** — the message index to fork at (0-based). Messages at
  indices 0 through N-1 are copied; the message at index N becomes the
  first new message in the forked session. If omitted, all messages are
  copied.

The tool returns `{ "key": "<session-key>", "forkPoint": N }`.

## RPC Method

The `sessions.fork` RPC method is the underlying mechanism:

```json
{ "key": "main", "forkPoint": 5, "label": "my-fork" }
```

On success the response payload contains `{ "sessionKey": "session:<uuid>",
"forkPoint": N, "label": "..." }`.

## What Gets Inherited

When forking, the new session inherits:

| Inherited | Not inherited |
|-----------|---------------|
| Messages (up to fork point) | Worktree branch |
| Model selection | Sandbox settings |
| Project assignment | Channel binding |
| Agent ID | |
| MCP disabled flag | |
| Node assignment | |

## Parent-Child Relationships

Fork relationships are stored directly on the `sessions` table:

- **`parent_session_key`** — the key of the session this was forked from.
- **`fork_point`** — the message index where the fork occurred.

These fields drive the tree rendering in the sidebar. Sessions with a parent
appear indented under it; deeply nested forks indent further.

```admonish warning title="Deleting a parent"
Deleting a parent session does **not** cascade to its children. Child sessions
become top-level sessions — they keep their messages and history but lose
their visual nesting in the sidebar.
```

## Navigation After Delete

When you delete a forked session, the UI navigates back to its parent session.
If the deleted session had no parent (or the parent no longer exists), it falls
back to the next sibling or `main`.

## Archive in the UI

The web UI also lets you archive sessions when you want to keep them without
leaving them in the main sidebar list.

- Open **More controls** for a session and click **Archive**.
- Archived sessions are hidden from the default sidebar list.
- Enable **Show archived sessions** in the sidebar to reveal and restore them.

Archive is available for any session — including `main`, cron, and
channel-bound chats — except when the session is the current active session for
its bound channel chat. That prevents hiding the live Telegram, Discord, or
similar chat out from under the channel router. Deleting `main` is safe: an
empty `main` session is recreated as soon as it is opened or receives a
message. Archiving `main` just hides it from the default sidebar list like any
other archived session — restore it with the **Show archived sessions** toggle.

```admonish info title="Independence"
A forked session is fully independent after creation. Changes to the parent
do not propagate to the fork, and vice versa.
```