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

# Branches and AI tools

> How Hiveku AI, the Claude Code plugin, Codex, VS Code and AI apps work with versions, branches, reviews and the merge line, what each asks you first, and the full list of tools

AI tools use the same [versions](/editor/versions), [branches](/editor/branches), [reviews](/editor/reviews) and [merge line](/editor/merge-line) as people. A tool names the branch on every call; nothing "checks out" or switches on the server, so several tools and people can work on one site at once.

## The words AI tools use

| In the dashboard | In AI tools |
| - | - |
| Your site | `main` |
| Version | Commit (`project_vcs_commit`) |
| Review | Pull request, PR (`project_vcs_pr_*`) |
| Merge line | Merge queue (`project_vcs_queue*`) |
| Roll back | Rollback (`project_vcs_rollback`) |

## Hiveku AI

Hiveku AI, the chat in the editor, works on the branch the editor is on. The editor decides which branch a request works on, never the AI.

* **Its edits land on the branch** you are working on, and each request is saved as one version ("Saved automatically after an AI request").
* **Chatting on a branch** needs **Websites › Deployments: Manage**. A chat belongs to the branch it started on: switch back to that branch to carry on with it.
* **It asks you first** with an approval card in the chat before it merges a branch or a review, adds a review to the merge line (never as urgent), moves a review to another branch, shows a branch on Development or Staging, deletes a branch, moves changes that are not live yet to a branch, rolls back, or deploys.
* **It goes ahead without a card** to read branches, versions, reviews and the merge line; start a branch; restore an archived branch; open, close, decline and reopen reviews; comment and ask for changes (it never approves); resolve conflicts on the branch it is working on; and start or stop a branch preview.
* **A few tools refuse on a branch** because they change Your site directly, such as syncing universal components, adding from the section library, the redesign tools, and deleting, moving or optimizing images: "This tool changes your site directly, so it can't run while you're working on the branch *name*."
* **In plan mode** it changes nothing.

Hiveku AI is not affected by **Require reviews for outside AI tools**. With **Require an approval** on, it is the only AI that can merge a branch straight into Your site, and only after you approve its card.

## Outside AI tools

Outside AI tools (the Claude Code plugin, Codex, the VS Code extension, Hiveku Sync, and AI apps connected to Hiveku such as claude.ai and ChatGPT) connect with a person's own Hiveku key. Each call can do only what that person can do in the dashboard: a key whose creator can only read the site is read-only.

What no AI tool can do, whatever its key:

* approve a review (`403 approval_needs_person`)
* change Branch settings
* dismiss someone else's review, or edit or delete someone else's comment
* put a review at the front of the merge line, unless the key's creator is an owner or admin
* approve its own request on a merge-line [approval link](/editor/merge-line#the-approval-link)

When the site has **Require reviews for outside AI tools** on, these tools cannot change Your site's files at all: they save on a branch, open a review, and add it to the merge line. See [Require reviews for outside AI tools](/editor/merge-line#require-reviews-for-outside-ai-tools).

### Claude Code plugin

| Command | What it does | What it asks first |
| - | - | - |
| `/hiveku:branch` | Lists, creates, restores and deletes branches; shows one on an environment; rolls a branch back | Deleting names the branch and needs your yes; a rollback shows a dry run first |
| `/hiveku:pr` | Opens, lists, reviews, merges, closes, declines and reopens reviews; adds them to the merge line; resolves conflicts | Merging names From and Into and asks; the merge line is asked in plain words; each conflict is decided with you; review text is shown before it is posted |
| `/hiveku:review-pr` | A careful review: reads, builds and comments, then posts one review | Posts only after your yes; never approves |
| `/hiveku:commit` | Checks the build, then saves one version on Your site or a branch | Shows what will be saved and asks |
| `/hiveku:rollback` | Dry run, then rolls back; publishing is a separate step | Asks before rolling back, and again before publishing |
| `/hiveku:history` | Versions, the version log and restore points | Read only |
| `/hiveku:restore` | A restore point, a moment in time, or one file | Shows a dry run and confirms the target |
| `/hiveku:deploy` | Reads which branch each environment shows, then deploys | Asks |
| `/hiveku:preview` | Starts the preview of Your site or a branch | |

Whatever your Claude Code settings say, the plugin always asks before it saves a version with files, applies a rollback, resolves conflicts, or adds a review to the merge line. The ask list in its install guide also covers deploys, merges, environment changes, deleting branches, moving changes to a branch, editing a review, and restores.

The plugin tells Hiveku that it asks you first, so on a site that requires reviews for outside AI tools, it adds reviews to the merge line after its own question, with no approval link. See [Claude Code plugin](/integrations/claude-code-plugin).

### Codex

The Codex plugin's **hiveku-ship** skill covers the whole flow: save, check, version, deploy, roll back, branches, reviews, conflicts and the merge line. Codex asks before it deploys, saves several files at once, saves a version, merges, resolves conflicts, rolls back, edits a review, adds a review to the merge line, changes an environment, deletes a branch, moves changes to a branch, or restores. Everything else runs without asking, including saving or deleting a single file, creating branches, opening, closing and reopening reviews, comments, and taking a review out of the merge line.

### VS Code extension

The extension works from the Source Control view, the status bar (which shows the branch your folder tracks) and the command palette. It uses developer words: "pull request" for a review, "commit" for a version.

| Command | What it does |
| - | - |
| **Hiveku: Save a Version** | Names and saves a version |
| **Hiveku: Switch Branch…** | Changes the branch your local folder tracks; push and pull then work on it |
| **Hiveku: Create Branch…** | Starts a branch from the current one |
| **Hiveku: Merge Branch…** | Merges a branch into another, after a confirm |
| **Hiveku: Pull Requests…** | Lists reviews and whether each merges cleanly; opens side-by-side diffs; merges, closes and reopens them |
| **Hiveku: Environments → Branch…** | Shows a branch on Development or Staging ("This does NOT deploy") |
| **Hiveku: Move Pending Changes to a Branch…** | Moves changes that are not live yet to a new branch |
| **Hiveku: Delete Branch…** | Deletes a branch, after a confirm |
| **Hiveku: Compare Branches…** | Lists the files that differ between two branches |
| **Hiveku: Preview Branch on Fly…** / **Hiveku: Stop Branch Preview…** | Starts or stops a branch preview |
| **Hiveku: Show History** / **Hiveku: Go Back to a Version…** | Lists versions and rolls back to one, with an option to update the live site too |
| **Hiveku: Deploy…** | Labels each environment with the branch it serves ("production - always main") |
| **Hiveku: File History** (editor right-click) | One file's earlier copies, with **Compare File Version** and **Restore This Version** |

VS Code has no merge line, and it cannot approve or post reviews: **Open in the dashboard** takes you there. A merge refused for conflicts offers **Resolve in the dashboard**, or **Resolve here** to keep one side per file, then **Merge again**. A change to an archived branch offers **Restore branch**.

In folders it sets up, the extension also adds Claude Code commands (`/hiveku-branch`, `/hiveku-pr`, `/hiveku-commit`, `/hiveku-rollback` and more) that ask before a rollback, resolving conflicts, or adding to the merge line.

### AI apps connected to Hiveku

AI apps connected through Hiveku's connector, such as claude.ai and ChatGPT, use the same tools. Their apps do not ask you before adding a review to the merge line, so on a site that requires reviews for outside AI tools, Hiveku sends them an [approval link](/editor/merge-line#the-approval-link) to give you instead.

## The tools

### Versions and status

| Tool | What it does |
| - | - |
| `project_vcs_status` | What is not in a version yet on Your site or a branch, and which version each environment runs |
| `project_vcs_commit` | Saves a version. With no files, it versions the latest changes; with files, it writes them and saves a version in one step |
| `project_vcs_history` | Versions, newest first, with who saved each and where each runs |
| `project_vcs_rollback` | Goes back to a version. A dry run by default; applying on Your site needs `expected_head_commit_id` from the dry run (send it on a branch too) |
| `project_vcs_compare` | The files that differ between two branches |
| `project_vcs_diff_file` | One file's two sides between two branches |
| `project_vcs_checkout` | A branch's files, page by page. A read: nothing switches |

### Branches

| Tool | What it does |
| - | - |
| `project_vcs_branches` | Branches, with how far ahead and behind each is, latest changes, `working_tree_etag`, description and links. `include_archived` lists archived ones too |
| `project_vcs_branch_create` | Starts a branch from a branch, or from a version (`from_commit_id`) |
| `project_vcs_branch_update` | Changes a branch's description and linked tasks and feedback |
| `project_vcs_branch_delete` | Deletes a branch (`confirm: true`) |
| `project_vcs_branch_restore` | Brings back an archived branch, within 30 days |
| `project_vcs_stash` | Moves changes that are not live yet to a new branch. A dry run by default |
| `project_vcs_prune` | Cleans up branch storage nothing uses. A dry run by default |

### Merging and conflicts

| Tool | What it does |
| - | - |
| `project_vcs_merge` | Merges a branch into another directly. Files that merge cleanly go in; conflicts come back to resolve |
| `project_vcs_conflicts` | A branch's conflicts with the branch it was started from |
| `project_vcs_resolve` | Settles conflicts (`branch`, `parent`, or the final `content`) as one version on the branch. A `branch` or `content` choice carries `parent_hash`, so a later change on the other side is never lost |

### Reviews

| Tool | What it does |
| - | - |
| `project_vcs_pr_create` | Opens a review. The answer already says whether it merges cleanly and what it collides with |
| `project_vcs_pr_list` / `project_vcs_pr_get` | Lists reviews; one review with its changes, `mergeable`, `review_status` and place in the merge line |
| `project_vcs_pr_merge` | Merges a review: all or nothing |
| `project_vcs_pr_update` | Changes the title, description, draft state, where it goes, or whether the branch is kept |
| `project_vcs_pr_close` / `project_vcs_pr_decline` / `project_vcs_pr_reopen` | Closes, closes with a reason and note, or reopens |
| `project_vcs_pr_review` | Comments or asks for changes, with line comments. Never approves |
| `project_vcs_pr_reviews` / `project_vcs_pr_review_dismiss` | Reads the reviews; takes back the tool's own |
| `project_vcs_pr_comment`, `_comments`, `_comment_edit`, `_comment_delete`, `_comment_resolve`, `_comment_unresolve` | Comments, line comments and replies; reads, edits, deletes, resolves and reopens conversations |

### The merge line and settings

| Tool | What it does |
| - | - |
| `project_vcs_queue` | Reads the merge line |
| `project_vcs_queue_add` | Adds a review: `priority`, `depends_on`, and `approval_token` after an approval link |
| `project_vcs_queue_remove` / `project_vcs_queue_update` | Takes a review out; changes its priority or what it waits for |
| `project_vcs_settings` | Reads the three Branch settings. No tool changes them |

### Environments, previews and builds

| Tool | What it does |
| - | - |
| `project_vcs_env_bindings` | Which branch Development and Staging show. Read it before deploying |
| `project_vcs_env_bind` | Shows a branch on Development or Staging, or sets it back to Your site. Production always shows Your site |
| `deploy_site` | Deploys an environment. It ships what the environment shows; `branch` checks that it is the one you expect |
| `project_vcs_branch_preview` / `_status` / `_teardown` | Starts a preview of a branch or a version, checks on it, stops it |
| `preview_http_get`, `preview_screenshot`, `preview_logs` | Take `branch` to work on a branch's preview |
| `project_test_build` | Builds without deploying; with `use_db_state: true` and `branch`, it builds the branch |

The file tools take `branch` too: `project_files_bulk_get`, `project_files_bulk_save`, `project_file_get`, `project_file_save` and `project_file_delete`. Leave it out, or pass `main`, to work on Your site. `project_files_status` accepts `target: "branch:<name>"`.

The checks `verify_typecheck`, `verify_lint` and `verify_run_tests` run in Your site's preview only.

## When a tool is refused

| Answer | When | What to do |
| - | - | - |
| `409 pull_request_required` | A change to Your site, on a site that requires reviews for outside AI tools; or a direct merge into Your site on a site that requires an approval | Save on a branch, open a review, add it to the merge line |
| `409 merge_queue_required` | Merging a review into Your site, on a site that requires reviews for outside AI tools | Add the review to the merge line |
| `202 approval_required` | Adding a review to the merge line from an app that does not ask you first, on a site that requires reviews for outside AI tools | Give the person the `approval_url`, then repeat the call with `approval_token` |
| `409 approval_required` | Merging into Your site without a current approval | A person approves the current changes in the dashboard |
| `403 approval_needs_person` | An approval from an AI tool | Only a person approves |
| `409 source_changed` | The branch changed after the approval the merge relies on | Review the current changes again |
| `409 merge_conflicts` | Files changed in the same place on both sides | Resolve with `project_vcs_conflicts` and `project_vcs_resolve`, then merge again |
| `409 pull_request_is_draft` | Approving, merging or queueing a draft | Mark it ready (`project_vcs_pr_update`) |
| `409 branch_archived` | A change to a branch archived after its review merged | Restore it with `project_vcs_branch_restore` |
| `409 branch_busy` / `409 pr_merge_busy` | Someone else is writing the branch, or another review is merging | Try again in a few seconds |
| `409 nothing_to_commit` | Saving a version with nothing new | Nothing to do |

## Working on a shared site

When several people and AI tools work on one site:

1. Read the merge line (`project_vcs_queue`) and the open reviews before you start.
2. Start a branch for each piece of work, and save on it by name.
3. Record `working_tree_etag` from `project_vcs_branches` when you read, and check it again before you write, to catch changes made meanwhile.
4. Open a review and add it to the merge line. Joining is the approval to merge, so ask the person first.
5. Publishing is a separate step. Merging never puts anything live.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.