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 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 — 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) 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) 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 (which calls IPC.PROJECT_UPDATE with { hideBranchInHeader }), and the Edit Project dialog in 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. The global toggle UI is in 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.

Related

• edit-a-project.md — the Edit Project dialog where the per-project toggle lives
• start-a-new-session.md — Isolate option creates a worktree, which switches the header icon
• open-settings.md — Settings → Appearance → Show current git branch in header (global toggle)