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

invalid agent name: ${name}

Error message

invalid agent name: ${name}

What it means

The agent name fails the pattern ^[A-Za-z0-9][A-Za-z0-9_-]*$: it must start with an alphanumeric character and may only contain letters, digits, underscores and hyphens. Spaces, dots, slashes, leading hyphens/underscores, or unicode characters are rejected because the name becomes a TOML filename and identifier.

Source

Thrown at src/cli/agents.ts:48

  scope: AgentScope;
  path: string;
  file: string;
  name: string;
  description: string;
  model?: string;
}

function isReservedNativeAgentName(name: string): boolean {
  return RESERVED_NATIVE_AGENT_NAMES.has(name.trim());
}

function normalizeAgentName(name: string): string {
  const trimmed = name.trim();
  if (!trimmed) {
    throw new Error('agent name must not be empty');
  }
  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(trimmed)) {
    throw new Error(`invalid agent name: ${name}`);
  }
  if (isReservedNativeAgentName(trimmed)) {
    throw new Error(`"${trimmed}" is reserved by Codex built-in agents`);
  }
  return trimmed;
}

function resolveAgentsDir(scope: AgentScope, cwd = process.cwd()): string {
  return scope === 'project' ? projectCodexAgentsDir(cwd) : codexAgentsDir();
}

function parseScopeArg(args: string[]): AgentScope | undefined {
  for (let i = 0; i < args.length; i += 1) {
    const arg = args[i];
    if (arg === '--scope') {
      const value = args[i + 1];
      if (value === 'user' || value === 'project') return value;
      throw new Error('Expected --scope user|project');

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Rewrite the name using only A-Z a-z 0-9 _ - starting with a letter or digit
2. Remove file extensions and path separators
3. Quote shell arguments so spaces do not split — then remove the spaces

Example fix

# before
omx agent add "code reviewer"

# after
omx agent add code-reviewer

const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
if (!NAME_RE.test(name.trim())) {
  console.error('agent name must be alphanumeric/underscore/hyphen, starting alphanumeric');
  process.exit(2);
}

const isValidAgentName = (n: string): boolean => /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(n.trim());

When it happens

Trigger: addNativeAgent('my agent.toml'), addNativeAgent('-ops'), addNativeAgent('rev/iew'), or names with spaces passed unquoted through the shell.

Common situations: Descriptive names with spaces ('code reviewer'), file extensions included, path separators, or copy-pasted display names used as identifiers.

Related errors

• agent name must not be empty
• \"${trimmed}\" is reserved by Codex built-in agents
• catalog_manifest_invalid:agents[${index}]
• catalog_manifest_invalid:agents[${index}].category
• catalog_manifest_invalid:agents[${index}].status

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