Better Sidebar

A spaces sidebar that shows each space's Git branch on the same row, nests worktrees under their main checkout, and colours each space by its pull request's state. The same mod also draws an agents list, a one-line footer and a right panel toggle.

Version 3.2.0Needs: Git, ghSource on GitHub

Install with the prompt below. It takes the place of your spaces list.
Each space shows its branch on the right and its PR state below the name. Cmd-click the PR number to open it on GitHub.
Click the icon beside Agents to group agents by space, main space or name prefix.

Read ~/.config/herdr-app/AGENTS.md, then add this mod: https://github.com/munza/herdr-mods/tree/main/better-sidebar

Requirements: Git on every machine whose spaces you use, and the GitHub CLI logged in with gh auth login, with access to the repositories you want to show. There is no Node.js dependency.

The agent reads the package, tells you that it runs Git and gh and reaches GitHub with your local login, and copies only mods/better-sidebar/ into the app configuration. The manifest uses "place": "none", so the agent replaces your existing spaces block's mod reference instead of adding a second sidebar, keeping its ID, size, the agents list, other panels and key bindings. Herdr's shipped layouts (main, terminals, win98) are read-only, so if you are on one the agent clones it and edits the clone; if you already have your own layout, it asks whether to add the mod there or make a new one.

Each block is optional. The spaces block references "mod": "better-sidebar", the agents block { "mod": "better-sidebar", "props": { "view": "agents" } }, and the footer block { "mod": "better-sidebar", "props": { "view": "footer" } } at 37px high. The right panel toggle sits in a row beside the tab bar:

{ "id": "tabs-row", "type": "row", "size": { "px": 42 }, "children": [
  { "id": "tabs", "type": "block", "window_drag": true, "content": { "mod": "better-tabs" } },
  { "id": "panel-toggle", "type": "block", "size": { "px": 36 }, "content": { "mod": "better-sidebar", "props": { "view": "panel-toggle" } } }
] }

The included keys.json binds Cmd+Shift+B on macOS to better-sidebar.toggle-panel. Merge it into ~/.config/herdr-app/keys.json. The command only works while the panel toggle block is in the layout.

To roll back, point the spaces block back at the previous mod. Leave that mod installed if other layouts still use it.

Branches: the current branch sits beside the space name, small and dim. main, master and a branch that repeats the space name are hidden. The selected space also shows how far it is ahead of or behind its remote.
Worktrees: worktree spaces nest under an open space for the same repository, each with its own branch and PR. A worktree whose main space isn't open stays a top-level row.
PR: at the right of the space's row, an icon and number coloured green Open, gray Draft, purple Merged, red Closed or red Checks failed. Hover for repository, title and status. Several open PRs show the newest with a +N summary; hover it for the others.
Spaces and Agents tabs: the lists view puts both lists in one block. Spaces shows each space's tabs beneath it, joined by tree lines, as the tab's title with its program beside it (1 Claude Code, 2 zsh); click one to open it. Pinned agents sit in a Pinned group above every space. Agents shows the agents list with its grouping menu at the right of the tabs, and a count on the tab. The tab you pick is remembered. On the narrow rail the two lists sit one above the other.
Open a PR: Cmd-click the number (Ctrl-click on Linux and Windows) to open it on GitHub. A plain click selects the space.
Spaces as before: click to select, right-click for the space menu, drag to reorder within a machine, plus to create a space, machine groups with fold, and a compact rail when the sidebar is narrower than 160px.
Agents grouping: the icon beside Agents picks Priority, Grouped by space, Grouped by main space (a worktree's agents go with its main checkout; needs this mod's spaces block in the same layout) or Grouped by prefix (names like PR-12, INS-4, feature/INS-4; the rest go under No prefix, last).
Footer: Settings and Add machine as icons on one line, with names in tooltips. Settings shows a dot when an update is ready. With Better Config installed, a Mod settings icon opens it.
Right panel toggle: the panel icon at the far right of the tab bar hides or shows the right panel without changing its selected view. It is dim while the panel is hidden.
Errors: if gh fails, the last good PR stays for the same branch, marked stale, with the error on hover. With no earlier result it reads PR unavailable.

A space's branch and PR come from its first terminal's live folder, falling back to the space's folder. Only GitHub.com HTTPS and SSH remotes are supported. PRs refresh at most once a minute per checkout, and straight away when the branch changes. The mod only reads: it never stages, commits, checks out, creates PRs or changes Git configuration.

Change them in Better Config or in ~/.config/herdr-app/mods/better-sidebar/mod.json under "settings".

Key	Default	What it does
`git.retry_after`	`15s`	How long a failed Git read waits before it's tried again.
`combined`	`true`	Show the `lists` view as Spaces and Agents tabs. Off stacks spaces above agents in the same block.
`pull_request_status`	`true`	Colour spaces by their PR's state through the GitHub CLI. Set `false` if you don't have `gh`.

Copy mods/better-sidebar/ into ~/.config/herdr-app/mods/ again (or ask your agent to). This replaces mod.json, so copy your settings block forward, or let Better Config notice the reset and offer to restore each value.

One mod draws five blocks. props.view picks which:

`props.view`	Other props	What it draws
(none)	None	The spaces list. This is the default.
`lists`	None	Spaces and agents in one block, under Spaces and Agents tabs (or stacked with `combined` off). Estro uses this.
`agents`	None	The agents list with its grouping choices.
`footer`	None	The one-line footer. Give its block a 37px height.
`panel-toggle`	`target`: the layout node to toggle, default `panel`	A 36px button that runs `layout.toggle` on the target.

Command: better-sidebar.toggle-panel toggles the target, only while a panel-toggle block is in the layout.

The spaces view publishes better-sidebar.space-parents in shared state from its Git data; the agents view reads it for Grouped by main space.

A branch.<branch>.herdr-pr Git setting such as owner/repo#42 overrides automatic PR discovery. The mod only reads that setting.

Work on the mod

mods/better-sidebar/main.js: picks the part from props.view. settings.js: shared with the other mods.
git/checkouts.js: reading a space's checkout. git/pr-status.js: GitHub discovery, PR appearance, caching and stale results.
views/spaces.js, views/agents.js, views/footer.js, views/panel-toggle.js: the parts. views/ui.js: the design kit.
icons/: the mod's icons. sync.sh: copies the mod into Herdr, which reloads it (a symlink loads the code but not the icons).
tests/spaces.test.cjs, tests/agents.test.cjs: tests with Herdr stand-ins.

node --test tests/*.test.cjs
herdr-app check "$PWD/mods/better-sidebar"

Better Sidebar

Quick start

Install

Use

Settings

Update

For developers

Work on the mod