プラグイン

Preview docs describe unreleased preview builds. Stable docs remain at /docs/.

Nagi プラグインは、共有可能で実行可能なワークフローパッケージです。マニフェスト v2 プラグインは Nagi がホストする WebAssembly コンポーネントです。従来のプラグインは Bash スクリプト、JavaScript アプリ、Lua スクリプト、Rust バイナリ、その他マシンで 実行できる任意の argv コマンドにできます。Nagi はホスト側の面を担います: インストール、マニフェスト検証、キーバインド、ターミナルペイン、イベント、 呼び出しコンテキスト、ソケットアクセスです。プラグインは自分の実装言語、依存関係、 ファイル、永続状態を担います。

プラグインは Nagi を軽量に保つために存在します。コアはターミナルワークスペース、 ペイン、エージェント、安定した CLI/ソケット API に集中し続けます。プラグインは その既存の拡張面を、あらゆるワークフローを Nagi 本体に追加することなく、 誰もが作成・インストール・共有できる再利用可能なワークフローに変えます。

プラグインは SDK インテグレーションではありません。nagi-plugin.toml マニフェストと、Nagi が起動できるコマンドを持つディレクトリです。Nagi は マニフェストを検証し、ランタイムコンテキストを注入し、宣言されたコマンドを起動し、 ログを記録します。コマンドはさらに作業が必要なときに、CLI またはソケット経由で Nagi を呼び出します。

従来のネイティブプラグインに、独立した SDK や制限付きコマンドセットはありません。Nagi CLI 全体が プラグイン API です: CLI リファレンスのすべてのコマンドを プラグインから使えます。自分で nagi ... として実行できるものは、プラグインも 実行できます。ほとんどのプラグインは、実行中の Nagi バイナリを指す NAGI_BIN_PATH を通じて Nagi を呼び出すべきです。これにより、Unix ソケットと Windows 名前付きパイプの両方でプラグインの移植性が保たれます。生の JSON リクエストを 自分で送りたいときはソケット APIを使ってください。

ランタイムでのアクション登録と、ターミナル以外のネイティブなプラグイン UI は プラグイン v1 の範囲外です。アクション、イベントフック、ペイン、リンクハンドラーは すべてマニフェストで宣言します。

信頼とセキュリティ

マニフェスト v2 コンポーネントは、WASI Component Model を使って Wasmtime 内で 実行されます。Nagi はコンポーネントサイズ、リニアメモリ、テーブル、インスタンス、 出力、fuel、実行時間を制限します。ホスト環境、ファイルシステム、ネットワークアクセスは 継承しません。capability を要求するコンポーネントは、有効化の前に nagi plugin approve <id> が必要です。承認はプラグインのバージョン、マニフェストと パッケージのチェックサムに結び付けられます。変更後は再審査が必要です。 nagi plugin revoke <id> は承認を取り消し、プラグインを無効化します。

承認されても、未実装のホスト API が自動的に追加されることはありません。ブローカーとの バインディングがない capability は利用できず、新しい権限はデフォルトで閉じた状態を保ちます。

ネイティブプラグインはあなたのマシンで動く普通のコードです。インストールまたはリンクすると、 そのビルドコマンドとランタイムコマンドはあなたのユーザーとして、あなたの環境で 実行され、Nagi CLI 全体を呼び出せます — エディタ、シェル、コーディングエージェントに 追加する拡張機能と同じです。

信頼できる作者とリポジトリからプラグインをインストールし、新しいプラグインが 何をするのか先に目を通してください: nagi-plugin.toml マニフェストと、実行される スクリプトやバイナリです。nagi plugin install はソース、リビジョン、ビルドコマンド、 無制限アクセスの警告を表示します。非対話インストールでは --yes と --trust-native の両方が必要です。ローカルリンクは nagi plugin link <path> --trust-native を使います。特定のリビジョンが欲しいときは --ref で固定してください。

Nagi はマニフェストを検証し、明示的な信頼ゲートを要求し、継承環境を消去し、各プラグインの 設定と状態を専用ディレクトリに保ちます。ネイティブプラグイン自体はサンドボックス化されません。 古いレジストリエントリは、無効かつ未信頼の状態へ移行します。

マニフェスト v2: サンドボックス化コンポーネント

manifest_version = 2
id = "example.review"
name = "Review current mission"
version = "1.0.0"
min_nagi_version = "0.7.4"
runtime = "wasi-component"
entrypoint = "plugin.wasm"
capabilities = []

[[contributions.commands]]
id = "review"
title = "Review current mission"
contexts = ["mission"]

capability を持たないコンポーネントは nagi plugin link ./example-review でリンクできます。 capability を要求する場合は、ソースを確認してから次を実行します:

nagi plugin approve example.review
nagi plugin enable example.review

従来のマニフェスト: 信頼済みネイティブ

マニフェストは Nagi とプラグインの間の契約です。パッケージのメタデータ、対応 プラットフォーム、任意のビルドコマンド、Nagi が実行できるエントリーポイントを 宣言します。

id = "example.layout"
name = "Layout"
version = "0.1.0"
min_nagi_version = "0.7.0"
description = "Apply project layouts"
platforms = ["linux", "macos", "windows"]

[[build]]
command = ["npm", "ci"]

[[build]]
command = ["npm", "run", "build"]
platforms = ["linux", "macos"]

[[actions]]
id = "apply"
title = "Apply layout"
contexts = ["workspace"]
command = ["node", "dist/apply.js"]

[[events]]
on = "worktree.created"
command = ["nagi", "workspace", "list"]

[[panes]]
id = "board"
title = "Project board"
placement = "overlay"
command = ["nagi-board"]

[[link_handlers]]
id = "github-issue"
title = "Open GitHub issue"
pattern = "^https://github\\.com/[^/]+/[^/]+/(issues|pull)/[0-9]+$"
action = "apply"

トップレベルの id、name、version、min_nagi_version は必須です。 min_nagi_version には、プラグインが使うプラグイン API、イベント名、 マニフェストフィールドをサポートする最も古い Nagi バージョンを設定してください。 プラグインの最低バージョンが現在のバイナリより新しい場合、Nagi はリンクや インストールを拒否します。description は任意です。プラグイン id には ASCII の 英字、数字、ドット、コロン、アンダースコア、ハイフンが使えます。

アクション id、ペイン id、リンクハンドラー id はプラグイン内部のローカル id です。 ASCII の英字、数字、コロン、アンダースコア、ハイフンが使えますが、ドットは 使えません。各 id の種類はプラグイン内で一意でなければなりません。グローバルに 一意な名前が必要なとき、Nagi はアクション id を plugin.id.action の形に修飾します。

プラグインが動作する場所は platforms = ["linux", "macos", "windows"] で宣言します。 ビルドコマンド、アクション、イベントフック、ペイン、リンクハンドラーも独自の platforms を宣言でき、項目レベルの platforms はトップレベルのリストを 上書きします。トップレベルの platforms がないローカルプラグインは警告付きで リンクされます。

command の値は argv 配列です。Nagi はこれをシェル経由で実行しないため、 コマンド自身がシェルを起動しない限りシェル展開はありません。言語固有の挙動は スクリプトやバイナリの側に置いてください。

最初のプラグイン

nagi-plugin.toml と実行可能なスクリプトまたはプログラムをひとつ含む ディレクトリから始めます:

my-plugin/
  nagi-plugin.toml
  index.js

id = "example.workspace-tools"
name = "Workspace Tools"
version = "0.1.0"
min_nagi_version = "0.7.0"
description = "Small workspace helpers"
platforms = ["linux", "macos", "windows"]

[[actions]]
id = "list-workspaces"
title = "List workspaces"
contexts = ["workspace"]
command = ["node", "index.js"]

コマンドの中からは NAGI_BIN_PATH で Nagi を呼び出します:

const { spawnSync } = require("node:child_process");

const nagi = process.env.NAGI_BIN_PATH ?? "nagi";
const result = spawnSync(nagi, ["workspace", "list"], {
  encoding: "utf8",
  stdio: ["ignore", "pipe", "pipe"],
});

process.stdout.write(result.stdout);
process.stderr.write(result.stderr);
process.exit(result.status ?? 1);

この例は Node を使っていますが、プラグインに Node は必須ではありません。 マニフェストは Bash、PowerShell、Python、Rust、Go、Lua、Bun など、ユーザーの マシンで使える任意のコマンドを起動できます。

インストールとリンク

サンプルプラグインをインストールします:

nagi plugin install owner/nagi-plugin/agent-telegram-notify
nagi plugin config-dir examples.agent-telegram-notify
nagi plugin list
nagi plugin action list --plugin examples.agent-telegram-notify

ローカルでプラグインを作成しているときは、代わりに作業ディレクトリをリンクします:

nagi plugin link /path/to/plugin
nagi plugin config-dir example.layout
nagi plugin action list --plugin example.layout
nagi plugin action invoke example.layout.apply
nagi plugin pane open --plugin example.layout --entrypoint board
nagi plugin log list --plugin example.layout

plugin install は owner/repo/subdir のような GitHub 省略記法のみを受け付けます。 git でクローンし、対話的なターミナルではプレビューを表示し、サポートされる ビルドコマンドを実行し、チェックアウトを Nagi 管理のプラグインデータの下に保存して 登録します。非対話的なインストールには --yes を使ってください。GitHub 管理の プラグインを再インストールすると、その管理チェックアウトが置き換えられます。 ローカルにリンクされたプラグインへの上書きインストールは拒否されます。先に ローカルプラグインを unlink または uninstall してください。plugin install と plugin link はプラグインの設定・状態ディレクトリを作成し、 plugin config-dir <id> はセットアップドキュメントやシェルスクリプト向けに 設定ディレクトリを表示します。

plugin uninstall <id-or-source> はプラグインの登録を解除します。GitHub 管理の インストールでは管理チェックアウトも削除し、プラグイン id と、install で使うのと 同じ owner/repo[/subdir...] 省略記法の両方を受け付けます。plugin unlink <id> は 登録解除のみを行いファイルには触れないため、ローカル開発に便利です。v1 に独立した plugin update はありません。管理プラグインを更新するには GitHub から 再インストールしてください。

サンプル集のリポジトリは owner/nagi-plugin です。 agent-telegram-notify、github-link-preview、dev-layout-bootstrap を含む 独立したサンプルプラグインがサブディレクトリに入っています。これらはコピーする ためのサンプルであり、メンテナンスされる公式プラグインではありません。

ビルドコマンド

ビルドコマンドは GitHub からの plugin install 中、確認の後、Nagi がプラグインを 登録する前に実行されます。ビルドコマンドが失敗するとインストールは中止され、 プラグインは登録されません。plugin link はビルドコマンドを実行しません。 ローカルの作者は自分で作業ツリーをビルドします。ビルドコマンドはファイルを生成して 構いませんが、インストールプレビュー後に nagi-plugin.toml を変更すると インストールは中止されます。ビルド失敗時には、プラグイン id、ビルドのインデックス、 作業ディレクトリ、コマンド、終了ステータスまたは spawn エラー、上限付きの stdout/stderr が、ツールの出力を解釈せずに表示されます。

ビルドコマンドも素の argv コマンドですが、ランタイムのプラグインコンテキストや Nagi のソケット環境変数は受け取りません。プラグインの作者は cargo、npm、 bun、lua といった必要なシステムツールをドキュメントに書いてください。Nagi は ビルドの失敗を報告しますが、足りないツールチェーンをインストールすることはありません。

コマンドと環境

ランタイムコマンドは、プラグインディレクトリを作業ディレクトリとして実行されます。 Nagi は NAGI_SOCKET_PATH、NAGI_BIN_PATH、NAGI_ENV=1、 NAGI_PLUGIN_ID、NAGI_PLUGIN_ROOT、NAGI_PLUGIN_CONFIG_DIR、 NAGI_PLUGIN_STATE_DIR、NAGI_PLUGIN_CONTEXT_JSON、そして利用可能なら NAGI_WORKSPACE_ID、NAGI_TAB_ID、NAGI_PANE_ID を注入します。アクション コマンドは加えて NAGI_PLUGIN_ACTION_ID を受け取ります。イベントフックは NAGI_PLUGIN_EVENT と NAGI_PLUGIN_EVENT_JSON を、ペインコマンドは NAGI_PLUGIN_ENTRYPOINT_ID を受け取ります。

NAGI_PLUGIN_ROOT は、インストールまたはリンクされたプラグインディレクトリです。 GitHub からインストールされたプラグインのルートは管理されたソースチェックアウト なので、そこにユーザーの認証情報や永続状態を保存しないでください。.env ファイルの ようなユーザーが編集する設定は NAGI_PLUGIN_CONFIG_DIR の下に、ローカルの ランタイム状態は NAGI_PLUGIN_STATE_DIR の下に置いてください。Nagi はこれらの ディレクトリを作成し、レガシーなプラグイン設定の場所が存在すれば NAGI_PLUGIN_CONFIG_DIR に初期内容を移しますが、その中身の検証、同期、削除は しません。ファイル形式とライフサイクルはプラグインが所有します。

NAGI_PLUGIN_CONTEXT_JSON には、その呼び出しで利用可能な場合、ワークスペース、 タブ、フォーカス中のペイン、worktree、エージェント、選択テキスト、クリックされた URL、リンクハンドラーのフィールドが含まれます。シェルプラグインは、よく使う id は 個別の環境変数から読み、完全な形が必要ならコンテキスト JSON をパースできます。

Node、PowerShell、Bash など別のランタイムから移植性を保って Nagi を呼び出す必要が あるときは NAGI_BIN_PATH を使ってください。NAGI_SOCKET_PATH の背後にある生の ソケットトランスポートは OS 固有です: Unix クライアントは Unix ソケットパスに、 Windows クライアントは名前付きパイプに接続します。NAGI_BIN_PATH を通じた CLI 呼び出しなら、そのトランスポートの違いを気にせずに済みます。利用可能なコマンドは CLI リファレンス、生のリクエスト形式は ソケット APIを参照してください。

ペイン

マニフェストのペイン placement のデフォルトは overlay で、アクティブなペインの 上に一時的なズームオーバーレイを開き、閉じるときに以前のフォーカスとズームを 復元します。plugin.pane.open リクエストは、マニフェストの placement を overlay、popup、split、tab、zoomed で上書きできます。

placement = "popup" は、タイルレイアウトを変更せずにセッションモーダルなターミナルポップアップを開きます。 マニフェストまたは open リクエストで任意の width と height を指定できます。 省略するとデフォルトの半分のサイズになり、数値なら外側のターミナルセル数、"80%" のような文字列ならターミナル領域に対する割合になります。 Escape を含むすべてのターミナル入力を受け取り、コマンドが終了するか popup.close リクエストが送られると閉じます。 最小サイズより小さい寸法は最小値に制限されます。

ペインを常に一時的にしたい場合は、プラグインペインのエントリーポイントに placement を直接宣言します:

[[panes]]
id = "picker"
title = "Picker"
platforms = ["linux", "macos"]
placement = "popup"
width = "80%"
height = 20
command = ["sh", "picker.sh"]

split、tab、zoomed、overlay のプラグインペインは、開いた後は通常の Nagi ペインです。プラグインはソケットや CLI を 通じて pane.move、pane.swap、pane.resize、pane.zoom といった標準のペイン API を呼び出せます。ペインがタブやワークスペースをまたいで移動しても、Nagi は プラグインペインの所有権を元のペインに結び付けたまま維持します。 ポップアップは Nagi ペインではなく、セッションに 1 つだけ存在できるリソースです。 ペイン id を持たず、プラグインのフォーカスコンテキストを変更せず、ペインのライフサイクルイベントを発行せず、pane、layout、永続化、エージェント API に参加しません。 そのプロセスには NAGI_PANE_ID が渡されず、背後のタイルペインは NAGI_PLUGIN_CONTEXT_JSON から参照できます。 Settings、コピーモード、または別の Nagi モーダルが開いている間にポップアップを開くと ui_busy が返り、起動後の plugin.pane.open は ok を返します。

Windows では、ビルドコマンド、アクションコマンド、イベントコマンドは、素の コマンドが PATH にあれば npm.cmd、bun.cmd、pnpm.cmd のような一般的な PATHEXT shim を解決します。ペインコマンドは Nagi の通常の Windows ペイン ランチャーを使うため、引き続き有効な Windows の argv コマンドでなければなりません。

キーバインド

インストール済みプラグインのアクションにキーを割り当てます:

[[keys.command]]
key = "prefix+l"
type = "plugin_action"
command = "example.layout.apply"
description = "apply layout"

リンクハンドラー

[[link_handlers]] を使うと、マッチしたターミナル URL への修飾キー付きクリックを、 ブラウザで URL を開く代わりにプラグインのアクションにルーティングできます。 修飾キー付きクリックの修飾キーは macOS を含むすべてのプラットフォームで Control です。キャプチャされたターミナルのマウスレポートは、Command/Super を通常のクリックと 区別して伝えないからです。pattern はクリックされた URL に対してマッチする Rust の 正規表現で、action には同じプラグインが宣言したアクション名を指定します。リンク ハンドラーのアクションは NAGI_PLUGIN_CONTEXT_JSON で invocation_source = "link_click"、clicked_url、link_handler_id を受け取ります。 シェルプラグインは NAGI_PLUGIN_CLICKED_URL と NAGI_PLUGIN_LINK_HANDLER_ID も 読めます。ハンドラーは各プラグイン内でマニフェストの順にチェックされます。

ストレージ

v1 には Nagi が管理するプラグインストレージ API はありません。永続状態が必要な プラグインは、自分のファイルやデータベースを持ってください。

マーケットプレイス

公開レジストリは計画中で、まだプラグインを掲載していません。GitHub からの 直接インストールとローカルリンクは利用できるため、作者は nagi-plugin.toml を含むリポジトリを公開し、nagi plugin install owner/repo[/subdir] を共有できます。

現在、nagi-plugin トピックを追加しても掲載は作成されません。現在の境界と 公開準備はマーケットプレイスを参照してください。