2
5

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

最小限のターミナルCoding Agent「pi」を動かす — インストールからローカルvLLM連携、プラグインと学習経路まで

2
Posted at

はじめに

ターミナル上のCoding Agent(Claude Code、Codex、opencodeなど)は、すでに日常の作業に組み込まれています。一方で、そうしたツールは機能の量が多い分、自分のワークフローに合わない部分が出ても、内側を触れずに我慢せざるを得ないことがあります。

別のアプローチとして、「コアは最小限にし、足りない分は自分で拡張してつくる」という設計思想を持つCoding Agentがあります。それが pi です。

piはearendil-works(Mario Zechner氏)が開発するターミナルCoding Agentで、公式リポジトリは earendil-works/pi です(執筆時点でGitHub 9万スター超)。モットーは「piを自分のワークフローに合わせる。逆ではない(Adapt pi to your workflows, not the other way around)」です。

本記事では、次の内容を説明します。

  1. piとは何か(設計思想・4つのモード)
  2. インストール方法
  3. 認証とモデルの選び方
  4. 設定ファイルの構造(ローカルLLMの連携まで)
  5. インタラクティブモードの実用的な操作
  6. セッション管理(ツリー構造・分岐・コンパクト化)
  7. 拡張機構(Extension / Skill / Prompt Template / Theme / Package)
  8. 最初に導入しておきたいプラグイン
  9. piの学習経路

なお、本記事の検証環境は、前回のvLLM記事と同じ RTX 4090 × 4枚のローカルLLMマシン です。ローカルモデルをpiに繋ぐ手順も踏まえます。

バージョンは2026年8月16日時点のものです。pi本体は 0.84.2、Node.jsは 24.9.0。

1. piとは何か

piは「minimal terminal coding harness」を自称するCoding Agentです。コアは小さく、他ツールが標準搭載している機能(サブエージェント、プランモード、権限ダイアログ、MCP、todoリスト、バックグラウンドbash)は あえて入れていません。

pi
= 最小限のTUI(ターミナルUI)
+ デフォルト4ツール: read / write / edit / bash
+ セッション管理(JSONLのツリー構造)
+ プロバイダ抽象化(30以上のモデルプロバイダ)
+ 拡張ポイント: Extension / Skill / Prompt Template / Theme / Pi Package

サブエージェントが欲しいならtmuxでpiを複数起動するか、自分でExtensionを書くか、既存のパッケージをインストールする。どの選び方もOK、というのが公式のスタンスです。設計思想の全文は著者のブログ記事(参考リンク)にあります。

実行モードは4つです。

モード 起動方法 用途
Interactive pi 通常の作業
Print pi -p "..." シェル・CIからのワンショット
JSON pi --mode json 全イベントをJSONLで消費
RPC pi --mode rpc 別プロセス・別言語からの組み込み

さらにTypeScript SDKがあり、piのセッションエンジンを自分のアプリに組み込むこともできます。

2. インストール

Node.js 22.19.0以上 が必要です(本機は24.9.0で検証済み)。

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

--ignore-scriptsは依存パッケージのライフサイクルスクリプトを無効化するフラグです。pi自体はスクリプト不要なので、公式のインストール手順にこのフラグが入っています。

curlインストーラを使う手もあります。

curl -fsSL https://pi.dev/install.sh | sh

バージョン確認:

pi -v
# 0.84.2

アンインストールは:

npm uninstall -g @earendil-works/pi-coding-agent

アンインストールしても ~/.pi/agent/(設定・認証情報・セッション・パッケージ)は残ります。再インストールすればそのまま復帰します。

3. 初回起動と認証

作業するプロジェクトのディレクトリに移動して pi を起動します。初回は認証を求められます。

方法1: サブスクリプションログイン(/login)

pi
/login   # プロバイダを選択

対応しているサブスクリプションは次の3つです。

  • Anthropic Claude Pro/Max
  • OpenAI ChatGPT Plus/Pro(Codex)
  • GitHub Copilot

方法2: APIキー

export ANTHROPIC_API_KEY=sk-ant-...
pi

APIキー対応プロバイダは30以上(Anthropic、OpenAI、DeepSeek、Google Gemini、Bedrock、Groq、Cerebras、OpenRouter、xAI、Mistralなど)あります。/loginから選択すると ~/.pi/agent/auth.json に保存されます。

認証が終わったら:

  • /model(またはCtrl+L)でモデルを切り替え
  • Shift+Tab でthinkingレベル(off〜max)を切り替え

4. 設定ファイルの構造

piの設定はJSONファイルで、グローバルとプロジェクトの2段構造です。

~/.pi/agent/                  # グローバル(全プロジェクト)
├── settings.json             # デフォルトモデル・テーマ・パッケージ等
├── models.json               # カスタムプロバイダ(vLLM・Ollama等)
├── auth.json                 # /login の認証情報
├── trust.json                # プロジェクトの信頼決定
├── keybindings.json          # キーバインド
├── AGENTS.md                 # グローバルなコンテキストファイル
├── SYSTEM.md                 # (任意)システムプロンプトの置き換え
├── sessions/                 # セッション(JSONL、作業ディレクトリごとに整理)
├── extensions/               # グローバルExtension(TypeScript)
├── skills/                   # グローバルSkill
├── prompts/                  # プロンプトテンプレート
├── themes/                   # テーマ
├── npm/                      # npmで入れたPi Package
└── git/                      # gitで入れたPi Package

.pi/                          # プロジェクトローカル(グローバルを上書き)
├── settings.json
├── extensions/
├── skills/
└── prompts/

settings.json の実例(本機のものです)。

{
  "defaultProvider": "vllm-local",
  "defaultModel": "claude-opus-5",
  "defaultThinkingLevel": "xhigh",
  "theme": "dark",
  "packages": [
    "npm:pi-hermes-memory",
    "npm:pi-subagents",
    "npm:@juanibiapina/pi-powerbar",
    "npm:pi-plan",
    "npm:pi-mcp-adapter",
    "npm:pi-multimodal-proxy"
  ]
}

大半の項目は /settings のUIからJSONを触らずに変更できます。

4.1 ローカルLLM(vLLM)の接続

本記事の中核です。piは30以上のプロバイダを内蔵していますが、ローカルサーバー(vLLM、Ollama、LM Studioなど)を繋ぐ場合は ~/.pi/agent/models.json を書くだけです。本機で使用している設定をそのまま示します。

{
  "providers": {
    "vllm-local": {
      "baseUrl": "http://127.0.0.1:8000/v1",
      "api": "openai-responses",
      "apiKey": "sk-dummy",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false,
        "supportsStrictMode": false
      },
      "models": [
        {
          "id": "claude-opus-5",
          "name": "Claude Opus 5 (4090x4)",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 114688,
          "maxTokens": 16384,
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
          "samplingParams": { "temperature": 1.0, "top_p": 0.95, "top_k": 64 }
        }
      ]
    }
  }
}

ポイントは次の通りです。

  • api は openai-responses / openai-completions / anthropic-messages などから選びます。vLLMはOpenAI互換なので openai-responses か openai-completions が使えます
  • 認証不要のローカルサーバーでも apiKey にダミー値を入れておきます。鍵が一切無いとモデルが /model に現れないためです
  • compat はOpenAI互換サーバーとの相性調整です。developerロールや reasoning_effort を理解しないvLLMサーバーに対しては false にします
  • contextWindow はvLLM側の実コンテキスト(本機では前回記事の設定から余裕を持たせた値)に合わせます
  • models.json は /model を開くたびに再読込されます。セッション中に編集しても再起動不要です

4.2 コンテキストファイル(AGENTS.md)

piは起動時に AGENTS.md(または CLAUDE.md)を以下の場所から読み込み、すべて連結します。

  1. ~/.pi/agent/AGENTS.md(グローバル)
  2. 現在ディレクトリの各親ディレクトリ
  3. 現在ディレクトリ

プロジェクトの規約、テストの叩き方、命名規則などを書き置きしておくと、それがシステムプロンプトに追記されます。AGENTS.override.md があると、そのディレクトリの AGENTS.md を置き換えます。

システムプロンプトそのものを差し替えたい場合は .pi/SYSTEM.md(プロジェクト)または ~/.pi/agent/SYSTEM.md(グローバル)を置き、追記だけで済ませたい場合は APPEND_SYSTEM.md を使います。

5. インタラクティブモード

画面は上から、ヘッダー(ショートカット情報・読み込んだAGENTS.md・拡張一覧)→ メッセージ → エディタ → フッター(cwd・トークン使用量・コスト・コンテキスト使用率・現在モデル)の構成です。

5.1 エディタの便利機能

機能 やり方
ファイル参照 @ を入力するとプロジェクト内ファイルをファジ検索
パス補完 Tab
複数行入力 Shift+Enter
外部エディタ Ctrl+G($VISUAL / $EDITOR)
画像貼り付け Ctrl+V、またはターミナルへのドラッグ&ドロップ
コマンド実行して結果をモデルに渡す !ls -la
コマンドを実行だけ(モデルに渡さない) !!ls -la

5.2 よく使うコマンド

エディタに / を入力すると補完が出ます。

コマンド 説明
/login / /logout 認証情報の管理
/model モデルの切り替え
/settings thinkingレベル・テーマ等の設定
/new / /resume 新規セッション / 過去のセッションから選択
/tree セッションツリーを表示し、任意の時点から再開
/compact [指示] コンテキストをまとめて圧縮
/fork / /clone 過去のユーザーメッセージから新セッション / 現在の分岐を複製
/copy / /export [file] 最終メッセージのクリップボードコピー / HTML・JSONL書き出し
/share 非公開GitHub gistとして共有リンクを作る
/reload 拡張・スキル・テーマ等を再読み込み
/hotkeys 全キーバインドを表示
/changelog バージョン履歴

5.3 よく使うキーバインド

キー 動作
Ctrl+C エディタをクリア(2回押すと終了)
Escape 中断(2回押すと /tree)
Ctrl+L モデル選択
Shift+Tab thinkingレベルの切り替え
Ctrl+O ツール出力の折りたたみ・展開
Ctrl+T 思考ブロックの折りたたみ・展開
Ctrl+X 最後のメッセージをコピー

5.4 メッセージキュー(steering)

piが作業中にもメッセージをキューイングできます。

  • Enter: steering。現在のツール呼び出しが終わった直後に投下
  • Alt+Enter: follow-up。piが全部の仕事が終わった後に投下
  • Escape: 中断。キュー中のメッセージはエディタに戻す
  • Alt+Up: キュー中のメッセージをエディタに回収

「今の処理の途中で、あれ、こっちの方がいいな」と差し込めるのが実用上効いてきます。

6. セッション管理

セッションはJSONLファイルのツリー構造として ~/.pi/agent/sessions/ に作業ディレクトリごとに自動保存されます。1つのファイルに全履歴・全分岐が入ります。

pi -c               # 直前のセッションを継続
pi -r               # 過去のセッションから選んで再開
pi --no-session     # 一時的(保存しない)
pi --name "タスク名" # セッション名を付ける
  • /tree — 履歴の任意の時点に飛び、そこから継続する。分岐同士の移動も可能
  • /fork — 過去のユーザーメッセージから新しいセッションファイルを作る。プロンプトを編集して再提出できる
  • /clone — 現在の分岐を新しいセッションファイルに複製
  • /compact [指示] — 古いメッセージを要約してコンテキストを圧縮。既定では自動compactも有効で、コンテキスト溢れ時は自動で復旧・リトライします
  #1 ユーザー: 認証バグを直して
  │
  #2 アシスタント: 調査中…
  │
  #3 ユーザー: 方針Aで
  ├── (分岐A) #4: 方針Aで実装…
  │
  └── (分岐B: /treeで#3から継続) #4': 方針Bで実装…

注意として、compactはlossy(情報を失う)です。ただし完全な履歴はJSONLに残り続け、/tree でいつでも戻れます。

7. 非対話・プログラマティックな使い方

# ワンショット
pi -p "このリポジトリの構造を要約して"

# stdinからパイプ
cat README.md | pi -p "この内容を要約して"

# 読み取り専用モード(レビュー用途)
pi --tools read,grep,find,ls -p "コードをレビューして"

TypeScript SDKでも同じセッションエンジンを使えます。

import { createAgentSession, ModelRuntime, SessionManager } from "@earendil-works/pi-coding-agent";

const modelRuntime = await ModelRuntime.create();
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  modelRuntime,
});

await session.prompt("カレントディレクトリに何が あるか教えて");

piを土台に自作ツールを作るならSDK、別言語から組み込むならRPCモード(LF区切りJSONLプロトコル)が入口になります。

8. 拡張機構

piの拡張機構は5つあります。

機構 形式 役割
Extension TypeScript カスタムツール・コマンド・UI・イベントフック
Skill Markdown(SKILL.md) 再利用可能な手順書。必要時にロード
Prompt Template Markdown /名前 で展開される再利用プロンプト
Theme JSON TUIの外観
Pi Package npm / git 上記をバンドルして配布する単位

8.1 Extension

ExtensionはTypeScriptモジュールです。

export default function (pi: ExtensionAPI) {
  pi.registerTool({ name: "deploy", /* ... */ });
  pi.registerCommand("stats", { /* ... */ });
  pi.on("tool_call", async (event, ctx) => { /* ... */ });
}

これだけで次のようなことが可能です。

  • カスタムツールの追加(内蔵ツールの差し替えも可)
  • サブエージェント・プランモードの実装
  • 権限ゲート(rm -rf や sudo 前の確認ダイアログ)
  • パス保護(.env 等への書き込みブロック)
  • 独自のcompact(要約ロジックの差し替え)
  • ステータスバー・カスタムフッター
  • Gitチェックポイント・自動コミット
  • 待ち時間のゲーム(Doomが動きます)

配置場所は ~/.pi/agent/extensions/(グローバル)または .pi/extensions/(プロジェクト)。配置すれば /reload でホットリロードされます。公式リポジトリの examples/extensions/ に30個以上の動くサンプル(git-checkpoint.ts、confirm-destructive.ts、custom-compaction.ts、doom-overlay/ など)があります。

最大のポイントは、Extensionをpi自身に書いてもらうのが正規ルートである、ことです。公式ドキュメントの書き出しが「piにpiパッケージを作らせればいい」です。「コミット前に確認する拡張を作って」と言えば、ドキュメントを読んで書いてくれます。

8.2 Skill

Skillは Agent Skills 準拠のMarkdownです。

<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
# My Skill
ユーザーがXを尋ねたときに使う。

## 手順
1. これをする
2. 次にあれをする

/skill:my-skill で明示的に呼び出せますが、agentが状況を見て自動でロードすることも多いです。「毎回同じ手順を踏む作業」を教えるのに使います。

8.3 Prompt Template

<!-- ~/.pi/agent/prompts/review.md -->
このコードのバグ・セキュリティ・性能問題をレビューして。
特に注目: {{focus}}

/review と入力すると {{focus}} を含めて展開されます。

8.4 Theme

内蔵は dark / light。JSONで色定義し直せば ~/.pi/agent/themes/ 等に置けます。ファイルを変更すると即座に反映されます。

8.5 Pi Package

Extension・Skill・Prompt・Themeをまとめてnpmやgitで配布する単位です。

pi install npm:pi-subagents
pi install npm:@foo/pi-tools@1.2.3    # バージョン固定
pi install git:github.com/user/repo@v1
pi list
pi update --all      # pi本体とパッケージをまとめて更新
pi update --models   # モデルカタログだけ更新
pi config            # パッケージの各リソースの有効/無効

-l を付けるとプロジェクトローカル(.pi/)にインストールされ、リポジトリにコミットすればチームで共有できます。インストールせずに一時的に試す場合は pi -e npm:pi-subagents のように -e で指定できます。

セキュリティ: Piパッケージはフルシステムアクセスで実行されます。Extensionは任意コードを実行し、Skillは実行可能ファイルの実行を含むあらゆる行動をモデルに指示し得ます。サードパーティパッケージは必ずソースを確認してからインストールしてください。

パッケージの検索は npm(keywords: pi-package) か公式Discordが定番です。

9. この環境で入れているプラグイン

本機の settings.json で有効なパッケージは6つです。

{
  "packages": [
    "npm:pi-hermes-memory",
    "npm:pi-subagents",
    "npm:@juanibiapina/pi-powerbar",
    "npm:pi-plan",
    "npm:pi-mcp-adapter",
    "npm:pi-multimodal-proxy"
  ]
}
パッケージ 役割 使う場面
pi-subagents 子エージェントへの委譲。scout(コードベース調査)・researcher(リサーチ)・worker(実装)・reviewer(レビュー)等の組み込みエージェントあり。並列実行・背景実行・ワークフローScriptも可 コードレビュー、第二意見、複数観点の並列監査
pi-hermes-memory 永続メモリ+セッション全文検索(SQLite FTS5)+失敗記憶+手続き型スキル 「先週認証の件、何で合意したっけ?」をagent自身に聞けるようにする
pi-plan プランモード(/plan)。計画中は読み取り専用ツールしか使えず、承認後に実行 大きな変更で「まず全体像を固めてから触らせたい」場合
pi-mcp-adapter MCPサーバーを文脈を食わずに使えるようにする。オンデマンドでツール発見 既存のMCPサーバー(DB・ブラウザ等)をpiで使いたい場合
@juanibiapina/pi-powerbar tmux風のpowerlineステータスバー(gitブランチ・トークン使用量・コンテキスト進行バー等) 状態を常時見たい場合
pi-multimodal-proxy 画像・動画・音声をビジュアルモデルにルーティングしてテキスト化し、文脈に注入 テキストモデル(ローカルモデル含む)に画像を見せたい場合

補足として3点あります。

  1. piはMCPを標準で持ちません。 著者は「MCPはそもそも要らない(bashツールで代用できる)」という記事を書いていますが、pi-mcp-adapter が入れば既存エコシステムも文脈ブloatなしで使えます
  2. サブエージェントもプランモードも同様にデフォルトには無く、pi-subagents や pi-plan で補完します。「最小コア+不足分をパッケージで足す」構成が実運用として成立している例です
  3. 本環境では特に pi-hermes-memory が効いています。過去のセッションをインデックスし、跨いで「前回どうなった?」を聞けるようになったのが大きい

10. piの学習経路

効果が大きい順に並べます。

  1. 公式リポジトリのREADMEとdocs — earendil-works/pi の packages/coding-agent/README.md が最良の概要です。docs/ には extensions.md、sessions.md、sdk.md、rpc.md、custom-provider.md 等の25ページ以上あります。npmパッケージには docs/ と examples/ が同梱されているので、ネットワークが制限された環境でもオフラインで読めます(本環境もそうでした)

    ls /usr/local/lib/nodejs/node-v24.9.0-linux-x64/lib/node_modules/@earendil-works/pi-coding-agent/docs
    
  2. pi.dev と公式Discord — pi.dev は情報源の集約地です。質問や新パッケージの共有は Discord が最速です

  3. 著者(Mario Zechner)のブログ — piの設計思想がここにあります

  4. examples/extensions/ — 動くExtensionのサンプル集です。APIの使い方を知るならここを読むのが早い

  5. pi自身に聞く — 「このケース用Extensionを書いて」「このpiパッケージを作れ」と頼むのが正規の手順です。生成されたコードを読むのが勉強になります

  6. OSSセッションの共有・閲覧 — 公開OSSリポジトリでpiを使う場合は badlogic/pi-share-hf で自分のセッションをHugging Faceに公開できます。著者自身がpi-monoでの作業セッションを定期的に公開しており、読むのも学習方法です

起動時のヘッダーは読み込んだAGENTS.md・拡張・スキルの一覧を表示するので、まずここを見ると「今何が載っているか」が一目で分かります。ショートカット一覧は /hotkeys で確認できます。

11. 注意点

セキュリティ

  • Piパッケージは任意コードとして実行されます。インストール前にソースを確認してください
  • piは実行ユーザーの全権限で動きます。気になる場合はコンテナに入れてください(公式に docs/containerization.md あり)
  • プロジェクト信頼(project trust): プロジェクトローカル設定・拡張を持つディレクトリで初めてpiを起動すると信頼するかの質問が出ます。決定は trust.json に保存されます。CI等の非対話実行では --approve / --no-approve で制御します

バージョン

  • piは更新が速いです。/changelog で差分確認、pi update --self で本体更新
  • npm:pkg@1.2.3 のようにバージョンを固定したパッケージは pi update --extensions では移動しません。動かしたい場合は pi install npm:pkg@new-version で再固定します
  • 執筆時点での互換関係(pi 0.84.2 / Node 24.9.0 / 上記パッケージ群)で確認しています

ローカルモデルを使う場合

  • defaultThinkingLevel は品質オプションというより メモリ設計の一部 です(前回記事の reasoning_effort 議論の続き)。大きなコンテキストを使うローカル構成ではレベルの調整が速度・メモリに直結します
  • OpenAI互換サーバーで developer ロールや reasoning_effort が通らない場合は models.json の compat で無効化してください
  • vLLMの --max-model-len に対して contextWindow をそのまま書くと実運用で詰まることがあります。頭余白を持たせてください

ネットワーク動作

  • 起動時にpi.devへバージョンチェック、初回インストール後に匿名のバージョン報告が送られます。PI_TELEMETRY=0 で無効化、PI_SKIP_VERSION_CHECK=1 でバージョンチェック停止、--offline / PI_OFFLINE=1 で起動時ネットワーク操作を全部切れます

12. まとめ

  • piはearendil-works製の「最小限のターミナルCoding Agent」です。デフォルトツールは read / write / edit / bash の4つで、サブエージェント・プランモード・MCP・todoは 最初から無い ことを設計思想として持っています
  • npm install -g --ignore-scripts @earendil-works/pi-coding-agent(Node 22.19以上)で入ります
  • ~/.pi/agent/models.json に数行書けばvLLM・Ollama等のローカルLLMが使えるようになります。編集後は /model を開くだけで反映
  • セッションはJSONLのツリーで、/tree で任意の時点に飛べます。compactはlossyですが全履歴はファイルに残ります
  • 拡張機構は Extension(TypeScript)/ Skill / Prompt Template / Theme / Pi Package の5つ。不足機能はすべてこの5つで補完します
  • プラグインは pi-subagents(委譲)・pi-plan(プラン)・pi-mcp-adapter(MCP)・pi-hermes-memory(記憶)の組み合わせが最初の導入におすすめです
  • 学習経路は 公式docs(npmパッケージに同梱・オフライン読込可)→ examples/ → 著者のブログ → Discord → pi自身に書いてもらう、の順で回せます

本記事で使ったローカルモデルは、前回記事の4090×4マシン(vLLM/Docker)が提供しているものです。「ローカルで十分高性能なモデル × 最小のコアに好きな拡張を足すagent」の組み合わせは、API課金なし・データがマシン外に出ない、という点でローカルLLMを持つ人に向いていると思います。

参考リンク

2
5
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
2
5

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?