Lix

<p align="center"> <img src="https://raw.githubusercontent.com/opral/lix/main/assets/logo.svg" alt="Lix" height="60"> </p> <h3 align="center">Semantic version control system for AI agents</h3> <p align="center"> <a href="https://www.npmjs.com/package/@lix-js/sdk"><img src="https://img.shields.io/npm/dw/%40lix-js%2Fsdk?logo=npm&logoColor=red&label=npm%20downloads" alt="97k weekly downloads on NPM"></a> <a href="https://discord.gg/gdMPPWy57R"><img src="https://img.shields.io/discord/897438559458430986?style=flat&logo=discord&labelColor=white" alt="Discord"></a> <a href="https://github.com/opral/lix"><img src="https://img.shields.io/github/stars/opral/lix?style=flat&logo=github&color=brightgreen" alt="GitHub Stars"></a> <a href="https://x.com/lixCCS"><img src="https://img.shields.io/badge/Follow-@lixCCS-black?logo=x&logoColor=white" alt="X (Twitter)"></a> </p>

[!NOTE]

Lix is in alpha · Follow progress to v1.0 →

---

Lix is a semantic version control system for AI agents.

Lix is not a git replacement, nor is it explicitly designed for software engineering. The goal is to bring version control to industries other than software engineering like health, finance, policy making, design, etc.

What makes Lix unique:

• Semantic tracking - Understands changes semantically like "This paragraph changed", not "line 5 changed".
• Supports any file format - Tracks changes in .docx, .pdf, .json, etc. via plugins.
• Embeddable - Works as standalone repository, or on top of existing SQL databases.

---

📖 How does Lix compare to Git? →

---

Use cases

• AI agent sandboxing - Agents making changes to files can be tracked, diffed, and rolled back.
• Context management - Knowing what changed and why for better humant/agent performance.
• In-app version control - Branching and merging, audit trails, embedded in applications.

When to use & not to use lix

Use lix if your app or agent is modifying documents e.g. Word, PDFs, etc. Don't use lix if your main use case is not modifying documents, or the documents are on off generated artifacts that do not change.

Getting started

<p> <img src="https://cdn.simpleicons.org/javascript/F7DF1E" alt="JavaScript" width="18" height="18" /> JavaScript · <a href="https://github.com/opral/lix/issues/370"><img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/python/python-original.svg" alt="Python" width="18" height="18" /> Python</a> · <a href="https://github.com/opral/lix/issues/371"><img src="https://cdn.simpleicons.org/rust/CE422B" alt="Rust" width="18" height="18" /> Rust</a> · <a href="https://github.com/opral/lix/issues/373"><img src="https://cdn.simpleicons.org/go/00ADD8" alt="Go" width="18" height="18" /> Go</a> </p>

npm install @lix-js/sdk

import { openLix, selectWorkingDiff } from "@lix-js/sdk";

const lix = await openLix({
  environment: new InMemorySQLite()
});

await lix.db.insertInto("file").values({ path: "/hello.txt", data: ... }).execute();

const diff = await selectWorkingDiff({ lix }).selectAll().execute();

Semantic change (delta) tracking

Unlike Git's line-based diffs, Lix understands file structure through plugins. Lix sees price: 10 → 12 or cell B4: pending → shipped, not "line 4 changed" or "binary files differ".

JSON file example

Before:

{"theme":"light","notifications":true,"language":"en"}

After:

{"theme":"dark","notifications":true,"language":"en"}

Git sees:

-{"theme":"light","notifications":true,"language":"en"}
+{"theme":"dark","notifications":true,"language":"en"}

Lix sees:

property theme:
- light
+ dark

Excel file example

The same approach works for binary formats. With an XLSX plugin, Lix shows cell-level changes:

Before:

  | order_id | product  | status   |
  | -------- | -------- | -------- |
  | 1001     | Widget A | shipped  |
  | 1002     | Widget B | pending |

After:

  | order_id | product  | status   |
  | -------- | -------- | -------- |
  | 1001     | Widget A | shipped  |
  | 1002     | Widget B | shipped |

Git sees:

-Binary files differ

Lix sees:

order_id 1002 status:

- pending
+ shipped

How Lix Works

Lix uses SQL databases as query engine and persistence layer. Virtual tables like file and file_history are exposed on top:

SELECT * FROM file_history
WHERE path = '/orders.xlsx'
ORDER BY created_at DESC;

When a file is written, a plugin parses it and detects entity-level changes. These changes (deltas) are stored in the database, enabling branching, merging, and audit trails.

┌─────────────────────────────────────────────────┐
│                      Lix                        │
│                                                 │
│ ┌────────────┐ ┌──────────┐ ┌─────────┐ ┌─────┐ │
│ │ Filesystem │ │ Branches │ │ History │ │ ... │ │
│ └────────────┘ └──────────┘ └─────────┘ └─────┘ │
└────────────────────────┬────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────┐
│                  SQL database                   │
│            (SQLite, Postgres, etc.)             │
└─────────────────────────────────────────────────┘

Read more about Lix architecture →

Learn More

• Getting Started Guide - Build your first app with Lix
• Documentation - Full API reference and guides
• Discord - Get help and join the community
• GitHub - Report issues and contribute

Blog posts

• Introducing Lix: An embeddable version control system
• What if a Git SDK to build apps exists?
• Git is unsuited for applications
• Does a git-based architecture make sense?

License

MIT