GitButler for Parallel AI Agents: Multiple Branches, One Build

GitButler lets parallel AI coding agents contribute separate branches to one working directory, so compatible changes can run together in one local application. Its parallel-agent documentation explicitly describes sharing a dependency installation and development server while committing each task's changes separately.

The appeal is immediate: keep a feature, an unrelated fix and another agent's task moving while you inspect their combined result. An agent can manage the version-control operations through the CLI, leaving the developer to direct the work and judge the product.

The next opportunity is multiplayer development: several people and agents coordinating around a continuously updated product. The difficult part is agreeing on what “updated” means. Current files, current agent knowledge and a tested integration are three different states.

Sources reviewed on 8 October 2026. Commands below follow current official documentation and are illustrative, not a recorded GitButler execution. The proposed operating policy and verification matrix are Wavect's analysis. “10x” speedups and “100x” multiplayer gains are discussed as experience claims and predictions, not measured Wavect results.

How can GitButler put multiple branches in one running build?

GitButler composes applied branches into a shared checkout while preserving their separate histories. Its workspace-branch documentation explains the generated gitbutler/workspace merge commit and the combined committed state visible to ordinary Git tooling.

This does not give every agent a private filesystem. They see the same files, dependency installation and generated output. That is useful when a customer filter and an unrelated invoice display fix can coexist. It becomes a coordination problem when both agents rewrite the same shared type or generate the same artifact.

“One running build” means the development process can use the combined files. It does not promise that every file update is atomic, that hot reload handles every change, or that dependencies and database state never require a restart. Our guide to atomic multi-file edits by coding agents explains what a running reader can observe while several files change.

Use GitButler's write operations in its managed workspace. Treating gitbutler/workspace as an ordinary feature branch and committing directly to it works against the arrangement the tool maintains.

When should AI agents share GitButler, and when should they use worktrees?

Share a workspace when the tasks can share files and runtime state. Use separate worktrees when they need incompatible checkouts or competing implementations. Git's own worktree documentation describes multiple working trees sharing a repository, with worktree-specific state such as HEAD and the index.

A worktree separates checked-out files; arrange separate ports, databases and external resources when the tasks also need those isolated. Conversely, two files living in different folders does not prove that their changes are independent. A shared schema, lockfile or migration can connect them.

For the wider repository and provisioning decision, see our Git worktrees versus Jujutsu guide for AI coding agents. The decision here is narrower: do you want a composed local application or physically separate working changes?

Can an agent control GitButler without using the desktop app?

Yes. GitButler documents an agent workflow driven through its but CLI. Start with the agent setup guide. After installing the CLI, run this from the repository:

but agent setup
but status

The wizard can install the skill, write workflow instructions and initialize workspace mode when needed. Review the proposed scope and instruction changes. The skill teaches the agent how to operate GitButler; repository permissions and branch protection provide the access limits.

You can then describe an outcome in ordinary language. For example:

Implement the customer filter on feature/customer-filter. Keep unrelated fixes separate. Coordinate changes to shared files with the other agent. Commit only this task's changes, and report the branch base and checks you ran.

That is a proposed task prompt, not a special command. The agent should translate it into the appropriate operations. For human inspection, GitButler supports CLI, TUI and desktop views through its agent-work review workflow.

The easy mistake is committing another agent's work. The current but commit reference says its default includes all uncommitted changes. Specifying a destination branch alone does not select only that task's edits. Select the intended files or hunks as positional change IDs.

The IDs below are examples. Replace q3, w7 and n2 with IDs from your own current output, and inspect each selection before proceeding. GitButler's CLI ID documentation warns that identifiers can change as workspace context changes.

but diff
but commit -b feature/customer-filter -m "Add customer filter" q3 w7

but diff
but commit -b fix/invoice-display -m "Fix invoice display" n2

but status

This follows the selective-commit approach in the branching and committing tutorial. If the named destination does not exist, -b creates it as a parallel branch. If it already exists but is not applied, the commit command rejects that target. Coordinate the selection and mutation so another writer does not invalidate what you just inspected.

How do multiple agents avoid overwriting or mixing each other's changes?

Branch assignment needs an ownership policy for the shared files. Assign each task a branch and a defined area of work. Call out common collision points in advance: routing tables, shared types, dependency manifests, lockfiles, migrations and generated code.

Consider a file that two agents read before either edits it. If the second agent later writes an outdated full-file replacement, it can remove the first agent's change before there are two preserved commits to merge. A branch label does not make that filesystem operation exclusive.

Our proposed policy is to keep independent implementation parallel and appoint one coordinating agent or developer for operations that change the shared workspace as a whole. Coordinate applying or removing branches, updating the target, reorganizing history and entering a conflict-resolution mode. Agents can handle that coordination; every routine decision need not return to a human.

Before editing a shared file, refresh the relevant content and agree who owns the change. Before committing, inspect the actual selected diff. After a peer changes an interface your task depends on, update your assumptions and rerun the affected checks. These are workflow recommendations, not a claim that GitButler enforces file ownership or automatically refreshes every agent's context.

Why can a green shared build still hide a broken branch?

A successful combined build validates the composition you ran. It does not establish that each branch works independently. This is the practical consequence of the documented hidden-dependency risk.

In a hypothetical example, branch A adds a delivery estimate to an API response. Branch B adds a badge that reads that field. With both branches applied, the feature works. If B is reviewed and shipped against a target that lacks A, the badge can fail even though no lines conflict.

If that dependency is intentional, make it explicit. The current but branch reference documents creating a dependent branch with but branch new delivery-badge --above delivery-api. If B was meant to be independent, remove the accidental dependency or change the delivery plan.

Run isolated branch or stack checks in an appropriate checkout or CI environment. Continuously removing branches from a workspace that other agents are editing can create a new source of interference.

GitHub's merge queue documentation illustrates the final distinction: required checks run against an integration of the latest target and queued changes. A queue runs configured checks; it does not prove behavior those checks never exercise.

Record exactly what was tested. If agents keep editing during a test run, its result may cover a mixture of states. Use a stable candidate for an approval decision, then revalidate when relevant inputs change. The shared preview remains valuable for fast feedback while the review evidence stays tied to a reproducible state.

What happens when reviewing someone else's branch creates conflicts?

First distinguish target mergeability from compatibility with the current workspace. The checks described by but branch list and but branch show BRANCH --check concern the upstream target. A branch that fits that target can still conflict with other changes you have applied locally.

Before a disruptive review, agree on the branch composition and record a recovery point. The operation-log reference documents but oplog snapshot -m "Before branch review". Record application state separately when needed; a version-control checkpoint is not a database backup.

The conflict-resolution CLI supports an AI-assisted path using --ai. It also documents but resolve conflicts and but resolve apply for working with conflicted commits without entering resolution mode.

The traditional interactive route has a different effect. The rebasing and conflicts guide describes temporarily replacing the composite checkout with the conflicted commit. Coordinate that change with other writers and with the running application. Do not assume every resolution path has identical workspace behavior.

An agent may finish a straightforward textual resolution quickly. A report of “under a minute” does not establish that the result preserves both tasks' intent. Review changed interfaces, behavior and generated artifacts, then run the relevant individual and integration checks. Resolution time and verification time are separate parts of the workflow.

Is a multiplayer GitButler workflow already available?

GitButler already supports collaboration through remote branches. The reviewed documentation does not establish an always-synchronized workspace for every participant's uncommitted work. Butler Flow explains applying teammates' remote branches alongside local work for early integration, including branches created without GitButler.

The but pull reference documents an explicit update: fetch remote changes and rebase all applied branches onto the updated target. but pull --check previews the update. Coordinate it with active agents because it can affect their shared working state.

The multiplayer direction is credible. In its Series A announcement, GitButler describes a future with earlier awareness of teammates' conflicts, work built on continuously changing branches, and agents understanding the team's activity. That is a public product vision, not a release commitment for every synchronization behavior a team might want.

Our bet is that the next substantial improvement will come from shortening the distance between a teammate's useful change and everybody else's informed response to it. Sharing code is part of that. Sharing which version was reviewed, what is still speculative and why a decision was made is equally necessary.

For collaboration through shared sessions and organizational context, see our Mosaic shared-agent-session analysis. Synchronized conversations and synchronized product state answer different questions.

What would “everyone is on the latest” actually require?

A useful multiplayer system needs to distinguish current files, current agent context and a current validated composition. This is our proposed way to evaluate the idea, rather than a description of an existing GitButler feature.

Automatic synchronization should preserve the ability to hold a stable review candidate while development continues elsewhere. A reviewer needs to know which revision they approved. A developer investigating a failure needs to reproduce it. A teammate should be able to decline a speculative branch without losing access to accepted work.

Dependencies also need to travel with the change. If a UI branch requires an API branch, the team should see that relationship before approving either in isolation. When a peer changes the API, affected agents need a reason to reread it, not merely a notification that some files changed.

That is the substantive “100x” ambition: reduce coordination delay across the team while preserving understandable, testable changes. The multiplier and arrival time remain predictions. More simultaneous edits alone cannot establish that improvement.

How should a team test the claimed development-speed improvement?

Measure accepted work and coordination effort, starting with a small, representative task pair. Try one feature and one independent fix. Check each review unit, run them together, and integrate against the current target. Repeat with the team's existing workflow and with separate worktrees where those are a credible alternative.

Use comparable tasks and record task complexity, agent/model configuration and reviewer availability. Track elapsed time to a reviewable, tested change, reviewer minutes per accepted change, integration rework and failures discovered only when a branch is tested independently. Count the model and infrastructure cost of retries and repairs as well.

A personal “10x” experience can be useful motivation to experiment. It does not determine another team's result. The improvement may come from fewer setup steps, fewer context switches, faster combined feedback or less manual version-control work. Identify which of those actually changed before attributing the entire gain to one tool.

Wavect's AI enablement service can help teams define that operating policy and evaluate it against delivery outcomes. Our Hyperstate AI engineering case study is a separate product engagement, not evidence of a GitButler deployment or speed benchmark.

Use the software QA checklist before launch to make acceptance criteria concrete, or discuss your team's parallel-agent development workflow. Bring two representative tasks, a recent integration failure and the review process you use today.