# @tintinweb/pi-subagents

English · 简体中文 · 日本語 · 한국어

> これは英語版 README の一部を翻訳したものです(機械翻訳のため、誤りのご指摘を歓迎します)。概要、機能、インストール、クイックスタート、`/agents` コマンドのみを収録しています。UI、カスタムエージェント、ツールのパラメーター、設定とデフォルト値、イベント、RPC などその他の内容は英語版でのみ提供しています。全文は [英語版 README(完全版)](README.md) を参照してください。 > > *Partial translation of the English README. Full reference: [README.md](README.md) · https://github.com/tintinweb/pi-subagents/blob/master/README.md*

@tintinweb/pi-subagents

npm バージョン npm ダウンロード数 CI ライセンス: MIT

pi >= 1.1.0 が必要 pi.dev パッケージ Claude Code 互換 最終コミット

pi のための Claude Code スタイルのサブエージェントとワークフローオーケストレーション。

インストール · クイックスタート · UI (EN) · カスタムエージェント (EN) · ツール (EN) · 設定 (EN) · ワークフロー (EN) · 変更履歴 (EN)

pi install npm:@tintinweb/pi-subagents

**Claude Code スタイルの自律型サブエージェントとワークフローオーケストレーション**を実現する [pi](https://pi.dev) 拡張機能です。独立したセッションで動く専用エージェントを起動でき、各エージェントはそれぞれ独自のツール、システムプロンプト、モデル、思考レベルを持ちます。バックグラウンドで実行する(デフォルト)ことも、完了までブロックすることもできます。実行中にステアリング(指示を送って軌道修正)したり、完了したセッションを再開したり、独自のエージェントタイプを定義したりできます。オーケストレーションをその場の判断に任せるべきでない場合は、決定論的な JavaScript スクリプトを `SubagentWorkflow` ツールに渡します(`agent()`、`parallel()`、`pipeline()`)。Claude Code の `Workflow` ツール向けに書かれたスクリプトは、いくつかの[相違点](https://github.com/tintinweb/pi-subagents/blob/master/docs/workflows.md#coming-from-claude-code)を除いてここでも動きます。 pi-subagents のスクリーンショット https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543 pi-color-badges-white ## 機能 - **Claude Code と同じ見た目と操作感**:ツール名、呼び出し規約、UI パターン(`Agent`、`get_subagent_result`、`steer_subagent`)が同じで、ネイティブ機能のように感じられます - **並列バックグラウンドエージェント**:複数のエージェントを同時に実行でき、自動でキューイングされます(同時実行数の上限は設定可能、デフォルトは 10)。完了通知は親エージェントの次のターンの切れ目で届き、同時に完了した場合はまとめて届きます - **ライブウィジェット UI**:エディターの上に常駐するウィジェットで、アニメーションするスピナー、ツールの動作状況のリアルタイム表示、トークン数、色付きのステータスアイコンを表示します。`/agents → Settings → Widget` で設定できます:`all`(すべてのエージェント)、`background`(デフォルト。フォアグラウンド実行は `Agent` ツールの結果としてすでにインライン表示されるため非表示)、`off` - **FleetView**:エディターの下に表示される、Claude Code スタイルの操作可能なリストで、`main` と実行中のすべてのサブエージェントが並びます(起動が早い順)。空のプロンプトで `↓`(または `←`)を押すとリストにフォーカスが移り、`↑`/`↓` で選択を移動、`Enter` で選択したエージェントの会話を開き(リアルタイムで自動更新されます)、`Esc` で戻ります。完了したエージェントは少しの間残ってから消えます。ビューアーは完了後も開いたままなので、最終出力を読めます。`/agents → Settings → Fleet view` で切り替えます - **会話ビューアー**:`/agents` で任意のエージェントを選ぶと、その会話全体をリアルタイムでスクロール表示するオーバーレイが開きます(新しい内容に自動で追従し、上にスクロールすると一時停止)。pi のフルスクリーンモードでは、枠なしで端末全体を使う、マウス対応の観察画面になります。`Enter` で入力欄を開き、入力して `Enter` で送信すると、実行中のエージェントをその場でステアリングできます(`Esc` または空のまま送信で戻ります)。メッセージはユーザーメッセージとして表示され、エージェントは現在のツール呼び出しを終えた後、その指示に沿って方向を変えます。実行中のフォアグラウンド `Agent` 呼び出しで `b` を押すと、その実行をバックグラウンドに移せます([フォアグラウンドのエージェントをバックグラウンドに移す](#フォアグラウンドのエージェントをバックグラウンドに移す)を参照)。まだ実行中のエージェントは `x` を押す(確認のためもう一度 `x`)と停止できます。ステアリングと停止はバックグラウンドのエージェントにも使えます。ツール呼び出しは、エージェントのセッションに登録されたレンダラーを通じて、pi 自身のトランスクリプトと同じように表示されます:bash 呼び出しはコマンドと出力、`read` は行番号、`edit` は差分、拡張機能のツールは独自のレンダラーで表示され、レンダラーのないツールは引数と長さ制限付きの出力プレビューにフォールバックします。`ctrl+o`(または `app.tools.expand` に割り当てたキー)で省略されたツール出力を展開します。アシスタントのテキストは Markdown として描画され、`m` で「オフ」「アシスタントのみ」「すべて」の 3 つを切り替えます([Viewer markdown](README.md#persistent-settings) を参照) - **カスタムエージェントタイプ**:`.pi/agents/.md` または `.agents/agents/.md`(プロジェクト)、あるいはグローバルにエージェントを定義します。YAML frontmatter で、システムプロンプト、モデル選択、思考レベル、ツール制限、Claude Code 互換の色付き名前バッジを指定できます - **パッケージ同梱のエージェント**:pi パッケージは `package.json` に `"pi": { "subagents": { "agents": ["./agents"] } }` と書くことで、独自のサブエージェント(とワークフロースクリプト)を宣言できます。`pi install` だけでセットアップが完了し、マシンごとやコンテナ起動のたびに `.pi/agents/` へファイルをコピーする必要はありません。読み込むのは pi が実際にインストールしたパッケージだけで(`node_modules` は決して読みません)、パッケージの定義はユーザーが定義したどのエージェントよりも優先度が低く、`/agents` では読み取り専用で表示され、Eject と Disable が使えます。`packageAgents` / `packageWorkflows` で対象を絞り込んだり、無効にしたりできます。**[詳細ガイド](https://github.com/tintinweb/pi-subagents/blob/master/docs/packages.md)** - **ネストしたサブエージェント**:組み込みの `general-purpose` エージェントは、Claude Code と同じく自身のサブエージェントに作業を委任できます。`Explore` と `Plan` は委任できず、カスタムエージェントは `allowed_subagents` を設定すると有効になります。委任するエージェントは、自身の子エージェントだけを対象とする独自の `Agent`、`get_subagent_result`、`steer_subagent` ツールを持ち、メインセッションからの深さには上限があります(デフォルトは 2)。操作できるのは自分の子エージェントだけで、自分が終了すると子エージェントは停止され、子のトランスクリプトとトークン消費は親に集計されます。この許可リストは権限の境界です。子エージェントは自身のツールで動くため、`tools:` そのものと同じくらい慎重に選んでください - **エージェントメンション**:サブエージェントはファーストクラスの存在です。プロンプトで `@explore also check the RPC path` と入力すると、その内容はメインモデルではなくそのエージェントに届き、メインの会話には一切残りません。1 つの構文でライフサイクル全体を扱えます:実行中のエージェントにメッセージを送る、完了したエージェントを再開する、ずっと後になってからディスク上のセッションを開き直す、一度も実行されていなければ起動する。実行中でないエージェントをメンションすると、画面外で複製した会話を通じて起動されるため、Claude Code と同じように文脈を踏まえて書かれたプロンプトと本物の `Agent` ツール呼び出しが得られ、やはりメインの会話には一切残りません。`direct` モードでは、モデルを一切呼ばずに、入力したテキストからその場で起動します。オーケストレーターがエージェントに `name` を付ければ `@auth-audit` のように呼びかけられ、その名前は `steer_subagent`/`get_subagent_result` でも使えます。`@` を入力すると、pi のファイル補完に加えて、実行中のエージェント、再開可能なエージェント、起動可能なタイプが補完候補に表示されます。`@main` を付けると、テキストを強制的にメインモデルへ戻します。`/agents → Settings → Agent mentions` で切り替えます - **スクリプトによるワークフロー**:`SubagentWorkflow` ツールは、多数のサブエージェントをオーケストレーションする決定論的な JavaScript スクリプトを実行します:`agent()`、`parallel()`、`pipeline()`、`phase()`、`log()`、`args` を使い、純粋なリテラルの `meta` ブロックでフェーズを宣言します。`pipeline()` にはステージ間のバリアがないため、ある項目が後のステージに進んでいる間に、別の項目がまだ最初のステージにあることもあります。これに対し `parallel()` は、最も遅いエージェントが終わるまで速いエージェントをすべて待たせます。ワークフローはライブカード付きでバックグラウンド実行され、`/agents → Workflows` または FleetView で実行を選ぶと中身を確認できます。`agent()` は `gate: "npm test"` も受け付け、別のモデルに尋ねる代わりにコマンドを実行して(分離されている場合はその worktree 内で)子エージェントを検証します。`resume: "