Skip to content

source-map.en.md

Latest commit

 

History

History
206 lines (162 loc) · 9.54 KB

source-map.en.md

File metadata and controls

206 lines (162 loc) · 9.54 KB

Claude Code Mainline Source Map

中文 | English

This map answers one question only: where is a request on the mainline right now, and where should you trace next?

If you do not yet have the mainline in your head, go back to the Learning Paths. If you are coming from an example, open the example-to-source bridge first.

Request lifecycle at a glance

flowchart TD
    A([User input]) --> B

    subgraph S1[“Step 1 · Startup / mode routing”]
        B[“main.tsx → setup.ts → entrypoints/”]
    end

    subgraph S2[“Step 2 · Enter query / queryLoop”]
        C[“QueryEngine.ts → query.ts\nasync function* query()”]
    end

    subgraph S3[“Step 3 · Model call / output parsing”]
        D[“services/api/claude.ts\nqueryModelWithStreaming”]
    end

    subgraph S4[“Step 4 · Tool execution”]
        E[“bashPermissions.ts\nsemantic deny → rule match → ask user”]
    end

    subgraph S5[“Step 5 · tool_result flows back”]
        F[“Append to message history\nsame queryLoop turn continues”]
    end

    subgraph S6[“Step 6 · State / UI update”]
        G[“REPL.tsx + bootstrap/state.ts”]
    end

    B --> C
    C --> D
    D -->|”tool_use”| E
    E --> F
    F -->|”back to while true”| D
    D -->|”end_turn”| G
    G --> H{Next turn?}
    H -->|”user continues”| C
    H -->|”exit”| Z([Done])
Loading

How to use this map

  1. First locate which mainline step you are standing on.
  2. Use the input / output pair to verify what this step actually finishes.
  3. Open only 1 to 2 core files first, and search 2 to 4 symbols before broadening out.
  4. Follow the “next flow” line instead of reading every side system in parallel.

Step 1 — Startup / mode routing

  • Mainline position: user input → startup / mode routing

  • Input: CLI args, current working directory, config / environment, runtime mode selection

  • Output: a chosen entrypoint, baseline setup completion, and a decision to enter interactive, headless, bridge, or another runtime surface

  • Open these files first:

  • claudecode_src/src/main.tsx

  • claudecode_src/src/setup.ts

  • claudecode_src/src/cli/print.ts

  • Search these symbols first:

  • main

  • setup

  • runHeadless

  • Next flow: Move into Step 2, where the prompt, history, and tool context are actually handed to query / queryLoop.

Step 2 — Enter query / queryLoop

  • Mainline position: startup complete → enter the single-turn request loop

  • Input: chosen runtime mode, current session state, user message / initial message, tool context

  • Output: QueryEngine or the REPL hands one turn to query, and queryLoop starts the async-generator mainline

  • Open these files first:

  • claudecode_src/src/QueryEngine.ts

  • claudecode_src/src/query.ts

  • claudecode_src/src/screens/REPL.tsx

  • Search these symbols first:

  • QueryEngine

  • query

  • queryLoop

  • processInitialMessage

  • Next flow: Continue to Step 3 to see how the model request is sent and why the returned assistant content becomes either “continue talking” or “call a tool.”

Step 3 — Model output / tool selection

  • Mainline position: inside queryLoop → call the model → parse streaming events → decide whether a tool_use should happen

  • Input: current message history, system prompt, model configuration, available tool set

  • Output: assistant text blocks, tool_use blocks, stop reasons, and the event stream that drives the next step

  • Open these files first:

  • claudecode_src/src/query.ts

  • claudecode_src/src/services/api/claude.ts

  • claudecode_src/src/tools.ts

  • claudecode_src/src/Tool.ts

  • Search these symbols first:

  • queryModelWithStreaming

  • getTools

  • buildTool

  • isWithheldMaxOutputTokens

  • Next flow: If the model emits tool_use, continue to Step 4. If it produces a directly displayable assistant result, skip ahead to Step 6 / Step 7 for state updates and exit conditions.

Step 4 — Tool execution

Step 5 — Tool result re-entry

  • Mainline position: tool execution finishes → results are written back into message history → the same queryLoop turn keeps advancing

  • Input: tool output, denial / error messages, existing assistant trajectory

  • Output: user-side messages containing tool_result, updated turn history, and the next model-call input

  • Open these files first:

  • claudecode_src/src/query.ts

  • claudecode_src/src/services/api/claude.ts

  • claudecode_src/src/utils/contentArray.ts

  • Search these symbols first:

  • tool_result

  • queryLoop

  • normalizeMessagesForAPI

  • insertBlockAfterToolResults

  • Next flow: Step 5 is the control-flow continuation of the same turn: once the tool result is written back into history, queryLoop returns to Step 3 for the next model continuation. Step 6 is not a separate control path; it is the UI / state observation surface for those same events.

Step 6 — State / UI update

  • Mainline position: as turn events advance, the REPL and app state make the current status visible

  • Input: query events, message history, loading / permission / notification state, initial messages, and command-entry state

  • Output: terminal rendering, session-state updates, and user-visible messages / tool results / prompts

  • Open these files first:

  • claudecode_src/src/bootstrap/state.ts

  • claudecode_src/src/screens/REPL.tsx

  • claudecode_src/src/components/Messages.tsx

  • claudecode_src/src/history.ts

  • Search these symbols first:

  • DO NOT ADD MORE STATE HERE

  • REPL

  • processInitialMessage

  • setAppState

  • Next flow: If the current turn is still running, keep following Step 3 / Step 5 events. If the turn has converged, move to Step 7 to see whether the runtime continues or exits.

Step 7 — Next turn / exit conditions

Common extensions outside the spine