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

Expected --scope user|project

Error message

Expected --scope user|project

What it means

The --scope flag was given as two arguments (`--scope <value>`) but the following value is neither 'user' nor 'project'. The one-argument forms --scope=user/--scope=project are validated by exact match, so this error specifically indicates `--scope foo`, `--scope` at end of args, or `--scope` followed by another flag.

Source

Thrown at src/cli/agents.ts:66

    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');
    }
    if (arg === '--scope=user') return 'user';
    if (arg === '--scope=project') return 'project';
  }
  return undefined;
}

function inferMutationScope(cwd = process.cwd()): AgentScope {
  const persistedScopePath = join(cwd, '.omx', 'setup-scope.json');
  if (existsSync(persistedScopePath)) {
    try {
      const parsed = JSON.parse(readFileSync(persistedScopePath, 'utf8')) as { scope?: string };
      if (parsed.scope === 'project' || parsed.scope === 'project-local') return 'project';
      if (parsed.scope === 'user') return 'user';
    } catch {
      // fall through
    }
  }

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Use `--scope user` or `--scope project` (or `--scope=user`)
2. Ensure a value follows --scope and is not another flag
3. Omit --scope entirely to use the inferred default

Example fix

# before
omx agent add x --scope --force

# after
omx agent add x --scope project --force

const i = args.indexOf('--scope');
if (i !== -1 && !['user', 'project', '--scope=user', '--scope=project'].some(v => args.includes(v))) {
  const v = args[i + 1];
  if (v !== 'user' && v !== 'project') { console.error('scope must be user|project'); process.exit(2); }
}

const isScopeValue = (v: unknown): v is 'user' | 'project' => v === 'user' || v === 'project';

When it happens

Trigger: `omx agent add x --scope team`, `omx agent add x --scope` (missing value), or `--scope --force` where the next token is consumed as the value.

Common situations: Missing value after --scope, expecting other scopes (org/team), or flag ordering that lets another flag be eaten as the scope value.

Related errors

• agent name must not be empty
• invalid agent name: ${name}
• \"${trimmed}\" is reserved by Codex built-in agents
• agent already exists: ${path}
• agent not found: ${normalized}

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