【設定・環境構築】Ghostty + herdr CLI から herdr app に乗り換える — 同じ名前の別製品だった

前に書いた記事で Ghostty + herdr という積み方に落ち着いてから、しばらくその構成で Claude Code を回していました。そこに herdr のデスクトップアプリ（herdr app）が出てきたので、乗り換えてみることにしました。

最初は「CLI のアプリ版でしょ、設定はそのまま読んでくれるはず」と思っていたんですが、調べてみると同じ herdr という名前の、別の製品でした。設定ファイルの場所も形式も違うし、CLI で動いているエージェントは app からは見えません。なので今回は、移すものを1つずつ確かめて、1本のスクリプトにまとめました。

はじめに#

乗り換えの動機は単純で、ターミナル（Ghostty）とマルチプレクサ（herdr CLI）を2つ起動して使うより、1つのアプリにまとまっていたほうが楽そうだったからです。herdr app はターミナルとエージェントの管理を1つのウィンドウでやるアプリで、サイドバーにワークスペース（app では space）とエージェントの状態が並びます。

対象読者#

• herdr CLI を使っていて、herdr app が気になっている人
• Ghostty + マルチプレクサの構成から、アプリ1つにまとめたい人

herdr CLI と herdr app は別物#

まずここを押さえておかないと、移行の作業がずっと噛み合いません。公式サイトの FAQ にも「2つはエージェントを共有しないので、片方で動いているものはもう片方に出てこない」と書かれています。

app のほうは「ウィンドウはターミナルを並べるだけで、ターミナル自体は core が動かしている」という作りです。ウィンドウを閉じてもターミナルは動き続けます。

インストール#

公式のインストーラを使いました。

curl -fsSL https://releases.herdr.dev/app/install.sh | sh

スクリプトを読むと、やっていることは次の3つでした。

• ~/Applications/Herdr.app にアプリを置く
• ~/.local/bin/herdr-app にコマンドのシンボリックリンクを作る
• herdr-core が無ければ ~/.local/bin/herdr-core と hc を入れる

気になっていたのは CLI の herdr コマンドと衝突しないかでしたが、app 側が使う名前は herdr-app・herdr-core・hc だけで、herdr は触りません。CLI と app は同時に入れておけます。

設定ファイルの対応#

app の設定は ~/.config/herdr-app/ にまとまっています。初回起動するとこういう構成ができます。

~/.config/herdr-app/
├── AGENTS.md        # 設定と mod の書き方の説明（app が書き出す）
├── settings.json    # 人に紐づく設定（ズーム・音・フォント・テーマ）
├── keys.json        # キー割り当て
├── layouts/         # 画面の構成（main.json など）
├── mods/            # UI 部品（サイドバー、タブバー、ファイルパネル…）
└── themes/          # テーマ（*.json）

CLI で使っていた設定は、この5項目だけでした。

onboarding = false
[theme]
name = "tokyo-night"
auto_switch = false

[ui.toast]
delivery = "system"

[ui]
show_agent_labels_on_pane_borders = true

それぞれ app のどこに当たるかを調べた結果がこれです。

テーマを持ち込む#

テーマファイルの形式は background・foreground・selection・cursor と16色の ansi で、パネルの色はここから自動で作られます。colors で個別の色を上書きできます。Tokyo Night の配色で書くとこうなります。

{
  "background": "#1a1b26",
  "foreground": "#c0caf5",
  "selection": "#283457",
  "cursor": "#c0caf5",
  "ansi": [
    "#15161e", "#f7768e", "#9ece6a", "#e0af68", "#7aa2f7", "#bb9af7", "#7dcfff", "#a9b1d6",
    "#414868", "#f7768e", "#9ece6a", "#e0af68", "#7aa2f7", "#bb9af7", "#7dcfff", "#c0caf5"
  ],
  "colors": { "accent": "#7aa2f7" }
}

themes/ に置いたファイルは設定画面のテーマ一覧に自動で出てきます。settings.json からはファイル名で指定します。

{
  "theme": "tokyo-night",
  "appearance": "dark",
  "sounds": { "enabled": true }
}

キー割り当て#

keys.json は global・terminal・layout:<name>・mod:<name> のセクションに分かれていて、値には app のコマンド名を書きます。ここでは、次の記事で作る Markdown プレビューを開くキーだけ足しました。

{
  "global": { "cmd-shift-m": "mod.open:md-preview" },
  "mod:md-preview": { "cmd-e": "md-preview.toggle", "cmd-r": "md-preview.reload" }
}

使えるコマンドは herdr-app commands で一覧できます。herdr-app do pane.split:right のようにシェルから実行もできるので、スクリプトからも app を操作できます。

移行スクリプト#

ここまでの作業を、何度実行しても同じ結果になるスクリプトにまとめました。全体はこういう流れです。

1. app が入っていなければ公式インストーラで入れる
2. テーマ・キー・mod を ~/.config/herdr-app/ に置く（既存ファイルは .bak-日時 で退避）
3. Ghostty の設定からフォントを読んで settings.json を書く
4. ~/.zshrc に PATH などを追記する（目印のコメントで二重追記を防ぐ）
5. herdr-app check で mod がエラーなく読めるか確かめる

Ghostty のフォントは、設定ファイルから font-family と font-size の最初の行だけ抜き出しています。macOS の Ghostty は ~/.config/ghostty/config ではなく ~/Library/Application Support/com.mitchellh.ghostty/config に設定を置くことがあるので、両方を見ます。

for c in "$HOME/Library/Application Support/com.mitchellh.ghostty/config" "$HOME/.config/ghostty/config"; do
  if [[ -f "$c" ]]; then GCONF="$c"; break; fi
done
FONT="$(sed -nE 's/^[[:space:]]*font-family[[:space:]]*=[[:space:]]*"?([^"]*)"?[[:space:]]*$/\1/p' "$GCONF" | head -1)"
SIZE="$(sed -nE 's/^[[:space:]]*font-size[[:space:]]*=[[:space:]]*([0-9.]+).*$/\1/p' "$GCONF" | head -1)"

フォントを書かなかった場合、app は同梱の JetBrains Mono を使います。app の font_size はズーム1倍のときのピクセル数なので、Ghostty のポイント数をそのまま入れても大きくはずれません。

ワークスペースも移す#

CLI のワークスペースは ~/.config/herdr/session.json に保存されています。各ワークスペースの identity_cwd がそのフォルダなので、重複を除いて app の space として作り直します。

python3 - "$HOME/.config/herdr/session.json" <<'PY' | while IFS= read -r d; do
import json, sys
seen = []
for w in json.load(open(sys.argv[1]))["workspaces"]:
    d = w.get("identity_cwd")
    if d and d not in seen: seen.append(d)
print("\n".join(seen))
PY
  herdr-app do space.new --folder "$d"
done

移るのはフォルダだけで、中で動いていた Claude Code のセッションは移りません。CLI と app はエージェントを共有しないので、必要なら app 側で claude --resume し直すことになります。

AGENTS.md が一番の資料だった#

調べていて一番役に立ったのが、app が ~/.config/herdr-app/ に書き出す AGENTS.md でした。設定ファイルの全キー、コマンドの一覧、mod の書き方までがエージェント向けにまとまっています。同じ場所には mod 用の型定義（herdr.d.ts、gpui-kit.d.ts）も置かれます。

Claude Code に app の設定を頼むなら、まずこのファイルを読ませるのが早いです。今回の移行も、ほとんどこの AGENTS.md と型定義を根拠にして進めました。

Tips#

• テレメトリ（匿名の利用データ送信）は最初からオンです。止めるなら settings.json に "telemetry": false を入れます
• CLI の herdr server stop はペインで動いているプロセスを全部終わらせます。CLI 側で作業中のエージェントが片付いてから止めるのが安全です
• 同梱のレイアウトや mod は app を起動するたびに上書きされます。手を入れたいときは複製してから編集します（次の記事で詳しく書きます）
• 操作がおかしくなったら ctrl-alt-shift-escape でレイアウトと keys.json を初期状態に戻せます

まとめ#

• herdr CLI と herdr app は同じ名前の別製品で、設定の場所も形式も違い、エージェントも共有しない
• CLI の設定のうちテーマは themes/*.json で持ち込める。システム通知の設定には同じものが無かった
• インストーラは herdr コマンドを触らないので、CLI と並べて置いておける
• 移行はテーマ・キー・フォント・ワークスペースのフォルダを1本のスクリプトにまとめると、やり直しが楽
• 設定を調べるなら、app が書き出す AGENTS.md と型定義を読むのが一番確実

次の記事では、app の UI 部品（mod）を書いて、ファイルパネルで Markdown や PDF をプレビューできるようにした話を書きます。

参考リンク#

• herdr 公式サイト
• herdrdev/herdr-app（GitHub）
• Ghostty・tmux・herdr・cmux をどう積むか（前の記事）
• herdr を実際に使ってみる（前の記事）