このページの翻訳は LLM によって生成されています。誤りに気づいた場合は GitHub で issue を開いてお知らせください。

インテグレーション

Next docs describe unreleased work from master. Stable docs remain at /docs/.

PK-Herdr は対応エージェントを自動的に検出します。公式インテグレーションは、復元のためのネイティブセッション識別、ライフサイクル状態の報告、またはその両方を追加できます。

Claude Code/Codex/Copilot/Devin 系のフックによるエージェントネイティブのセッション復元、Pi/OMP/Kimi/OpenCode/Kilo/Hermes/MastraCode 系のフックまたはプラグインによる直接のライフサイクル報告、あるいはその両方が欲しいときにインテグレーションを使ってください。状態権威モデルの全体像はエージェントを参照してください。

インテグレーションをインストールする

PK-Herdr 内で設定を開き、インテグレーションタブから PATH 上で見つかったエージェント向けの推奨インテグレーションをインストールするか、コマンドを手動で実行します:

pk-herdr integration install pi
pk-herdr integration install omp
pk-herdr integration install ompk
pk-herdr integration install claude
pk-herdr integration install codex
pk-herdr integration install copilot
pk-herdr integration install devin
pk-herdr integration install droid
pk-herdr integration install kimi
pk-herdr integration install opencode
pk-herdr integration install kilo
pk-herdr integration install hermes
pk-herdr integration install mastracode
pk-herdr integration install qodercli
pk-herdr integration install cursor

インテグレーションをアンインストールする

pk-herdr integration uninstall pi
pk-herdr integration uninstall omp
pk-herdr integration uninstall ompk
pk-herdr integration uninstall claude
pk-herdr integration uninstall codex
pk-herdr integration uninstall copilot
pk-herdr integration uninstall devin
pk-herdr integration uninstall droid
pk-herdr integration uninstall kimi
pk-herdr integration uninstall opencode
pk-herdr integration uninstall kilo
pk-herdr integration uninstall hermes
pk-herdr integration uninstall mastracode
pk-herdr integration uninstall qodercli
pk-herdr integration uninstall cursor

PK-Herdr がインテグレーションをどう使うか

PK-Herdr はインテグレーションを 2 つの異なる方法で使います:

インテグレーションの種類	エージェント	効果
ライフサイクル権威	Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、MastraCode	インストールされ、そのペインについて能動的に報告している間は、フックまたはプラグインのイベントが `idle`、`working`、`blocked` を決定します。同じライフサイクル権威に対して、PK-Herdr はスクリーンマニフェストのフォールバックを併用しません。
セッション識別	Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Qoder CLI、Cursor Agent CLI	インテグレーションは復元用のネイティブセッション参照を報告します。状態は引き続き PK-Herdr のスクリーンマニフェスト検出から得られます。

カスタムソケットインテグレーションも、ネイティブのターミナル UI では見えない状態を定義する場合に状態を報告できます。

一部のインテグレーションは、エージェントのネイティブセッション参照を報告します。PK-Herdr は公式のセッション参照を使って、[session] resume_agents_on_restore = false で無効化されていない限り、PK-Herdr サーバーの再起動後に Claude Code、Codex、Devin CLI、Droid、Kimi Code CLI、Qoder CLI、Cursor Agent CLI、GitHub Copilot CLI、Pi、OMP、Hermes Agent、OpenCode、Kilo Code CLI、MastraCode のペインを resume します。

エージェントネイティブのセッション復元には最新の PK-Herdr インテグレーションが必要です: Pi インテグレーションはバージョン 2、OMP は 3、Claude Code は 6、Codex は 5、GitHub Copilot CLI は 2、Devin CLI は 2、Droid は 2、Kimi Code CLI は 3、Qoder CLI は 2、Cursor Agent CLI は 1、OpenCode は 5、Kilo Code CLI は 1、Hermes Agent は 2、MastraCode は 1 です。インストール済みバージョンは pk-herdr integration status で確認してください。

Pi

Pi インテグレーションをインストールします:

pk-herdr integration install pi

PK-Herdr はバンドルされた拡張を次の場所に書き込みます:

~/.pi/agent/extensions/herdr-agent-state.ts

PI_CODING_AGENT_DIR が設定されている場合は、代わりに $PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts に書き込みます。Pi の agent ディレクトリが存在する場合、PK-Herdr は extensions ディレクトリを作成します。アンインストールはその拡張ファイルだけを削除します。

OMP

OMP インテグレーションをインストールします:

pk-herdr integration install omp
pk-herdr integration install ompk

PK-Herdr はバンドルされた拡張を次の場所に書き込みます:

~/.omp/agent/extensions/herdr-omp-agent-state.ts

ompk フォークを使う場合は pk-herdr integration install ompk を実行します。拡張は ~/.ompk/agent/extensions/herdr-omp-agent-state.ts に書き込まれます。omp と ompk は同じインテグレーションを共有します。OMP_PROFILE（または PI_PROFILE）が設定されている場合は <設定ディレクトリ>/profiles/<profile>/agent/extensions/herdr-omp-agent-state.ts に書き込みます。PI_CONFIG_DIR は既定の設定ディレクトリ名を上書きし、PI_CODING_AGENT_DIR は agent ディレクトリ全体を上書きします。OMP の agent ディレクトリが存在する場合、PK-Herdr は extensions ディレクトリを作成します。アンインストールはその拡張ファイルだけを削除します。

OMP インテグレーションは、PK-Herdr のソケット API を通じてエージェントラベル omp、ライフサイクル状態、ネイティブセッション識別を報告します。omp 実行ファイルのネイティブプロセス検出は不要で、PK-Herdr はサーバー再起動後に omp --resume=<session> で OMP ペインを resume できます。

Claude Code

Claude Code フックをインストールします:

pk-herdr integration install claude

このフックは、セッション開始時に Claude Code のセッション識別をローカルの PK-Herdr ソケットに報告します。Claude Code の状態は PK-Herdr のスクリーンマニフェスト検出から得られます。

PK-Herdr はデフォルトで ~/.claude を使い、CLAUDE_CONFIG_DIR が設定されていればそちらを使います。Claude の設定ディレクトリはあらかじめ存在している必要があります。インストールは hooks/herdr-agent-state.sh を書き込み、settings.json に PK-Herdr のフックエントリを追加します。アンインストールは一致するフックエントリを削除し、フックスクリプトを削除します。

Codex

Codex フックをインストールします:

pk-herdr integration install codex

Codex フックは、他のインテグレーションと同じローカルソケット API を通じてセッション識別を報告します。Codex の状態は PK-Herdr のスクリーンマニフェスト検出から得られます。

PK-Herdr はデフォルトで ~/.codex を使い、CODEX_HOME が設定されていればそちらを使います。Codex の設定ディレクトリはあらかじめ存在している必要があります。インストールは herdr-agent-state.sh を書き込み、hooks.json を更新し、config.toml に [features] hooks = true があることを保証します。非推奨のトップレベル codex_hooks フラグが存在すれば削除もします。アンインストールは hooks.json から PK-Herdr のエントリを削除してフックスクリプトを削除しますが、config.toml は変更しません。

GitHub Copilot CLI

GitHub Copilot CLI フックをインストールします:

pk-herdr integration install copilot

Copilot フックは、他のインテグレーションと同じローカルソケット API を通じてセッション識別を報告します。Copilot の状態は PK-Herdr のスクリーンマニフェスト検出から得られます。

PK-Herdr はデフォルトで ~/.copilot を使い、COPILOT_HOME が設定されていればそちらを使います。Copilot の設定ディレクトリはあらかじめ存在している必要があります。インストールは hooks/herdr-agent-state.sh を書き込み、settings.json に SessionStart フックエントリを追加します。アンインストールは settings.json から PK-Herdr のエントリを削除し、フックスクリプトを削除します。

Copilot がセッション情報を含むイベントを発行した後、PK-Herdr は報告されたセッション id を使って copilot --resume=<id> でペインを resume できます。

Devin CLI

Devin CLI フックをインストールします:

pk-herdr integration install devin

このフックは、Devin のセッション、プロンプト、ツール使用、許可、停止の各イベントからネイティブセッション識別を報告します。Devin のフックはすべての許可キャンセルやユーザー割り込みの後に信頼できる状態遷移を発行しないため、Devin の状態は引き続き PK-Herdr のスクリーンマニフェストと OSC 検出から得られます。

PK-Herdr はデフォルトで ~/.config/devin を使い、XDG_CONFIG_HOME が設定されていれば $XDG_CONFIG_HOME/devin を使います。Devin の設定ディレクトリはあらかじめ存在している必要があります。インストールは herdr-agent-state.sh を書き込み、config.json に PK-Herdr のフックエントリを追加します。フックは Devin の実行中にセッション参照を更新します。アンインストールは config.json から PK-Herdr のエントリを削除し、フックスクリプトを削除します。

PK-Herdr は保存された Devin セッションを devin --resume <id> で resume します。フックのインストール有無にかかわらず、スクリーンマニフェスト検出が状態の権威のままです。

Kimi Code CLI

Kimi Code CLI フックをインストールします:

pk-herdr integration install kimi

このフックは、ネイティブ復元と権威ある idle、working、blocked 状態のために、Kimi のセッション識別とライフサイクル状態を PK-Herdr に報告します。Kimi Code CLI 0.14.0 以上が必要です。

PK-Herdr はデフォルトで ~/.kimi-code を使い、KIMI_CODE_HOME が設定されていればそちらを使います。Kimi Code の設定ディレクトリはあらかじめ存在している必要があります。インストールは hooks/herdr-agent-state.sh を書き込み、config.toml に PK-Herdr 管理の [[hooks]] エントリを追記します。アンインストールは PK-Herdr 管理の設定ブロックを削除し、フックスクリプトを削除します。

PK-Herdr は保存された Kimi セッションを kimi --session <id> で resume します。

Droid

Droid フックをインストールします:

pk-herdr integration install droid

Droid フックは、他のインテグレーションと同じローカルソケット API を通じてセッション識別を報告します。Droid のフックはすべてのライフサイクル遷移をカバーしていないため、ライフサイクル状態は引き続き PK-Herdr のスクリーンマニフェスト検出から得られます。

PK-Herdr は Droid フックに ~/.factory を使います。Factory の設定ディレクトリはあらかじめ存在している必要があります。インストールは hooks/herdr-agent-state.sh を書き込み、settings.json に PK-Herdr の SessionStart フックエントリを追加し、hooks.json に古い PK-Herdr Droid フックエントリがあれば削除します。アンインストールは両方の設定ファイルから PK-Herdr のエントリを削除し、フックスクリプトを削除します。

Droid がセッション開始イベントを発行した後、PK-Herdr は報告されたセッション id を使って droid --resume <id> でペインを resume できます。

OpenCode

OpenCode プラグインをインストールします:

pk-herdr integration install opencode

PK-Herdr はプラグインを ~/.config/opencode/plugins/herdr-agent-state.js に書き込みます。OpenCode の設定ディレクトリはあらかじめ存在している必要があります。アンインストールはそのプラグインファイルだけを削除します。

このプラグインは、OpenCode が PK-Herdr のペイン内で動いている間、ライフサイクル状態とセッション識別を報告します。OpenCode がセッション情報を含むイベントを発行した後、PK-Herdr は報告されたセッション id を使って opencode --session <id> でペインを resume できます。プラグインがインストールされていないときは、スクリーンマニフェスト検出が引き続き利用できます。

Kilo Code CLI

Kilo Code CLI プラグインをインストールします:

pk-herdr integration install kilo

PK-Herdr はプラグインを ~/.config/kilo/plugin/herdr-agent-state.js に書き込みます。Kilo の設定ディレクトリはあらかじめ存在している必要があります。アンインストールはそのプラグインファイルだけを削除します。

このプラグインは、Kilo が PK-Herdr のペイン内で動いている間、ライフサイクル状態とセッション識別を報告します。Kilo がセッション情報を含むイベントを発行した後、PK-Herdr は報告されたセッション id を使って kilo --session <id> でペインを resume できます。プラグインがインストールされていないときは、スクリーンマニフェスト検出が引き続き利用できます。

Hermes Agent

Hermes Agent プラグインをインストールします:

pk-herdr integration install hermes

PK-Herdr は ~/.hermes/plugins/herdr-agent-state/ を書き込み、~/.hermes/config.yaml で herdr-agent-state を有効にします。Hermes の設定ディレクトリはあらかじめ存在している必要があります。プラグインを読み込ませるため、インストール後に Hermes を再起動してください。アンインストールはプラグインディレクトリを削除し、plugins.enabled から herdr-agent-state を削除します。

このプラグインは、Hermes が PK-Herdr のペイン内で動いている間、ライフサイクル、ツール、承認状態、セッション id を報告します。PK-Herdr は報告されたセッション id を使って hermes --resume <id> でペインを resume できます。プラグインがインストールされていないときは、スクリーンマニフェスト検出が引き続き利用できます。

Qoder CLI

Qoder CLI フックをインストールします:

pk-herdr integration install qodercli

このフックは、ネイティブ復元のために Qoder CLI のセッション識別を PK-Herdr に報告します。Qoder のフックはすべてのライフサイクル遷移をカバーしていないため、ライフサイクル状態は引き続き PK-Herdr のスクリーンマニフェスト検出から得られます。

PK-Herdr はデフォルトで ~/.qoder を使い、QODER_CONFIG_DIR が設定されていればそちらを使います。Qoder の設定ディレクトリはあらかじめ存在している必要があります。インストールは hooks/herdr-agent-state.sh を書き込み、settings.json に PK-Herdr のフックエントリを追加します。アンインストールは一致するフックエントリを削除し、フックスクリプトを削除します。

PK-Herdr は保存された Qoder CLI セッションを qodercli --resume <id> で resume します。

フックがインストールされていないときは、スクリーンマニフェスト検出が引き続き利用できます。

Cursor Agent CLI

Cursor Agent CLI フックをインストールします:

pk-herdr integration install cursor

このフックは、Cursor Agent CLI が PK-Herdr のペイン内で動いている間、Cursor の sessionStart フックを通じてセッション識別を報告します。Cursor の状態は PK-Herdr のスクリーンマニフェスト検出から得られます。

PK-Herdr はデフォルトで ~/.cursor を使い、CURSOR_CONFIG_DIR が設定されていればそちらを使います。Cursor の設定ディレクトリはあらかじめ存在している必要があります。インストールは herdr-agent-state.sh を書き込み、hooks.json に PK-Herdr の sessionStart エントリを追加します。アンインストールは一致するフックエントリを削除し、フックスクリプトを削除します。

Cursor がセッション開始イベントを発行した後、PK-Herdr は報告されたセッション id を使って cursor-agent --resume <id> でペインを resume できます。PK-Herdr がペインを復元するとき、cursor-agent コマンドが PATH にある必要があります。PK-Herdr は汎用の agent コマンドを起動しません。

MastraCode

MastraCode フックをインストールします:

pk-herdr integration install mastracode

このフックは、MastraCode のライフサイクル状態とスレッド識別を PK-Herdr に報告し、権威ある idle、working、blocked 状態とネイティブ復元を提供します。MastraCode にはスクリーンマニフェストのフォールバックはありません。MastraCode が PK-Herdr ペイン内で動いている間、状態はフックから得られます。

PK-Herdr は ~/.mastracode を使います。インストールは hooks/herdr-agent-state.sh を書き込み、hooks.json に PK-Herdr のコマンドエントリを追加します。ディレクトリがなければ作成します。アンインストールは一致するフックエントリを削除し、フックスクリプトを削除します。

PK-Herdr は保存された MastraCode スレッドを mastracode --thread <id> で resume します。

カスタムステータスラベル

インテグレーションは、ライフサイクル状態を意味的な状態としてのみ報告します。たとえば、ライフサイクル報告に表示フィールドを加えず、エージェントを working として報告します。

pk-herdr pane report-agent w1:p1 \
  --source custom:docs \
  --agent docs-bot \
  --state working

PK-Herdr 管理のインテグレーションと並走するユーザーフックは、report-agent ではなくメタデータを使うべきです。メタデータは、インテグレーションの idle、working、blocked やセッション復元の権威を奪わずに表示を変えます。--agent と --applies-to-source は表示フィールド (--title、--display-agent、--state-label) だけを保護します。トークンパッチは常に適用され、クリアまたは TTL の更新は報告側が管理します。--display-agent は表示名を変更します。

pk-herdr pane report-metadata "$HERDR_PANE_ID" \
  --source user:claude-title \
  --agent claude \
  --title "Refactor auth middleware" \
  --display-agent "Claude: auth" \
  --token summary="refactor auth" \
  --state-label working="refactoring auth" \
  --ttl-ms 3600000

トークンと状態ラベルは表示専用です。wait、通知、ワークスペースのロールアップは引き続き意味的な状態を使います。

インテグレーション状態のデバッグ

既知のエージェントを一覧します:

pk-herdr agent list

PK-Herdr に何が見えているか確認する必要があるときはペインを読みます:

pk-herdr pane read w1:p1 --source recent --lines 50

インテグレーションの状態がおかしく見えるときは、まずエージェントが PK-Herdr 内で動いていること、そして該当のフックまたはプラグインが同じユーザーアカウントにインストールされていることを確認してください。