Yeachan-Heo/oh-my-codex · error · Error

unknown agents subcommand: ${subcommand}

Error message

unknown agents subcommand: ${subcommand}

What it means

The `omx agents` command dispatches on a subcommand string and throws when it does not match any known case (list/add/remove). This is a CLI argument parsing error indicating the user typed an unrecognized or misspelled subcommand.

Source

Thrown at src/cli/agents.ts:304

      console.log(`Created native agent: ${path}`);
      return;
    }
    case 'edit': {
      const name = args[1];
      assert.ok(name, 'Usage: omx agents edit <name>');
      const path = await editNativeAgent(name, { cwd: process.cwd(), scope });
      console.log(`Edited native agent: ${path}`);
      return;
    }
    case 'remove': {
      const name = args[1];
      assert.ok(name, 'Usage: omx agents remove <name>');
      const path = await removeNativeAgent(name, { cwd: process.cwd(), scope, force });
      console.log(`Removed native agent: ${path}`);
      return;
    }
    default:
      throw new Error(`unknown agents subcommand: ${subcommand}`);
  }
}

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Run `omx agents --help` (or read the CLI docs) to list supported subcommands
2. Use the exact verb shown in help, e.g. `omx agents remove <name>` instead of `delete`
3. Update to the latest omx version in case the subcommand was renamed
4. Check shell scripts/aliases for hardcoded subcommand strings that no longer exist

Example fix

# before
omx agents delete my-agent
# after
omx agents remove my-agent

const VALID = new Set(['list','add','remove']);
if (!VALID.has(sub)) {
  console.error(`unknown agents subcommand: ${sub}`);
  process.exit(1);
}

const isAgentsSubcommand = (s: string): s is 'list' | 'add' | 'remove' =>
  ['list','add','remove'].includes(s);

catch (e) { if (e instanceof Error && e.message.startsWith('unknown agents subcommand')) { printAgentsHelp(); } else throw e; }

When it happens

Trigger: Running `omx agents <something>` where <something> is not one of the supported subcommands (e.g. `omx agents delete`, `omx agents rm`, or a typo like `omx agents lst`).

Common situations: Users guessing CLI verbs (delete vs remove), older/newer versions where subcommand sets differ, or shell aliases/scripts passing stale subcommand names.

Related errors

• Unknown adapt argument: ${arg}
• Unknown adapt subcommand: ${subcommand}. Supported subcomman
• agents-init accepts at most one path argument.\n${AGENTS_INI
• agent name must not be empty
• invalid agent name: ${name}

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/fb33bbb243c1ed85. Report an issue: GitHub.