herdr — コーディングエージェント向けターミナルマルチプレクサ

Rust

単一バイナリ

Agent-aware

状態をサイドバー表示

Socket API

エージェントも操作可

AGPL-3.0

商用ライセンス別途

herdr はターミナル上で動くエージェントマルチプレクサ。ペイン内のコーディングエージェントを検出し、working blocked done などを一覧できる。detach してもプロセスは動き続け、別ターミナルや SSH から reattach できる。

実ターミナルビュー（ラップされた解釈ではない）
キーボード（tmux 風 prefix）とマウス（クリック・ドラッグ・分割）の両方が第一級
プラグインとマーケットプレイスでペイン・ワークフローを拡張
Electron なし。既存ターミナル内で動作

tmux との違い: herdr はマウスファーストかつエージェント認識。tmux コマンドや .tmux.conf の知識は当てはめない。公式ドキュメントと herdr --help が正。

覚える順

概念	役割	公開 ID 例
Session	永続バックグラウンドサーバの名前空間。通常は default。名前付きは完全に分離	`default` / `work`
Workspace	プロジェクト単位のコンテナ。タブとペインを所有。サイドバーはワークスペース単位で状態を集約	`w1`
Tab	ワークスペース内のレイアウト（agents / logs / server など）	`w1:t1`
Pane	実ターミナル。右・下に分割可能。クライアント detach 後も生存	`w1:p1`
Agent	ペイン内で認識されたプロセス。状態とメタデータを公開	（pane に紐づく）
Terminal	PTY 側の内部ハンドル	`term_...`

モードは 3 つ。ターミナルモード（キーをフォーカスペインへ送る）、prefix モード（既定 ctrl+b のあと 1 アクション）、navigate モード（継続的なナビ面）。

ID の扱い: 公開 ID は不透明な文字列。閉じたタブ・ペインの ID は再利用されない。ペインを別ワークスペースへ移すと新しい pane ID になる。変異後は JSON レスポンスを再読し、番号から組み立てない。

ランタイム境界

バックグラウンドサーバがセッション状態と PTY を持ち、TUI クライアントが描画する。新機能は「サーバ所有のランタイム事実」と「TUI だけの表示状態」に分けて設計する方針（AGENTS.md）。

flowchart TD
  subgraph clients["Clients"]
    TUI["TUI client"]
    CLI["herdr CLI"]
    AG["Agent in pane"]
  end
  subgraph server["Background server"]
    SESS["Session / AppState"]
    WS["Workspace / Tab / Pane"]
    DET["Agent detection"]
    API["JSON API / events"]
  end
  subgraph term["Terminals"]
    PTY["portable-pty"]
    VT["libghostty-vt"]
  end
  TUI --> API
  CLI --> API
  AG --> CLI
  API --> SESS
  SESS --> WS
  WS --> PTY
  PTY --> VT
  DET --> VT
  DET --> API

src/serverヘッドレスサーバ、クライアント受理、handoff、ソケット

src/appAppState・アクション・入力。状態と描画を分離

src/clipane / workspace / tab / wait / session 等の制御面

src/detect画面スナップショットからのエージェント検出（manifest）

src/apiJSON API・イベント・スキーマ

vendor/portable-pty / libghostty-vt のベンダー

agent_status

ペイン記録は agent / agent_status / ネイティブセッションメタデータを公開する。値は idle、working、blocked、done、unknown。

状態	意味
idle	待機中で、結果は「見た」扱い。初回プロンプト表示も idle
working	作業中
blocked	入力待ち。人間またはフォローアップが必要
done	完了したが結果はまだ未読。バックグラウンド完了で付きやすい
unknown	未検出、または統合前

idle と done は同じ完了セマンティクスで、差分は注意（seen）状態だけ。フォーカスやタブ切替で visible になると done → idle。離れただけでは idle が done に戻らない。

検出の権威: 画面検出は bottom-buffer の証跡ベース。統合を入れると権威ある状態になる — herdr integration install <name>。診断は herdr agent explain <target> --json。

Linux / macOS

curl -fsSL https://herdr.dev/install.sh | sh
# または: brew install herdr · mise use -g herdr
herdr

Windows（preview beta）

powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
herdr

STEP 01

プロジェクトで起動

cd して herdr。default セッションへ attach。初回はオンボーディング。

STEP 02

エージェント起動

claude / codex 等をペインで実行。必要なら herdr integration install claude。

STEP 03

マウスで操作

クリックでフォーカス、境界ドラッグで分割、右クリックメニュー。キーバインド必須ではない。

STEP 04

detach / reattach

prefix+q（ctrl+b のあと q）またはウィンドウを閉じる。再開は herdr。完全停止は herdr server stop。

設定は任意。既定パスは ~/.config/herdr/config.toml。既定値の全文は herdr --default-config。実行中サーバへは herdr server reload-config。

制御コマンドの多くは JSON を返す。構文の権威はインストール済みバイナリ。探索はグループを引数なしで呼ぶ（裸の herdr は TUI 起動なので使わない）。

herdr --help
herdr pane
herdr workspace
herdr worktree
herdr tab
herdr wait
herdr terminal
herdr notification
herdr integration
herdr session

環境変数（呼び出し側コンテキスト）

変数	意味
`HERDR_ENV=1`	Herdr 管理下のペイン内。制御コマンドを出す前提条件
`HERDR_WORKSPACE_ID`	呼び出し元ワークスペース
`HERDR_TAB_ID`	呼び出し元タブ
`HERDR_PANE_ID`	呼び出し元ペイン
`HERDR_SESSION`	セッション名（必要時）

ペインコマンドは --current で呼び出し元を明示するのが安全。省略すると UI フォーカス先になり、別クライアントのペインを誤操作しうる。

ネスト禁止: 既に HERDR_ENV=1 のとき、内側から再度裸の herdr で TUI を起動しない。デバッグビルドを試すときはソケット上書きを外す — env -u HERDR_SOCKET_PATH -u HERDR_CLIENT_SOCKET_PATH cargo run -- …。

SKILL.md の要点

リポジトリ同梱の SKILL.md は、Herdr 内のエージェントが隣接ペインを制御するための手順。スキル適用前に必ず test "${HERDR_ENV:-}" = 1 を確認する。

兄弟ペインでエージェントを起動する流れ

herdr pane layout --pane "$HERDR_PANE_ID"
herdr pane split --current --direction right --no-focus
# JSON の result.pane.pane_id を読む
herdr pane rename <pane-id> "reviewer"
herdr pane run <pane-id> "codex"
herdr wait agent-status <pane-id> --status idle --timeout 30000
herdr pane run <pane-id> "Review the current diff and report only actionable findings."
herdr wait agent-status <pane-id> --status working --timeout 30000
herdr wait agent-status <pane-id> --status done --timeout 120000
herdr pane read <pane-id> --source recent-unwrapped --lines 120

read ソース

source	用途
`visible`	現在の描画ビューポート
`recent`	最近のスクロールバック（ソフトラップ込み）
`recent-unwrapped`	ソフトラップ結合。ログ・トランスクリプト向け
`detection`	エージェント検出用 bottom-buffer

背景作業は --no-focus。フォーカスを奪わない
自分で作っていない workspace / tab / pane / session を閉じない
明示指示なしに herdr server stop やメインプロセス kill をしない
待ちタイムアウト後は pane get と pane read で現況を確認してから判断

スキル導入例: npx skills add ogulcancelik/herdr --skill herdr -g（対応ハーネスの場合）。正本は GitHub の SKILL.md。

ビルド・テスト

git clone https://github.com/ogulcancelik/herdr
cd herdr
cargo build --release
just test        # unit tests
just check       # formatting, tests, maintenance checks

状態とランタイム分離 AppState は純粋データ。PaneState と PaneRuntime を分離。PTY なしでテスト可能。

純な描画 compute_view() が幾何と変異。render() は &AppState を読んで描くだけ。

プラットフォーム隔離 OS 固有は src/platform/<os>.rs。コアに #[cfg(target_os)] を増やさない。

検出の分離 detector は画面スナップショットだけを読む。パーサやビューポート状態には触らない。

バージョン（Cargo.toml）: 0.7.4。ライセンスは AGPL-3.0-or-later と商用のデュアル。問い合わせ: hey@herdr.dev。

ogulcancelik/herdr — ソースリポジトリ
herdr.dev — 公式サイト
ドキュメント — quick start / concepts / agents / keyboard / configuration
Socket API
Agent skill / リポジトリ内 SKILL.md
Plugin marketplace
Releases