Branch

Conversation forks.

---

Purpose

Show alternative responses, create conversation branches, enable A/B testing.

Use <branch> when multiple valid paths should stay visible inside one interaction instead of being flattened into a single narrative.

---

Try it Live

editor.g

12345678910111213141516171819

Grain document editor

Edit the Grain document and inspect the rendered preview beside it.

<message role="assistant"> <think model="chain-of-thought" visible="false"> The user wants a weather update for Mumbai. </think> <stream>Checking Mumbai weather...</stream> </message> <tool name="get_weather" args='{"city":"Mumbai"}' status="running"> <input>City: Mumbai</input> <progress value="45" max="100">Fetching live conditions</progress> </tool> <tool name="get_weather" status="complete"> <result temperature="28" condition="sunny" humidity="65" /> </tool> <message role="assistant"> <stream>It is 28°C and sunny in Mumbai.</stream> </message>

preview

Interactive preview initializes after hydration.

Interactive preview initializes after hydration. Open the docs preview at /grain/; the site is mounted under the project base path.

---

G-Lang

<branch id="alt-1" label="Alternative: Recursive Solution" active="true">
  <message role="assistant">
    <artifact type="code" language="javascript">
      function factorial(n) {
        if (n <= 1) return 1;
        return n * factorial(n - 1);
      }
    </artifact>
  </message>
</branch>

<branch id="alt-2" label="Alternative: Iterative Solution">
  <message role="assistant">
    <artifact type="code" language="javascript">
      function factorial(n) {
        let result = 1;
        for (let i = 2; i <= n; i++) {
          result *= i;
        }
        return result;
      }
    </artifact>
  </message>
</branch>

---

Attributes

Attribute	Type	Description
id	string	Unique branch ID
label	string	Branch label
active	true | false	Is active branch
mergeable	true | false	Can merge
parent	string	Parent branch ID

---

States

CREATED → EXPANDED → ACTIVE
   ↓        ↓         ↓
MERGED  COLLAPSED  MERGING → ACTIVE

---

Events

Event	Description
branch.create	Branch created
branch.expand	User expanded
branch.activate	User switched to branch
branch.merge	Branch merged

---

Examples

Two alternatives

<message role="assistant">
  <stream>I found two possible solutions:</stream>
</message>

<branch id="opt-1" label="Option A: Quick Fix" active="true">
  <message role="assistant">
    <stream>Quick but temporary solution...</stream>
  </message>
</branch>

<branch id="opt-2" label="Option B: Permanent Fix">
  <message role="assistant">
    <stream>Comprehensive solution...</stream>
  </message>
</branch>

Nested branches

<branch id="main" label="Main Discussion" active="true">
  <message role="assistant">
    <stream>Main response...</stream>
  </message>
  
  <branch id="sub-1" label="Detail A">
    <message role="assistant">
      <stream>More details on A...</stream>
    </message>
  </branch>
</branch>

Mergeable branch

<branch id="draft" label="Draft Response" mergeable="true">
  <message role="assistant">
    <stream>This is a draft that can be merged...</stream>
  </message>
</branch>

---

Related

• Artifact — Content display
• Message — Container
• Playground — Try it live

Usage Notes

• Keep branch labels user-readable so the decision surface is understandable without opening every branch.
• Use active to indicate the current path instead of inferring it from order.
• Prefer branches when alternatives should remain inspectable; prefer <stream> plus final selection when the alternates are only internal.