Herdr 與 herdr-file-viewer 安裝小記
環境：
- macOS 26.6.2
- Herdr 0.9.5
- herdr-file-viewer 1.18.0
- git-delta 0.20.1 / glow / bat
- git-graph 0.8.3
- Antigravity CLI 1.5.9
今天來安裝最近很熱門的套件 Herdr, 我裝的是 CLI, 然後他也有 GUI
安裝想法
- Herdr 相對於 Tmux 已知道 AI agent 以及他的狀態, 故在多 agent 的工作情境時, 可以讓 herdr 去關注 ai agent 的狀況, 讓人類即時接手
- 想要找個 vscode 的 CLI 平替環境 (檔案樹觀察 與 git 分支歷史)
這次使用專為 AI Agent 設計的終端機工作區管理工具 Herdr，搭配社群外掛 herdr-file-viewer（GitHub https://github.com/smarzban/herdr-file-viewer ）與 git-graph，在 CLI 環境組出一個輕量 VS Code CLI 平替 工作區。
1. 使用 Homebrew 安裝 Herdr
Herdr 已經收錄在 Homebrew core 中，直接透過 brew 即可安裝：
# 安裝 Herdr
brew install herdr
# 確認版本
herdr --version
實際安裝與版本輸出：
==> Downloading bottle manifests
✔︎ Bottle Manifest herdr (0.9.5)
==> Fetching downloads for: herdr
✔︎ Bottle herdr (0.9.5)
==> Pouring herdr--0.9.5.arm64_tahoe.bottle.tar.gz
🍺 /opt/homebrew/Cellar/herdr/0.9.5: 12 files, 24.6MB
==> Caveats
zsh completions have been installed to:
/opt/homebrew/share/zsh/site-functions
herdr 0.9.5
2. 安裝 herdr-file-viewer 外掛與渲染工具
接著使用 Herdr 內建的 plugin install 安裝 smarzban/herdr-file-viewer。它會自動抓取對應 macOS 架構的 prebuilt binary，不需要在本地重編 Rust。另外為了讓檔案預覽支援漂亮的 Git Diff、Markdown 與語法高亮，一併確認 git-delta、glow、bat 都已安裝：
# 安裝 herdr-file-viewer plugin
herdr plugin install smarzban/herdr-file-viewer
# 補齊 Diff 渲染器 git-delta（環境已有 glow 與 bat）
brew install git-delta
# 查看已安裝的 plugin 列表
herdr plugin list
安裝過程會列出 Plugin 預覽資訊（包含綁定的 6 個 actions 與 2 個 panes），輸入 y 即可完成：
Plugin install preview:
id: herdr-file-viewer
name: herdr-file-viewer
version: 1.18.0
source: smarzban/herdr-file-viewer
commit: d17a068ee753daf5ba205bafd59c130b81b8c6c0
actions: 6
panes: 2
build: /bin/sh scripts/fetch-or-build.sh
action open-file-viewer: bash scripts/open-file-viewer.sh
action open-file-viewer-tab: bash scripts/open-file-viewer-tab.sh
pane file-viewer: ./target/release/herdr-file-viewer
pane root-picker: ./target/release/herdr-file-viewer --pick-root
Install this plugin? [y/N] y
Installed herdr-file-viewer from smarzban/herdr-file-viewer.
Config: /Users/max/.config/herdr/plugins/config/herdr-file-viewer
3. 設定檔路徑與目錄結構
Herdr 的設定檔與外掛統一放在 ~/.config/herdr/ 目錄下：
~/.config/herdr/config.toml：Herdr 主設定檔（設定快捷鍵與主題）~/.config/herdr/plugins.json：已安裝 Plugin 清單與版本紀錄~/.config/herdr/plugins/config/herdr-file-viewer/config.toml：File Viewer 專屬設定檔
在 ~/.config/herdr/config.toml 設定快捷鍵與介面調整：
- 淺色主題（
[theme]）：macOS 內建終端機預設是白底，而 Herdr 預設載入深色的catppuccin，會導致側邊欄選取列變成黑底壓住深灰字。改設為淺色的catppuccin-latte並開啟auto_switch = true，配色就順眼多了。 - 顯示 Agent 狀態文字（
[ui.sidebar.agents]）：預設側邊欄只顯示小圓點state_icon（○），補上"state_text"後，就會直接印出idle、working、done、blocked文字，搭配delivery = "herdr"開啟視窗內 Toast 彈出通知。 - 檔案總管快捷鍵（
[[keys.command]]）：綁定prefix+f一鍵開啟或收合右側的herdr-file-viewer分割視窗。
# ~/.config/herdr/config.toml
onboarding = false
[theme]
name = "catppuccin-latte"
auto_switch = true
dark_name = "catppuccin"
light_name = "catppuccin-latte"
[ui.sidebar.agents]
row_gap = 1
rows = [["state_icon", "workspace", "tab"], ["agent", "state_text"]]
[ui.sidebar.spaces]
row_gap = 1
rows = [["state_icon", "workspace", "state_text"], ["branch", "git_status"]]
[ui.toast]
delivery = "herdr"
delay_seconds = 1
[[keys.command]]
key = "prefix+f"
type = "plugin_action"
command = "herdr-file-viewer.open-file-viewer"
description = "open file viewer in split"
[[keys.command]]
key = "prefix+shift+f"
type = "plugin_action"
command = "herdr-file-viewer.open-file-viewer-tab"
description = "open file viewer in tab"
- 所以開啟與關閉
herdr-file-viewer的方式都是：先按 快捷鍵 Ctrl + b 放開後再按 f 就可以（畫面沒有獨立按鈕可用滑鼠點開，必須按快捷鍵呼叫；但打開視窗之後，裡面點選檔案、展開資料夾、滾輪捲動、拉動分隔線與反白複製都完全支援滑鼠操作！）
為了讓 Herdr 更精準捕捉 agy（Antigravity CLI）的執行與等待狀態，再安裝內建的 integration Hook，並執行 reload-config 讓設定直接熱重載生效：
# 安裝 Antigravity CLI 狀態回報 Hook
herdr integration install antigravity-cli
# 熱重載 config.toml（不需關閉現有視窗）
herdr server reload-config
執行輸出：
installed antigravity-cli integration hook to /Users/max/.gemini/config/hooks/herdr-agent-state.sh
ensured antigravity-cli hooks at /Users/max/.gemini/config/hooks.json
{"id":"cli:server:reload-config","result":{"diagnostics":[],"status":"applied","type":"config_reload"}}
另外在 ~/.config/herdr/plugins/config/herdr-file-viewer/config.toml 開啟 expand_changed = true，讓有 Git 異動的資料夾在啟動時自動展開：
# ~/.config/herdr/plugins/config/herdr-file-viewer/config.toml
expand_changed = true
update_check = false
tree_width = 34
tree_max_cols = 34
安裝與設定完成後，用 find / ls 確認一下 ~/.config/herdr 的實際目錄結構：
~/.config/herdr/
├── config.toml
├── plugins.json
├── .plugins.lock
└── plugins/
├── .locks/
│ └── .herdr-file-viewer-c993314e2614.lock
├── config/
│ └── herdr-file-viewer/
│ └── config.toml
└── github-installations/
└── herdr-file-viewer-c993314e2614/
└── 90808-0/
├── .in-use
└── checkout/
├── herdr-plugin.toml
├── scripts/
└── target/release/herdr-file-viewer
4. 實測 herdr-file-viewer：Git 狀態標記與即時 Diff
就像 VS Code 會在檔案總管標示 M（Modified）與 U（Untracked），herdr-file-viewer 則是採用原生 git status -s 的符號標準，在左側目錄樹直接用顏色與符號標出 Git 狀態：
- ●（亮紅色）：內含未提交變更的資料夾（Dirty directory）
- M（亮紅色）：已修改的檔案（Modified），游標移過去右側會自動用
delta渲染紅綠對比 Diff - A（亮綠色）：已加入暫存區的新檔案（執行
git add後的 Added 狀態） - ?（亮綠色）：未追蹤的新檔案（對應
git status -s的??，等同於 VS Code 的U）
在 herdr-file-viewer 視窗內除了可以直接用滑鼠點擊、雙擊展開、滾輪捲動之外，幾個常用的單鍵快捷鍵也很順手（不需要按 Ctrl + b）：
]/[：直接跳到下一個／上一個有 Git 異動的檔案c：切換「只顯示有 Git 異動的檔案」（Changed-only 過濾）v：切換右側檢視模式（Git Diff ⇄ Markdown 渲染 ⇄ 原始碼高亮）f/s：f模糊搜尋檔名、s搜尋專案內文?/q：?開啟說明面板、q或Esc關閉視窗
實際在測試專案 demo-app 開啟 herdr-file-viewer 的終端機畫面（按 ] 可直接跳到下一個變更檔 src/main.py 查看即時 Diff）：
┌demo-app──────────────────────┐┌main.py─────────────────────────────────────────────────────┐
│● ▾ src ││ │
│ config.py ││ src/main.py │
│A helper.py ││ ───────────────────────────────────────────────────────────│
│M main.py ││ │
│ retry.py ││ ───┐ │
│M README.md ││ 1: │ │
│? notes.md ││ ───┘ │
│ pyproject.toml ││ from src.config import APP_NAME, TIMEOUT_SEC │
│ ││ from src.config import APP_NAME, TIMEOUT_SEC, MAX_RETRIES │
│ ││ from src.helper import format_status │
│ ││ │
│ ││ def run_task(task_name: str) -> None: │
│ ││ print(f"[{APP_NAME}] running {task_name} (timeout={TIME│
│ ││ status = format_status("agy", "working") │
│ ││ print(f"[{APP_NAME}] {status} -> {task_name} (retries={│
│ ││ │
│ ││ if __name__ == "__main__": │
│ ││ run_task("sync-agents") │
│ ││ │
│ ││ │
└main──────────────────────────┘└──────────────────────────────────────────────────────? help┘
5. 組合技：Herdr 三分割畫面打造 VS Code CLI 平替
最後透過 Herdr 的分割視窗把三個核心工具放在同一個畫面：
- 左上分區（AI Agent）：啟動
agy（Antigravity CLI），Herdr 左下角側邊欄的agents區塊會自動辨識出agy並追蹤執行狀態。 - 左下分區（Git Commit 樹）：執行
git-graph觀察 Workspace 的分支與合併歷史，直接平替 VS Code 的 Git Graph 外掛。 - 右側分區（Files 檔案總管 + Diff）：常駐
herdr-file-viewer隨時檢視目錄結構、Git 狀態標記與程式碼變更。
也可以透過 Herdr CLI 直接在現有 Session 中把這三個分區自動化切出來：
# 1. 在右側開啟 herdr-file-viewer 分割視窗
herdr plugin pane open --plugin herdr-file-viewer --entrypoint file-viewer --placement split --direction right
# 2. 將左側主視窗往下分割出第二個終端機跑 git-graph
herdr pane split w1:p1 --direction down --ratio 0.62 --no-focus
herdr pane run w1:p3 "clear && git-graph"
# 3. 在左上視窗啟動 Antigravity CLI (agy)
herdr pane run w1:p1 "clear && agy"
實際跑起來的 Herdr 三分區完整終端機畫面（包含左側 Herdr 側邊欄、左上 Antigravity CLI 1.5.9、左下 git-graph 以及右側 herdr-file-viewer）：
spaces │ 1 +
│┌──────────────────────────────────────────────────────────────┐┌ Files ───────────────────────────────────────────────────────────────────────────────────────┐
○ demo-app ││ ▀▀▀▀▀▀ ││┌demo-app──────────────────────┐┌main.py─────────────────────────────────────────────────────┐│
main ││ ▀▀▀▀▀▀▀▀ │││● ▾ src ││ ││
││ ▄▀▀ ▀▀▄ │││ config.py ││ src/main.py ││
││ ▄▀▀ ▀▀▄ │││A helper.py ││ ───────────────────────────────────────────────────────────││
││ │││M main.py ││ ││
││ Antigravity CLI 1.5.9 │││ retry.py ││ ───┐ ││
││ sakanamax@gmail.com (Google AI Pro) │││M README.md ││ 1: │ ││
││ Gemini 4 Argon (Medium) │││? notes.md ││ ───┘ ││
││ ~/Downloads/local_lab/lab_temp/02_實作中/20261114_herdr/dem │││ pyproject.toml ││ from src.config import APP_NAME, TIMEOUT_SEC ││
││ │││ ││ from src.config import APP_NAME, TIMEOUT_SEC, MAX_RETRIES ││
││ │││ ││ from src.helper import format_status ││
││ ┃ Introducing Gemini 4 Hydrogen │││ ││ ││
││ ┃ Our daily driver for rapid coding and dependable agentic │││ ││ def run_task(task_name: str) -> None: ││
││ ┃ execution! │││ ││ print(f"[{APP_NAME}] running {task_name} (timeout={TIME││
││ ┃ esc to dismiss │││ ││ status = format_status("agy", "working") ││
new menu││───────────────────────────────────────────────────────────── │││ ││ print(f"[{APP_NAME}] {status} -> {task_name} (retries={││
─────────────────────────││> Auto mode: edits & safe commands auto-approved (shift+t... │││ ││ ││
agents grouped││───────────────────────────────────────────────────────────── │││ ││ if __name__ == "__main__": ││
││Gemini 4 Argon (Medium) | policy:always-proceed | effort:medi │││ ││ run_task("sync-agents") ││
○ demo-app ││📂 cwd: ~/Downloads/local_lab/lab_temp/02_實作中/20261114_her │││ ││ ││
agy │└──────────────────────────────────────────────────────────────┘││ ││ ││
│┌──────────────────────────────────────────────────────────────┐││ ││ ││
││ ○<┐ 014f1cd (HEAD -> main) chore: 合併 feat/retry-policy │││ ││ ││
││ │ │ 分支 │││ ││ ││
││ ● │ 0b8ded6 docs: 補充 README 啟動說明 │││ ││ ││
││ │ ● 2d79184 (feat/retry-policy) feat: 實作 should_retry │││ ││ ││
││ │ │ 判斷邏輯 │││ ││ ││
││ │ ● 071c22b feat: 新增 MAX_RETRIES 重試次數設定 │││ ││ ││
││ ├─┘ │││ ││ ││
││ ● 2f5fc79 feat: 初始化專案結構與核心任務執行器 │││ ││ ││
││max@Max-MacAir demo-app % │││ ││ ││
││ │││ ││ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ ││
││ ││└main──────────────────────────┘└──────────────────────────────────────────────────────? help┘│
«│└──────────────────────────────────────────────────────────────┘└──────────────────────────────────────────────────────────────────────────────────────────────┘
不用開肥大的 GUI 編輯器，在純終端機裡就能同時掌握 AI Agent 狀態、Git 分支演進、檔案樹與即時 Diff，is not really useful :)
又前進一步 ~ enjoy it
Reference
- https://herdr.dev
- https://github.com/smarzban/herdr-file-viewer
