Skip to main content
ツールと拡張機能

Plugins

options.plugins を使用して、ローカルプラグインディレクトリを現在のセッションに読み込みます。SDK は各ローカルプラグインを --plugin-dir <path> 起動パラメータに変換します。プラグインに含まれる commands、agents、skills、MCP servers はすべて今回のセッションの機能発見の対象になります。

ローカルプラグインの読み込み

import { query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'List the commands and agents contributed by the current plugins',
  options: {
    plugins: [
      { type: 'local', path: '/path/to/my-plugin' },
    ],
  },
});

const init = await q.initializationResult();
console.log(init.commands);
console.log(init.agents);
console.log(init.skills);

const plugins = await q.listPlugins();
console.log(plugins);
複数のローカルプラグインを同時に渡すことができ、その順序で複数回 --plugin-dir が出力されます。 
const q = query({
  options: {
    plugins: [
      { type: 'local', path: '/path/to/plugin-a' },
      { type: 'local', path: '/path/to/plugin-b' },
    ],
  },
});
💡 Python では query() は単発のメッセージストリームで、ハンドシェイク後に init レスポンスを照会できません。プラグインが提供するコマンド / agent / skill を読むには、QoderSDKClient を使って connect() 後に get_server_info() を呼ぶか、メッセージストリームで SystemMessage(subtype='init') を捕捉して message.data を自分で読んでください。完全な plugin inventory は client.list_plugins() で取得します。

プラグインディレクトリレイアウト

ローカルプラグインは通常以下を含むことができます： 
my-plugin/
  .qoder-plugin/plugin.json
  commands/
  agents/
  skills/
  .mcp.json
.qoder-plugin/plugin.json はプラグイン名、バージョン、説明を宣言するために使用します。その他のディレクトリはファイルタイプに応じて CLI が自動的にスキャンします。 SDK はパスが存在するか / 妥当かを検証しません。
  • 存在しない --plugin-dir パスは SDK モードではサイレントに無視され、セッションは正常に初期化されます。
  • 破損したフロントマター / .mcp.json は init をブロックしません。破損したコマンドは init レスポンスに表示されません。
  • plugin のロード失敗を明示的に診断したい場合、現時点では リロード後の error_count が唯一のフォールバックです。

プラグインが提供する slash commands

プラグイン内の commands/*.md は初期化結果に現れ、名前は <plugin>:<cmd> の修飾形式になります： 
const commands = await q.supportedCommands();
console.log(commands.map((cmd) => cmd.name));

プラグインが提供する agents

プラグイン内の agents/*.md は初期化結果に現れます。SDK はこのリストを直接取得する簡便メソッドを提供します： 
const agents = await q.supportedAgents();
console.log(agents.map((agent) => agent.name));

プラグインが提供する skills

プラグイン内の skills/<name>/SKILL.md はプラグイン修飾名（plugin:skill）で登録されます。options.skills でメインセッションでのコンテキスト可視性と呼び出しポリシーを制御できます：修飾名を渡して特定 skill を有効化、'all' で発見済みすべてを有効化、省略で CLI デフォルトポリシー。Skills ドキュメント を参照してください。

プラグインが提供する MCP servers

プラグイン内の .mcp.json は CLI が起動し、MCP 状態に組み込まれます： 
const servers = await q.mcpServerStatus();
console.log(servers);

インストール済み同名プラグインの一時的な上書き

options.plugins で読み込まれたローカルプラグインはセッションスコープです。現在のセッション内で既にインストールされているプラグインと同名の場合、ローカルプラグインが今回のセッションの機能発見で優先されます。この機能はプラグインの開発、デバッグ、段階的検証に適しています。 
const q = query({
  options: {
    // The local version only takes effect for this query session and does not
    // touch the user's global install state.
    plugins: [{ type: 'local', path: './my-plugin-dev' }],
  },
});

実行中の Plugins リロード

plugin ディレクトリが変わった場合、同じセッション内で reloadPlugins() / reload_plugins() を呼ぶと、CLI が plugin リソースを再スキャンします。 
const refreshed = await q.reloadPlugins();

console.log(refreshed.commands);
console.log(refreshed.agents);
console.log(refreshed.plugins);
console.log(refreshed.mcpServers);
console.log(refreshed.error_count);
典型的な用途：
  • プラグイン開発時に commands/*.md を追加・削除した後のリフレッシュ。
  • ローカルプラグインのインストールまたは更新後、ホストアプリケーションを再起動せずに反映。
  • ホスト UI でリロード後の commands、agents、plugins、MCP 状態を表示する必要がある場合。
注意：Python では reload_plugins() は QoderSDKClient（streaming）モードでのみ意味を持ちます。単発の query() ストリームにはランタイム制御チャンネルがありません。

インストール済みプラグインの管理（TypeScript）

TypeScript SDK には、アクティブな query を作成せずにプラグインを検証、一覧表示、インストール、アンインストール、有効化、無効化するトップレベル関数があります。 
import {
  disablePlugin,
  enablePlugin,
  installPlugin,
  listPlugins,
  uninstallPlugin,
  validatePlugin,
} from '@qoder-ai/qoder-agent-sdk';

const cwd = '/path/to/project';
const pluginPath = '/path/to/project/my-plugin';
const report = await validatePlugin(pluginPath);
const plugins = await listPlugins({ cwd });

if (report.valid) {
  const installed = await installPlugin(pluginPath, {
    scope: 'project',
    cwd,
  });

  await disablePlugin(installed.pluginId, { scope: 'project', cwd });
  await enablePlugin(installed.pluginId, { scope: 'project', cwd });

  await uninstallPlugin(installed.pluginId, {
    scope: 'project',
    cwd,
    keepData: true,
  });
}
installPlugin() と uninstallPlugin() は user、project、local scope をサポートし、デフォルトは user です。project または local を使用する場合は、変更対象の workspace を特定するために cwd を渡してください。
Scope動作
user現在のユーザーのすべてのプロジェクトで利用可能。デフォルト値
projectcwd 配下のプロジェクト設定へ書き込み、バージョン管理へコミット可能
localcwd 配下のローカルプロジェクト設定へ書き込み、現在のマシンのみで利用
installPlugin() は { pluginId, version, path } を返します。uninstallPlugin() は { pluginId, fullyRemoved, reverseDependents } を返し、keepData: true を指定するとプラグインのデータディレクトリを保持します。 トップレベルの listPlugins() は、組み合わせた qodercli が報告するすべてのインストール項目を返します。CLI がプロジェクトパスを提供する場合、projectPath は project と local の行にのみ設定され、user およびその他の非プロジェクト行では省略されます。enabled は cwd での有効状態を表し、cwd を省略した場合は SDK プロセスの現在の作業ディレクトリが使われます。セッションメソッド q.listPlugins() は、そのセッションで実際に読み込まれたプラグインを返します。 これらの関数は、組み合わせた qodercli を通して処理を実行します。エラーには安定した code プロパティがあります。 すでにセッションが実行中の場合は、プラグインのインストール、アンインストール、有効化、無効化の後に q.reloadPlugins() を呼び出し、そのセッションへ変更を反映してください。

Options クイックリファレンス

フィールド（TypeScript / Python）説明
plugins / pluginsローカル plugin ディレクトリをロード。{ type: 'local', path } が一般的
settings / settingsCLI に透過する settings。enabledPlugins、pluginConfigs などを含められる
settingSources / setting_sourcesCLI が読む settings ソースを制御
settings.enabledPlugins でプラグインの有効状態を制御し、settings.pluginConfigs で MCP server 置換などのプラグイン設定を提供します。

戻り値リファレンス

初期化結果

initializationResult()（TypeScript）/ client.get_server_info()（Python）は、セッションで発見された commands、agents、skills などの初期化リソースを返します。安定した plugin inventory フィールドは含まれません。完全な戻り値型は SDK References を参照してください。 
{
    "commands": [
        {"name": "plugin-a:greet", "description": "...", "argumentHint": "..."},
        ...
    ],
    "agents": [
        {"name": "plugin-a:helper", "description": "...", "model": "sonnet"},
        ...
    ],
    "skills": [
        {"name": "plugin-a:echo", "description": "...", "source": "plugin"},
        ...
    ],
    # Also includes models / account / output_style and other fields
}

現在のセッションのプラグイン一覧

q.listPlugins(): Promise<PluginDetails[]>;
現在のセッションで実際に読み込まれた plugin 一覧と各 plugin のリソースサマリーを読み取ります。ホスト UI で現在のセッションの plugin inventory を表示する場合は、初期化結果の plugins フィールドではなくこのメソッドを使ってください。セッションを作成せずにインストール済み plugin を一覧表示するには、トップレベルの listPlugins() を使用します。 各項目は PluginDetails で、id、name、source、path、version、scope、enabled、canDisable と、skills、agents、mcpServers、commands、hooks に分類された resources の概要を含みます。

プラグインのリロード

reloadPlugins() / reload_plugins() の戻り値： 
type SDKControlReloadPluginsResponse = {
  commands: Array<{ name: string; description?: string; argumentHint?: string }>;
  agents: Array<{ name: string; description?: string }>;
  plugins: Array<{ name: string; path: string; source?: string }>;
  mcpServers: Array<Record<string, unknown>>;
  error_count: number;  // Number of plugins that failed to load in this reload
};

ベストプラクティス

  • 初期化リソースと plugin 一覧を区別する：発見済みの commands、agents、skills は初期化結果で表示し、q.listPlugins() / client.list_plugins() で現在のセッションの plugin inventory、トップレベルの listPlugins() でインストール済み plugin を表示します。初期化結果の skills は発見リストであり、メインセッションの呼び出し可能セットではありません。
  • プラグイン開発時は options.plugins を使用：現在のセッションにのみ影響し、ユーザーのグローバルインストール状態を変更する必要がありません。
  • リロード前にユーザーへの通知を用意する：リロードは CLI にディスク再スキャンをさせ、利用可能リソースのリストが一時的に変わる可能性があります。UI も同期して更新するのが望ましいです。
  • エラー診断には error_count を確認：リロード後に error_count > 0 の場合はプラグインリソースの読み込みに失敗があることを示しており、そのソースをユーザーに表示すべきです。

現在の制限事項

  • 一部の qodercli バージョンでは、ローカル plugin の commands、agents、MCP は初期化結果に正常に現れる一方、plugin skills が発見リストに現れないことがあります。これは CLI 側の発見チェーンの問題です。
  • 現在の qodercli 実装では、存在しない --plugin-dir パスは SDK モードで黙って無視されます。plugin ロード失敗を明示的に診断するには、現時点ではリロード後の error_count が唯一の手段です。
  • リロードは SDK が公開するランタイム制御 API です。現在の CLI バージョンが this._plugins 関連の内部エラーを返す場合は、修正済みの qodercli にアップグレードしてください。
Plugins - Qoder