The Commands System

1. What Is a Command?

Every /something you type in Claude Code is a Command — a TypeScript object that carries metadata (name, description, availability) plus one of three execution strategies (local, local-jsx, or prompt). Commands live in src/commands.ts and the src/commands/ directory tree.

The top-level type is a discriminated union:

export type Command = CommandBase &
  (PromptCommand | LocalCommand | LocalJSXCommand)

The discriminant is the type field — every command object must declare exactly one of the three string literals: "local", "local-jsx", or "prompt".

2. Three Command Types

Type decision tree

const compact = {
  type: 'local',
  name: 'compact',
  description: 'Clear conversation history but keep a summary in context',
  isEnabled: () => !isEnvTruthy(process.env.DISABLE_COMPACT),
  supportsNonInteractive: true,
  argumentHint: '<optional custom summarization instructions>',
  load: () => import('./compact.js'),
} satisfies Command

export const call: LocalCommandCall = async (args, context) => {
  // args = trimmed string after "/compact"
  // context = ToolUseContext + REPL state
  const customInstructions = args.trim()
  // ... runs compaction, returns:
  return { type: 'compact', compactionResult, displayText }
}

const help = {
  type: 'local-jsx',
  name: 'help',
  description: 'Show help and available commands',
  load: () => import('./help.js'),
} satisfies Command

export const call: LocalJSXCommandCall = async (
  onDone,
  { options: { commands } },
) => {
  return <HelpV2 commands={commands} onClose={onDone} />
}

export default {
  type: 'local-jsx',
  name: 'model',
  get description() {
    return `Set the AI model (currently ${renderModelName(getMainLoopModel())})`
  },
  argumentHint: '[model]',
  get immediate() {
    return shouldInferenceConfigCommandBeImmediate()
  },
  load: () => import('./model.js'),
}

const command = {
  type: 'prompt',
  name: 'commit',
  description: 'Create a git commit',
  allowedTools: ['Bash(git add:*)', 'Bash(git status:*)', 'Bash(git commit:*)'],
  contentLength: 0,  // 0 = dynamic (computed at call time)
  progressMessage: 'creating commit',
  source: 'builtin',
  async getPromptForCommand(_args, context) {
    const promptContent = getPromptContent()
    const finalContent = await executeShellCommandsInPrompt(
      promptContent, context, '/commit'
    )
    return [{ type: 'text', text: finalContent }]
  },
} satisfies Command

3. The CommandBase Contract

All three types share a common base. The most important fields:

4. Registration Pipeline

Commands reach the REPL through a multi-stage assembly pipeline in src/commands.ts:

Stage 1: Static core commands (COMMANDS())

A memoized function returns the canonical list of ~80 built-in commands — /help, /model, /clear, /compact, /commit, /review, etc. It is declared as a function (not a constant) so that it executes after config is readable at startup:

const COMMANDS = memoize((): Command[] => [
  addDir, advisor, agents, branch, btw,
  clear, compact, config, cost, diff, ...
  // feature-flagged commands are spread conditionally:
  ...(ultraplan ? [ultraplan] : []),
  ...(!isUsing3PServices() ? [logout, login()] : []),
])

Stage 2: Dynamic command sources (loadAllCommands)

All non-static sources are loaded in parallel and merged. The merge order is deterministic and matters for deduplication:

const loadAllCommands = memoize(async (cwd: string) => {
  const [
    { skillDirCommands, pluginSkills, bundledSkills, builtinPluginSkills },
    pluginCommands,
    workflowCommands,
  ] = await Promise.all([
    getSkills(cwd),
    getPluginCommands(),
    getWorkflowCommands ? getWorkflowCommands(cwd) : Promise.resolve([]),
  ])

  return [
    ...bundledSkills,         // lowest index → highest priority in dedup
    ...builtinPluginSkills,
    ...skillDirCommands,
    ...workflowCommands,
    ...pluginCommands,
    ...pluginSkills,
    ...COMMANDS(),            // built-ins last
  ]
})

Stage 3: Filtering and dynamic skill insertion (getCommands)

Every call to getCommands(cwd) re-runs availability and isEnabled checks against the memoized command pool. Dynamic skills (discovered during file operations) are inserted just before the built-in commands block:

export async function getCommands(cwd: string): Promise<Command[]> {
  const allCommands = await loadAllCommands(cwd)
  const dynamicSkills = getDynamicSkills()

  const baseCommands = allCommands.filter(
    _ => meetsAvailabilityRequirement(_) && isCommandEnabled(_)
  )
  // Insert dynamic skills at the right position...
}

export const INTERNAL_ONLY_COMMANDS = [
  backfillSessions,
  breakCache,
  bughunter,
  commit,
  commitPushPr,
  mockLimits,
  bridgeKick,
  // ...many more
].filter(Boolean)

// Inside COMMANDS():
...(!process.env.IS_DEMO && process.env.USER_TYPE === 'ant'
  ? INTERNAL_ONLY_COMMANDS : [])

5. Input Processing

When the user submits text starting with /, the REPL runs lookup and dispatch before anything touches the model. The key helpers live at the bottom of src/commands.ts:

Lookup functions

// Returns the first Command matching by name, userFacingName, or alias
export function findCommand(commandName: string, commands: Command[]): Command | undefined

// Presence check (wraps findCommand)
export function hasCommand(commandName: string, commands: Command[]): boolean

// Throws ReferenceError listing all available commands if not found
export function getCommand(commandName: string, commands: Command[]): Command

The findCommand matcher checks three things in order: _.name === commandName, getCommandName(_) === commandName (the user-facing override), and _.aliases?.includes(commandName). This is why /reset and /new both trigger the clear command.

Argument passing

Everything after the command name (trimmed) is the args string. There is no framework-level argument parsing — each command is responsible for interpreting its own args. /compact focus on the database layer delivers "focus on the database layer" to the compact handler, which passes it to the summarization model as customInstructions.

Shell command substitution in prompts

Prompt commands often embed shell output inline. The executeShellCommandsInPrompt utility scans prompt text for !`shell command` patterns and replaces them with live output before the prompt reaches the model. /commit uses this to automatically inject git status, git diff HEAD, and recent log output:

const PROMPT = `## Context

- Current git status: !\`git status\`
- Current git diff: !\`git diff HEAD\`
- Current branch: !\`git branch --show-current\`
- Recent commits: !\`git log --oneline -10\`

## Your task
Based on the above changes, create a single git commit...`

Description formatting for UI vs model

The formatDescriptionWithSource(cmd) utility adds a provenance annotation for user-facing surfaces (typeahead, help screen) without polluting the model-facing description. A skill from a plugin named "frontend-design" displays as "(frontend-design) Polish and refine UI components" in autocomplete, but the model only sees "Polish and refine UI components".

6. REPL Integration

The REPL (Read-Eval-Print Loop) is the heart of the interactive session. It renders via launchRepl in src/replLauncher.tsx, which lazy-loads the App and REPL Ink components. Commands flow through the REPL in three distinct dispatch paths depending on their type:

The processSlashCommand flow

Inside the REPL, slash command handling follows this sequence:

The immediate flag on a command bypasses the normal "wait for any in-flight AI request to stop" behavior. /status sets immediate: true so you can check connection status even while a long generation is running.

Result handling by type

type LocalJSXCommandOnDone = (
  result?: string,
  options?: {
    display?: 'skip' | 'system' | 'user'  // default: 'user'
    shouldQuery?: boolean               // send messages to model after done
    metaMessages?: string[]            // model-visible but hidden from UI
    nextInput?: string                 // pre-fill the input box
    submitNextInput?: boolean          // auto-submit nextInput
  }
) => void

7. Availability & Feature Gating

Commands have two independent gate layers that both must pass before the command appears in the REPL:

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':
        if (!isClaudeAISubscriber() && !isUsing3PServices()
            && isFirstPartyAnthropicBaseUrl()) return true; break
    }
  }
  return false
}

Feature-flagged commands

Several commands only exist when a Bun bundle feature flag is active. At build time, Bun's dead-code elimination drops the entire require chain if the feature is off:

const ultraplan = feature('ULTRAPLAN')
  ? require('./commands/ultraplan.js').default
  : null

const voiceCommand = feature('VOICE_MODE')
  ? require('./commands/voice/index.js').default
  : null

// Then in COMMANDS():
...(ultraplan ? [ultraplan] : []),
...(voiceCommand ? [voiceCommand] : []),

8. Cache Management

Command loading is expensive — it involves disk I/O, YAML parsing, dynamic imports, and MCP round-trips. Three layers of memoization keep repeated calls fast:

Two granular clear functions exist for different invalidation scenarios:

// Clears command memoization only — does NOT clear skill file caches.
// Use when dynamic skills are added mid-session.
export function clearCommandMemoizationCaches(): void {
  loadAllCommands.cache?.clear?.()
  getSkillToolCommands.cache?.clear?.()
  getSlashCommandToolSkills.cache?.clear?.()
  clearSkillIndexCache?.()  // outer search index must also be cleared
}

// Full reset: command + plugin + skill file caches.
// Use when plugins are installed/removed or skills dir changes.
export function clearCommandsCache(): void {
  clearCommandMemoizationCaches()
  clearPluginCommandCache()
  clearPluginSkillsCache()
  clearSkillCaches()
}

9. Bridge & Remote Mode

Claude Code can run in a remote mode (accessed via browser/mobile) and can receive commands over a bridge (the Remote Control protocol). Both modes restrict which commands are available.

Remote-safe commands (--remote flag)

When Claude Code starts with --remote, only commands in REMOTE_SAFE_COMMANDS are made available before the CCR init message arrives. These are commands that only affect local TUI state and do not touch the filesystem, git, shell, or IDE:

export const REMOTE_SAFE_COMMANDS: Set<Command> = new Set([
  session,    // Shows QR code / URL for remote session
  exit,       // Exit the TUI
  clear,      // Clear screen
  help,       // Show help
  theme,      // Change terminal theme
  cost,       // Show session cost
  plan,       // Plan mode toggle
  // ...more
])

Bridge-safe commands

The bridge (mobile/web client) sends slash commands over a Remote Control connection. The isBridgeSafeCommand predicate determines which ones execute rather than getting silently dropped:

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

The rule is intuitive: local-jsx commands render terminal UI that the bridge client can't display, so they are always blocked. prompt commands just generate text, so they are always safe. Plain local commands must be explicitly listed in BRIDGE_SAFE_COMMANDS — by default they are blocked. The allowlist includes /compact, /clear, /cost, /files, and a few others.

10. Key Takeaways

• 🔵
  Every slash command is a Command object — a CommandBase discriminated union of three execution types: local (pure TS function), local-jsx (Ink component), and prompt (text injected into model context).
• ⚡
  Both local and local-jsx commands use lazy loading via load: () => import('./cmd.js') — the implementation module is not imported until the command is actually invoked, keeping startup time fast.
• 🔀
  The registration pipeline merges bundled skills, plugin skills, skill dir commands, workflows, plugin commands, and static built-ins via loadAllCommands(cwd), then filters by availability and isEnabled on every getCommands() call.
• 🛡️
  Two independent gates control visibility: availability (static auth-provider check, re-evaluated per call) and isEnabled() (runtime feature-flag check). Both must pass. Neither is memoized, so auth changes take effect immediately.
• 🌐
  Bridge and remote mode apply a third filter. local-jsx commands are always blocked over the bridge (they render terminal UI). prompt commands are always allowed. local commands require explicit opt-in via BRIDGE_SAFE_COMMANDS.
• 📝
  Prompt commands use shell substitution via !`cmd` patterns to embed live shell output into the prompt before it reaches the model — this is how /commit auto-injects git status, git diff HEAD, and recent log without you needing to paste them.
• 🔒
  Internal-only commands (/commit, /bughunter, etc.) are wrapped in INTERNAL_ONLY_COMMANDS and dead-code-eliminated by Bun at build time in the public binary — they do not exist at all in the version users install.

11. Quiz