EveryInc/compound-engineering-plugin · error · Error

Unknown permissions mode: ${permissions}

Error message

Unknown permissions mode: ${permissions}

What it means

`install` validates `--permissions` exactly like `convert`: the value must be one of "none", "broad", or "from-commands" (the `permissionModes` array). An unknown value throws this error at the top of `run`, before plugin path resolution or any file writes.

Source

Thrown at src/commands/install.ts:87

      description: "Infer agent temperature from name/description",
    },
    includeSkills: {
      type: "boolean",
      default: false,
      alias: "include-skills",
      description: "For --to codex only: also emit skills and commands. Default is agents-only, the recommended pairing with `codex plugin install`. Set this flag for a legacy / standalone install without Codex native plugin install. Ignored by other targets.",
    },
    branch: {
      type: "string",
      description: "Git branch to clone from (e.g. feat/new-agents)",
    },
  },
  async run({ args }) {
    const targetName = String(args.to)

    const permissions = String(args.permissions)
    if (!permissionModes.includes(permissions as PermissionMode)) {
      throw new Error(`Unknown permissions mode: ${permissions}`)
    }

    const branch = args.branch ? String(args.branch) : undefined
    const resolvedPlugin = await resolvePluginPath(String(args.plugin), branch)

    try {
      const plugin = await loadClaudePlugin(resolvedPlugin.path)
      const outputRoot = resolveOutputRoot(args.output)
      const codexHome = resolveCodexHome(args.codexHome)
      const piHome = resolveTargetHome(args.piHome, path.join(os.homedir(), ".pi", "agent"))
      const hasExplicitOutput = Boolean(args.output && String(args.output).trim())

      const options: ClaudeToOpenCodeOptions = {
        agentMode: String(args.agentMode) === "primary" ? "primary" : "subagent",
        inferTemperature: Boolean(args.inferTemperature),
        permissions: permissions as PermissionMode,
        codexIncludeSkills: Boolean(args.includeSkills),
      }

View on GitHub (pinned to c9c10f8c75)

Solutions

1. Pass one of the exact modes: none, broad, or from-commands (note the hyphen in from-commands).
2. Fix casing and whitespace — comparison is exact and case-sensitive.
3. Echo the variable feeding --permissions in scripts to confirm it isn't empty or mis-expanded.
4. Check `install --help` for the supported modes in your installed CLI version.

Example fix

// before
bun run src/index.ts install --to codex --permissions "from commands"
// Error: Unknown permissions mode: from commands

// after
bun run src/index.ts install --to codex --permissions from-commands

const PERMISSION_MODES = ["none", "broad", "from-commands"] as const
const mode = args.permissions ?? "broad"
if (!(PERMISSION_MODES as readonly string[]).includes(mode)) {
  throw new Error(`install --permissions must be one of ${PERMISSION_MODES.join(" | ")}, got: '${mode}'`)
}

type PermissionMode = "none" | "broad" | "from-commands"
function isPermissionMode(v: unknown): v is PermissionMode {
  return typeof v === "string" && (["none", "broad", "from-commands"] as const).includes(v as never)
}

try {
  await install({ to, permissions })
} catch (e) {
  if (e instanceof Error && e.message.startsWith("Unknown permissions mode:")) {
    console.error(`${e.message} — use none | broad | from-commands`)
    process.exitCode = 2
  } else throw e
}

When it happens

Trigger: Calling install with `--permissions` set to a value outside none/broad/from-commands — misspellings, wrong casing, an empty interpolated variable in a script, or a mode name borrowed from another tool.

Common situations: CI scripts with a stale or misconfigured permissions variable; copying install commands between tools with different permission vocabularies; hand-editing a script and dropping part of a hyphenated value ("from commands" with a space instead of "from-commands").

Understand the failure class

Background: "invalid argument", "unknown mode", "not supported": invalid enum-like argument errors explained — this error's family across 19 libraries.

Related errors

• Unknown cleanup target: ${target}. Use one of: ${cleanupTarg
• Unknown permissions mode: ${permissions}
• Unknown target: ${targetName}
• Unknown target: ${targetName}
• Cleanup currently supports only the compound-engineering plu

AI-assisted analysis of EveryInc/compound-engineering-plugin@c9c10f8c75 (2026-08-31). Data as JSON: /api/errors/9ea3884677c661f2. Report an issue: GitHub.