Branches, environments and pull requests

Every Hiveku project has built-in version control. You do not need GitHub to use branches: create one, work on it in the editor with a live preview and the AI chat, let Development or Staging serve it, open a pull request, and merge it into main when it is ready.

​

The working branch selector

The branch selector sits at the top left of the editor, next to the project menu. It shows the branch you are working on and switches everything in the editor to that branch:

• The file tree and every open file
• The live preview (each branch gets its own preview, see Branch previews)
• The AI chat, so edits from a chat turn land on the branch you are looking at
• The Database panel, which shows the shared project database with a note explaining that data is not branched

Open the selector to search your branches (when you have many), create a new branch, commit your changes, open a pull request, or jump to the Branches tab. main is always listed first and carries a lock icon; branches that already serve Development or Staging show a small environment dot; a branch with uncommitted changes shows an amber dot.

​

Uncommitted and committed changes

A branch has two states that the editor keeps separate: Commit changes in the selector records the whole branch as one commit. You write a message; there is no need to pick files. Uncommitted work is never lost between sessions, and Hiveku commits it for you whenever something needs a fixed point:

• Deploying a branch to Development or Staging commits your unsaved branch changes first (the commit is named after the deploy, for example Deploy to Development).
• Merging a pull request commits the source branch first, so the merge includes everything you saved.
• Creating a branch from a branch with uncommitted changes commits those changes first.
• Deleting a branch with uncommitted changes takes a snapshot first, so nothing disappears silently.
• An AI chat turn on a branch starts from a commit of your editor changes and ends with a single commit of what the AI wrote, so Undo this turn returns the branch to exactly where it was.

​

Environments: which branch each tier serves

Assign a branch from the Environments strip at the top of the Branches tab: pick a branch for Development or Staging and click Deploy. The strip shows what each tier is serving and since when. If a tier is assigned to a branch that has since been deleted, the strip flags it and offers a one-click Move back to main. The Deploy button in the top right understands the branch you are on:

• On main with no assignments, every tier deploys main as it always has.
• On a branch, Development and Staging offer Deploy branch to Development, or Bind Development to branch and deploy if the tier still serves main (Move Development from other to branch and deploy if it serves another branch). Hiveku confirms before moving a tier off main.
• Production offers Open pull request branch into main (or Review PR #n if one is already open). It never deploys a branch directly.

Each deploy of a bound tier ships the branch’s latest commit, and commits your unsaved branch changes first so what you see is what ships. The change count for that tier counts commits on the branch since its last deploy, plus any unsaved changes.

​

One database per project

Files are versioned; data is not. Every branch and every tier reads and writes the same project database, and uploaded assets in the Media library are shared across branches too. On a branch, the Database panel shows the development connection with a banner that reads: “One database for this project. Files on branch are versioned; the data you see here is the same on every branch and every tier.” This means a migration you run while working on a branch changes the database that production reads. Test schema changes against a copy of your data, or keep them additive until the branch is merged.

​

Content and visual editing stay on main

The CMS and visual editing work on main only.

• On a branch, the CMS panel is read-only and shows “Content lives on main. You are working on branch. Switch to main to edit content.” with a Switch button.
• Visual edit mode is unavailable on a branch (“Visual editing changes main. Switch to main to use it.”).
• Per-file Version History and checkpoint restore are main features. On a branch, use the branch’s commit history in the Branches tab and Undo this turn in the chat.

If the project has a CMS, the Environments strip warns you when you assign a branch to a tier: content edits always write to main, so they do not appear on that tier until the branch is merged, and a scheduled publish will report success without reaching it.

​

Pull requests

A pull request proposes merging a branch into main (or into another branch). Open one from the selector, from the Deploy menu’s Production entry while you are on a branch, or from the Branches tab. The pull request drawer shows:

• Title, source and target, status, and who opened it
• A note when main has changed since the branch was created, and a note when the branch has uncommitted changes that will be included
• The list of changed files; click one for a side-by-side diff

​

Strict merge

Merging is all or nothing. Hiveku performs a three-way merge against the point where the branch left main; if any file conflicts, nothing is merged and the drawer lists the conflicting files: “n conflicting files. Nothing was merged. Resolve them on branch and try again.” To resolve, switch to the branch, open each listed file, bring in the change from main by hand, commit, and merge again. A merge into main never edits main partially, so a half-applied merge cannot reach production.

​

After the merge

Once merged, Hiveku offers three follow-ups: Deploy production (ship the new main), Delete branch (any tier assigned to the branch moves back to main first), or Keep branch. If you were working on the merged branch, the prompt also offers Switch to main. Pull requests can be closed without merging and reopened later. The PR list in the Branches tab filters by Open, Merged, and Closed.

​

Branch previews

Each branch gets its own live preview, separate from the main preview.

• Switching to a branch starts its preview automatically. A boot card shows progress; most previews are ready in one to two minutes, and the editor waits up to five before offering a Start preview retry.
• The preview is marked ready only after the branch’s files have landed in it, so what you see is the branch, not a starter scaffold.
• Saves on the branch sync to its preview the same way saves on main sync to the main preview.
• A preview that has been idle for an hour is stopped. Switching back to the branch starts it again. You can also stop it yourself with Stop preview in the branch menu.
• A project can run up to five branch previews at a time.

​

From Claude Code and VS Code

Agents and editors work on a branch by naming it; nothing “checks out” or switches on the server.

​

Claude Code and other MCP agents

• The file tools take a branch parameter: project_files_bulk_get, project_files_bulk_save, project_file_get, project_file_save, project_file_delete, project_test_build, preview_http_get, and preview_screenshot. Omit it (or pass main) to work on main. The two preview tools need a running branch preview; start one with project_vcs_branch_preview. project_files_status accepts target: "branch:<name>" to compare local files against a branch.
• project_vcs_checkout reads a branch’s files; it does not switch anything. Pass branch to the file tools to work there.
• project_vcs_branches lists each branch with uncommitted and working_tree_etag. Record the etag when you pull and compare before you push to catch edits made elsewhere.
• project_vcs_commit with a files list commits those files. Called with no files, it promotes the branch’s uncommitted changes into a commit (the response reports promoted: true). If there is nothing to commit, it says so instead of creating an empty commit.
• project_vcs_diff_file returns one file’s before-and-after between two branches (from, to, path). For a pull request, from is the target and to is the source.
• Call project_vcs_env_bindings before deploy_site. The bindings decide what ships: a bound tier deploys its branch (unsaved changes are committed first), production always deploys main. deploy_site refuses any branch other than main for production and refuses a branch that does not match the tier’s assignment.
• With the Claude Code plugin, /hiveku:branch lists, creates, assigns and deletes branches, /hiveku:pr opens, reviews and merges pull requests, and /hiveku:code and /hiveku:deploy follow the same rules.

​

VS Code extension

• Hiveku: Switch Branch changes the branch your local folder tracks. Push and pull then operate on that branch; the status bar shows the current branch.
• Hiveku: Pull Requests lists open pull requests, opens a per-file diff for review, and merges, closes or reopens them.
• Hiveku: Environments → Branch assigns a branch to Development or Staging, and the deploy picker labels each tier with its branch (“development - serves branch feat/x”, “production - always main”).
• Hiveku: Preview Branch on Fly starts a branch preview from VS Code, and a companion command in the palette stops it.

​

Common questions