Claude Code Command System: Six Sources, One Registry

When people first see a coding agent's slash commands, the assumption is that they are convenience aliases — shorthand for text the model could handle anyway.

That is not how Claude Code is structured.

The command system is part of the product runtime. It decides what command surface exists for the current session, enforces auth and environment gates, and — for some commands — determines whether execution stays on the main thread or forks into a sub-agent.

File structure

src/
├── services/
│   ├── plugins/
│   │   └── index.ts
├── skills/
│   └── index.ts
├── types/
│   └── command.ts

Two questions, two files

The command system answers two questions, and they are handled in separate files:

1. What commands exist right now? → commands.ts
2. What should happen with this specific user input? → processUserInput.ts

That split is not accidental. Loading commands is expensive (disk I/O, dynamic imports, auth checks). Processing input happens on every keystroke and submit. Keeping them separate means the expensive loading is memoized by cwd and auth changes invalidate selectively, not globally.

Command sources: six, merged in order

getCommands() returns a flat list, but that list is assembled from six sources:

The merge is not simply [...all]. Dynamic skills insert at the position of the first built-in command, not at the end. That insertion point is found by checking which commands are in COMMANDS() (the static built-in set):

const builtInNames = new Set(COMMANDS().map(c => c.name))
const insertIndex = baseCommands.findIndex(c => builtInNames.has(c.name))

return [
  ...baseCommands.slice(0, insertIndex),
  ...uniqueDynamicSkills,
  ...baseCommands.slice(insertIndex),
]

The position matters for UX — dynamic skills surface near the top of the command list, not buried after all the built-ins.

Availability gating

Not all commands from the merged list are returned. getCommands() filters by two predicates:

• meetsAvailabilityRequirement(cmd) — checks whether the current user's auth context satisfies the command's declared availability
• isCommandEnabled(cmd) — checks feature flags and other enable conditions

The availability check against auth context is what makes commands like /login appear conditionally:

export function meetsAvailabilityRequirement(cmd: Command): boolean {
  if (!cmd.availability) return true
  for (const a of cmd.availability) {
    switch (a) {
      case 'claude-ai':
        if (isClaudeAISubscriber()) return true
        break
      case 'console':
        // Direct Anthropic API key, not Bedrock/Vertex/3P proxy
        if (!isClaudeAISubscriber() && !isUsing3PServices() && isFirstPartyAnthropicBaseUrl())
          return true
        break
    }
  }
  return false
}

The implication: the command surface is not static. Auth state changes (like /login completing) can change which commands are available. getCommands() runs the availability and isEnabled checks on every call — only the expensive loading is memoized.

Remote and bridge safety: explicit allowlists

When Claude Code runs in remote mode (someone connects from a phone or web client), not all commands are safe to execute. The command system encodes this with two explicit allowlists:

REMOTE_SAFE_COMMANDS — commands safe to show in the REPL when --remote mode is active. These are UI and session-management commands that have no dangerous local side effects.

BRIDGE_SAFE_COMMANDS — commands safe to execute when the input arrived over the Remote Control bridge (mobile app sending slash commands to a desktop session). The distinction from REMOTE_SAFE_COMMANDS is the execution origin: bridge commands are triggered by a remote client, not a local user.

The safety classification follows a type rule:

export function isBridgeSafeCommand(cmd: Command): boolean {
  if (cmd.type === 'local-jsx') return false   // renders Ink UI — never safe remotely
  if (cmd.type === 'prompt') return true        // expands to text — safe by construction
  return BRIDGE_SAFE_COMMANDS.has(cmd)          // 'local' type — explicit opt-in required
}

local-jsx commands pop Ink UI pickers on the terminal. Sending /model from iOS and watching a picker open on the desktop was the real incident that motivated this allowlist (referenced in the source comment as PR #19134).

// loadAllCommands is memoized by cwd — expensive loading happens once
const loadAllCommands = memoize(async (cwd) => {
const [{ skillDirCommands, pluginSkills, bundledSkills }, pluginCommands, workflowCommands] =
  await Promise.all([getSkills(cwd), getPluginCommands(), getWorkflowCommands(cwd)])

return [...bundledSkills, ...skillDirCommands, ...workflowCommands, ...pluginCommands, ...pluginSkills, ...COMMANDS()]
})

// getCommands runs availability/enabled checks fresh every call
export async function getCommands(cwd) {
const allCommands = await loadAllCommands(cwd)
const dynamicSkills = getDynamicSkills()

const baseCommands = allCommands.filter(
  cmd => meetsAvailabilityRequirement(cmd) && isCommandEnabled(cmd)
)

// Insert dynamic skills at the right position, not the tail
const builtInNames = new Set(COMMANDS().map(c => c.name))
const insertIndex = baseCommands.findIndex(c => builtInNames.has(c.name))
if (insertIndex === -1) return [...baseCommands, ...uniqueDynamicSkills]

return [
  ...baseCommands.slice(0, insertIndex),
  ...uniqueDynamicSkills,
  ...baseCommands.slice(insertIndex),
]
}

The input routing layer

commands.ts builds the command list. processUserInput.ts decides what to do with a specific message. The pipeline there handles:

1. Image and attachment normalization — images, file paths, and memory attachments are extracted before routing
2. Hook processing — pre_tool_use and similar hooks can intercept and transform input
3. Bridge origin check — input arriving over the bridge is checked against isBridgeSafeCommand before the slash handler runs
4. Slash dispatch — if the trimmed message starts with /, the runtime checks if it matches a command and executes it; if not, it is treated as plain text

The bridge safety check is where the /model on iOS → desktop Ink picker problem was fixed. The fix was not to detect the mobile client and skip the command — it was to make the allowlist explicit and default-deny for local-jsx commands regardless of origin.

What this means for extensibility

The command system is designed for extension at three levels:

• Project level: drop a .md file in .claude/commands/ and the skill is discovered on next getCommands() call
• Plugin level: install a plugin and its commands appear in the filtered list
• Runtime level: skills discovered during file operations (CLAUDE.md parsing) insert mid-session without requiring a restart

The key design decision is that extension points are additive, not overriding. Skills and plugins can add commands, but they cannot replace built-in commands. The priority order (bundled first, built-ins last) enforces that.