slopus/happy · error · Error

Usage: happy acp <agent-name> or happy acp -- <command> [arg

Error message

Usage: happy acp <agent-name> or happy acp -- <command> [args]

What it means

resolveAcpAgentConfig validates CLI arguments for `happy acp`. With zero arguments there is neither a named agent nor an inline command, so it throws a usage error explaining the two accepted forms: `happy acp <agent-name>` or `happy acp -- <command> [args]`.

Source

Thrown at packages/happy-cli/src/agent/acp/acpAgentConfig.ts:19

export type AcpAgentConfig = {
  command: string;
  args: string[];
};

export const KNOWN_ACP_AGENTS: Record<string, AcpAgentConfig> = {
  gemini: { command: 'gemini', args: ['--experimental-acp'] },
  opencode: { command: 'opencode', args: ['acp'] },
};

export type ResolvedAcpAgentConfig = {
  agentName: string;
  command: string;
  args: string[];
};

export function resolveAcpAgentConfig(cliArgs: string[]): ResolvedAcpAgentConfig {
  if (cliArgs.length === 0) {
    throw new Error('Usage: happy acp <agent-name> or happy acp -- <command> [args]');
  }

  if (cliArgs[0] === '--') {
    const command = cliArgs[1];
    if (!command) {
      throw new Error('Missing command after "--". Usage: happy acp -- <command> [args]');
    }
    return {
      agentName: command,
      command,
      args: cliArgs.slice(2),
    };
  }

  const agentName = cliArgs[0];
  const known = KNOWN_ACP_AGENTS[agentName];
  if (known) {
    const passthroughArgs = cliArgs

View on GitHub (pinned to b824cd0a46)

Solutions

1. Pass an agent name: `happy acp claude-code` (or another registered agent).
2. Or pass an explicit command: `happy acp -- npx @example/agent --flag`.
3. Run `happy acp` help/README to list valid agent names.

Example fix

// before
$ happy acp
// after
$ happy acp claude-code
// or
$ happy acp -- npx @zed_industries/claude-code-acp

const acpArgs = process.argv.slice(3); // after 'happy acp'
if (acpArgs.length === 0) {
  console.error('Usage: happy acp <agent-name> | happy acp -- <command> [args]');
  process.exit(1);
}

try {
  const cfg = resolveAcpAgentConfig(cliArgs);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Usage: happy acp')) {
    printAcpUsage();
    process.exit(1);
  } else throw err;
}

When it happens

Trigger: Running `happy acp` (or `happy acp` with only flags not routed into cliArgs) so cliArgs resolves to an empty array.

Common situations: User forgets the agent name; shell alias/wrapper strips arguments; scripted invocation passes no args; misrouting of parsed CLI flags before resolveAcpAgentConfig.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Missing command after "--". Usage: happy acp -- <command> [a
• Happy session ID is required: happy resume <session-id>
• Unsupported vendor: ${vendor}
• Daemon-spawned sessions cannot use local/interactive mode. U
• Unsupported Claude goal action

AI-assisted analysis of slopus/happy@b824cd0a46 (2026-08-31). Data as JSON: /api/errors/aeca7638d89857e9. Report an issue: GitHub.