pi-agent

Pi エージェント

ユーザーが Pi を操作したい場合、または Pi を基盤に何かを構築したい場合に、このスキルを使用します。Pi は、TypeScript 拡張機能、スキル、プロンプトテンプレート、テーマ、パッケージ、カスタムモデル／プロバイダー、SDK 統合、RPC モード、JSON イベントストリーム、TUI コンポーネントによって拡張できる、最小構成のターミナル向けコーディングハーネスです。

最初の判断

回答またはコーディングを始める前に、参照先を選んでください。

ユーザーの意図	参照先
Pi の概要、ドキュメントの案内、インストール方法	references/overview.md
インストール、認証、初回起動	references/quickstart.md
日常的な CLI の使い方、コマンド、モード、フラグ、プロジェクトの信頼設定	references/usage.md
プロバイダー認証、API キー、クラウドプロバイダーの設定	references/providers.md
カスタムモデルのエントリー、ローカルモデル、プロキシ、互換性フラグ	references/models.md
ローカル llama.cpp ルーター、/llama、モデルのダウンロード／読み込み	references/llama-cpp.md
設定キーとデフォルト値	references/settings.md
PI_* などの環境変数	references/environment-variables.md
拡張機能の開発、カスタムツール、イベント、コマンド	references/extensions.md
カスタムプロバイダーの実装、OAuth、カスタムストリーミング	references/custom-provider.md
Node/TypeScript への Pi の組み込み	references/sdk.md
別のプロセス／言語からの統合	references/rpc.md
JSONL イベント出力の利用	references/json.md
ターミナル UI コンポーネントの構築	references/tui.md
拡張機能／スキル／プロンプト／テーマのパッケージ化	references/packages.md
サブエージェントへの委任、チェーン、並列実行、オーケストレーション	references/pi-subagents.md
MCP サーバーの接続、MCP ツールの検出／設定	references/pi-mcp-adapter.md
対話型インタビューフォーム、構造化されたユーザー入力	references/pi-interview.md
ウェブ検索、URL／PDF／リポジトリの取得、動画の理解	references/pi-web-access.md
Pi スキルの作成	references/skills.md
プロンプトテンプレートまたはテーマ	references/prompt-templates.md、references/themes.md
セッション、ブランチ作成、圧縮、JSONL の解析	references/sessions.md、references/compaction.md、references/session-format.md
セキュリティ、サンドボックス化、信頼	references/security.md、references/containerization.md
キーボードまたはターミナルの問題	references/keybindings.md、references/terminal-setup.md、references/tmux.md、references/windows.md、references/termux.md、references/shell-aliases.md
Pi 自体の開発	references/development.md

Pi を基盤に構築する際のデフォルト

型安全性、状態への直接アクセス、プロセス内でのカスタムツール／拡張機能、またはカスタムリソースの読み込みが必要な Node/TypeScript アプリでは、SDK を優先してください。安定した単一セッションには createAgentSession() を使用します。アプリで新規作成／再開／フォーク／複製／インポートの各フローを通じてセッションを置き換える必要がある場合は、createAgentSessionRuntime() を使用します。認証とモデルの検索には ModelRuntime.create() を使用します。

クライアントが Node.js 以外である場合、プロセス分離が必要な場合、または言語に依存しない JSONL プロトコルを必要とする場合は、RPC モードを優先してください。ステートレスなサブプロセス統合では pi --mode rpc --no-session から始め、永続化が必要になったらセッションフラグを追加します。レコードは \n のみで分割してください。Node の readline はプロトコルに準拠していません。

双方向制御ではなく、ストリーミングイベントのみを必要とする単発のコマンドラインパイプラインでは、JSON モードを優先してください。pi --mode json "prompt" を使用します。

カスタムツール、コマンドハンドラー、イベントフック、プロバイダー登録、カスタム圧縮、パス保護、プロジェクトの信頼ポリシー、UI プロンプト、ウィジェット、TUI コンポーネントなど、Pi ネイティブの動作には拡張機能を使用します。

複数のマシンやプロジェクト間で、再利用可能な拡張機能、スキル、プロンプトテンプレート、テーマを共有またはインストールする場合は、パッケージを使用します。

安全性のデフォルト設定

Pi はローカルで動作し、デフォルトではサンドボックス化されていません。拡張機能、パッケージ、スキル、シェルコマンド、プロジェクトローカルの .pi リソースは、Pi プロセスと同じ権限を持つコードとして扱ってください。プロジェクトの信頼設定で制限できるのは、読み込まれるプロジェクト入力だけです。これはサンドボックスではありません。信頼できないリポジトリや無人の自動処理では、Docker、OpenShell、Gondolin、VM、またはリモートサンドボックスで隔離してください。

プロジェクトファイルにシークレットを保存しないでください。環境変数、~/.pi/agent/auth.json、/login を使った OAuth、または models.json／プロバイダー設定でのコマンドによるシークレット参照を優先してください。

よく使うコマンド

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi
pi -p "Summarize this codebase"
pi --mode json "List files"
pi --mode rpc --no-session
pi --provider anthropic --model claude-sonnet-4-5
pi --model sonnet:high "Solve this complex problem"
pi --tools read,grep,find,ls -p "Review this repository"
pi --tui-mode fullscreen
pi install npm:pi-subagents
pi update --all

対象範囲

これらのリファレンスは、Pi のドキュメント（https://pi.dev/docs/latest）と、その配下にあるすべてのドキュメントページを、Pi 0.84.2 時点でまとめたものです（ドキュメントのソース：https://github.com/earendil-works/pi（旧 pi-mono）の packages/coding-agent/docs/）。また、https://pi.dev/packages/ にある pi-subagents、pi-mcp-adapter、pi-interview、pi-web-access の各パッケージページも対象とし、公開済みの npm README およびパッケージドキュメント（pi-web-access 0.22.0、pi-mcp-adapter 2.25.0、pi-subagents 0.49.0、pi-interview 0.11.0）と照合しています。API の正確な動作が重要な場合は、引用されているリファレンスページを優先し、node_modules/@earendil-works/pi-coding-agent/dist/ および node_modules/@earendil-works/pi-ai/dist/ にあるインストール済みの TypeScript 定義を確認してください。

エージェントの運用手順

1. 環境を確認します。 目標、評価指標、予算（時間、計算資源、費用）、停止条件を確認します。
2. 入力を明確にします。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果に影響する値を推測せず、質問してください。
3. まず小規模に実行します。 最初に 1 回の反復を最初から最後まで実行し、規模を拡大する前にログを確認します。
4. 上記の指示とリファレンスを使って、タスク全体を実行します。
5. 結果を検証します。 保留データで評価し、各反復、仮説、結果の監査証跡を残します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未解決の不確実な点を明記します。

こうなった場合	こうしてください
1 回の反復で、疑わしいほど大きな改善が得られた	結果を受け入れる前に、データリークや評価の不具合がないか確認してください。
これらの指示にある関数、フラグ、エンドポイントがインストール済みのバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、対応を調整してユーザーに伝えてください。API を捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧である	ユーザーに確認するか、実行前に仮定を明示してください。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計を捏造しないでください。実行または検証できない場合は、その旨を明確に伝えてください。
• 否定的な結果も記録し、好ましい実行結果だけを選んだり報告したりしないでください。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があります。インストール済みバージョンの公式ドキュメントで確認してください。
• 費用が発生する操作、共有 GPU やクラウドのクォータを消費する操作、個人データや患者データを扱う操作、元に戻せない操作を行う前に、許可を得てください。

関連スキル

• qiskit：Qiskit と IBM Quantum Runtime を使って、量子回路を構築、シミュレーション、トランスパイル、実行します。