--- title: Branch header --- # Branch header ## What it is When a session's working directory is a git repository, Omniscio can show the **current git branch name** in the session header (off by default — enable it in **Settings → Appearance**) — small grey text next to the session name, with a branch icon (`GitBranch`) or a folder-plus-branch icon (`FolderGit2`) if the session is running on a per-session **git worktree** (see [start-a-new-session.md](start-a-new-session.md) Isolate option). Hovering shows a tooltip like "Current git branch: feat/add-auth" or "Current git branch: feat/add-auth (worktree)". ## Where to find it ### How to use it 1. **To hide the branch for ONE project.** Right-click the project in the **Projects sidebar** and pick **Hide branch in header** (or open the project's edit dialog via the three-dot menu → **Edit project** and flip **Hide git branch in header**). The toggle takes effect immediately on every session in that project. The same menu entry now reads **Show branch in header** so you can flip it back. 2. **To show the branch app-wide.** It's **off by default** — open Settings (gear icon) → **Appearance**, scroll to **Show current git branch in header**, and turn it on. Per-project toggles still apply on top — turning the global toggle off hides everywhere; turning it on falls back to the per-project setting. 3. **To force-refresh the branch.** The header polls automatically; if it ever looks stale, switching to another session and back re-runs the watch. 4. **What it shows for worktree sessions.** When you launched the session with **Isolate** turned on, the icon switches from a plain branch glyph to a folder-plus-branch glyph and the tooltip appends "(worktree)" — a visual reminder that this session is operating on a git worktree copy of the project, not the main checkout. 5. **Why no branch shows up.** The folder isn't a git repo (no `.git/`), it's a virtual project, the per-project hide toggle is on, the global toggle is off, or the watch hasn't reported a result yet. There's no error UI for "git not installed" — the header just stays empty. ## How it behaves It updates live — if the agent runs `git checkout` or you switch branches in another terminal, the header reflects the change within a couple of seconds. The header is read-only: there's no way to switch branches by clicking it. The branch indicator is hidden in three cases: 1. The session's project has **Hide git branch in header** turned on (per-project toggle). 2. The global **Show current git branch in header** setting under **Settings → Appearance** is off (defaults to off — the badge is opt-in). 3. The project's folder is a virtual project (Settings, Inbox, Recipes, etc. — those have no git working directory). The branch text only appears on desktop layouts (`md:` breakpoint and up); mobile session headers omit it to save horizontal space. ## For agents ### How it works The display component is [SessionHeaderBranch.tsx](../../src/renderer/src/features/sessions/SessionHeaderBranch.tsx) — a tiny presentational component that returns `null` when `enabled` is false or `branch` is empty. It's rendered inside the session panel's own header ([SessionPanel/SessionPanelHeader.tsx](../../src/renderer/src/features/sessions/SessionPanel/SessionPanelHeader.tsx)) wrapped in a `hidden md:block` div so it only appears on desktop. The `branchEnabled` flag combines the global setting (`settings.showCurrentBranchInHeader`, default `false`) with the per-project flag (`!sessionProject.hideBranchInHeader`) and an `isVirtualProjectPath` check. The branch value comes from a watch loop. The session panel calls `IPC.SESSION_WATCH_BRANCH` (handler in [src/main/ipc/git-handlers.ts](../../src/main/ipc/git-handlers.ts)) when it becomes visible; the handler calls `startBranchWatch({ sessionId, cwd })` against the session's `worktreePath` (if isolated) or the project's resolved working directory. The handler short-circuits when `project.hideBranchInHeader` is true or the project is virtual. Branch updates push back to the renderer, which stores them on `useSessionStore` as `activeSessionBranch` + `activeSessionIsWorktree` — those drive the component. The per-project toggle has two entry points: the right-click menu in [ProjectListItem.tsx](../../src/renderer/src/features/dashboard/ProjectListItem.tsx) (which calls `IPC.PROJECT_UPDATE` with `{ hideBranchInHeader }`), and the Edit Project dialog in [EditProjectDialog.tsx](../../src/renderer/src/features/projects/EditProjectDialog.tsx) (which writes the same field on save). The DB column is `hide_branch_in_header` on the `projects` table; mapping is in [queries-projects/projects.ts](../../src/main/db/queries-projects/projects.ts). The global toggle UI is in [AppearanceSettings.tsx](../../src/renderer/src/features/settings/sections/appearance/AppearanceSettings.tsx) under the `data-setting-id="show-current-branch-in-header"` row. The CLI control server's project PATCH endpoint also accepts `hideBranchInHeader` as a cosmetic update (no approval gate) — see [cli-server-project-routes.ts](../../src/main/services/cli/cli-server-project-routes.ts). ## Related - [edit-a-project.md](edit-a-project.md) — the Edit Project dialog where the per-project toggle lives - [start-a-new-session.md](start-a-new-session.md) — Isolate option creates a worktree, which switches the header icon - [open-settings.md](open-settings.md) — Settings → Appearance → Show current git branch in header (global toggle)