Branches & Versioning

Branches

Every repo starts with a main branch. You can create additional branches for scenario testing — each branch is a full copy of the repo at a point in time.

Scenario comparison workflow

The core use case for branches is running “what-if” scenarios side by side. The workflow has four steps:

Step 1 — Create a scenario branch

create_branch("optimistic", base_branch="main")

This preserves the base model exactly as-is on main.

Step 2 — Edit models on the scenario branch

Use patch_file for small targeted edits or update_file for larger rewrites with branch="optimistic" to change assumptions (e.g. raise the growth rate from 20% to 35%). All changes stay isolated on the scenario branch.

Step 3 — Compare outputs

compare_branches(scenario_branch="optimistic")

Both branches run concurrently against the same data snapshot and execute the full project entrypoint. The response includes a structured diff showing which metrics changed and by how much. If you only care about one top-level output, pass output_name to focus the returned diff without changing what gets executed. Changes of 10% or more are flagged as significant:

Main branch revenue:     $1,200,000
Optimistic branch:       $1,450,000
Delta:                   +$250,000 (+20.8%) ⚠️ significant

Step 4 — Adopt or discard the scenario

If the scenario wins, merge it into main:

Solo work (Owner): call merge_branch directly — no review step needed.
Team workflow: call create_pull_request, have a colleague review and approve, then call merge_pull_request.

If the scenario is not useful, leave the branch as-is or delete it with delete_branch.

Merge permissions

Both merge_branch (direct) and merge_pull_request (PR-based) require Owner role. This protects main from unreviewed assumption changes.

Role	Create branches	Edit models on a branch	Merge
Viewer	No	No	No
Editor	Yes	Yes	No — must open a pull request
Owner	Yes	Yes	Yes — direct merge or via PR

Editors submit their work for review by opening a pull request with create_pull_request. An Owner then approves and merges via merge_pull_request. See the team collaboration guide for the full PR-based workflow.

Branch tools

Tool	Role required	Description
`create_branch`	Editor	Create a new branch from a base (default: `main`)
`list_branches`	Viewer	List all branches in a project
`compare_branches`	Viewer	Run a project on two branches and diff the outputs
`merge_branch`	Owner	Merge a scenario branch directly into a base branch
`delete_branch`	Owner	Delete a branch (cannot delete `main`)

Versioning

Every model change creates a Git commit. The version tools let you inspect and navigate this history.

Tool	Description
`list_versions`	Show commit history (optionally filtered to one model)
`diff`	Unified diff between two commits
`rollback_version`	Restore a model to a previous version (new commit, no rewrite)

Non-destructive rollback

rollback_version creates a new commit with the content from the target SHA. It does not rewrite history — the rollback itself is a versioned change with a full audit trail.