Plugins

​

Loading Local Plugins

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);

const q = query({
  options: {
    plugins: [
      { type: 'local', path: '/path/to/plugin-a' },
      { type: 'local', path: '/path/to/plugin-b' },
    ],
  },
});

​

Plugin Directory Layout

my-plugin/
  .qoder-plugin/plugin.json
  commands/
  agents/
  skills/
  .mcp.json

​

Plugin-contributed Slash Commands

const commands = await q.supportedCommands();
console.log(commands.map((cmd) => cmd.name));

​

Plugin-contributed Agents

const agents = await q.supportedAgents();
console.log(agents.map((agent) => agent.name));

​

Plugin-contributed Skills

​

Plugin-contributed MCP Servers

const servers = await q.mcpServerStatus();
console.log(servers);

​

Temporarily Overriding an Installed Plugin with the Same Name

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' }],
  },
});

​

Reloading Plugins at Runtime

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);

• Refreshing after adding or deleting commands/*.md during plugin development.
• After installing or updating a local plugin without restarting the host application.
• When the host UI needs to display commands, agents, plugins, and MCP status after a reload.

​

Options Reference

​

Return Value Reference

​

initializationResult()

​

listPlugins()

listPlugins(): Promise<PluginDetails[]>;

​

reloadPlugins()

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;
};

​

Best Practices

• Separate initialization resources from plugin inventory: Use initializationResult() for discovered commands, agents, and skills, and use listPlugins() for plugin inventory. Skills in the initialization result are a discovery inventory, not every skill currently callable by the main session.
• Use options.plugins during plugin development: It only affects the current session without modifying the user's global install state.
• Prepare user prompts before reloading: reloadPlugins() triggers the CLI to rescan disk, which may briefly change the available resource list; synchronize UI updates accordingly.
• Check error_count for diagnostics: If error_count > 0 after reload, some plugin resources failed to load; display the source to the user.

​

Current Limitations

• In some qodercli versions, local plugin commands, agents, and MCP can appear correctly in the initialization result, but plugin skills may not appear in initializationResult().skills — this is a CLI-side discovery pipeline issue.
• Under the current qodercli implementation, non-existent --plugin-dir paths are silently ignored in SDK mode; to explicitly diagnose plugin loading failures, currently the only option is reloadPlugins().error_count as a fallback.
• reloadPlugins() is a runtime control API exposed by the SDK; if the current CLI version returns internal errors related to this._plugins, an upgrade to the fixed qodercli is needed.