Versions - Enable Parallel Work

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.

Versions


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

Agent (or your orchestration layer) creates a version.
Agent writes data; Lix auto-commits each change.
Human (or another agent) asks for a diff vs main.
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:

import { openLix, createVersion, switchVersion  } from "@lix-js/sdk";
import { plugin as jsonPlugin } from "@lix-js/plugin-json";

const lix = await openLix({
  providePlugins: [jsonPlugin],
});

// Get main version info for later use
const mainVersion = await lix.db
  .selectFrom("version")
  .where("name", "=", "main")
  .select(["id"])
  .executeTakeFirstOrThrow();

// Helper function to log file differences
const logFileDifferences = (allFiles: any[]) => {
  allFiles.forEach((file) => {
    const data = JSON.parse(new TextDecoder().decode(file.data));
    const versionName =
      file.lixcol_version_id === mainVersion.id ? "main" : "price-update";
    const tshirtPrice = data.items.find(
      (item: any) => item.name === "T-Shirt",
    ).price;
    console.log(`T-Shirt price in '${versionName}': $${tshirtPrice}`);
  });
};

// Create a product catalog file in the main version
await lix.db
  .insertInto("file")
  .values({
    path: "/products.json",
    data: new TextEncoder().encode(
      JSON.stringify({
        items: [{ id: 1, name: "T-Shirt", price: 29.99, stock: 100 }],
      }),
    ),
  })
  .execute();

// 1. Create a new version (branches from active version by default)
const priceUpdateVersion = await createVersion({
  lix,
  name: "price-update",
});

// 2. Switch to the new version
await switchVersion({ lix, to: priceUpdateVersion });

// 3. Modify the file - update prices
await lix.db
  .updateTable("file")
  .set({
    data: new TextEncoder().encode(
      JSON.stringify({
        items: [{ id: 1, name: "T-Shirt", price: 34.99, stock: 100 }],
      }),
    ),
  })
  .where("path", "=", "/products.json")
  .execute();

// 4. Query files across all versions to see the differences
const allFiles = await lix.db
  .selectFrom("file_all")
  .where("path", "=", "/products.json")
  .select(["lixcol_version_id", "data"])
  .execute();

logFileDifferences(allFiles);

API reference quick-links

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

ON THIS PAGE

#Versions - Enable Parallel Work

#Use case examples

#Human-AI Agent Collaboration

#A/B Testing

#How Versions Work

#Interactive example