Reading the board
盤面の読み方
The board is one column per repository, one card per session, sorted by urgency: needs input → working → idle. Everything below is what the pieces mean. The same legend lives in the app behind the ? button in the HUD header.
盤面はリポジトリごとに1列、セッションごとに1カードで、緊急度順 （応答待ち → 作業中 → 待機）に並びます。以下はそれぞれのパーツの意味です。 同じ凡例は HUD ヘッダーの ? ボタンからアプリ内でも確認できます。
The header
ヘッダー
- Plan usage bars — your Claude plan's 5-hour and weekly windows (plus a model-scoped weekly bar when your plan has one), with time until each resets. When a weekly window passes 90% it's mirrored as an alert chip (threshold configurable).
- Range filter — show everything, or only sessions active in the last 24 hours.
- Count pills — needs input N working N — the board's one-line summary.
- Controls — minimize (the HUD collapses to a small strip), ＋ new session, ⚙ settings, ? legend.
- プラン使用量バー — Claude プランの5時間枠と週間枠（プランにモデル別の週間バーがある場合はそれも）を、それぞれのリセットまでの時間とともに表示します。週間枠が90%を超えるとアラートチップにも反映されます（閾値は設定可能）。
- 表示範囲フィルタ — すべて表示するか、直近24時間にアクティブだったセッションのみ表示するかを切り替えます。
- 件数ピル — 応答待ち N 作業中 N — 盤面の状態を1行で要約します。
- コントロール — 最小化（HUD が小さなストリップに折りたたまれます）、＋ 新規セッション、⚙ 設定、? 凡例。
Card anatomy
カードの解剖図
- 1Status banner — only on blocked or errored cards: what state it's in and for how long. Long-ignored questions get a “neglected” tag.
- 2Status dot & title — the dot is the status color (below). The title is the AI-generated task name from the transcript — the same title Claude Code gives the terminal tab.
#Nis the GitHub issue, read from the branch name. - 3Chips — Claude's permission mode (
PLAN= plan-only,⏵⏵ EDITS= auto-accept edits,BYPASS= all prompts skipped), the model tier in use, and where the session runs (zellij,VS Code,Ghostty, a headlessclaude -p…). - 4The question — the exact decision the agent is waiting on. Right-click → Reply answers it from here (how).
- 5Deliverables — a unified PR badge (number + CI: ✓ pass, ✕ fail, dashed circle running; click to open) and links to Artifacts the session published.
- 6Meta — elapsed time, uncommitted changed-file count (
±6), and the context-window pie. Hover the card's bottom edge for exact tokens left. - 7Family strip — appears when the session has children. Click to fold/unfold the child cards; hover while folded to peek at each child's status. The card's bottom edge is a 3px context gauge (teal → yellow at 60% → red at 85%).
- 1ステータスバナー — 応答待ちやエラー状態のカードにのみ表示され、状態とその継続時間を示します。長く放置された質問には「放置」タグが付きます。
- 2ステータスドット & タイトル — ドットはステータスの色（下記参照）です。タイトルは transcript から生成された AI 生成のタスク名で、Claude Code がターミナルタブに付けるものと同じです。
#Nはブランチ名から読み取った GitHub issue 番号です。 - 3チップ — Claude の権限モード（
PLAN= プランのみ、⏵⏵ EDITS= 編集自動承認、BYPASS= すべてのプロンプトをスキップ）、使用中のモデルティア、セッションの実行環境（zellij・VS Code・Ghostty・headless のclaude -pなど）。 - 4質問 — エージェントが待っている決定事項そのものです。右クリック → 回答するでここから直接答えられます（方法）。
- 5成果物 — 統合 PR バッジ（番号 + CI: ✓ 成功、✕ 失敗、破線の丸は実行中。クリックで開く）と、セッションが公開した Artifact へのリンク。
- 6メタ情報 — 経過時間、未コミットの変更ファイル数（
±6）、コンテキストゲージの円グラフ。カード下端をホバーすると残りトークン数の正確な値が見られます。 - 7ファミリーストリップ — セッションに子がある場合に表示されます。クリックで子カードを畳む/展開でき、畳んだ状態でホバーすると各子の状態を覗き見できます。カード下端は3pxのコンテキストゲージです（teal → 60%で yellow → 85%で red）。
Cards also show the session's directory (with a worktree mark when it lives in a linked worktree) and branch, and the current activity line — what Claude is doing right now.
カードにはセッションのディレクトリ（リンクされた worktree に居る場合は worktree マーク付き）と ブランチ、そして現在の作業内容を示すアクティビティ行も表示されます。
Status colors
ステータスの色
| edge / dot | meaning | what to do |
|---|---|---|
| needs input | Stopped, waiting on a question or a permission prompt. | Right-click → Reply, or click through to the pane. The only state that actually needs you. |
| error | Something failed — an API error, an abnormal exit. | Open the session and look. |
| working | Claude is actively working. | Nothing. That's the point. |
| idle | Nothing running. | Resume it, or close it. |
| 色 / ドット | 意味 | 対応 |
|---|---|---|
| 応答待ち | 停止中で、質問や権限プロンプトへの応答を待っています。 | 右クリック → 回答する、またはクリックしてペインを開きます。実際にあなたの対応が必要な唯一の状態です。 |
| エラー | 何かが失敗しました — API エラーや異常終了。 | セッションを開いて確認してください。 |
| 作業中 | Claude が実際に作業しています。 | 何もしなくて大丈夫です。それが目的です。 |
| 待機 | 何も実行されていません。 | 再開するか、閉じてください。 |
Card symbols
カードの記号
| symbol | meaning |
|---|---|
| #123 | The GitHub issue being worked on (from the branch name or label). |
| PLAN / ⏵⏵ EDITS / BYPASS | Claude's permission mode: plan-only / edits auto-accepted / all prompts bypassed. |
| FABLE / OPUS / … | The model in use. A board where every chip is the same color usually means nobody chose models — see the playbook. |
| zellij / VS Code / Ghostty / claude -p | What the session runs on: a zellij pane, a VS Code-family integrated terminal, a bare terminal app, or a headless claude -p run. Background workers wear the BG chip instead. |
| ±8 | Uncommitted changed files in that worktree. |
| ◥ (amber dog-ear) | Top-right fold = the worktree has uncommitted changes. Fine while working; a reminder before closing. |
| ◔ 72% | Context-window usage — yellow ≥ 60%, red ≥ 85%. Hover for tokens remaining. |
| stale? | Says “working” but the transcript hasn't moved in 2+ minutes — probably interrupted (Esc) and actually stopped. Attach and check. |
| </> code brackets | The session lives in a VS Code-family integrated terminal or the Claude Code extension panel — clicking the card opens that editor instead of a terminal. (Built to cover Cursor/Windsurf-style forks too, though those are untested.) |
| 📡 antenna | Remote-control (/remote-control) is enabled for this pane. |
| 📎 sent | A dropped file was just sent to this session. |
| ✨ child working | A subagent or child session of this card is running (the child's own card carries the same mark). |
| ⑂ fork mark | This session was forked/resumed from another; it nests under its origin. |
| parked | A live background worker sitting idle. It still holds real memory (~600 MB measured); after 30 minutes the chip escalates to “parked 42m — forgot to stop?”. |
| 記号 | 意味 |
|---|---|
| #123 | 対応中の GitHub issue（ブランチ名またはラベルから取得）。 |
| PLAN / ⏵⏵ EDITS / BYPASS | Claude の権限モード: プランのみ / 編集自動承認 / すべてのプロンプトをバイパス。 |
| FABLE / OPUS / … | 使用中のモデル。盤面のチップが全部同じ色なのは、たいてい誰もモデルを選んでいないサインです — 群れの導き方を参照。 |
| zellij / VS Code / Ghostty / claude -p | セッションの実行環境: zellij ペイン、VS Code 系の統合ターミナル、素のターミナルアプリ、または headless の claude -p 実行。バックグラウンドワーカーは代わりに BG チップが付きます。 |
| ±8 | その worktree の未コミットの変更ファイル数。 |
| ◥（琥珀の折り目） | 右上の折り目は worktree に未コミットの変更があることを示します。作業中は問題ありません。閉じる前の確認用です。 |
| ◔ 72% | コンテキストウィンドウの使用率 — 60%以上で yellow、85%以上で red。ホバーで残りトークン数を確認できます。 |
| stale? | 「作業中」と表示されていても transcript が2分以上動いていない状態 — おそらく中断（Esc）されて実際は停止しています。attach して確認してください。 |
| </> コードブラケット | VS Code 系の統合ターミナルまたは Claude Code 拡張パネルで動くセッション — カードのクリックはターミナルではなくそのエディタを開きます。（Cursor / Windsurf 系フォークにも対応する設計ですが、フォークでの動作は未検証です。） |
| 📡 アンテナ | このペインで遠隔操作（/remote-control）が有効になっています。 |
| 📎 送信済み | ドロップしたファイルがこのセッションに送信されたことを示します。 |
| ✨ 子が作業中 | このカードのサブエージェントまたは子セッションが実行中です（子カード自体にも同じマークが付きます）。 |
| ⑂ フォークマーク | このセッションは別のセッションからフォーク/再開されたもので、元のセッションの下にネストします。 |
| parked | アイドル状態のライブなバックグラウンドワーカー（アプリでは「駐機中」と表示されます）。実メモリを消費し続けます（実測約600 MB）。30分経過するとチップが「parked 42m — forgot to stop?」に切り替わります。 |
Families: children, forks, and the strip
ファミリー: 子セッション・フォーク・ストリップ
Subagents and teammates nest under their parent card while they work, then disappear when
they finish — the board stays as small as the number of workstreams, not the number of processes.
Child sessions (a separate claude process your session launched) nest when the parent
exported SHEPHERD_PARENT_SESSION_ID; forks are detected automatically and get a branch mark.
サブエージェントと teammate は作業中だけ親カードの下にネストし、終了すると消えます —
盤面はプロセス数ではなくワークストリーム数だけの大きさに保たれます。子セッション
（親セッションが起動した別の claude プロセス）は、親が SHEPHERD_PARENT_SESSION_ID
を export していればネストします。フォークは自動検出され、ブランチマークが付きます。
The strip along a parent's bottom edge sums it up (2 children · 1 working, plus a blocked child's question when there is one). Click anywhere on the strip to fold or unfold the family; hover while folded to peek without unfolding.
親カードの下端に沿ったストリップがそれを要約します（子 2 件・稼働中 1、加えて子が 応答待ちならその質問も表示）。ストリップのどこをクリックしても家族を畳む/展開でき、畳んだ状態で ホバーすると展開せずに覗き見できます。
The archive lane
アーカイブレーン
Finished background records collapse into one thin lane per repository instead of littering the
board. Click to unfold. A finished session can be reopened right where it left off —
click its card and Shepherd runs claude attach for it (with a confirmation first).
終了したバックグラウンド記録は、盤面を散らかす代わりにリポジトリごとの1本の細いレーンに畳まれます。
クリックで展開できます。終了したセッションは中断した場所からそのまま再開できます —
カードをクリックすると Shepherd が（確認の上で）claude attach を実行します。
Signals worth acting on
対応すべきシグナル
| signal | meaning | do |
|---|---|---|
| orange banner ? … | Agent blocked on a question or permission. | Answer it. Everything else is running fine without you. |
| context gauge red | The window is ≥85% full; quality degrades before the hard limit. | Wrap up, or have the agent write a handoff and start fresh. |
| parked + duration | A background worker you forgot to stop, burning memory. | Right-click → Stop, unless you're about to attach. |
| stale? | Looks busy, isn't. | Attach and check — likely interrupted. |
| ◥ dog-ear | Uncommitted changes. | Fine while working; commit or stash before closing. |
| model chips all one color | Nobody chose models for the fleet. | See the playbook §2. |
| シグナル | 意味 | 対応 |
|---|---|---|
| オレンジのバナー ? … | エージェントが質問または権限プロンプトで停止しています。 | 回答してください。他はあなたなしで問題なく進んでいます。 |
| コンテキストゲージが赤 | コンテキストウィンドウが85%以上埋まっています。上限に達する前に品質が落ち始めます。 | 作業を締めるか、エージェントに引き継ぎメモを書かせて新しく始めてください。 |
| parked + 経過時間 | 停止し忘れたバックグラウンドワーカーがメモリを消費しています。 | attach する予定がなければ、右クリック → 停止してください。 |
| stale? | 作業中に見えても、実際は動いていません。 | attach して確認してください — おそらく中断されています。 |
| ◥ 折り目 | 未コミットの変更があります。 | 作業中は問題ありません。閉じる前にコミットまたは stash してください。 |
| モデルチップが全部同じ色 | 群れ全体でモデルを誰も選んでいません。 | 群れの導き方 §2 を参照。 |