Skip to main content
A branch is a copy of your app where you can build and test changes without touching the live version. Each branch has its own isolated backend, so the Agent can work in parallel while your main app stays untouched. When you’re happy with the result, merge the branch back into main. If you don’t want the changes, don’t merge: nothing on a branch reaches your main app until you merge it.
Preview header showing the branch name picker with redesign-landing-page/v1 selected and a Merge button

​
When should I use a branch?

Use a branch when you want to try changes safely, away from your main app:
  • Test a risky change or large rework before it reaches your main app
  • Let the Agent work on a feature in the background while you keep building on main
  • Try changes against a copy of your real data without affecting production
  • Run several efforts in parallel, each on its own branch
For trying changes against throwaway data on a separate backend, see Environments. For running multiple Agents at once, see Multi-Agent.

​
How do I create a branch?

  1. Open your app in the Dashboard
  2. In the chat click the Branch icon (the icon to the right of New Chat)
Chat panel showing the New Chat button with the branch icon to its right
  1. Enter a Branch name
  2. Optionally turn on Replicate production data to copy your production database into the branch
  3. Click Create branch
Create branch dialog with a branch name field and a Replicate production data toggle
Hercules creates the branch with its own isolated backend. Branch names must be unique, you can’t reuse the name of a branch that’s already open.
Start your main dev session before creating a branch. If it isn’t running yet, open your app’s preview first, then create the branch.

​
What can I do on a branch?

A branch works like any other chat. You can:
  • Chat with the Agent and ask for changes
  • See a live preview of the branch as the Agent works
  • View the diff (the list of files the branch has changed compared to main)
  • Open more than one chat on the same branch, they share the same backend and code
The preview header shows the branch name and a Merge button so you can merge without leaving the preview.

​
How do I merge a branch into main?

Click Merge in the branch banner above the chat input. Merge brings your main app’s latest changes into the branch, then merges the branch into your main app in the same click. To review the combined result first, ask the Agent to bring your main app’s latest changes into the branch, then check Code diff and the branch preview. When the merge finishes, you’ll see Merged into main and a “Branch merged into main” confirmation. After a merge, the branch is done:
  • Its changes are now part of your main app
  • The chat for that branch can no longer be continued
To keep building, start a new chat on main or create a new branch.

​
What happens if there are merge conflicts?

A conflict happens when the branch and your main app both changed the same thing. If Hercules can’t merge cleanly, the banner changes to Resolve merge conflicts and shows which files conflict. Nothing reaches your main app until you ask the Agent to resolve them and click Merge into main branch.

​
Additional FAQ

A branch is one of three states:
  • Open. Active and being built. You can chat on it or merge it.
  • Resolving. A merge started but hit conflicts. Resolve them, then complete the merge.
  • Merged. The changes are now in your main app. The branch is finished.
Merged is final. To keep building, start a new chat or branch.
No. Once a branch is merged it’s finished, and its chat can’t be continued. Start a new chat on main, or create a new branch to keep building.
Merge uses the latest saved version of the branch. Before merging, Hercules saves any unsaved changes on the branch and brings in the latest main, so everything you see on the branch is included. To check what will be added to main, click Code diff next to Preview. Merging doesn’t publish your website, so your live site keeps its current version until you publish. Backend changes (functions, schema and indexes) don’t wait for Publish. If your main app uses your production backend, which is the default, they go live there the next time your main dev session starts, for example when you open your app’s preview. Your live site starts using them right away, so publish soon after merging. If your app has a development deployment, Publish sends backend changes to production instead.
Yes. After you create a branch, the New Chat in Branch button starts another chat on it. All chats on the same branch share the same backend and code, so changes from one show up for the others.
It copies your production database into the branch when the branch is created, so you can test against a copy of real data. The copy is a one-time snapshot, changes you make on the branch afterward don’t affect production. The option is only available if your app has a production deployment. See Environments and Database.
Version control tracks every change to your main app in sequence so you can revert. A branch is a separate, isolated copy where you build changes in parallel, then merge them back into main in one step. Use a branch to work safely off to the side, use version history to step back to an earlier point.
There is no way to delete or close a branch yet. Leave it unmerged: nothing on it reaches your main app. To hide it, click Branches, hover the branch, open Branch actions, and click Archive. Archiving hides the branch’s chats, and Unarchive in the same menu brings them back.
Each app can have up to 100 branches over its lifetime. Merging branches you’re done with keeps you well under the limit.
The branch’s backend is shut down, so its live preview stops. In its place you’ll see a notice explaining what happened. Your main app’s preview is unaffected.