Install

インストール

Requirements

必要環境

macOS 13+
Xcode Command Line Tools to build: xcode-select --install
Optional: Ghostty as the preferred terminal (falls back to Terminal.app), gh for PR badges, an Elgato Stream Deck if you have one

macOS 13+
ビルドに Xcode Command Line Tools が必要: xcode-select --install
任意: 優先ターミナルとして Ghostty（無ければ Terminal.app にフォールバック）、PR バッジ用の gh、お持ちなら Elgato Stream Deck

No Xcode project, no SwiftPM, no runtime dependencies — build.sh is a plain swiftc invocation.

Xcode プロジェクトなし、SwiftPM なし、実行時依存なし — build.sh は素の swiftc 呼び出しです。

Homebrew

Homebrew でインストール

$ brew install --cask sadayuki-matsuno/tap/shepherd

The prebuilt app is ad-hoc signed (no Apple Developer ID yet), so macOS may block the first launch. Right-click Shepherd.app → Open once, or install with brew install --cask --no-quarantine sadayuki-matsuno/tap/shepherd. Building from source (below) avoids this entirely.

配布バイナリは ad-hoc 署名（Apple Developer ID 未取得）のため、初回起動時に macOS にブロックされることがあります。Shepherd.app を右クリック → 開くを一度行うか、 brew install --cask --no-quarantine sadayuki-matsuno/tap/shepherd でインストールしてください。下記のソースビルドならこの問題はありません。

Build from source

ソースからビルド

$ git clone https://github.com/sadayuki-matsuno/shepherd.git
$ cd shepherd
$ ./build.sh          # builds & installs /Applications/Shepherd.app
$ open -a Shepherd

A prebuilt zip is also attached to each GitHub Release (same Gatekeeper note applies: right-click → Open on first launch).

ビルド済み zip は各 GitHub Release にも添付されています（Gatekeeper の注意は同じ: 初回は右クリック → 開く）。

The HUD appears in the corner of your screen, floating above every window and Space. Drag it anywhere — the position is remembered. There is no Dock icon; quit from the ⚙ menu.

HUD は画面の隅に現れ、すべてのウィンドウと Space の上にフローティング表示されます。好きな場所にドラッグでき、位置は記憶されます。Dock アイコンは無く、終了は ⚙ メニューから行います。

First launch

初回起動

Any Claude Code session already running shows up immediately — there is nothing to register. If the board is empty, start a claude session anywhere and watch the card appear.
The first time you click a card to jump into a terminal, macOS asks for an automation consent (Shepherd → Ghostty/Terminal). Allow it — that's how Shepherd focuses the right window.
To update later: git pull && ./build.sh, then quit and relaunch Shepherd.

すでに動いている Claude Code セッションはすぐに表示されます — 登録操作は不要です。盤面が空なら、どこかで claude セッションを起動してカードが現れるのを確認してください。
初めてカードをクリックしてターミナルへジャンプする際、macOS が自動化の許可ダイアログ（Shepherd → Ghostty/Terminal）を表示します。許可してください — これによって Shepherd が正しいウィンドウにフォーカスできます。
後で更新するには: git pull && ./build.sh を実行し、Shepherd を終了して再起動してください。

Upgrading from a version that installed a hook

フックをインストールしていた旧版からの移行

Old versions (pre 2026-07) installed a status hook. Current Shepherd uses none — clean up the leftovers:

旧版（2026-07 より前）はステータスフックをインストールしていました。現行の Shepherd はフックを使いません — 残骸を掃除してください:

Delete ~/.claude/hooks/shepherd-agent-status.sh and ~/.claude/agent-status/
Remove the shepherd-agent-status.sh entries from the hooks section of ~/.claude/settings.json

~/.claude/hooks/shepherd-agent-status.sh と ~/.claude/agent-status/ を削除する
~/.claude/settings.json の hooks セクションから shepherd-agent-status.sh の登録を削除する

Uninstall

アンインストール

$ pkill -x Shepherd
$ rm -rf /Applications/Shepherd.app
$ defaults delete com.sadayuki-matsuno.shepherd   # optional: forget position & settings

Shepherd writes nothing else to your machine.

Shepherd はこれ以外、あなたのマシンに何も書き込みません。

← Overview← 概要 Reading the board →盤面の読み方 →