Difference Between Convert and Install Commands in Compound Engineering Plugin

The convert command transforms a local Claude Code plugin directory into another agent-platform format, while the install command fetches plugins by name from GitHub, converts them, and places the results in your global configuration directory.

The Compound Engineering Plugin CLI provides two distinct workflows for adapting Claude Code plugins for other AI agent platforms. Both commands share the same core conversion pipeline—parsing the plugin, selecting targets, and writing bundles—but they differ fundamentally in how they locate source code and where they write output files.

Core Differences Between Convert and Install Commands

Source Resolution and Discovery

The most significant architectural difference lies in how each command resolves the input plugin path.

convert calls loadClaudePlugin directly on the path provided by the positional source argument in src/commands/convert.ts (lines 79-84). It performs no network operations or GitHub lookups.

install utilizes resolvePluginPath() in src/commands/install.ts (lines 80-87). This utility checks if the argument resembles a file path; if not, it clones the official GitHub repository, checks out the requested plugin, and returns a temporary path to the downloaded code.

Default Output Locations

Where the generated files land by default diverges between the two commands.

convert defaults to your current working directory (process.cwd()). The resolveOutputRoot function in convert.ts uses the --output flag when provided, otherwise falls back to wherever you invoked the command.

install defaults to the OpenCode global configuration directory at ~/.config/opencode (see lines 66-68 of src/commands/install.ts). This places converted plugins directly into your user configuration for immediate use by the OpenCode agent.

Temporary Resource Management

The install command handles ephemeral resources that convert never creates.

Because install may clone a GitHub repository, it receives a resolvedPlugin object containing a cleanup() function. The command wraps its execution in a try/finally block (lines 28-32 of install.ts) to ensure the temporary clone directory is deleted even if the conversion fails.

The convert command requires no such cleanup because it operates exclusively on local, persistent directories.

Command Workflows and Implementation Details

Convert Command Implementation

Located in src/commands/convert.ts, the convert command follows a straightforward local-to-local workflow:

// convert.ts lines 79-84
const plugin = await loadClaudePlugin(String(args.source))
const outputRoot = resolveOutputRoot(args.output)   // defaults to cwd

The command immediately loads the plugin from the specified source directory and resolves the output root to either the --output flag or process.cwd().

Install Command Implementation

Located in src/commands/install.ts, the install command adds remote fetching and global installation capabilities:

// install.ts lines 80-87
const resolvedPlugin = await resolvePluginPath(String(args.plugin))
const plugin = await loadClaudePlugin(resolvedPlugin.path)
const outputRoot = resolveOutputRoot(args.output)   // defaults to ~/.config/opencode

The critical addition is resolvePluginPath(), which handles GitHub cloning when a plugin name rather than a path is provided. The cleanup logic follows in the finally block:

// install.ts lines 28-32
finally {
    if (resolvedPlugin.cleanup) await resolvedPlugin.cleanup()
}

Practical Usage Examples

Converting a Local Plugin

Use convert when you have the plugin source code on your machine and want to generate platform-specific files in a specific directory:

# Convert a local Claude plugin to OpenCode format

compound convert ./my-claude-plugin --to opencode --output ./converted-output

# Result: ./converted-output contains the generated OpenCode configuration

This corresponds to the implementation in src/commands/convert.ts where args.source is passed directly to loadClaudePlugin.

Installing by Name from GitHub

Use install when you want to fetch a plugin from the official repository and place it directly into your global configuration:

# Install the "my-agent" plugin from GitHub into ~/.config/opencode

compound install my-agent --to opencode

# Result: ~/.config/opencode now contains the converted plugin files

This triggers the resolvePluginPath() logic in src/commands/install.ts to clone the repository and the default output resolution to ~/.config/opencode.

Installing with Explicit Output for Cursor

When using install with an explicit --output flag, the behavior for cursor and gemini targets changes to write to subdirectories:

# Install and place cursor-specific files in a custom project directory

compound install my-agent --to cursor --output ./my-project

# Result: Files are placed at ./my-project/.cursor

As noted in the source analysis, this special handling occurs in install.ts lines 83-90, whereas convert always writes to the specified output root.

Summary

• convert transforms local Claude Code plugin directories into other agent-platform formats, defaults output to the current working directory, and performs no network operations or cleanup.
• install fetches plugins by name from GitHub, converts them, and places results in the global OpenCode configuration directory (~/.config/opencode), automatically cleaning up temporary clone directories.
• Both commands share the core conversion pipeline in src/targets/index.ts and use loadClaudePlugin from src/parsers/claude.ts, but diverge in source resolution (convert.ts vs. install.ts lines 80-87) and default output handling.
• Use convert for local development workflows and install for global plugin management and remote repository integration.

Frequently Asked Questions

Can I use install with a local directory instead of a plugin name?

Yes. The resolvePluginPath() function in install.ts checks whether the argument resembles a file path. If you provide a path to a local directory (e.g., compound install ./my-local-plugin), it will use that directly without attempting to clone from GitHub, functioning similarly to convert but with install's default output location.

Why does install default to ~/.config/opencode while convert uses the current directory?

The install command is designed for system-wide or user-wide plugin installation, placing converted files directly into the OpenCode global configuration directory so they are immediately available to the agent. In contrast, convert is intended for development and inspection workflows where you want the output in your project folder or a specific build directory, hence defaulting to process.cwd().

Does convert support fetching plugins from GitHub like install does?

No. The convert command in src/commands/convert.ts calls loadClaudePlugin directly on the provided source path without any intermediate resolution step. It does not implement the resolvePluginPath() logic found in install.ts that handles GitHub cloning. To fetch from GitHub, you must use the install command.

What happens to temporary files if the install command fails?

The install command wraps its execution in a try/finally block (lines 28-32 of install.ts). If resolvePluginPath() cloned a GitHub repository, it returns a cleanup() function. This function is called in the finally block regardless of whether the conversion succeeded or threw an error, ensuring no temporary clone directories are left behind on your filesystem.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}