Pi Agent セッション管理
Pi Agent のセッション管理システムは、その最も強力な機能の一つです。
この章では、セッションの保存、復元、分岐、エクスポートについて詳しく説明します。
セッション保存メカニズム
各会話は自動的に1つのセッションファイルとして保存され、JSONL 形式が使用されます。~/.pi/agent/sessions/その中で、プロジェクトパスごとに分類されます。
ディレクトリ名は、プロジェクトの絶対パスから変換されます。スラッシュをハイフンに置き換え、前後に -- を付けます。
ファイル名は、作成タイムスタンプとセッション UUID を連結して作られます。
各セッションは内部でツリー構造として編成されています。つまり、過去の任意のノードでフォークしても、以前の会話内容が失われることはありません。
~/.pi/agent/sessions/
└── --Users-サンプル-projects-サンプル-demo--/ # 目录名为项目路径，斜杠已替换为连字符
├── 2026-08-31T02-40-11-000Z_019fc2a1-93b4-7c22-8d5e-2b3c4d5e6f7a.jsonl # 时间戳_UUID.jsonl
├── 2026-08-31T04-12-38-000Z_2c8f71ba-4a19-4e63-9d02-7f5a6b8c9d0e.jsonl
└── 2026-08-31T08-55-02-000Z_5e3d92f4-8b26-47ac-a174-9c0d1e2f3a4b.jsonl
セッションファイルの内部構造
セッションファイルの最初の行は固定のメタデータで、セッション形式のバージョン、セッション ID、作成時刻、作業ディレクトリを記録します。
このメタデータには id と parentId フィールドがなく、会話ツリーには参加しません。
2行目以降は1行に1つのエントリが入り、すべて id と parentId フィールドを持ち、この2つがツリー構造を構成します。
エントリのタイプには、message、compaction、branch_summary、label、custom などがあります。
/fork または /clone で作成されたセッションでは、先頭行のメタデータに parentSession フィールドが追加され、元のセッションファイルを指します。
{"type":"session","version":3,"id":"019fc2a1-93b4-7c22-8d5e-2b3c4d5e6f7a","timestamp":"2026-08-31T02:40:11.000Z","cwd":"/Users/サンプル/projects/サンプル-demo"}
{"type":"message","id":"m1","parentId":null,"message":{"role":"user","content":[{"type":"text","text":"帮我实现登录功能"}]}}
{"type":"message","id":"m2","parentId":"m1","message":{"role":"assistant","content":[{"type":"text","text":"好的，我用 JWT 来实现"}]}}
セッションディレクトリもカスタマイズできます。優先度は高い順に、--session-dir パラメータ、環境変数、PI_CODING_AGENT_SESSION_DIRsettings.json 内のsessionDir。
起動時のセッションオプション
コマンドライン引数を使用して、起動時にセッションの動作を制御します：
$ pi -c Resumed session abc123-def456 (42 messages, model claude-sonnet-4-5) $ pi -r ┌ 选择要恢复的会话： │ > abc123 快速审查 3 分钟前 │ def456 重构认证模块 2 小时前 └ $ pi --session ~/.pi/agent/sessions/--Users-サンプル-projects-サンプル-demo--/2026-08-30T09-15-04-000Z_019fbb5d-7a2e-7f31-b5c4-1a2b3c4d5e6f.jsonl Resumed session 019fbb5d-7a2e-7f31-b5c4-1a2b3c4d5e6f $ pi --session abc123 Resumed session abc123-def456 $ pi --fork abc123 Forked to session 9f2e7a01-5c48 $ pi --name "重构认证模块" Session renamed: 重构认证模块 $ pi --no-session Temporary session (will not be saved)
セッション管理コマンド
対話モードに入ると、以下のコマンドがセッションの日常的な管理作業をカバーします。
| コマンド | 機能 | 使用シナリオ |
|---|---|---|
| /resume | 履歴セッションの閲覧と復元 | 以前の会話に切り替えて作業を継続する |
| /new | 新しいセッションを開始 | 履歴に関係のない新しいタスクを開始する |
| /name 名前 | セッション名を設定 | セッションに覚えやすい名前を付ける |
| /session | セッション情報を表示 | ファイルパス、メッセージ数、トークン使用量、費用を確認する |
| /tree | セッションツリーブラウザを開く | 会話ツリーの任意のノードにジャンプする |
| /fork | セッションをフォーク | 以前のユーザーメッセージから新しいセッションを作成する |
| /clone | セッションをクローン | 現在のアクティブなブランチを新しいセッションファイルにコピーする |
| /export ファイル | HTML または JSONL ファイルとしてエクスポート | ローカルアーカイブまたはオフライン共有 |
| /share | セッションを共有 | GitHub Gist にアップロードして、共有可能なリンクを生成する |
/resume セッションセレクター
/resume を入力するか、pi -r で起動すると、現在のプロジェクトのセッションセレクターが開きます。
リストに文字を直接入力するとセッションをフィルタリングできます。その他の操作キーは次のとおりです：
| 操作 | キー | 説明 |
|---|---|---|
| セッションをフィルタリング | 文字を直接入力 | 入力内容に応じて、現在のプロジェクトのセッションリストをリアルタイムにフィルタリングする |
| パス表示の切り替え | Ctrl+P | セッションの作業ディレクトリパスの表示/非表示を切り替える |
| 並び替えの切り替え | Ctrl+S | 並び替え方法を切り替える |
| 名前付きセッションのみ表示 | Ctrl+N | 名前が設定されているセッションをフィルタリングして表示する |
| 名前を変更 | Ctrl+R | 選択したセッションの名前を変更する |
| 削除 | Ctrl+D | 確認後に実行されます。システムに trash コマンドがある場合は、完全に削除するのではなくゴミ箱に移動されます。 |
セッションツリー（/tree）
これは Pi Agent の最もユニークな機能です。セッションはツリー構造で保存され、過去の任意のノードでフォークできます。
ツリーの構造
以下は、典型的なセッションツリーの構造です：
├─ user: "帮我实现一个登录功能..." │ └─ assistant: "好的，我来实现..." │ ├─ user: "用 JWT 方案..." │ │ └─ assistant: "使用 JWT 实现..." │ │ └─ user: "测试通过了" ← 当前活跃分支 │ └─ user: "还是用 Session 方案..." │ └─ assistant: "使用 Session 实现..."
この例では、同じ起点から出発して、JWT と Session の2つの案をそれぞれ検討し、各案の会話がすべて完全に保持されています。
ツリーブラウザの操作
/tree を開くと、以下のキーでツリー内を移動して選択できます。
| 操作 | ショートカットキー | 説明 |
|---|---|---|
| 上下に移動 | ↑/↓ | 表示されているエントリ間でカーソルを移動する |
| ページ送り | ←/→ | 上/下にページ送り |
| 折りたたむ/展開 | Ctrl+←/Ctrl+→ または Alt+←/Alt+→ | ブランチセグメントを折りたたむ/展開する、またはジャンプする |
| ラベルを設定 | Shift+L | 選択したノードにラベルを設定する |
| タイムスタンプの切り替え | Shift+T | エントリのラベルのタイムスタンプを表示/非表示する（ラベルは Shift+L で設定） |
| 選択を確定 | Enter | 現在のノードを選択する |
| キャンセル | Escape / Ctrl+C | ツリーブラウザを終了する |
| フィルターモードを切り替え | Ctrl+O | フィルターモードを循環する（/tree ブラウザ内でのみ有効） |
フィルターモード
フィルターモードは、ツリーブラウザに表示するエントリを決定します。Ctrl+O で循環して切り替えます。
| モード | 表示内容 |
|---|---|
| default | デフォルトビュー。ツール呼び出しの詳細を折りたたむ |
| no-tools | すべてのツール呼び出しと結果を非表示にする |
| user-only | ユーザーメッセージのみ表示 |
| labeled-only | ラベル付きエントリのみ表示 |
| all | すべてのエントリを表示 |
ユーザーメッセージを選択すると、そのテキストがエディタ領域に入力され、再編集して送信することで新しいブランチを作成できます。
AI の応答またはツール呼び出しを選択すると、その位置に直接ジャンプし、そこから会話を続けることができます。
/tree と /fork と /clone の違い
3つはどれも履歴の位置に戻れますが、新しいセッションファイルが生成されるかどうか、また見える会話の範囲が異なります。
| コマンド | 出力 | ビュー | 典型的な用途 | ブランチサマリー | 一言メモ |
|---|---|---|---|---|---|
| /tree | 同じセッションファイル | 完全な会話ツリー | 同じセッション内で代替案を検討する | オプションの要約 | 複数のアイデアをまとめて管理でき、比較が容易 |
| /fork | 新しいセッションファイルを作成 | ユーザーメッセージのみ表示 | 以前のプロンプトから新しいセッションを開始する | 无 | ある履歴ポイントから完全に独立して再開する |
| /clone | 新しいセッションファイルを作成 | 現在のアクティブブランチ | 現在の作業をコピーして続行する | 无 | 続行する前にコピーを作成して、後戻りできるようにする |
ブランチサマリー
/tree を使ってあるブランチから別のブランチにジャンプするとき、Pi Agent は放棄されたブランチの要約を生成できます。
この要約は新しい場所に添付され、以前のブランチで何をしたかを把握できます：
| モード | 動作 | 適用シナリオ |
|---|---|---|
| 要約を生成しない | 直接ジャンプし、放棄されたブランチの情報は一切保持しない | 放棄した試行に保持する価値がない場合 |
| デフォルトの要約 | デフォルトのプロンプトを使用して、AI に放棄されたブランチを要約させる | 以前に何をしたか大体把握したいだけの場合 |
| カスタム要約 | 注目ポイントを指定すると、AI がニーズに応じて要約する | 特定の結論を持ち帰る必要がある場合、例えばハマった点など |
あなたは~/.pi/agent/settings.jsonで要約の動作を制御できます：
例
"branchSummary": {
"reserveTokens": 16384,
"skipPrompt": false
}
}
設定skipPrompttrue にすると、/tree ナビゲーション中に「要約を生成するか」の質問をスキップできます。
質問をスキップした場合、デフォルトでは要約を生成せず、直接ターゲット位置にジャンプします。
セッションのエクスポートと共有
セッションはローカルファイルにエクスポートでき、直接アップロードして共有リンクを生成することもできます。
HTML としてエクスポート
エクスポートすると、ブラウザで直接開ける単一ファイルのページが生成され、オフラインでの閲覧に適しています。
# 导出到默认位置 /export # 导出到指定文件 /export ~/Desktop/my-session.html
GitHub Gist として共有
ファイルをアップロードしたくない場合は、/share コマンド一つでオンラインリンクを生成できます。
/share
実行すると、プライベートな GitHub Gist が作成され、共有可能な HTML リンクが生成されます。
コマンドラインでのエクスポート
対話モードに入らなくても、既存のセッションをエクスポートできます。
$ pi --export session.jsonl output.html Exported to output.html (128 KB)
その他の拡張機能オープンソースプロジェクトを行っていて、研究目的でセッションを公開したい場合は、次を参照してください。pi-share-hfこのツールを使うと、セッションを Hugging Face データセットに公開できます。