PIDGIN-BRANCH(1)

NAME
pidgin-branch - Branch from existing conversation states

SYNOPSIS
pidgin branch CONVERSATION_ID [OPTIONS]

DESCRIPTION
The branch command creates a new conversation that continues from a specific point in an existing conversation. This allows exploring alternate conversation paths by changing prompts, models, or parameters while preserving the conversation history up to the branch point.

Branching is useful for:

•   Testing how different prompts affect conversation direction

•   Comparing different model responses to the same context

•   Exploring "what if" scenarios in conversation development

•   Creating conversation trees for analysis

ARGUMENTS

CONVERSATION_ID
    The conversation to branch from. Can be the full ID or a unique prefix.

OPTIONS

--turn N
    Turn number to branch from (required). The new conversation will include all messages up to and including this turn.

--prompt TEXT
    Custom prompt to inject at the branch point. If not provided, continues with normal message flow.

--agent-a MODEL
    Override agent A model for the branched conversation. Default: use the same model as the original.

--agent-b MODEL
    Override agent B model for the branched conversation. Default: use the same model as the original.

--max-turns N
    Maximum turns for the branched conversation. Default: same as original conversation.

--temperature FLOAT
    Set temperature for both agents in the branch.

--temp-a FLOAT
    Set temperature for agent A only.

--temp-b FLOAT
    Set temperature for agent B only.

--speaker AGENT
    Which agent speaks next (agent-a or agent-b). Default: follows natural turn order.

--name NAME
    Name for the branched conversation. Default: auto-generated based on original name.

--tail
    Show live conversation output (same as run --tail).

BEHAVIOR
When branching:

    1.  The original conversation's history up to the branch turn is copied

    2.  System prompts and configurations are preserved unless overridden

    3.  A new conversation ID is generated with branch metadata

    4.  The branch continues from the specified turn with new parameters

    5.  Both conversations remain independent and can be analyzed separately

EXAMPLES

Branch from turn 10 of a conversation:
    pidgin branch conv_abc123 --turn 10

Branch with a custom prompt injection:
    pidgin branch conv_abc123 --turn 15 \
        --prompt "Let's explore a different perspective on this topic"

Branch with different models:
    pidgin branch conv_abc123 --turn 20 \
        --agent-a gpt-4 --agent-b claude

Branch with modified temperature:
    pidgin branch conv_abc123 --turn 10 \
        --temperature 1.2 --name "high-temp-branch"

OUTPUT
Branched conversations are saved with metadata indicating:

•   Original conversation ID

•   Branch point (turn number)

•   Timestamp of branch creation

•   Any parameter overrides

The branch appears as a new conversation in experiments and can be analyzed independently or compared with the original.

NOTES
Branching does not modify the original conversation. All branches are independent conversations that happen to share initial history.

Multiple branches can be created from the same conversation at different turns or even the same turn with different parameters.

SEE ALSO
pidgin(1), pidgin-run(1), pidgin-info(1)

AUTHOR
Nicholas Lange and contributors