Plugins

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Loading Local Plugins

from qoder_agent_sdk import QoderAgentOptions, QoderSDKClient

options = QoderAgentOptions(
    plugins=[
        {"type": "local", "path": "/path/to/my-plugin"},
    ],
)

async with QoderSDKClient(options) as client:
    info = await client.get_server_info()
    print(info.get("commands"))
    print(info.get("agents"))
    print(info.get("plugins"))

options = QoderAgentOptions(
    plugins=[
        {"type": "local", "path": "/path/to/plugin-a"},
        {"type": "local", "path": "/path/to/plugin-b"},
    ],
)

💡 query() is a one-shot message stream; it cannot query the init response after the handshake. To read commands / agents / skills contributed by plugins, use QoderSDKClient and call get_server_info() after connect(), or capture SystemMessage(subtype='init') in the message stream and read message.data yourself.

​

Plugin Directory Layout

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

• A non-existent --plugin-dir path is silently ignored in SDK mode; the session still initializes normally.
• Broken frontmatter or .mcp.json does not block init; broken commands simply do not appear in the init response.
• To explicitly diagnose plugin loading failures, the only fallback right now is reload_plugins().error_count.

​

Plugin-contributed Slash Commands

async with QoderSDKClient(options) as client:
    info = await client.get_server_info()
    for cmd in info.get("commands", []):
        print(cmd["name"], cmd.get("description"))

​

Plugin-contributed Agents

async with QoderSDKClient(options) as client:
    for agent in client.supported_agents():
        print(agent["name"], agent.get("description"))

​

Plugin-contributed Skills

​

Plugin-contributed MCP Servers

async with QoderSDKClient(options) as client:
    status = await client.get_mcp_status()
    for server in status["mcpServers"]:
        print(server["name"], server["status"])

​

Temporarily Overriding an Installed Plugin with the Same Name

options = QoderAgentOptions(
    # 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

async with QoderSDKClient(options) as client:
    refreshed = await client.reload_plugins()

    print(refreshed["commands"])
    print(refreshed["agents"])
    print(refreshed["plugins"])
    print(refreshed["mcpServers"])
    print(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.

Note: reload_plugins() is only meaningful in QoderSDKClient (streaming) mode; the one-shot query() stream has no runtime control channel.

​

Options Reference

​

Return Value Reference

​

client.get_server_info() and SystemMessage(subtype='init').data

{
    "commands": [
        {"name": "plugin-a:greet", "description": "...", "argumentHint": "..."},
        ...
    ],
    "agents": [
        {"name": "plugin-a:helper", "description": "...", "model": "sonnet"},
        ...
    ],
    "skills": [
        {"name": "plugin-a:echo", "description": "...", "source": "plugin"},
        ...
    ],
    "plugins": [
        {"name": "plugin-a", "path": "/path/to/plugin-a", "source": "local"},
        ...
    ],
    # Also includes models / account / output_style and other fields
}

​

client.reload_plugins()

{
    "commands": list[Any],
    "agents": list[Any],
    "plugins": list[PluginInfo],            # {"name": str, "path": str, "source": str?}
    "mcpServers": list[McpServerStatus],    # See McpServerStatus in mcp.md
    "error_count": int,                     # Number of plugins that failed to load in this reload
}

​

Best Practices

• Read get_server_info() first for the host UI: It is the stable entry point for displaying commands, agents, skills, and plugins. If a one-shot query() needs this data, switch to QoderSDKClient, or read SystemMessage(subtype='init').data from the message stream.
• Use options.plugins during plugin development: It only affects the current session and does not require modifying the user’s global install state.
• Prepare user prompts before reloading: reload_plugins() 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 a 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 get_server_info()['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, the only fallback right now is reload_plugins().error_count.
• reload_plugins() is a runtime control API exposed by QoderSDKClient; if the current CLI version returns internal errors related to this._plugins, an upgrade to a fixed qodercli is needed.
• settings.strictPluginOnlyCustomization, settings.allowedChannelPlugins, and template substitution in settings.pluginConfigs.<pid>.options are dict pass-through fields. The SDK does not parse them; whether they take effect depends entirely on the CLI version.