Command system

Commands are user-facing actions invoked with a / prefix in the REPL (e.g., /commit, /review, /mcp). They live in src/commands/ and are registered in src/commands.ts (~25K lines).

Commands are distinct from tools. Tools are capabilities the LLM invokes autonomously during a query. Commands are actions the user invokes explicitly by typing /command-name.

Command types

Three command types cover the full range of use cases:

PromptCommand
LocalCommand
LocalJSXCommand

Sends a formatted prompt to the LLM with an injected tool allowlist. Used for AI-assisted actions like code review and commit message generation.

export type PromptCommand = {
  type: 'prompt'
  progressMessage: string
  contentLength: number
  argNames?: string[]
  allowedTools?: string[]   // Tool names or wildcard patterns
  model?: string            // Override the active model for this command
  source: SettingSource | 'builtin' | 'mcp' | 'plugin' | 'bundled'
  context?: 'inline' | 'fork'  // 'fork' runs as a sub-agent
  effort?: EffortValue
  getPromptForCommand(
    args: string,
    context: ToolUseContext,
  ): Promise<ContentBlockParam[]>
}

Example — the /insights command uses a lazy-loaded PromptCommand to defer a 113 KB module until invoked:

const usageReport: Command = {
  type: 'prompt',
  name: 'insights',
  description: 'Generate a report analyzing your Claude Code sessions',
  contentLength: 0,
  progressMessage: 'analyzing your sessions',
  source: 'builtin',
  async getPromptForCommand(args, context) {
    const real = (await import('./commands/insights.js')).default
    if (real.type !== 'prompt') throw new Error('unreachable')
    return real.getPromptForCommand(args, context)
  },
}

Runs in-process and returns plain text. Used for fast informational commands that do not require LLM involvement.

type LocalCommand = {
  type: 'local'
  supportsNonInteractive: boolean
  load: () => Promise<LocalCommandModule>
}

// Module shape returned by load()
export type LocalCommandModule = {
  call: (
    args: string,
    context: LocalJSXCommandContext,
  ) => Promise<LocalCommandResult>
}

export type LocalCommandResult =
  | { type: 'text'; value: string }
  | { type: 'compact'; compactionResult: CompactionResult; displayText?: string }
  | { type: 'skip' }

Examples: /cost, /version, /stats

Runs in-process and returns a React JSX node rendered to the terminal. Used for commands with rich interactive UI.

type LocalJSXCommand = {
  type: 'local-jsx'
  load: () => Promise<LocalJSXCommandModule>
}

// Module shape returned by load()
export type LocalJSXCommandModule = {
  call: (
    onDone: LocalJSXCommandOnDone,
    context: ToolUseContext & LocalJSXCommandContext,
    args: string,
  ) => Promise<React.ReactNode>
}

The onDone callback signals completion and can inject follow-up messages:

export type LocalJSXCommandOnDone = (
  result?: string,
  options?: {
    display?: 'skip' | 'system' | 'user'
    shouldQuery?: boolean      // Send messages to the model after completion
    metaMessages?: string[]    // Insert as isMeta (model-visible but hidden in UI)
    nextInput?: string
    submitNextInput?: boolean
  },
) => void

Examples: /doctor, /install, /onboarding

Command base shape

All three command types share a common CommandBase:

export type CommandBase = {
  name: string
  description: string
  aliases?: string[]
  availability?: CommandAvailability[]   // 'claude-ai' | 'console'
  isEnabled?: () => boolean              // GrowthBook / env var gating
  isHidden?: boolean                     // Hide from typeahead and /help
  argumentHint?: string                  // Displayed in gray after the command name
  whenToUse?: string                     // Usage guidance for the model
  isSensitive?: boolean                  // Args redacted from conversation history
  immediate?: boolean                    // Execute without waiting for a stop point
  userFacingName?: () => string          // Override the displayed name
}

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

Defining a command

A minimal PromptCommand definition:

const command = {
  type: 'prompt',
  name: 'review',
  description: 'AI-powered code review of staged/unstaged changes',
  progressMessage: 'reviewing changes',
  contentLength: 0,
  allowedTools: ['Bash(git *)', 'FileRead(*)'],
  source: 'builtin',
  async getPromptForCommand(args, context) {
    return [{ type: 'text', text: buildReviewPrompt(args) }]
  },
} satisfies Command

allowedTools accepts the same wildcard pattern format as the permission system:

Bash(git *)      # Allow all git subcommands
FileRead(*)      # Allow reading any file
FileEdit(/src/*) # Allow edits only under src/

How commands are invoked

User types /command-name

The REPL input handler detects the / prefix and looks up the command by name (or alias) in the registered command list.

Command type dispatch

LocalCommand — load() is called to lazy-load the module, then call() executes synchronously in-process. The text result appears in the REPL.
LocalJSXCommand — load() is called, then call() returns a React node that the REPL renders as a full-screen overlay.
PromptCommand — getPromptForCommand() builds the message content, which is injected into the conversation and submitted to the Query Engine with the command’s allowedTools as the active tool filter.

LLM context injection (PromptCommand only)

The Query Engine receives the formatted prompt and the allowedTools list. Tools not matching the allowlist are excluded from the API call’s tool spec, restricting what the model can invoke during the command’s execution.

Feature-flag gating and conditional imports

src/commands.ts gates a number of commands behind bun:bundle feature flags. Commands inside inactive flags are completely absent from production builds:

import { feature } from 'bun:bundle'

// Dead code elimination: inactive flags strip these require() calls at build time
const proactive =
  feature('PROACTIVE') || feature('KAIROS')
    ? require('./commands/proactive.js').default
    : null

const bridge = feature('BRIDGE_MODE')
  ? require('./commands/bridge/index.js').default
  : null

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

Environment-based conditional imports are used for internal-only commands:

const agentsPlatform =
  process.env.USER_TYPE === 'ant'
    ? require('./commands/agents-platform/index.js').default
    : null

Commands conditioned on process.env.USER_TYPE === 'ant' are Anthropic-internal and not available in public builds.

Command catalog

Git & version control

Command	Source	Description
`/commit`	`commit.ts`	Create a git commit with an AI-generated message
`/commit-push-pr`	`commit-push-pr.ts`	Commit, push, and create a PR in one step
`/branch`	`branch/`	Create or switch git branches
`/diff`	`diff/`	View file changes (staged, unstaged, or against a ref)
`/pr_comments`	`pr_comments/`	View and address PR review comments
`/rewind`	`rewind/`	Revert to a previous state

Code quality

Command	Source	Description
`/review`	`review.ts`	AI-powered code review of staged/unstaged changes
`/security-review`	`security-review.ts`	Security-focused code review
`/advisor`	`advisor.ts`	Get architectural or design advice
`/bughunter`	`bughunter/`	Find potential bugs in the codebase

Session & context

Command	Source	Description
`/compact`	`compact/`	Compress conversation context to fit more history
`/resume`	`resume/`	Restore a previous conversation session
`/session`	`session/`	Manage sessions (list, switch, delete)
`/export`	`export/`	Export conversation to a file
`/summary`	`summary/`	Generate a summary of the current session
`/clear`	`clear/`	Clear the conversation history

Configuration & settings

Command	Source	Description
`/config`	`config/`	View or modify Claude Code settings
`/permissions`	`permissions/`	Manage tool permission rules
`/model`	`model/`	Switch the active model
`/effort`	`effort/`	Adjust response effort level
`/theme`	`theme/`	Change the terminal color theme
`/vim`	`vim/`	Toggle vim mode for input

MCP, plugins & skills

Command	Source	Description
`/mcp`	`mcp/`	Manage MCP server connections
`/plugin`	`plugin/`	Install, remove, or manage plugins
`/reload-plugins`	`reload-plugins/`	Reload all installed plugins
`/skills`	`skills/`	View and manage skills

Diagnostics & status

Command	Source	Description
`/doctor`	`doctor/`	Run environment diagnostics
`/status`	`status/`	Show system and session status
`/cost`	`cost/`	Display token usage and estimated cost
`/stats`	`stats/`	Show session statistics
`/version`	`version.ts`	Show Claude Code version

IDE & desktop integration

Command	Source	Description
`/bridge`	`bridge/`	Manage IDE bridge connections (feature-gated)
`/ide`	`ide/`	Open in IDE
`/desktop`	`desktop/`	Hand off to the desktop app
`/teleport`	`teleport/`	Transfer session to another device

Get Started

Architecture

Subsystems

Reference

Command types

Command base shape

Defining a command

How commands are invoked

Feature-flag gating and conditional imports

Command catalog

See also

Build docs developers (and LLMs) love

Get Started

Architecture

Subsystems

Reference

​Command types

​Command base shape

​Defining a command

​How commands are invoked

​Feature-flag gating and conditional imports

​Command catalog

​See also

Build docs developers (and LLMs) love

Command types

Command base shape

Defining a command

How commands are invoked

Feature-flag gating and conditional imports

Command catalog

See also