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

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 (lines 52–57), the flag is defined with a default value of "subagent":

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

The same definition appears in src/commands/install.ts (lines 54–57). At lines 85–86 in convert.ts, the CLI normalizes the input to ensure only valid values are accepted:

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 converter writes the agentMode value directly into each agent's YAML front-matter. The type definition in src/converters/claude-to-opencode.ts (line 19) declares this as a required option:

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

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

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 (lines 14–17):

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:

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 (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:

// 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 and src/commands/install.ts, with the selected value written to agent front-matter in 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 and 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 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, 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 (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.

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