TLDR

Adds /branch (alias /fork) — forks the current conversation into a new session so you can explore an alternative direction without losing the current thread. Mirrors Claude Code's /branch: writes a new JSONL under a fresh sessionId with every record stamped forkedFrom, rebuilds the parentUuid chain in write order, swaps the CLI into the fork, and prints a two-line announcement that tells you how to /resume the original.

Screenshots / Video Demo

Dive Deeper

Why fork at all. Today if you want to explore "what if I asked a different follow-up?" you either /clear (losing context) or keep going and pollute the transcript. /branch writes a JSONL copy under a new id, stamps each copied record with forkedFrom: { sessionId, messageUuid } for audit, and swaps the CLI into the fork. The parent is untouched and reachable via /resume <oldSessionId>.

Storage model — mirrors Claude's /branch.

• Full in-memory copy + write. The source transcript is read through jsonl.read, each record is rewritten (sessionId → new, parentUuid rebuilt in write order so the fork is a clean linear descendant, forkedFrom stamped), and the result is written to <newId>.jsonl. Acceptable for typical session sizes; a streaming upgrade is noted in the code if transcripts grow very large.
• Atomic exclusive create. Target file is opened with fs.openSync(path, 'wx', 0o600) — one syscall that both asserts "doesn't exist yet" and opens for writing. No TOCTOU window, no silent overwrite.
• Guards. Rejects invalid sessionId patterns, missing/empty sources, cross-project sources (verified via getProjectHash(records[0].cwd)), and pre-existing targets.
• forkedFrom is write-only by design. Nothing consumes it at read time — it's per-message audit so a record inspected in isolation is self-describing. Matches Claude's behavior.

Swap ordering — "core first, UI last." useBranchCommand runs: finalize recorder → forkSession (disk) → loadSession → config.startNewSession → getGeminiClient().initialize() → UI sessionId swap → historyManager.clearItems + loadHistory → title + hook + announce. Anything that can still fail runs while the UI is still on the parent, so a throw leaves the user safely on the parent instead of stranded with a cleared history and a half-live client. Explicitly tested.

Title handling. Branch title is <name> (Branch) with (Branch 2), (Branch 3), ... collision bump (cap 99, then timestamp fallback). When no name is provided it's derived from the first real user ChatRecord — collapsed whitespace, 100-char truncation, fallback "Branched conversation". Reads ChatRecord[] (the JSONL transcript), not the API Content[] history, because the latter is prefixed with environment/context-injection bootstrap messages; those would poison the title. Records with subtype (cron, notification, slash-command echo) are skipped.

Guards at the command layer.

• isIdleRef — forking mid-stream or mid-tool-call would tear the new session's parent chain, so we refuse and tell the user to let the in-flight response finish.
• sessionExists(currentId) — nothing to fork from a brand-new empty session.
• /branch is added to SLASH_COMMANDS_SKIP_RECORDING so the command itself doesn't bleed into the fork's tail as a trailing user input (same reasoning as /new, /resume, /delete, /clear).

Hook surface. New SessionStartSource.Branch enum variant so hook consumers can distinguish a fork from a resume. A fork is semantically a derivative transcript under a new id — not a resume — so reusing SessionStartSource.Resume would have been wrong.

Announcement format. Two-line info items match Claude:

Branched conversation "my-experiment". You are now in the branch.
To resume the original: /resume <oldSessionId>

The quoted title in the first line is the raw user-provided name (no (Branch) decoration — that belongs in the picker/prompt bar, not the announcement).

Reviewer Test Plan

1. npm run build && npm start (or npx the built CLI).
2. Start a session and send a couple of prompts so there's real content to fork.
3. Run /branch my-experiment. Expect:
   • Two info lines: the branched-conversation line and the /resume <uuid> hint.
   • Prompt bar / picker shows my-experiment (Branch) as the session title.
   • ls ~/.qwen/projects/<hash>/chats/ shows a new <uuid>.jsonl with mode 600; every line has a forkedFrom field pointing back to the parent.
   • The source <oldId>.jsonl is unchanged.
4. Continue chatting in the fork — new turns append to the new JSONL, not the parent.
5. Run /resume <oldSessionId> (from the hint). You're back on the parent transcript with no traces of the fork.
6. Re-run /branch my-experiment on the parent again to exercise the collision bump — expect title my-experiment (Branch 2).
7. /branch with no arg on a session whose first user message is long — expect a title derived from the first ~100 chars of that message + (Branch).
8. /fork alias — same behavior as /branch.
9. Error paths:
   • Run /branch while a response is still streaming → error message, no fork, no session swap.
   • Run /branch in a brand-new empty session → "No conversation to branch."

Unit tests: vitest run packages/cli/src/ui/commands/branchCommand.test.ts packages/cli/src/ui/hooks/useBranchCommand.test.ts packages/cli/src/ui/hooks/slashCommandProcessor.test.ts packages/core/src/services/sessionService.test.ts — 90 tests, all green on my machine (6 + 11 + 41 + 32).

Testing Matrix

Linked issues / bugs

Resolves QwenLM#2994