Working in parallel

Several chats or teammates building one app at the same time — one per feature — is a first-class workflow. Each branch is isolated, and the platform now answers 'what's in motion?' for you, so you don't have to keep a coordination doc by hand.

Why it's safe to run several at once

Every branch gets its own preview instance and its own playground sandbox — a separate database and storage — so parallel branches never share or contend on the same data, and none of them can touch production. You work on a branch, preview it at its own URL, and land it through a reviewed pull request. See Branches, PRs & merges for the core flow.

The coordination board

manage_branch (action: list) is the shared status board — call it before starting work, and whenever you want to know what else is moving. For every branch it returns:

  • purpose — what the branch is for (see below), so you can see at a glance who’s doing what.
  • ahead / behind — commits relative to main. behind > 0 means main has moved since this branch last synced.
  • migrations — the migration files on that branch’s HEAD.
  • deployedUrl / lastDeployAt — the live preview and when it last shipped.

Alongside the branches it returns migrationCoordination — takenNumbers, nextAvailable, and a suggestedPrefix — computed across all branches and outstanding reservations.

Say what a branch is for

A name like feature-x doesn’t tell another agent what you’re in the middle of. Give the branch a one-line purpose and it shows up in the list:

manage_branch({ action: "set_purpose", appId, name: "pricing-guard",
  purpose: "Add per-unit price floor + validation on the pricing form" })

You can also set it when you explicitly create a branch (create takes an optional purpose). This is the lookup that replaces a hand-kept “who’s working on what” document.

Stay in sync as main moves

When another branch merges, main advances under you. You’ll see it two ways without asking: behind > 0 in the branch list, and a mainMovedNote in the response to deploy_app on a preview. When it happens, pull main into your branch so you resolve a little now instead of a lot at PR time:

merge_from_main({ appId, branch: "pricing-guard" })

Different files (or non-overlapping edits to the same file) merge automatically; only genuinely overlapping edits come back for you to reconcile.

Reserve a migration number before you write it

Migration prefixes must be unique across all branches, not just your own. Two branches that both take “next free” end up with the same number and the merge is refused. When several agents run at once, claim the number atomically the moment you know you’ll add one — before writing the file:

manage_branch({ action: "reserve_migration", appId, name: "pricing-guard" })
// -> { number: 47, prefix: "0047", branch: "pricing-guard" }
// then write migrations/0047_price_floor.sql
Reservation is race-free even under simultaneous calls — two agents get two different numbers. The reserved number then shows up as taken in the list’s migrationCoordination, so nobody reuses it. See Database & migrations.

Parallel test runs

Test runs are serialized per branch (so two runs can’t contend on one sandbox), and each branch’s sandbox is separate from the others’. If a run looks like it’s reading stale rows a prior run left behind, start from a clean slate with run_tests({ resetData: true }) — see Testing.

A quick loop for several agents

  1. manage_branch (list) — see what’s in motion and the next free migration number.
  2. Start your branch and set its purpose.
  3. If you’ll add a migration, reserve_migration first.
  4. Build → deploy_app (preview). If it says main moved, merge_from_main.
  5. Open a PR; an admin reviews and merges. Non-overlapping work merges cleanly.