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

agent name must not be empty

Error message

agent name must not be empty

What it means

normalizeAgentName trims the agent name and rejects an empty/whitespace-only result. Every agent subcommand (add/edit/remove) normalizes names first, so this fires before any filesystem access.

Source

Thrown at src/cli/agents.ts:45

type AgentScope = 'user' | 'project';

export interface NativeAgentInfo {
  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') {

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Check the name variable is set and non-empty before calling
2. Skip blank entries when iterating a list of names
3. Default to a concrete name in scripts

Example fix

# before
omx agent add "$AGENT_NAME"  # AGENT_NAME unset -> ''

# after
[ -n "$AGENT_NAME" ] || { echo 'AGENT_NAME required'; exit 1; }
omx agent add "$AGENT_NAME"

const name = String(rawName ?? '').trim();
if (!name) {
  console.error('agent name is required');
  process.exit(2);
}

const isNonEmptyName = (n: unknown): n is string => typeof n === 'string' && n.trim().length > 0;

When it happens

Trigger: Calling addNativeAgent(''), addNativeAgent(' '), or a CLI invocation like `omx agent add ""` where the name comes from an empty variable.

Common situations: Unset/empty shell variables in scripts ($AGENT_NAME not exported), reading names from a config list with blank lines, or programmatic loops over sparse arrays.

Related errors

• invalid agent name: ${name}
• \"${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/f7c9831d7ae12310. Report an issue: GitHub.