herdr-gitui

Thin herdr plugin: run gitui in a sidebar pane.

• herdr owns open / focus / toggle, worktree-aware reuse, and column width
• gitui owns all git interactions (stock binary, stock keys)

No private runtime pin, no AI commit, no in-app customCommands. Use your existing gitui on PATH.

Requires herdr >= 0.7.0, bash, git, python3, and gitui on PATH.

Install

herdr plugin install Shi1xin/herdr-gitui

# pin a release tag:
# herdr plugin install Shi1xin/herdr-gitui --ref v0.1.0

Local development checkout:

herdr plugin link /path/to/herdr-gitui

Add keybindings to your active herdr config.toml:

[[keys.command]]
key = "prefix+g"
type = "plugin_action"
command = "herdr-gitui.open"

[[keys.command]]
key = "prefix+shift+g"
type = "plugin_action"
command = "herdr-gitui.open-tab"

[[keys.command]]
key = "prefix+u"
type = "plugin_action"
command = "herdr-gitui.expand"

If prefix+g is already bound (e.g. to herdr-lazygit.open), pick free keys.
Then: herdr server reload-config.

Actions

Action	Behavior
herdr-gitui.open	Current tab: open split → focus → close (toggle). Opens at sidebar width.
herdr-gitui.open-tab	Current workspace: open tab / switch tab / focus / close.
herdr-gitui.expand	Toggle the GitUI pane between sidebar and expanded widths.

Reuse rules:

• Pane label is GitUI (does not collide with herdr-lazygit’s Git).
• Foreground process must contain gitui.
• Same git worktree (or same directory if not a repo) as the launch target.

Config

herdr plugin config-dir herdr-gitui
# → e.g. ~/.config/herdr/plugins/config/herdr-gitui

Write panel.conf there (see panel.conf.example):

SIDEBAR_COLS=90
EXPAND_COLS=130
THEME_MODE=auto   # auto | light | dark
# RUNTIME_GITUI_BIN='/opt/homebrew/bin/gitui'

Theme

Stock gitui paints chrome with ANSI Blue / DarkGray, which reads poorly on neutral Ghostty palettes (e.g. grok-day / grok-night). On each launch the plugin copies themes/herdr-gitui-{light,dark}.ron into ~/.config/gitui/ and starts gitui with -t, picking light/dark from THEME_MODE or macOS appearance.

Layout

herdr-plugin.toml
panel.conf.example
themes/
  herdr-gitui-light.ron
  herdr-gitui-dark.ron
scripts/
  lib.sh              # config + binary resolve + theme + lock
  decide.py           # OPEN/FOCUS/CLOSE/SWITCHTAB
  run-gitui.sh        # pane entrypoint
  open-gitui.sh       # split launcher
  open-gitui-tab.sh   # tab launcher
  toggle-expand.sh    # width toggle
  layout-helper.py    # absolute set-width via herdr socket
tests/
  test_decide.py

Tests

python3 -m unittest tests/test_decide.py -v

Coexistence with herdr-lazygit

Both can be installed. Titles differ (Git vs GitUI). Bind different keys.

License

MIT