Plugins & Extensions

Relevant source files

The following files were used as context for generating this wiki page:

• packages/coding-agent/DEVELOPMENT.md
• packages/coding-agent/src/discovery/helpers.ts
• packages/coding-agent/src/cli/plugin-cli.ts
• packages/coding-agent/src/extensibility/plugins/manager.ts
• packages/coding-agent/src/extensibility/plugins/marketplace/registry.ts

The extension system in oh-my-pi provides a flexible framework for augmenting the coding agent's capabilities. It allows developers to integrate new tools, hooks, skills, and custom commands via external TypeScript/JavaScript modules or marketplace-distributed plugins. The system is designed to handle local development links, npm-based packages, and marketplace-hosted extensions with specific scoping for users or projects.

Sources: packages/coding-agent/DEVELOPMENT.md:86-102, packages/coding-agent/src/cli/plugin-cli.ts:404-436

Architecture and Discovery

The extensibility layer relies on a discovery mechanism that scans specific directories for extension modules. Discovery follows a hierarchical search pattern:

1. Direct Files: Individual .ts or .js files within an extensions directory.
2. Subdirectories with Entry Points: Folders containing an index.ts or index.js.
3. Manifest-based Discovery: Subdirectories containing a package.json with an omp or pi field declaring specific extension entry points.

Extension Discovery Flow

The following diagram illustrates how the system identifies and loads extension modules from the filesystem.

Plugin Management Lifecycle

Plugins are managed via the PluginManager and MarketplaceManager classes, which handle installation, uninstallation, enabling/disabling, and configuration. The system supports two primary scopes:

• User Scope: Globally available plugins stored in the user's home directory (e.g., ~/.omp/plugins).
• Project Scope: Scoped to the current codebase, stored in a .omp folder at the project root.

Plugin Registry Structure

The system maintains an installed_plugins.json registry to track current installations.

Field	Type	Description
id	String	Unique identifier (e.g., name@marketplace)
scope	Enum	Either user or project
installPath	String	Absolute path to the plugin on disk
version	String	Installed version string
enabled	Boolean	Whether the plugin is currently active

Sources: packages/coding-agent/src/discovery/helpers.ts:503-524, packages/coding-agent/src/cli/plugin-cli.ts:40-58

Lifecycle Sequence

The following sequence diagram shows the process of installing a marketplace plugin.

Configuration and Settings

Plugins can define a schema for their settings in their manifest. The PluginManager provides utilities to validate and persist these settings.

Setting Validation Logic

The system supports different data types and constraints for plugin settings, including secret obfuscation for sensitive data like API keys.

// Example of setting parsing and validation in the CLI
const valueStr = valueArgs.join(" ");
const schema = plugin.manifest.settings?.[key];

let value: unknown = valueStr;
if (schema) {
    value = parseSettingValue(valueStr, schema);
    const validation = validateSetting(value, schema);
    if (!validation.valid) {
        console.error(chalk.red(validation.error!));
        process.exit(1);
    }
}
await manager.setPluginSetting(pluginName, key, value);

Sources: packages/coding-agent/src/cli/plugin-cli.ts:526-545, packages/coding-agent/src/extensibility/plugins/manager.ts

Local Development and Linking

For developers building plugins, the system provides a link command. This creates a symlink from the local development directory into the agent's plugin tree, ensuring that source code changes are reflected immediately without requiring a full re-installation.

• Command: omp plugin link <path>
• Logic: The PluginManager uses path.resolve to determine the absolute location and establishes a symlink in the internal node_modules structure of the agent's environment.

Sources: packages/coding-agent/src/cli/plugin-cli.ts:276-302, packages/coding-agent/src/discovery/helpers.ts:413-423

Marketplace Integration

The MarketplaceManager coordinates between multiple marketplace sources. It handles:

• Marketplace Discovery: Browsing available plugins across configured registries.
• Upgrades: Comparing installed versions against marketplace manifests and performing updates.
• Shadowing: Handling cases where project-scoped plugins shadow (take precedence over) user-scoped plugins of the same ID.

Sources: packages/coding-agent/src/cli/plugin-cli.ts:169-234, packages/coding-agent/src/discovery/helpers.ts:635-680

The plugin and extension system serves as the primary artery for repo-specific customizations, allowing the pi-coding-agent to adapt to various development environments and workflows through a structured, multi-scoped architecture.