Branch Switching Plugin

The Branch Switching Plugin adds per-conversation git branch selection to Codumentor. Each conversation can work on a different branch; when Workspace Isolation is active, the checkout is fully sandboxed and isolated from other conversations.

Overview

The Branch Switching plugin:

Lets users select a branch per repository via the UI before or during a conversation
Performs an isolated git checkout inside the conversation's bwrap overlay (requires Workspace Isolation)
Optionally builds a branch-specific vector index (overlay) so semantic search reflects the selected branch's code
Automatically recovers stale or interrupted overlay builds on startup
Publishes the active branch to the cross-plugin context so other plugins (e.g., Permalink) can use it

Requirements

Workspace Isolation is strongly recommended. Without it, branch checkout is skipped and a warning is logged — no changes are made to the working copy.
Git must be installed and available in PATH.

Configuration

Basic Configuration

plugins:
  - module: codumentor.plugins.branch_switching
    class: BranchSwitchingPlugin
    args:
      enabled: true
      overlay_indexing: true   # Build branch-specific vector indexes (default: true)

Configuration Parameters

enabled (optional): Whether the plugin is active (default: true)
overlay_indexing (optional): When true, maintains a Chroma overlay collection per branch that contains only the files differing from the default branch. This makes semantic search reflect the selected branch without re-indexing the full repository (default: true). Disable to reduce disk and compute usage at the cost of search accuracy on non-default branches.

Priority

This plugin runs at priority 6, after Workspace Isolation (priority 5), so the sandbox overlay is already set up when the branch checkout happens.

How It Works

Branch Selection

Users select a branch per repository from the Branch Selector UI widget (x-branch-selector), shown on the welcome/repos panel. The selection is stored in BranchStore and associated with the conversation ID.

Isolated Checkout

When a conversation starts (onContextReady), the plugin:

Reads the stored branch selection for the conversation
Checks whether Workspace Isolation is active
If isolated: runs git checkout <branch> inside the bwrap overlay (safe, no effect on other sessions)
If not isolated: skips checkout and logs a warning

For worktree-based snapshots where the branch is locked, the plugin automatically creates a local codumentor/switch/<branch> ref instead.

Overlay Indexing

If overlay_indexing is enabled, the plugin maintains a per-branch Chroma overlay collection. Overlays are built in the background and automatically rebuilt when the branch or base commit changes (staleness detection). Old overlays are cleaned up after 7 days. At most one overlay build runs per (repo, branch) pair at a time.

Admins can observe and manage overlays (force-rebuild, bulk-rebuild stale/errored, delete) from the Branch Overlays panel at the bottom of the Ingestion page (/admin/ingest).

UI

Widget	Element	Placement	Description
Branch Selector	`x-branch-selector`	`welcome-repos`	Select a branch per repository when starting a conversation
Branch Banner	`x-branch-banner`	`message-list-header`	Shows the active branch in the conversation header
Branch Overlays	`x-branch-overlays-admin`	`ingestion-panel`	Admin panel on the Ingestion page to observe/rebuild/delete per-branch overlays (admin-gated)

Events

Event	Description
`plugin.branch_switching.branches_set`	Fired when a branch selection is saved for a conversation
`plugin.branch_switching.overlay_ready`	Fired when a branch overlay index build completes
`plugin.branch_switching.overlay_error`	Fired when a branch overlay build fails