# Understanding the --agentMode Flag in Compound Engineering Plugin: Primary vs Subagent

> Learn how the --agentMode flag in Compound Engineering Plugin directs agents as primary or subagent. Understand when to use each for optimal workflow control.

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

---

**The `--agentMode` flag controls whether converted agents run as standalone primary entry points (`primary`) or as helper subagents invoked by other workflows (`subagent`, the default).**

The `EveryInc/compound-engineering-plugin` repository provides a CLI tool that transforms Claude Code plugins into target formats like OpenCode or Pi. When running the `convert` or `install` commands, the **`--agentMode`** flag determines how the resulting agents are classified in the generated configuration files—directly impacting how users and other agents interact with them.

## What Is the --agentMode Flag?

The `--agentMode` flag is a string option accepted by both the `convert` and `install` commands in the compound-engineering-plugin CLI. It specifies the default execution mode for all agents in the converted plugin, controlling whether they function as independent primary agents or as callable subagents within larger workflows.

### CLI Flag Definition and Defaults

In [`src/commands/convert.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/commands/convert.ts) (lines 52–57), the flag is defined with a default value of `"subagent"`:

```typescript
// src/commands/convert.ts
agentMode: {
  type: "string",
  default: "subagent",
  description: "Default agent mode: primary | subagent",
},

```

The same definition appears in [`src/commands/install.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/commands/install.ts) (lines 54–57). At lines 85–86 in [`convert.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/convert.ts), the CLI normalizes the input to ensure only valid values are accepted:

```typescript
const options = {
  agentMode: String(args.agentMode) === "primary" ? "primary" : "subagent",
  // ...
};

```

### Accepted Values: primary vs subagent

The flag accepts two mutually exclusive values that determine how the target platform treats the generated agent:

- **`primary`**: The agent is configured as the main entry point. In OpenCode, this writes `mode: "primary"` to the agent's front-matter, indicating the agent can be invoked directly by users or the host IDE.
- **`subagent`** (default): The agent is configured as a helper utility. The generated front-matter contains `mode: "subagent"`, signaling that the agent should be invoked via subagent extension tools rather than called directly.

## How --agentMode Affects Generated Configuration

The selected mode propagates through the conversion pipeline and materializes in the target configuration files.

### Front-Matter Injection in OpenCode

During conversion to OpenCode format, the [`claude-to-opencode.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/claude-to-opencode.ts) converter writes the `agentMode` value directly into each agent's YAML front-matter. The type definition in [`src/converters/claude-to-opencode.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-opencode.ts) (line 19) declares this as a required option:

```typescript
export type ClaudeToOpenCodeOptions = {
  agentMode: "primary" | "subagent";
  // ...
};

```

At lines 92–94, the converter constructs the front-matter object:

```typescript
const frontmatter: Record<string, unknown> = {
  description: agent.description,
  mode: options.agentMode,   // ← "primary" or "subagent"
};

```

### Type Safety and Validation

The allowed values are strictly typed in [`src/types/opencode.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/types/opencode.ts) (lines 14–17):

```typescript
export type OpenCodeAgentConfig = {
  description?: string;
  mode?: "primary" | "subagent";   // ← accepted values
  // ...
};

```

This ensures that any generated configuration conforms to the OpenCode specification, preventing invalid mode strings from reaching the output.

## When to Use Primary Mode

Use `--agentMode primary` when your agent serves as the main interface for a specific workflow or task that users invoke directly.

**Typical scenarios include:**

- **Review agents**: A code reviewer that users call explicitly via `/workflows:review` or similar commands.
- **Planner agents**: An architecture planning agent that serves as the starting point for complex multi-step operations.
- **Interactive assistants**: Agents that require direct user interaction and tool access without intermediary orchestration.

**Example conversion:**

```bash
bunx @every-env/compound-plugin install compound-engineering \
  --to opencode \
  --agentMode primary

```

This generates an agent file with `mode: primary` in its front-matter, making it available as a top-level command in OpenCode-compatible environments.

## When to Use Subagent Mode (Default)

Use `--agentMode subagent` (or omit the flag) when your agent functions as a utility or helper that other agents invoke as part of their workflows.

**Typical scenarios include:**

- **Data fetchers**: Small agents that retrieve external data or validate bug reports.
- **Parallel workers**: Agents designed to run simultaneously as part of a batch operation using `multi_tool_use.parallel`.
- **Specialized validators**: Single-purpose agents that check specific conditions and return results to a primary orchestrator.

**Pi Platform Mapping:**

In Pi-compatible outputs, subagents map to the **`subagent`** extension tool. As documented in [`src/targets/pi.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/targets/pi.ts) (lines 20–23), Claude's `Task(agent, args)` pattern translates to Pi's subagent invocation mechanism:

> *Claude Task(agent, args) maps to the subagent extension tool*  
> *For parallel agent runs, batch multiple subagent calls with `multi_tool_use.parallel`*

**Example invocation from a primary agent:**

```typescript
// Inside a primary agent using Pi
await pi.subagent("repo-research-analyst", { cwd: projectRoot });

```

## Summary

- The **`--agentMode`** flag controls how converted agents are classified in target platforms like OpenCode or Pi.
- **`primary`** designates agents as main entry points for direct user invocation, suitable for workflows like code review or planning.
- **`subagent`** (the default) designates agents as helper utilities invoked by other agents via extension tools, enabling composition and parallelism.
- The flag is defined in [`src/commands/convert.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/commands/convert.ts) and [`src/commands/install.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/commands/install.ts), with the selected value written to agent front-matter in [`src/converters/claude-to-opencode.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-opencode.ts).

## Frequently Asked Questions

### What is the default value of --agentMode?

The default value is **`subagent`**. This is explicitly set in the CLI argument definitions in both [`src/commands/convert.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/commands/convert.ts) and [`src/commands/install.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/commands/install.ts). If you omit the flag, the converter generates agents configured as subagents suitable for helper utilities and parallel execution.

### Can I mix primary and subagent modes in the same plugin?

The CLI only supports a **global default** via `--agentMode`. To mix modes within a single plugin, you must run the conversion twice with different flags or manually edit the generated front-matter in the output files. The source code in [`src/converters/claude-to-opencode.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-opencode.ts) applies the same `agentMode` value to every agent in the bundle.

### How does subagent mode work in Pi compared to OpenCode?

In OpenCode, `mode: subagent` simply marks the agent as non-primary in the front-matter. In Pi, this mode activates the **`subagent`** extension tool mapping. According to [`src/targets/pi.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/targets/pi.ts), Claude's `Task(agent, args)` pattern translates to Pi's subagent invocation, enabling nested agent calls and parallel batches via `multi_tool_use.parallel`.

### Where is the --agentMode flag validated in the source code?

Validation occurs in the command handlers. In [`src/commands/convert.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/commands/convert.ts) (lines 85–86), the code normalizes the input string: `String(args.agentMode) === "primary" ? "primary" : "subagent"`. This ensures that only the exact string `"primary"` selects primary mode; any other value (including undefined) falls back to `"subagent"`. The same logic appears in [`src/commands/install.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/commands/install.ts).