1 · The Entry Layer and Startup

This chapter covers what the program does between the moment you type claude in the terminal and the moment the interface appears.

1.1 Four launch modes

The same executable enters one of four completely different run modes depending on its arguments:

1.2 The first design decision at startup: fast-path dispatch

entrypoints/cli.tsx is the real program entry point, and it is only 302 lines. Its header comment gets straight to the point:

Why this matters

First, a bit of background: when a JavaScript program “imports” a module, that module’s top-level code runs immediately. If a program statically imports several hundred modules, then merely starting up means executing all several hundred of them, even if this particular run never uses them.

Bundled, Claude Code is a 300 MB single-file program with an enormous number of modules. If every run loaded all of it, even claude --version — a command that just wants to glance at the version number — would take several seconds.

So the entry file uses dynamic imports — a branch’s modules are loaded only when execution actually reaches that branch:

async function main(): Promise<void> {
  const args = process.argv.slice(2);          // grab the command-line arguments

  // Fast path 1: --version, zero modules loaded
  if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
    console.log(`${MACRO.VERSION} (Claude Code)`);   // the version is baked in at compile time
    return;                                     // return immediately; nothing was loaded
  }

  // Only the remaining paths load the startup profiler
  const { profileCheckpoint } = await import('../utils/startupProfiler.js');
  profileCheckpoint('cli_entry');               // record a timestamp

  // Fast path 2: --dump-system-prompt (export the system prompt, for evals)
  if (feature('DUMP_SYSTEM_PROMPT') && args[0] === '--dump-system-prompt') {
    const { enableConfigs } = await import('../utils/config.js');
    ...
    return;
  }

  // Fast path 3: the local host process for the browser extension
  if (process.argv[2] === '--claude-in-chrome-mcp') { ... return; }

  // Fast path 4: daemon worker (spawned by the main process; performance-sensitive)
  if (feature('DAEMON') && args[0] === '--daemon-worker') {
    const { runDaemonWorker } = await import('../daemon/workerRegistry.js');
    await runDaemonWorker(args[1]);
    return;
  }
  ...
  // No fast path matched → load the full CLI
}

claude-code/src/entrypoints/cli.tsx

The MACRO in MACRO.VERSION is a compile-time macro — it is replaced with a literal string at bundle time. So getting the version number does not even require reading a config file.

1.3 Command-line arguments: 60-plus options

The full command-line interface is defined in main.tsx using the Commander.js library. There are a great many options; below they are grouped by purpose:

Mode and I/O

Permissions and safety

Model and budget

Sessions and resume

Extensions and integrations

1.4 --bare: a minimal mode worth its own section

This option’s official description is long, and it is worth taking apart item by item, because it amounts to a list of “how much extra work a normal startup actually does”:

Read in reverse, that sentence says a normal startup does all of the following:

--bare mode has one more key behavior change, stated plainly in the description:

1.5 Startup sequence

Once fast-path dispatch is out of the way, the full startup runs roughly in this order:

1.6 The three-part structure of the system prompt

The three parts returned in step ⑦ are not an arbitrary split; they correspond to three different levels of cache stability:

The corresponding code in the main loop calls it like this:

// query.ts
const fullSystemPrompt = asSystemPrompt(
  appendSystemContext(systemPrompt, systemContext)     // system prompt + system context
)
...
messages: prependUserContext(messagesForQuery, userContext)   // user context + messages