path_pi

私の公開 Pi 設定、Agent Skills、統合ツールセットです。現在のリポジトリの中心は pi-agent-mcp です。Claude Code、Codex などの MCP Host は、独立したタスクを複数の永続的でコンテキストを再利用できる Pi セッションに割り当てることができます。

リポジトリの内容

skills/pi-agent/       # Claude Code/Codex 调用 MCP 的 Agent Skill
src/                   # pi-agent-mcp TypeScript 源码
scripts/install.sh     # 构建并配置 Skill + MCP Host
examples/              # 不含真实凭据的 Pi 配置样例
docs/INSTALL.zh-CN.md  # 中文安装、认证、升级与卸载指南

Related MCP server: pokeclaw

クイックインストール

git clone https://github.com/a809384377/path_pi.git
cd path_pi
./scripts/install.sh             # 自动配置检测到的 Claude Code/Codex
# 或：./scripts/install.sh --host claude|codex|all

Node.js >=22.19 <26、Pi 0.84.1 または互換バージョン、および少なくとも1つの認証済み Pi モデルが必要です。完全な手順は 中国語インストール・認証ガイド を参照してください。

リポジトリは匿名化されたサンプルのみを提供し、ローカルの auth.json、実際の models.json、API キー、GitHub トークン、Pi セッションは含まれません。これらのプライベートファイルを公開リポジトリにコピーしないでください。

pi-agent-mcp

pi-agent-mcp は、再利用可能な Pi コーディングエージェントセッションを Claude Code、Codex、および他の MCP クライアントに公開します。

Claude Code、Codex、および他のローカル MCP ホストは、デフォルトで ~/.pi/agent-mcp/ にある1つのレジストリを共有します。各論理セッションは独立した永続レコードと、カーネルバックアップの論理/ネイティブ所有権ロックを持ち、異なる MCP サーバーがレジストリ状態を上書きすることなく、異なるセッションで並行して作業できます。

各常駐セッションは1つの pi --mode rpc プロセスを所有します。タスクが完了すると、Pi はアイドル状態を維持し、両方の所有権ロックを保持して、次の pi_send のために会話を保存します。アイドル常駐セッションのオンラインハンドオフは意図的にありません。別の MCP ホストは、所有者が正常にシャットダウンするまで session_in_use を受け取ります。

要件

• macOS または Linux、x64 または arm64。Windows とネットワークファイルシステムはサポートされていません

• Node.js >=22.19 <26

• pi がインストールされ、PATH で利用可能であること（v2 プロトコルは Pi 0.84.1 または互換動作を対象としています）

• 設定済みの Pi モデル/プロバイダー

所有権は、固定された fs-ext-extra-prebuilt@2.2.12 カーネル flock バインディングを使用します。サポートされるマトリックスでバインディングをロードできない場合、起動またはツール呼び出しは ownership_unavailable でフェイルクローズします。PID/リースのフォールバックはありません。

インストールとビルド

npm install
npm run build

MCP エントリポイントは dist/src/index.js です。サーバーは stdio を使用します。stdout は MCP メッセージ用に予約され、診断情報は stderr に出力されます。

Claude Code の設定

claude mcp add --scope user --transport stdio \
  --env "PI_AGENT_MCP_PI_EXECUTABLE=$(command -v pi)" \
  pi-agent -- "$(command -v node)" "/absolute/path/to/path_pi/dist/src/index.js"

ビルドされたサーバーを絶対パスで登録します。通常の共有使用では、呼び出し元固有の状態ディレクトリを設定しないでください:

Codex の設定

[mcp_servers.pi_agent]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/path_pi/dist/src/index.js"]

[mcp_servers.pi_agent.env]
PI_AGENT_MCP_PI_EXECUTABLE = "/absolute/path/to/pi"

同じサーバーを ~/.codex/config.toml に追加します。こちらも状態ディレクトリのオーバーライドはありません:

両方のクライアントは、~/.pi/agent-mcp/ を通じて同じセッションを発見します。異なるセッションで並行してタスクを実行できます。特定の論理またはネイティブ Pi セッションを所有できる MCP サーバーは、一度に1つだけです。

オプションの分離

PI_AGENT_MCP_STATE_DIR=/absolute/private/path は、テストや高度なセットアップのために意図的に分離されたレジストリを作成します。任意の明示的なルートは、正規ルートやレガシールートをインポートまたは統合することはありません。既知の古いルート ~/.pi/agent-mcp-claude と ~/.pi/agent-mcp-codex は、アップグレードガイダンスとともに拒否され、古いクライアント設定が分割ロック名前空間を静かに再作成できないようにします。セッションを共有する予定の2つの長期クライアントに異なるオーバーライドを与えないでください。

別々の v1 ルートからのアップグレード

古い設定では、一般的に ~/.pi/agent-mcp-claude/ と ~/.pi/agent-mcp-codex/ が使用されていました。次の順序でアップグレードします:

1. すべての古い Claude Code/Codex MCP クライアントを停止し、それらの Pi RPC プロセスが終了したことを確認します。

2. 両方のクライアント設定から PI_AGENT_MCP_STATE_DIR を削除します。

3. 1つの v2 クライアントを起動します。まず未完了の移行トランザクションを再開し、次に正規、Claude、Codex、および設定されたレガシールートから sessions.json を ~/.pi/agent-mcp/ にインポートします。

4. pi_status と ~/.pi/agent-mcp/migrations/*/receipt.json の下の完了レシートを確認します。新しい移行は、レガシーマニフェストを決定的な sessions.v1.retired-<content-hash>.json ファイルとして退役させ、決して削除しません。以前の v2 ビルドによって作成されたトランザクションは、記録された sessions.v1.quarantine-* パスを保持して再開します。

5. 他の v2 クライアントを起動します。

移行はソースアトミックです。競合が発生すると、完全なソースがアクティブのままになり、migration_conflict が返されます。そのソースを部分的にアクティブにすることはありません。PI_AGENT_MCP_LEGACY_STATE_DIRS は、追加のレガシールートディレクトリの OS パス区切り文字で区切られたリストを提供できます。

v1 マニフェストに cleanShutdown: false がある場合、起動は legacy_state_uncertain を返します。すべての古い MCP および Pi プロセスが停止していることを手動で確認した後、PI_AGENT_MCP_IMPORT_DIRTY=1 を指定して1回の正規起動を実行します。これは自動化された古い所有者の検出ではなく、1回限りの人間による証明です。アクティブな v1 タスクは host_interrupted としてインポートされます。移行が成功したら変数を削除します。

ツール

公開 API は正確に5つのツールのままです。pi_wait は、終了条件を待つため、意図的にタイムアウトを受け付けなくなりました。

pi_spawn

新しい Pi セッションを作成し、最初のタスクをバックグラウンドで開始します:

{
  "task": "Inspect the authentication module and fix token refresh",
  "cwd": "/Users/me/project",
  "name": "auth-worker",
  "model": "anthropic/claude-sonnet-4-20250514"
}

{
  "session_id": "pi_...",
  "task_id": "task_...",
  "status": "running"
}

name と model はオプションです。cwd は既存の絶対ディレクトリである必要があります。

pi_send

既存のアイドルまたは休止セッションで次のタスクを開始します:

{
  "session_id": "pi_...",
  "task": "Continue by adding regression tests"
}

同じネイティブ Pi セッションファイルが再利用されます。セッションは一度に1つのタスクを実行します。別の MCP サーバー上のライブオーナーは session_in_use を返します。ネイティブエイリアスの競合は native_session_in_use を返します。古いオーナーが正常にシャットダウンした後、別のサーバーはすぐに復元して送信できます。

pi_wait

正確な現在または最後のタスク ID を待ちます:

{
  "task_ids": ["task_a", "task_b", "task_c"],
  "mode": "any"
}

• mode: "any" は、要求されたタスクの少なくとも1つが終了したときに返ります。pending は、まだ実行中の要求されたタスクをリストします。

• mode: "all" は、要求されたすべてのタスクが終了したときに返ります。pending は空です。

• pi_wait は真の終了待機です。MCP リクエストは、要求された条件が満たされるまで開いたままです。アプリケーションレベルのタイムアウトはなく、Pi タスクをキャンセルしません。MCP クライアントがリクエストをキャンセルした場合、その観察待機のみが停止します。Pi タスクは続行します。Claude Code は、長時間実行されるリクエストを独自のバックグラウンドタスクに移動し、その同じリクエストで最終結果を配信する場合があります。

• 待機中、サーバーはクライアントが進行トークンを提供した場合、30秒ごとに標準の MCP 進行ハートビートを送信します。ハートビートにより、クライアントが静かな終了待機をアイドルとして扱うのを防ぎます。ツール結果を返したり、新しいモデルターンをトリガーしたり、Pi をポーリングしたり、タスク状態を変更したりすることはありません。

• ローカル待機はイベント駆動です。クロスサーバー待機は、同じリクエストが開いている間、永続的な現在/最後のスロットを再チェックします。

• 終了状態は completed、failed、aborted、host_interrupted です。

• 死んだホストによって空きアクティブレコードが残された場合、待機者は完全な所有権を取得し、Pi を起動せずに host_interrupted を公開できます。孤児の Pi がまだロックを保持している場合、タスクは保留中のままです。

• 後のタスクがレコードの最後のタスクスロットを上書きすると、古い ID は unknown_task を返します。タスク履歴レジストリはありません。

pi_status

session_id を指定すると、その最終レコードをディスクから読み取ります。引数なしの場合は、閉じられていないすべての最終レコードを動的にリストします。ステータスは観察的です。ロックを取得したり、Pi を起動したりすることはありません。

重要なフィールド:

• state: 永続状態。このサーバーが同じレコードリビジョンでライブ所有権を保持している間のみ、ローカルランタイム状態でオーバーレイされます

• resident: ローカル所有セッションの場合は true/false、別の/フリーオーナーの場合は "unknown"

• ownership: local、other、または free_or_unknown。これは診断であり、認証ではありません

• recoverable: 保存されたネイティブ Pi セッションが厳密な ID 検証に合格したかどうか

• current_task_id と last_task: 永続的な現在/最後のタスクスロット

破損した最終レコードがある場合、pi_status は部分的なリストを返す代わりに明確に失敗します。

pi_close

論理セッションを永続的に閉じます:

{
  "session_id": "pi_..."
}

ローカル常駐の場合、アクティブな作業は aborted になり、Pi プロセスグループ全体が停止され、レコードは閉じられます。ネイティブ ID を持つフリーのリモートレコードの場合、close は論理とネイティブの両方の所有権を取得し、アクティブなタスクを host_interrupted として公開し、Pi を起動せずに閉じます。ID のないエラーレコードは、論理所有権の下でのみ閉じることができます。いずれかのネイティブ ID フィールドが存在する場合は、両方のフィールドとネイティブフェンシングが必要です。ライブオーナーは session_in_use を返します。ネイティブ Pi JSONL ファイルは保持されます。

エラー

所有権と移行の失敗は安定した公開コードを使用し、ロックパスやロック診断を公開しません:

• session_in_use: 別の準拠ホストまたは継承された孤児が論理セッションを所有しています

• native_session_in_use: 別の論理レコードが同じ実際のネイティブ Pi ID を所有しています

• migration_blocked: 別の移行/所有権操作が現在ソースをフェンスしています

• migration_conflict: レガシーソースが既存の正規レコードと競合し、未退役のままです

• legacy_state_uncertain: ダーティな v1 状態には、シャットダウン後の明示的な証明が必要です

• ownership_unavailable: カーネルロックバインディングまたはセキュアな所有権ルートが利用できません

unknown_session、unknown_task、session_busy、session_not_recoverable を含む他の既存の検証およびライフサイクルエラーは、確立された意味を保持します。

永続性、クラッシュ、孤児の回復

このプロジェクトは、デーモンではなく共有論理永続性を実装しています:

• 新しいセッションは、セッションごとのプライベート Pi ディレクトリと事前割り当てされたネイティブ ID を使用します。

• 正常なシャットダウンは、Pi プロセスグループ全体を停止し、dormant/closed を永続的に公開し、レコード書き込みを排出してから、所有権記述子を閉じます。

• 次の MCP サーバーは、pi_send で休止セッションを、その正確なネイティブファイルと ID を使用して遅延復元します。

• タスクはホストシャットダウン後に意図的に続行されず、自動的に再生されることはありません。

• MCP 親がクラッシュし Pi が存続する場合、Pi は両方のカーネルロック記述子を継承します。他のサーバーは、孤児の Pi プロセスグループが終了するまで session_in_use でフェイルクローズします。

• 永続的に孤児化されたセッションを回復するには、その Pi RPC プロセスグループを特定して終了し、pi_wait、pi_send、または pi_close を再試行します。ロックファイルを削除しないでください。その内容は診断のみであり、古いロックの権限ではありません。

共有レジストリのレイアウトは次のとおりです:

~/.pi/agent-mcp/
  sessions/       # one atomic v2 JSON record per logical session
  pi-sessions/    # exclusive directories for newly created native sessions
  locks/          # stable 0600 logical/native/migration lock files
  migrations/     # durable source snapshots, intents, conflicts, receipts
  tmp/

ディレクトリはプライベートモード 0700 です。レコードとロックファイルはモード 0600 です。

並行性の境界

異なる Pi セッションが同じ cwd を指す場合がありますが、このプロジェクトはワークツリーを作成したり、重複するコード編集を防いだりしません。並列セッションには、重複しないタスクまたは別のワークツリーディレクトリを指定してください。カーネル所有権は、2つの準拠 MCP サーバーが同じ Pi セッションに書き込むのを防ぎます。プロジェクトチェックアウトへの書き込みを調整したり、独立した Pi TUI/サードパーティプロセスから保護したりすることはありません。

設定

開発

npm run typecheck
npm run build
npm test
npm pack --dry-run

テストは一時ルートと制御可能なフェイクPiを使用し、ユーザーの実際の~/.piデータを読み書きしたり、モデルAPIを呼び出したりすることはありません。カバレッジには、RPCフレーミング、プロセスグループのクリーンアップ、レコードごとの原子性、ソースアトミックな移行、カーネル所有権の継承、サーバー間のステータス/待機/送信/クローズ動作、および5つのツールからなるMCPサーフェスが含まれます。