data/commands/builtin/branch_command library

Classes

BranchCommand

The /branch command — creates a fork (branch) of the current conversation.

ContentReplacementEntry

Represents a content-replacement record from the transcript. Without these in the fork JSONL, resume reconstructs state with an empty replacements Map, causing prompt cache misses and permanent overages.

ForkOrigin

Represents the origin of a forked transcript message.

ForkResult

Result returned after successfully creating a fork.

SerializedMessage

Lightweight representation of a serialized message for the fork log.

TranscriptEntry

A transcript entry extended with fork provenance metadata.

Functions

createFork({required String currentTranscriptPath, required String originalSessionId, required String projectDir, String? customTitle}) → Future<ForkResult>

Creates a fork of the current conversation by copying from the transcript file. Preserves all original metadata (timestamps, gitBranch, etc.) while updating sessionId and adding forkedFrom traceability.

deriveFirstPrompt(SerializedMessage? firstUserMessage) → String

Derive a single-line title base from the first user message. Collapses whitespace so multiline first messages (pasted stacks, code) don't flow into the saved title and break the resume hint.

generateUuid() → String

Generate a v4 UUID string.

getProjectDir(String cwd) → String

Get the project directory for session storage.

getTranscriptPathForSession(String projectDir, String sessionId) → String

Get the transcript path for a specific session ID.

getUniqueForkName(String projectDir, String baseName) → Future<String>

Generate a unique fork name by checking for collisions with existing session names. If "baseName (Branch)" already exists, tries "baseName (Branch 2)", "baseName (Branch 3)", etc.

isTranscriptMessage(Map<String, dynamic> entry) → bool

Check if an entry is a transcript message (not metadata like content-replacement).

parseJsonl(String content) → List<Map<String, dynamic>>

Parse JSONL content into a list of JSON maps.

saveCustomTitle(String projectDir, String sessionId, String title, String forkPath) → Future<void>

Save a custom title for a session by writing a metadata file.

searchSessionsByCustomTitle(String projectDir, String pattern, {bool exact = false}) → Future<List<Map<String, String>>>

Search for sessions matching a custom title pattern. Returns a list of maps with sessionId and customTitle fields.