Branches

Branches are the primary unit of isolation in Omnigraph. Every repository starts with a main branch. You create additional branches to propose changes, run agent tasks, or experiment without affecting the canonical state.

Creating a branch

Create a new branch from an existing one:

omnigraph branch create --uri ./repo.omni --from main feature-x

The new branch feature-x starts at the same snapshot as main. No data is copied — the branch is a pointer that shares storage with its parent until a write causes a table to diverge.

Options

The final positional argument is the name of the new branch.

Listing branches

List all branches in a repository:

omnigraph branch list --uri ./repo.omni

{
  "branches": [
    { "name": "main", "snapshot_version": 5 },
    { "name": "feature-x", "snapshot_version": 5 },
    { "name": "enrichment-run-42", "snapshot_version": 7 }
  ]
}

Each entry shows the branch name and the snapshot version it currently points to.

Reading from a branch

Any read command accepts a --branch flag to target a specific branch instead of the default (main):

omnigraph read ./repo.omni \
    --query queries.gq \
    --name friends_of \
    --params '{"name": "Alice"}' \
    --branch feature-x

If --branch is omitted, the read runs against main.

Writing to a branch

Load and mutation commands also accept --branch:

omnigraph load ./repo.omni --data updates.jsonl --branch feature-x

omnigraph change ./repo.omni \
    --query mutations.gq \
    --name mark_completed \
    --params '{"slug": "auth"}' \
    --branch feature-x

Each write advances the branch to a new snapshot. Other branches are unaffected.

Agent runs

An agent run is a special-purpose branch created for a single task. Runs provide the same isolation as regular branches, plus lifecycle management:

Create a run

omnigraph run create --agent enrichment ./repo.omni

This creates an isolated branch for the enrichment agent. The run gets a unique identifier (e.g., run_0042).

Inspect a run

Check the status and mutations of a run:

omnigraph run show ./repo.omni run_0042

Publish a run

When the run is complete and validated, publish it to merge the changes back to main:

omnigraph run publish ./repo.omni run_0042

Publishing validates all mutations against the schema before merging. If validation fails, the run stays open and the error is returned.

Abort a run

If the run produced incorrect results, discard it:

omnigraph run abort ./repo.omni run_0042

The branch and its mutations are discarded. No changes reach main.