13 · Build and Distribution

The last chapter covers how 512,000 lines of TypeScript become a single file you can double-click to run, and how that build process in turn shapes the way the code is written.

13.1 The Bun Single-File Executable

The facts first:

$ ls -la ~/.local/share/claude/versions/
-rwxr-xr-x  272553824  2.1.223      ← 260 MB
-rwxr-xr-x  279661952  2.1.226      ← 267 MB
-rwxr-xr-x  310740672  2.1.234      ← 296 MB

One file, 296 MB, directly executable. No Node.js to install, no npm install, no runtime dependencies of any kind.

This is a Bun capability: it can package “the JavaScript runtime + all your code + every dependency + all static assets” into one binary.

Embedding native programs

Section 4.4 mentioned a conditional:

// Ant-native builds have bfs/ugrep embedded in the bun binary (same ARGV0
// trick as ripgrep). When available, find/grep in Claude's shell are aliased
// to these fast tools, so the dedicated Glob/Grep tools are unnecessary.
...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),

Put plainly: internal native builds embed bfs / ugrep in the bun executable (using the same ARGV0 trick as ripgrep). When they're available, find/grep in Claude's shell are aliased to these fast tools, so the standalone Glob/Grep tools become unnecessary.

13.2 Compile-Time Feature Flags: 89 of Them

This pattern is everywhere in the source:

import { feature } from 'bun:bundle'

const reactiveCompact = feature('REACTIVE_COMPACT')
  ? (require('./services/compact/reactiveCompact.js') as typeof import('...'))
  : null

if (feature('CONTEXT_COLLAPSE')) {
  collapseOwnsIt = (contextCollapse?.isContextCollapseEnabled() ?? false) && isAutoCompactEnabled()
}

The count comes to 89 distinct compile-time flags. A partial list:

13.3 Dead-Code Elimination: Why It's Not Just an “if”

feature() is fundamentally different from an ordinary runtime check: at bundle time it's replaced with the literal true or false, and the bundler then deletes the unreachable branch wholesale.

That has three consequences:

The coding style born of the “excluded strings” check

The source has several comments like this:

// Entire block gated behind feature() so the excluded string
// is eliminated from external builds.
if (feature('CACHED_MICROCOMPACT') && pendingCacheEdits) { ... }

// The subtype check lives inside the injected callback so feature-gated
// strings stay out of this file (excluded-strings check).
snipReplay?: (yieldedSystemMsg, store) => { messages, executed } | undefined

The second one is especially telling. To keep an internal feature's string out of the external artifact, they turned a piece of logic into “a callback injected from outside” — so the string exists only on the injecting side (a module compiled only in internal builds).

Another spot: the ESLint rules join in

// biome-ignore-all assist/source/organizeImports: ANT-ONLY import markers must not be reordered
/* eslint-disable custom-rules/no-process-env-top-level, @typescript-eslint/no-require-imports */
/* eslint-disable custom-rules/no-top-level-side-effects */

You can see several custom lint rules:

• custom-rules/no-process-env-top-level — forbids reading environment variables at module top level (top-level code runs at import time, which would break the fast path's “zero loading”)
• custom-rules/no-top-level-side-effects — forbids top-level side effects (same reason)
• custom-rules/require-tool-match-name — requires the unified tool-name matching function (tools have aliases, so comparing strings directly would miss some)
• “ANT-ONLY import markers must not be reordered” — import-sorting tools would scramble those markers and defeat dead-code elimination

These rules are automated guardians of the build constraints. Not humans eyeballing it in code review, but violating code simply failing the check.

13.4 Compile-Time Macros

// MACRO.VERSION is inlined at build time
console.log(`${MACRO.VERSION} (Claude Code)`)

MACRO is a macro replaced with a literal at build time. So the --version fast path doesn't even need to read a config file (section 1.2).

13.5 Runtime Feature Flags: A Separate System

Besides compile-time flags, there's a set of runtime flags, using GrowthBook (an A/B experimentation platform):

const capEnabled = getFeatureValue_CACHED_MAY_BE_STALE('tengu_otk_slot_v1', false)

Note the function name: getFeatureValue_CACHED_MAY_BE_STALE (get feature value — cached — may be stale).

How the two flag systems divide the work

The two are often stacked: the compile-time flag decides “is this code present,” and the runtime flag decides “if present, should it run.” The cached microcompaction in section 6.3 works this way:

if (feature('CACHED_MICROCOMPACT')) {              // compile-time: external builds don't have this code
  const mod = await getCachedMCModule()
  if (mod.isCachedMicrocompactEnabled() &&         // runtime: can be switched off at any time
      mod.isModelSupportedForCacheEditing(model) &&
      isMainThreadSource(querySource)) {
    return await cachedMicrocompactPath(messages, querySource)
  }
}

13.6 Versions and Updates

The layout of the install directory reveals the update strategy:

~/.local/share/claude/
├── ClaudeCode.app/                the desktop app
└── versions/
    ├── 2.1.223                    ← old version, kept
    ├── 2.1.226                    ← old version, kept
    └── 2.1.234                    ← current version

~/.local/bin/claude  →  symlink pointing at versions/2.1.234

Multiple versions coexist; a symlink switches the current one. That way:

• An update is “download the new version + repoint the symlink,” an atomic operation, so there's no “program broke halfway through an update”
• If something goes wrong, rollback takes a second (repoint the symlink)
• Running processes on the old version are unaffected (they've already loaded the file into memory)

The cost is disk usage — three versions is 800 MB. So utils/nativeInstaller/installer.ts (53 KB) presumably has logic for cleaning up old versions.

13.7 Architectural Constraints Inferred from the Build

This chapter's content has actually left traces in every preceding chapter. To sum up “how the build shaped the code”: