Pi Agent コアコンセプト
Pi Agent を正式に使用する前に、その中核概念と動作方法を理解しておくと、より早く使い始めることができます。
ひとことで言うと Pi Agent
Pi Agent はターミナルで動作する AI プログラミングアシスタントです。
起動するとチャットソフトのようなインターフェースが表示され、自然言語で要求を入力すると、AI がコードを読み取り、コマンドを実行し、ファイルを変更します。
4つの実行モード
Pi Agent は4つの実行モードをサポートしており、さまざまなシーンに対応します：
| モード | コマンド | 説明 | 適用シーン |
|---|---|---|---|
| 対話モード | pi（デフォルト） | ターミナル TUI インターフェースで、リアルタイム対話、すべての機能をサポート | 日常開発、対話型プログラミング |
| Print モード | pi -p "プロンプト" | 一回限りのQ&Aで、結果を出力して終了 | スクリプト統合、クイック検索 |
| JSON モード | pi --mode json | すべてのイベントを JSON 行で出力し、プログラム解析に適しています | ツールチェーン統合、データ分析 |
| RPC モード | pi --mode rpc | stdin/stdout の JSONL プロトコルで統合 | プロセス間通信、エディタプラグイン |
対話モードは直接起動して TUI インターフェースに入ります：
$ pi Pi Agent 0.1.x | ~/projects/サンプル-demo claude-sonnet-4 | 上下文 2% | $0.0000 >
Print モードは回答が終わると終了するので、スクリプトに組み込むのに適しています：
$ pi -p "总结这个项目" 这是一个 TypeScript 命令行工具，核心逻辑位于 src/ 目录，包含会话管理、工具调度和扩展加载三个模块。 Tokens: 1.2k 输入 / 320 输出 | 费用 $0.0081
JSON モードは各イベントを1行の JSON として出力し、プログラムで解析しやすくします：
$ pi --mode json -p "总结这个项目"
{"type":"session","id":"a1b2c3d4"}
{"type":"message_start","role":"assistant"}
{"type":"message_end","usage":{"input":1200,"output":320}}
RPC モードは stdin/stdout を介して JSONL メッセージを送受信し、エディタプラグインから呼び出せるようにします：
$ pi --mode rpc
{"id":1,"method":"prompt","params":{"message":"列出 src 目录"}}
{"id":1,"result":{"state":"idle","messages":2}}
初心者としては、ほとんどの時間を対話モードで作業することになります。
慣れてきたら、Print モードをスクリプト自動化に使用できます。
組み込みツール
Pi Agent は起動後、デフォルトで AI に以下の4つの組み込みツールを提供します。さらに grep、find、ls の3つの読み取り専用ツールをオプションで有効にできます：
| ツール名 | 機能 | 例 | デフォルト状態 |
|---|---|---|---|
| read | ファイル内容の読み取り | AI が src/main.ts を読み取ってコードロジックを理解する | デフォルトで有効 |
| write | ファイルの作成または上書き | AI が新規ファイルを作成するか、ファイル全体を書き換える | デフォルトで有効 |
| edit | ファイル内の内容を正確に置換 | AI が関数内の特定の数行のコードを修正する | デフォルトで有効 |
| bash | シェルコマンドの実行 | AI がテストの実行、依存関係のインストール、lint の実行を行う | デフォルトで有効 |
| grep | ファイル内のテキスト検索 | AI が特定の関数がどのファイルで呼び出されているかを検索する | オプションで有効 |
| find | ファイル名で検索 | AI が *.test.ts という名前のすべてのファイルを探す | オプションで有効 |
| ls | ディレクトリ内容の一覧表示 | AI がディレクトリ構造を確認してモジュールを特定する | オプションで有効 |
3つの読み取り専用ツールは--toolsパラメータで手動に有効にします。例：pi --tools read,grep,find,ls。
拡張システム
Pi Agent は以下の5つの方法で機能を拡張します：
| 拡張方法 | ファイル形式 | 用途 | 難易度 |
|---|---|---|---|
| Extensions（拡張） | TypeScript（.ts） | カスタムツール、イベントリスナー、コマンド、UI コンポーネントを登録 | プログラミングが必要 |
| Skills（スキル） | Markdown（SKILL.md） | 専門分野のワークフロー指示とスクリプトを提供 | Markdown が書ければOK |
| Prompt Templates（プロンプトテンプレート） | Markdown（.md） | 再利用可能なプロンプトで、パラメータをサポート | 最も簡単 |
| Themes（テーマ） | JSON（.json） | ターミナルインターフェースの配色をカスタマイズ | 簡単 |
| Packages（パッケージ） | npm/git プロジェクト | 上記4種類のリソースをパッケージ化して共有 | 必要に応じて |
初心者としては、すべての拡張方法をすぐに理解する必要はありません。
まず基本的な使い方から始めて、ニーズが増えてきたら徐々に拡張システムを試してみてください。
ファイル読み込み順序
Pi Agent は起動時にプロジェクト指示ファイルを自動的に読み込み、AI の行動規範を取り決めることができます：
| レベル | パス | 適用範囲 | 優先度 |
|---|---|---|---|
| グローバル設定 | ~/.pi/agent/AGENTS.md | すべてのプロジェクト | 最も低く、共通のベースラインとして |
| プロジェクト設定 | プロジェクトディレクトリおよび親ディレクトリ内の AGENTS.md または CLAUDE.md | 現在のプロジェクト | 最も高く、グローバル指示を上書き可能 |
プロジェクトレベルの設定は親ディレクトリから上に向かって走査して読み込まれ、最終的に現在のディレクトリの設定とマージされます。
以前 Claude Code を使用していた場合は、既存の CLAUDE.md ファイルをそのまま再利用できます。Pi Agent が自動的に認識して読み込みます。
セッションとブランチ
Pi Agent のセッションシステムは、最も特徴的な機能の1つです。
各会話は自動的にセッションファイルとして保存され、~/.pi/agent/sessions/に格納されます。
セッション内部はツリー構造です。任意の履歴ノードから新しい探索方向に「ブランチ」を作成でき、以前の会話を失うことはありません。
これは、さまざまな実装方法を試す必要がある場合に非常に便利です。各アイデアを独立して保持し、いつでも遡ることができます。
その他の拡張