Versions (Branching)

Versions enable parallel work, safe experimentation, and clear diffs in Lix. They allow you to create isolated environments for different tasks or experiments, similar to branches in Git.

Parallel work	Multiple AI agents — and human editors — can make different changes at the same time without overwriting each other's progress.
Risk free experiments	Let agents make changes without impacting the users' version—delete instantly if results disappoint.
Clear diffs & reviews	See exactly what each agent (or human) changed between versions.

Use case examples

Human-AI Agent Collaboration

1. Agent (or your orchestration layer) creates a version.
2. Agent writes data; Lix auto-commits each change.
3. Human (or another agent) asks for a diff vs main.
4. On approval, merge or discard the version.

// 1. Create and switch to an isolated version for Agent A
const versionA = await createVersion({ lix, name: "agent-a-playground" });
await switchVersion({ lix, to: versionA });

// 2. Agent writes changes (auto-committed under the hood)
await agentA.runTasks(lix);

// 3. Diff against main
const diff = await diffVersion({ lix, from: versionA.id, to: "main" });

// 4. Review / merge or drop
if (await humanApproves(diff)) {
  await mergeVersion({ lix, from: versionA.id, into: "main" });
} else {
  await deleteVersion({ lix, id: versionA.id });
}

A/B Testing

Let different AI agents create competing advertisements autonomously, then automatically promote the one with better conversion rates.

// Create parallel versions for competing agents
const versionA = await createVersion({ lix, name: "agent-a-campaign" });
const versionB = await createVersion({ lix, name: "agent-b-campaign" });

// Let agents work autonomously with their own strategies
(agentA.createAdvertisements(versionA), agentB.createAdvertisements(versionB));

// Compare performance and merge the winner
const winner = await determineWinner(versionA, versionB);

await mergeVersion({ lix, source: winner.id, target: "main" });

// Clean up the losing version
const loser = winner.id === versionA.id ? versionB : versionA;
await deleteVersion({ lix, id: loser.id });

// Winner function compares conversion rates
async function determineWinner(versionA, versionB) {
  const [conversionsA, conversionsB] = await Promise.all([
    getConversionRate(versionA),
    getConversionRate(versionB),
  ]);

  return conversionsA > conversionsB ? versionA : versionB;
}

Key benefits:

• Safe experimentation: Both agents work in isolation, no risk to production
• Data-driven decisions: Compare real performance metrics, not just agent confidence
• Easy rollback: If both experiments fail, main version stays untouched
• Scalable testing: Run dozens of agent experiments simultaneously

How Versions Work

Versions in Lix are like branches in Git—they are pointers to a specific commit that expresses state at a point in time.

Version A (main)      ──► commit (245) ↘
                                        commit (309) ──► commit (38e) ...
Version B (feature-x) ──► commit (sh4) ↗

[!NOTE] Lix uses the term "version" instead of "branch" because it's more intuitive for non-technical users. "Version" mirrors the familiar concept of duplicating a file and adding v2 or final to the file name e.g. something_v2.docx or something_final.docx.

Interactive example

Versions let you work with different states of your data in isolation. Here's a simple example showing how to update product prices in a separate version:

API reference quick-links

Function / Type	Purpose	Docs
createVersion()	Create a new version branch	API reference
switchVersion()	Change active version	API reference
createCheckpoint()	Create a labeled commit	API reference
LixVersion	Version type definition	API reference