# Difference Between Convert and Install Commands in Compound Engineering Plugin

> Understand the difference between convert and install commands in the Compound Engineering Plugin. Learn how convert transforms local plugins and install fetches GitHub plugins for your global config.

- Repository: [Every/compound-engineering-plugin](https://github.com/everyinc/compound-engineering-plugin)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/commands/convert.ts) (lines 79-84). It performs no network operations or GitHub lookups.

**`install`** utilizes `resolvePluginPath()` in [`src/commands/install.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/commands/convert.ts), the `convert` command follows a straightforward local-to-local workflow:

```typescript
// 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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/commands/install.ts), the `install` command adds remote fetching and global installation capabilities:

```typescript
// 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:

```typescript
// 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:

```bash

# 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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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:

```bash

# 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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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:

```bash

# 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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/targets/index.ts) and use `loadClaudePlugin` from [`src/parsers/claude.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/parsers/claude.ts), but diverge in source resolution ([`convert.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/convert.ts) vs. [`install.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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.