> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stardeck.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Feature Branches

> Run parallel project-agent workstreams inside one app

A **feature branch** is a separate code workstream inside one project. Each tracked branch has its own project-agent chat and sandbox preview, so you can develop and test in parallel without mixing conversations.

<Info>
  Feature branches are currently enabled for selected organizations. If the branch **New** action is
  missing from the project branch list, your organization does not currently have access.
</Info>

## When to use branches

Use a feature branch when you want a parallel workstream inside the **same** app:

* Building a feature while other work continues on the default branch
* Trying a risky experiment without blocking the main agent
* Isolating a bug fix while another agent keeps shipping elsewhere

This is still one project — not a separate app, [Surface](/app-structure/surfaces), [Module](/app-structure/modules), or [conversation fork](/conversation-forking).

## What branches isolate (and what they don't)

Branches isolate:

* **Code** — each branch has its own GitHub branch and commits
* **Chat / agent work** — each tracked branch has its own project-agent conversation
* **Sandbox runtime** — each branch has its own builder sandbox and preview

They do **not** isolate the project's development data store. All project branches share the same sandbox data. Schema and data writes made on one branch can be visible to the others.

<Warning>
  Coordinate schema and data-changing work across branches. Avoid competing migrations on multiple
  branches at the same time — one branch's data changes can affect every other branch's sandbox
  preview.
</Warning>

## Working with branches

<img src="https://mintcdn.com/stardeck/UEbKYtPALX90UlsU/assets/feature-branches-menu.png?fit=max&auto=format&n=UEbKYtPALX90UlsU&q=85&s=29b84e504aff98152bcdc98210df7f7d" alt="Project branch menu with Create new branch and Track existing branch actions" width="800" height="1048" data-path="assets/feature-branches-menu.png" />

1. Open the project **Branches** list or branch selector.
2. Create or track a branch:
   * **New → Create new branch** creates a GitHub branch from the currently open branch and starts tracking it in the project.
   * **New → Track existing branch** makes an existing GitHub branch available in the project builder.
3. Switch branches from the list. Each tracked branch opens with its own project-agent chat and sandbox.
4. Work with the agent and test in the builder sandbox preview on that branch.

## Agent-driven merge

The primary merge flow is agent-driven. From a non-default branch:

1. Click **Merge**.
2. Review the plain-language merge preview and any conflict warning, then confirm.
3. The request opens in the **default branch’s** chat. That branch’s agent performs the merge, resolves file conflicts, and verifies the result.

<Note>
  If the default-branch agent is busy, the merge is not queued — wait until its current run
  finishes, then try again. If the default branch chat has never been opened, open it once first,
  then retry the merge.
</Note>

After a successful merge, **Stop Tracking** the feature branch is optional cleanup.

## Preview deployments and publishing

Feature branches can create shareable preview deployments for review outside the project builder.

* The default branch preview uses `https://app-slug-preview.stardeck.site`.
* A feature branch preview uses `https://app-slug-preview-branch-name.stardeck.site`. Stardeck normalizes the branch name so the hostname stays DNS-safe.
* A project can have up to **5 active feature-branch previews**. The default branch preview does not count toward this limit.

Production publishing remains **default-branch only**. To ship feature-branch work to production, merge it into the default branch, verify the result, then publish. See [Publishing & Deployment](/publishing-deployment).

## Default-branch-only operations

Some project operations stay on the default branch:

* [Blueprint](/app-structure/blueprints) updates
* [Module](/app-structure/modules) installs, updates, and declaration sync

Work on those from the default branch after merging related changes.

## Branch management

Open branch settings (gear icon) for a tracked branch to:

* **View on GitHub** — open the branch on GitHub
* **Stop Tracking** — remove it from Stardeck; any active preview deployment and its hostname are cleaned up, while the GitHub branch stays intact

The default branch cannot be untracked.

## Feature branches vs conversation forks

|               | Feature branch                   | Conversation fork                   |
| ------------- | -------------------------------- | ----------------------------------- |
| Changes code? | Yes — full project agent         | No — read-only planning/exploration |
| Isolation     | Separate code, chat, and sandbox | Separate chat only                  |
| Goal          | Parallel build workstreams       | Explore ideas without touching code |

Need a scratch pad for plans without changing code? Use [conversation forking](/conversation-forking). Need a parallel agent that can edit and test? Use a feature branch.