ComposioHQ/composio · error · Error

experimental_subAgent() could not determine an agent CLI…

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.

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

• Cannot determine save location: home directory is not…
• experimental_subAgent() expected valid JSON output for…
• experimental_subAgent() requires a non-empty prompt string.
• experimental_subAgent() requires Zod 4 with…
• experimental_subAgent() schema must be a Zod schema or JSON…

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

Appendix: 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)