Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt

Use this file to discover all available pages before exploring further.

Mesa versions every document with robust version control. The model is based on Jujutsu VCS which allows for full Git-compatibility while enabling more efficient agent-first workflows.

​
Core Primitives

​
Repository

A repository on Mesa is essentially just a folder that has its own version history and permissions. As the documents are modified in a repository the version history is updated and you can easily undo, redo, and modify this history as you please while never losing work. 
const repo = await mesa.repos.create({ name: "project-1234" });
When working with Mesa you’ll often have many repositories. For example, an app builder that turns user prompts into apps might treat every user app as a separate repository because two users building separate apps shouldn’t affect each other’s version history or documents.

​
Changes

The core primitive of Mesa’s version control is the Change. Think of a change as a logical unit of work or logical modification to your repository. Each change has a unique identifier, a message/description, and can contain anywhere from zero edited files to many edited files. An example of the change history for a simple repository that scaffolds an internal dashboard and adds a forecast widget might look like this: 
@  qzvqqupx   2026-03-16 10:42:31Z
│  Tune forecast widget behavior
○  puqltutt   2026-03-16 10:37:08Z
│  Add forecast widget
○  ovknlmro   2026-03-16 10:30:02Z
│  Seed dashboard layout
○  nuvyytnq   2026-03-16 10:24:19Z
│  Initialize dashboard repo
◆  root
Changes are organized into a Directed Acyclic Graph (DAG) of changes in the same way commits are in Git. This means that changes can have multiple parents and multiple children which allow for branching and merging. You can modify the change DAG with all the operations you’re familiar with: branching, merging, rebasing, reverting, cherry-picking, etc. Create a new change on top of an existing one by passing its id as base_change_id. The message serves as the change description. 
import { Buffer } from "node:buffer";

const change = await mesa.changes.create({
  repo: "project-1234",
  base_change_id: repo.head_change_id,
  message: "Add forecast widget",
  author: { name: "Agent", email: "agent@acme.dev" },
  files: [
    {
      path: "src/widgets/forecast.ts",
      action: "upsert",
      content: Buffer.from("// forecast widget").toString("base64"),
      encoding: "base64",
    },
  ],
});
From inside the virtual filesystem you can also create a new empty change on top of a bookmark and start editing files directly: 
// Create a new change from the tip of `main` and switch to it
await fs.change.new({ repo: "project-1234", bookmark: "main" });

const current = await fs.change.current({ repo: "project-1234" });

// Or switch to an existing change without creating a new one
await fs.change.edit({ repo: "project-1234", changeId: current.changeId });
When you mount the virtual filesystem, your first write automatically goes into a new change on top of the change/bookmark you targeted to keep you safe from accidental overwrites. Moving the bookmark is the typical way to accept those writes once you’re ready. See Writing to a Mount for more details.

​
Bookmarks

Git is very focused on branches but JJ uses lightweight bookmarks instead. A bookmark just a lightweight pointer to a specific change in the change DAG which allows you to use reference that change more easily. Almost any of our APIs where you can reference a change you can pass in either the change id or an associated bookmark. Bookmarks are mutable and can be moved from one change to another. Every repository on mesa has a default bookmark, usually called main although this is configurable when creating a repository. If cloned from an upstream like GitHub we will use the default branch as the default bookmark. 
@  qzvqqupx   2026-03-16 11:02:11Z  feature/widget
│  Polish widget interactions
│ ○  puqltutt   2026-03-16 10:58:40Z  main
├─╯  Prepare baseline release
○  ovknlmro   2026-03-16 10:30:02Z
│  Seed dashboard layout
○  nuvyytnq   2026-03-16 10:24:19Z
│  Initialize dashboard repo
◆  root
In the above version tree, we can see the main bookmark pointing to the puqltutt change and the feature/widget bookmark pointing to the qzvqqupx change. Create a bookmark at a given change and move it onto a newer change later: 
// Create a bookmark pointing at a change
await mesa.bookmarks.create({
  repo: "project-1234",
  name: "feature/widget",
  change_id: change.id,
});

// Move an existing bookmark to a different change
await mesa.bookmarks.move({
  repo: "project-1234",
  bookmark: "main",
  change_id: change.id,
});
To integrate the work on one bookmark into another, merge them. Mesa fast-forwards when possible and creates a merge commit when histories have diverged: 
const result = await mesa.bookmarks.merge({
  repo: "project-1234",
  target: "main",
  source: "feature/widget",
  delete_source: true,
});

console.log(result.merge_type); // 'merge_commit' | 'no_op'

​
Conflicts

Conflicts work exactly how they do in JJ. This is mostly the same as Git with the sole exception that conflicts are non-blocking. A change can be in a conflicted state and you can resolve the conflicts later or in some cases ignore them entirely. This prevents your agents from getting stuck and gives you maximum flexibility in how to handle conflicts. A conflict occurs when you’ve modified the same part of the same file in different ways on two separate branches and then try to merge them. We have multiple ways to resolve them. See dealing with conflicts for more details.

​
Dealing with conflicts

Mesa beta doesn’t currently have APIs for conflict resolution. These are coming in the next week.
A conflict happens when two branches start from the same base change and edit the same location differently Example: two separate branches edit overview.json and change the title property: Before any merge Both Chat A and Chat B have edited overview.json in the same place. 
@  qzvqqupx   2026-03-16 11:12:04Z  feature/chat-a
│  title = "Revenue + Forecast"
│ ○  puqltutt   2026-03-16 11:10:27Z  feature/chat-b
├─╯  title = "Revenue Q4 Summary"
○  ovknlmro   2026-03-16 10:58:40Z  main
│  title = "Revenue Overview"
◆  root
Chat B merges first Chat B merges first and creates a new change on top of the main bookmark. 
@  qzvqqupx   2026-03-16 11:12:04Z  feature/chat-a
│  title = "Revenue + Forecast"
○  puqltutt   2026-03-16 11:10:27Z  main
│  title = "Revenue Q4 Summary"
○  ovknlmro   2026-03-16 10:58:40Z
│  title = "Revenue Overview"
◆  root
Now, if we wanted to merge feature/chat-a into main Mesa will return an error because the new merge commit would be conflicted. Because conflicts are non-blocking, a merge can produce a conflicted change that you resolve later. The conflicted state would look like this: 
x  zxoosnnp   2026-03-16 11:13:52Z  main
│  (conflict) merge feature/chat-a into main
├─╮
│ ○  qzvqqupx   2026-03-16 11:12:04Z  feature/chat-a
│ │  title = "Revenue + Forecast"
○ │  puqltutt   2026-03-16 11:10:27Z
│ │  title = "Revenue Q4 Summary"
├─╯
○  ovknlmro   2026-03-16 10:58:40Z
│  title = "Revenue Overview"
◆  root
feature/chat-a bookmark still points to qzvqqupx (branched from original main change ovknlmro), while the conflicted merge change zxoosnnp combines both parents (qzvqqupx and puqltutt).
We will be adding more granular, line and hunk-based conflict resolution as well as powerful APIs for agents to resolve conflicts automatically.

​
Comparing to Git and JJ

Mesa is Jujutsu-based while retaining full Git compatibility. You can essentially treat changes like commits and bookmarks like branches but there are some key differences:
  • There’s no staging area like in Git. You are always editing an existing change and changes can evolve as you edit them. When you create a new change in Mesa it is initially empty and then you can edit and modify files at that change. This is ideal for agents running in sandboxes because any edits they make are automatically persisted to a very specific place in the version tree rather than being saved in some dangling staging area.
  • Bookmarks are like branches in git but lighter weight. They do not automatically move from one change to another but can be moved manually. The consequence of this is that you do not need to explicitly think about branching ahead of time. If you have a main bookmark, you can just create a new change from it and that’s effectively an unnamed branch. You can name it later or leave it unnamed and create new changes on top of it or just move the main bookmark to point at the new change.
Here’s a handy table to explain how Mesa version concepts map to Git and Jujutsu.
Mesa ConceptGitJJ
RepoRepoRepo
ChangeCommitChange
Bookmark~BranchBookmark

​
Syncing to GitHub & GitLab

Mesa can sync with arbitrary upstream git repositories including ones hosted on GitHub or GitLab. This is useful if you want to create a Mesa repository based on a template repo that lives in GitHub or use Mesa mounts as a faster way to access a GitHub-hosted repo. Add an upstream to a Mesa repository, then trigger a sync via syncUpstream in the SDK or the upstream syncs REST API. See GitHub Sync for setup, auth options, and sync observability.

​
Next steps