Command Surface

This page answers “how users access Claude Code’s capabilities.” 97 command entries form the system’s operation surface — the user-facing facade of tool capabilities. Understanding the distinction between commands and tools is key to understanding this system.

Visual companion: Commands page

Command-Tool Relationship

    flowchart LR
  subgraph User Surface
    U[User /command] --> CMD[Command router<br>src/commands/]
  end
  subgraph Orchestration
    CMD -->|Direct binding| T1[Single tool]
    CMD -->|Multi-tool| T2[Model selects tools]
    CMD -->|Service chain| S[Service calls]
    CMD -->|Independent| I[Internal logic]
  end
  subgraph Capability Surface
    T1 --> TOOL[Tool system<br>src/tools/]
    T2 --> TOOL
  end
  

Commands vs Tools

Key insight: Seeing a /commit command does not mean there’s a CommitTool. Commands are more like product entry points that orchestrate multiple tool capabilities together. Conversely, many tools (like FileEditTool) never need explicit user invocation — the model selects them automatically during the main loop.

Command Overview

Seven Groups

1. Setup & Config (22 commands, 73 files)

Installation, authentication, model selection, plugin management, permission settings, and environment configuration.

2. Daily Workflow (23 commands, 44 files)

Day-to-day coding, session recovery, planning, summarization, and task advancement.

3. Review & Git (10 commands, 18 files)

Branch management, commits, PRs, diffs, security reviews, and issue tracking.

4. Debugging & Diagnostics (18 commands, 26 files)

Problem diagnosis, metric observation, cache debugging, and internal tracing.

5. Bridge & Remote (7 commands, 12 files)

IDE bridging, cross-device connection, and remote control.

6. Experimental Surface (13 commands, 24 files)

Product-surface exploration entries that reveal direction.

7. Agents & Extensions (4 commands, 7 files)

Sub-agent management, Vim mode, and internal migration commands.

Command-to-Tool Mapping

Commands and tools are not one-to-one. A single command may orchestrate multiple tools, and a single tool may serve multiple commands. Here are the primary mapping relationships:

Reading this table:

• “Direct binding” means 1:1 command-to-tool correspondence
• “Multi-tool orchestration” means the model automatically selects multiple tools based on context
• “Service chain” means the command triggers a sequence of service calls, not going through the standard tool system
• “Independent path” means the command entirely bypasses tools and model, executing internal logic directly

This also explains why the command count (97) far exceeds the tool count (43) — commands are user-facing product entries, tools are model-facing capability surfaces; the mapping between them is not linear.

Feature-Flagged Commands

Of the 97 commands, a significant portion is controlled by feature flags and only appears under specific conditions. Their existence signals system evolution direction.

Key feature-flagged clusters:

• Diagnostic tools: ctx_viz, debug-tool-call, ant-trace, heapdump — internal debugging capabilities
• Experimental surface: ultraplan, advisor, thinkback — product direction exploration
• Remote connections: bridge, desktop, mobile — cross-interface extension

Reading Order

1. Tool Plane — Understand the capabilities behind commands
2. Runtime Loop — See how commands enter the main loop
3. Signals & Extensions — See the relationship between experimental commands and signals