ComposioHQ/composio · error · Error

experimental_subAgent() could not determine an agent CLI. Cu

Error message

experimental_subAgent() could not determine an agent CLI. Current master is user; install codex or claude, or pass { target: "codex" | "claude" }.

What it means

experimental_subAgent() needs an agent CLI (codex or claude) to spawn. Target resolution checks the configured target, detects the current master, and falls back to Bun.which for both binaries; if all fail and the master is 'user' (no agent context), this error is thrown.

Source

Thrown at ts/packages/cli/src/services/run-helpers-runtime.ts:825

    if (
      helperContext.master === 'claude' ||
      helperContext.master === 'codex' ||
      helperContext.master === 'user'
    ) {
      return helperContext.master;
    }
    return 'user';
  };

  const resolveInvokeAgentTarget = (requestedTarget?: string): 'claude' | 'codex' => {
    if (requestedTarget === 'claude' || requestedTarget === 'codex') return requestedTarget;
    const configuredTarget = readConfiguredExperimentalSubagentTarget(helperContext.cliConfigPath);
    if (configuredTarget === 'claude' || configuredTarget === 'codex') return configuredTarget;
    const detected = requestedTarget === 'user' ? 'user' : detectInvokeAgentMaster();
    if (detected === 'codex' || detected === 'claude') return detected;
    if (typeof Bun.which === 'function' && Bun.which('codex')) return 'codex';
    if (typeof Bun.which === 'function' && Bun.which('claude')) return 'claude';
    throw new Error(
      'experimental_subAgent() could not determine an agent CLI. Current master is user; install codex or claude, or pass { target: "codex" | "claude" }.'
    );
  };

  const experimentalSubAgentImpl = async (
    prompt: string,
    options: Record<string, unknown> = {}
  ) => {
    if (typeof prompt !== 'string' || prompt.trim().length === 0) {
      throw new Error('experimental_subAgent() requires a non-empty prompt string.');
    }
    const logFilePath =
      typeof helperContext.runLogFilePath === 'string' && helperContext.runLogFilePath.length > 0
        ? helperContext.runLogFilePath
        : undefined;
    const normalizedOptions = normalizeInvokeAgentOptions(options);
    const target = resolveInvokeAgentTarget(normalizedOptions.target);
    const master = detectInvokeAgentMaster();

View on GitHub (pinned to 64b1b85502)

Solutions

1. Install codex or claude and ensure the binary is on PATH
2. Pass an explicit target: experimental_subAgent(prompt, { target: 'codex' })
3. Set the configured experimental subagent target in the CLI config referenced by helperContext.cliConfigPath
4. Run from within a Codex or Claude Code session so the master is auto-detected

Example fix

// before
await experimental_subAgent('do thing'); // master is user, no CLIs found
// after
await experimental_subAgent('do thing', { target: 'codex' }); // requires codex on PATH
// or: install the CLI, e.g. npm i -g @openai/codex

const cli = ['codex','claude'].find(c => typeof Bun.which === 'function' && Bun.which(c));
if (!cli) throw new Error('no agent CLI on PATH');
await experimental_subAgent(prompt, { target: cli });

const agentCliAvailable = (): boolean => (typeof Bun.which === 'function' && (!!Bun.which('codex') || !!Bun.which('claude')));

catch (e) { if (e instanceof Error && e.message.includes('could not determine an agent CLI')) { /* install codex/claude or set explicit target */ } }

When it happens

Trigger: Running inside a context where the master agent is 'user' (plain shell/user session), no configured experimental subagent target is set, and neither `codex` nor `claude` is on PATH (or Bun.which is unavailable).

Common situations: Testing subagent code from a plain script instead of inside Codex/Claude Code; agent CLIs installed via a version manager not on the PATH the CLI process sees; stripped-down CI containers without agent binaries.

Related errors

• experimental_subAgent() target must be "claude", "codex", or
• experimental_subAgent() requires Zod 4 with z.toJSONSchema()
• experimental_subAgent() schema must be a Zod schema or JSON
• experimental_subAgent() requires a non-empty prompt string.
• Missing required flag: ${name}

AI-assisted analysis of ComposioHQ/composio@64b1b85502 (2026-08-28). Data as JSON: /api/errors/9cb4a7d7c3ed5e99. Report an issue: GitHub.