Introducing a new way to review your PRs.

Read the announcement

anthropics / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

View on GitHub

13 documents · Updated Nov 16, 2026

docs / diff-entrypoints-and-command-routing

Diff entrypoints and command routing

Overview

The diff mod is packaged as a Claude plugin by mods/…/plugin.json, which names the plugin diff and describes the /diff pane behavior users see. Runtime hook loading starts at mods/…/hooks.json: it declares ./register.ts as the only hook module, so mods/…/register.ts is the orchestrator for every user-facing entry into the diff subsystem. mods/…/README.md is the behavioral contract for that orchestrator: /diff toggles the pane or dialog, first edits may open it automatically, open panes refresh after edits and shell commands, and an ask button can attach one file's hunks to the next prompt.

mods/…/register.ts binds the engine during session.start. The bind helper wraps $ into a Host object, records the session start time from $.session.usage().startedAt when isRecord accepts that usage object, stores the session cwd for later git processes, and calls $.command.register(COMMAND_SPEC). COMMAND_SPEC comes from mods/…/command-spec.ts and uses Names.COMMAND_NAME (diff) plus Names.COMMAND_DESCRIPTION (Toggle the diff panel showing uncommitted changes). If command registration is refused with the built-in ownership message matched by mods/…/builtin-holds-pattern.ts, register.ts leaves host unset and the plugin stands down; if another registration error occurs, it writes Names.registerFailedTextOf(...) to $.ui.log so the transcript says the panel is unavailable.

The main /diff route is the command.run hook in mods/…/register.ts filtered to { command: 'diff' }. It drops overlapping toggles with the isToggling guard, pins a git backend on first open, and then uses PaneToggle.paneToggleOf to choose open, close, or too-narrow from the current pane belief and the command presentation. Opening calls openPane, which may fetch diff data before seating a docked pane, opens pane id Names.PANE_ID (diff) with title Names.PANE_TITLE (Diff), and returns transcript text from the name constants: Diff panel shown, Diff panel hidden, Diff dialog dismissed, Nothing here can draw the diff panel yet; it opens as soon as something can, Resize your terminal to at least 110 columns to show the diff panel, or the git/no-repository messages. Once a docked pane is placed, register.ts registers DOCKED_COMMAND_SPEC from mods/…/docked-command-spec.ts, which is the same command spec with immediate: true so /diff can close the docked pane even during an active turn. Inline/dialog usage keeps the normal, non-immediate spec because that dialog takes keyboard focus.

Other user-facing routes in mods/…/register.ts feed the same pane state. ui.render for PromptHint records viewport width and fullscreen/docked capability, which gates automatic first-edit opens. ui.render for Pane resolves engine UI primitives, verifies requestId === Names.PANE_ID, marks an awaited open as shown, updates placement and body dimensions, and delegates drawing/actions to Views.paneView. ui.close either backs an inline dialog out of detail view or records a person close and persists Names.STORE_OPEN_KEY (open) as false for docked panes. ui.scroll owns docked pane body/list scrolling. ui.focus is filtered by Names.PLUGIN_NAMES (diff and cc-plugin-diff) so focus events stamped with either plugin name can keep the inline dialog's selected file centered.

Edits and commands enter through the tool.call hook in mods/…/register.ts, filtered to the tool constants in mods/…/editing-tools.ts (Edit, Write, NotebookEdit) and mods/…/shell-tools.ts (Bash, PowerShell). afterTool increments the landed-change counter for successful edits or shell calls that mods/…/may-have-written.ts does not mark read-only. Landed changes refresh an already seen pane; a main-loop edit with no agentId can trigger the first automatic open, while any later landed change can retry an automatic open that previously found nothing to show. /clear and /resume are also routed through command.run in register.ts: after the underlying command completes, they unpin repository state, clear ask state and queued refresh state, reset the model, and either keep an open pane across /clear with a fresh read or close/reopen for restored /resume turns.

The ask route starts in pane actions inside mods/…/register.ts: toggleAsk calls Ask.armedAskOf from mods/…/armed-ask-of.ts, which turns one file path plus its hunks into an ArmedAsk with a provenance line and unified hunk text capped at Limits.MAX_LINES_PER_FILE. The selected path is stored in model.armedPath, and $.ui.status tells the user that the file will ride the next prompt. On prompt.submit, register.ts computes remaining prompt-context room, calls Ask.fittedAskTextOf from mods/…/fitted-ask-text-of.ts, and appends the ask text to e.context if it fits. If it does not fit even past the first hunk line, the ask is dropped, the status explains that the diff did not fit, and the prompt continues without extra context. When an ask is attached and the prompt is accepted, Record.recorderOf(...).asked() logs diff_selection_attach, then the ask is disarmed so it is one-shot.

Small helper modules under this doc's scope keep the routes defensive and user-facing text stable. mods/…/message-of.ts converts any caught value to text before regex matching built-in command ownership or printing registration errors. mods/…/is-record.ts is used in register.ts and in the direct dependency mods/…/open-outcome-of.ts to safely inspect engine-returned objects such as session usage and $.ui.open results. mods/diff/hooks/names/** centralizes command names, pane IDs, store keys, plugin names, and transcript/status strings so tests can assert exact built-in-compatible wording.

The bootstrap tests under mods/diff/tests/** are broad, but the routing coverage is concentrated in mods/…/register.test.ts, mods/…/fitted-ask-text-of.test.ts, and fixtures such as mods/…/diff.ts, mods/…/dialog-diff.ts, mods/…/diff-at.ts, mods/…/read-only-answer.ts, mods/…/typed-prompt-of.ts, and mods/…/unsaid-hint.ts. Those tests assert that startup runs no git, built-in /diff ownership makes the plugin idle, docked opens re-register /diff as immediate, too-narrow/fullscreen/dialog command presentations produce the expected answers, read-only shell commands do not refresh, automatic opens are gated by viewport and checkpointing, no-surface opens are kept until drawn, and ask context is attached or dropped according to prompt room.

Coverage/routing

  • mods/diff/.claude-plugin/**: plugin metadata; currently plugin.json names/describes the plugin.
  • mods/…/README.md: user-facing behavior and hook/event contract for the diff pane.
  • mods/…/hooks.json: hook loader entry that points at register.ts.
  • mods/…/index.ts: barrel export for the diff hook package, including register.js and helper modules.
  • mods/…/register.ts: central hook registration and routing for /diff, render/close/scroll/focus events, edit/shell refresh triggers, /clear, /resume, and prompt ask attachment.
  • mods/diff/hooks/command-spec/**: /diff command specs, including the docked immediate variant.
  • mods/diff/hooks/ask/**: armed ask shape, ask text construction, and prompt-context fitting/cut note.
  • mods/diff/hooks/message-of/**: caught-value-to-message helper used by registration/probe error handling.
  • mods/diff/hooks/names/**: command/pane/store identifiers and exact user-facing strings.
  • mods/diff/hooks/is-record/**: object-shape guard used before reading engine-returned records.
  • mods/diff/tests/**: tests and fixtures that exercise the routing, command presentation, automatic open, refresh trigger, and ask flows.

Coupling

Risks

  • mods/…/register.ts has many interacting asynchronous gates (isToggling, probing, isRefreshing, isRefreshQueued, isOpenAskKept, awaited, pin.epoch, and personCloses). If one branch stops checking the epoch or close count, a stale automatic open can seat a pane after /clear, /resume, or a person close. mods/…/register.test.ts carries many regression cases for these races, and history shows repeated routing fixes around automatic open/read timing, including 2287e5d, 92ec78f, and 7974a70.
  • mods/…/register.ts relies on exact built-in-compatible engine wording for standing down (Names.BUILTIN_HOLDS_PATTERN) and for awaited no-surface opens via openOutcomeOf. If the engine changes these strings without updating mods/…/builtin-holds-pattern.ts or mods/…/open-outcome-of.ts, the plugin may either log an alarming registration failure while the built-in owns /diff, or withdraw a pane that should wait for a future surface.
  • mods/…/docked-command-spec.ts intentionally changes /diff to immediate: true only after a docked pane is placed. If that registration moves earlier or starts applying to inline dialogs, /diff can run during turns when permission prompts need the keyboard; if it is omitted, users cannot close an auto-opened docked pane until the turn ends. mods/…/register.test.ts has an explicit "once docked" assertion for this transition.
  • mods/…/fitted-ask-text-of.ts counts JavaScript string lengths against Limits.PROMPT_CONTEXT_MAX_CHARS, not tokens or display cells. If prompt context accounting changes elsewhere, this helper can either drop useful asks too aggressively or attach text that the engine later rejects; keep the fitting tests in mods/…/fitted-ask-text-of.test.ts aligned with the engine's context contract.