pi

Pi Agent Harness — earendil-works（CLI・統一 LLM API・エージェントランタイム・TUI）

1 — 概要
何か
pi.dev 0.80.6 MIT TypeScript Node >= 22.19

pi（GitHub: earendil-works/pi）は、Pi agent harness の TypeScript モノレポ。中心の @earendil-works/pi-coding-agent は対話型コーディングエージェント CLI（read / write / edit / bash）として位置づけられている。

Pi は「ワークフローをツールに合わせる」のではなく、拡張・スキル・プロンプトテンプレート・テーマ・Pi Packages で ユーザー側の運用に合わせて変形する。公式サイトは pi.dev、ドキュメントは pi.dev/docs/latest。

5主要パッケージ
4実行モード
30+LLM プロバイダー
piCLI entrypoint
設計思想: コアは最小に保ち、サブエージェント・plan mode・MCP・権限確認・ToDo などは組み込み機能ではなく、拡張や外部パッケージとして足せる余地を残す。組み込みの権限システムは持たない。隔離が必要ならコンテナ化を使う。
2 — Pi coding agent
使い始め

@earendil-works/pi-coding-agent は、read・write・edit・bash を標準ツールとして持つ対話型コーディングエージェント CLI。API キーでも、既存サブスクリプションの /login でも始められる。通常の npm インストールでは依存の lifecycle script は不要なので、--ignore-scripts を付ける。

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# インストーラ代替
curl -fsSL https://pi.dev/install.sh | sh

# API key で起動
export ANTHROPIC_API_KEY=sk-ant-...
pi

# 既存サブスクリプションで認証
pi
/login
interactive

標準 TUI。エディタ、メッセージ、ツール呼び出し、フッターで状態を見ながら作業する。

-p

一回だけ応答して終了。標準入力も初期プロンプトに混ぜられる。

--mode json

イベントを JSON Lines で出す。ログ処理や非対話実行向け。

--mode rpc

stdin/stdout の LF 区切り JSONL RPC。Node 以外のプロセス連携向け。

埋め込み向けに SDK もある。実例は openclaw/openclaw。

モデルと認証

サブスクリプション

Anthropic Claude Pro/Max、OpenAI ChatGPT Plus/Pro（Codex）、GitHub Copilot を /login で使える。

API キー

Anthropic、Ant Ling、OpenAI、Azure OpenAI、DeepSeek、NVIDIA NIM、Google Gemini / Vertex、Amazon Bedrock、Mistral、Groq、Cerebras、Cloudflare AI Gateway / Workers AI、xAI、OpenRouter、Vercel AI Gateway、ZAI Coding Plan、OpenCode Zen / Go、Hugging Face、Fireworks、Together AI、Kimi For Coding、MiniMax、Xiaomi MiMo などに対応する。詳細は providers.md。

3 — パッケージ一覧
モノレポ構成

公開パッケージは 0.80.6 系で揃っている（ルート monorepo の package.json は 0.0.3）。責務は統一 LLM API、エージェントランタイム、coding agent CLI、差分レンダリング TUI、実験的 orchestrator に分かれる。旧 pi-web-ui は本リポジトリから外れており、Slack / チャット自動化は別リポ earendil-works/pi-chat を参照する。

パッケージ 役割
@earendil-works/pi-coding-agent Pi CLI 本体。read / bash / edit / write ツール、セッション管理、TUI、JSON / RPC / SDK 連携を提供。
@earendil-works/pi-ai 自動モデル発見、プロバイダー設定、トークン・コスト計測、モデル間ハンドオフを持つ統一 LLM API。
@earendil-works/pi-agent-core ツール呼び出し、状態管理、添付ファイル対応を持つ汎用エージェント基盤（transport 抽象あり）。
@earendil-works/pi-tui 差分レンダリング付きターミナル UI ライブラリ。
@earendil-works/pi-orchestrator 実験的。CLI / API / 挙動は未安定で、変更・削除の可能性がある。
4 — セッションと共有
JSONL + tree

Pi のセッションは JSONL ファイルとして保存され、各エントリが id と parentId を持つ。これにより、別ファイルを増やさずに履歴ツリー上で分岐できる。

/tree

過去の任意地点へ移動し、そこから続行。検索、折りたたみ、ラベル付けもできる。

/fork

過去のユーザーメッセージから新しいセッションファイルを作る。

/clone

現在のアクティブブランチを新しいセッションに複製する。

/compact

古いメッセージを要約し、長いセッションのコンテキスト逼迫を回復する。

pi -c                  # 最新セッションを継続
pi -r                  # 過去セッションを選択
pi --no-session        # 保存しない一時セッション
pi --session <path|id> # 特定セッションを利用
pi --fork <path|id>    # 特定セッションから分岐
OSS セッション共有

README は、OSS で Pi や他の coding agent を使った作業セッションの共有を呼びかけている。狙いは、toy benchmark ではなく実作業のツール呼び出し・失敗・修正を集め、モデル・プロンプト・ツール・評価を改善すること。

共有ツールは badlogic/pi-share-hf。作者自身の作業セッションは README の表記どおり Hugging Face: badlogicgames/pi-mono（データセット名は従来の pi-mono のまま）で公開されている。

5 — 拡張モデル
core stays small

Pi はサブエージェントや plan mode を標準装備しない。その代わり、TypeScript 拡張と Agent Skills 標準、プロンプトテンプレート、テーマ、Pi Packages で、各チームのワークフローを後付けする。MCP、権限ゲート、サンドボックス、Git チェックポイント、独自 UI も拡張側で組み込める。

Prompt Templates

Markdown の再利用プロンプト。/name で展開し、変数も使える。

Skills

Agent Skills 標準の手順パッケージ。/skill:name または自動ロードで使う。

Extensions

TypeScript でツール、コマンド、キー、イベント、UI コンポーネント、プロバイダーを追加する。

Pi Packages

extensions / skills / prompts / themes を npm または git で配布・インストールする。

セキュリティ注意: Pi Packages はシステム権限で動く。拡張は任意コードを実行でき、スキルはモデルに任意の操作を指示できるため、第三者パッケージはソース確認が前提。
インストール例 
pi install npm:@foo/pi-tools
pi install npm:@foo/pi-tools@1.2.3
pi install git:github.com/user/repo
pi install https://github.com/user/repo@v1
pi remove npm:@foo/pi-tools
pi list
pi update
pi config
pi update --extensions
pi update --self
pi update npm:@foo/pi-tools
6 — 権限と隔離
Permissions & Containerization

Pi にはファイルシステム・プロセス・ネットワーク・資格情報を制限する組み込み権限システムはない。起動したユーザーとプロセスの権限で動く。境界が必要ならコンテナ化またはサンドボックスを使う。詳細は containerization.md。

パターン 隔離対象 向き
Gondolin extension 組み込みツールと ! コマンド ホストに pi とプロバイダ認証を残し、ツール実行だけをローカル Linux micro-VM へ流す
Plain Docker pi プロセス全体 単純なローカル隔離。API キーはコンテナに入る
OpenShell pi プロセス全体 ポリシー制御付きサンドボックス（ローカル / リモート）
注意: 拡張は pi プロセスが動いている場所で動く。ホスト上の pi にツール転送拡張を付けても、他のカスタム拡張ツールは委譲しない限りホスト側で実行される。
7 — 開発・貢献
ビルド・検証

依存の hydrate は lifecycle script を止めて行う。npm run check は Biome、pinned deps、TS import、shrinkwrap、browser smoke、tsgo などをまとめて見る。

npm install --ignore-scripts  # lifecycle script なしで依存を入れる
npm run build                 # 全パッケージのビルド
npm run check                 # lint / type / shrinkwrap / smoke
./test.sh                     # API キーなしなら LLM 依存テストはスキップ
./pi-test.sh                  # ソースから pi を実行（任意の cwd から可）
Supply-chain hardening

npm 依存の変更はレビュー対象のコード変更として扱う。

  • 外部直依存は exact pin。ワークスペース内部パッケージだけ version range を残す。
  • .npmrc で save-exact=true と min-release-age=2。
  • package-lock.json が依存の正。lockfile の偶然コミットは pre-commit が止め、PI_ALLOW_LOCKFILE_CHANGE=1 が必要。
  • 公開 CLI にはルート lockfile から生成した packages/coding-agent/npm-shrinkwrap.json を同梱する。
  • ローカルリリース検証は npm run release:local。CI は npm ci --ignore-scripts、定期で npm audit / signature 検証。
Contribution gate

新規 contributor の Issue / PR はデフォルトで自動クローズされる。メンテナーが日次で見直し、質の高いものだけを reopen または承認する。中長期計画は RFC（keyword: pi） も参照。

  1. 1短く具体的で、1 画面に収まる Issue を出す。バグや要望と「なぜ重要か」を明確にする。
  2. 2lgtmi なら今後の Issue、lgtm なら今後の Issue と PR が承認済み扱いになる。
  3. 3PR 前に npm run check と ./test.sh を通す。CHANGELOG.md は直接編集しない。
唯一のルール: 自分のコードを理解していること。AI で書くのは問題ないが、変更内容と影響を説明できない PR はクローズされる。

公式サイト: pi.dev

ドキュメント: pi.dev/docs/latest

リポジトリ: earendil-works/pi（旧 badlogic/pi-mono）

Discord: discord.com/invite/3cU7Bz4UPx

Pi coding agent: @earendil-works/pi-coding-agent

LLM API: @earendil-works/pi-ai

コンテナ化: containerization.md

pi-chat（別リポ）: earendil-works/pi-chat

セッション共有ツール: badlogic/pi-share-hf

公開セッション: Hugging Face: badlogicgames/pi-mono

RFC: rfc.earendil.com/keyword/pi

CONTRIBUTING: CONTRIBUTING.md

AGENTS.md: AGENTS.md