Skip to content

startup-performance.md

Latest commit

 

History

History
111 lines (89 loc) · 3.93 KB

startup-performance.md

File metadata and controls

111 lines (89 loc) · 3.93 KB

Startup & Performance

Overview

As a CLI tool invoked frequently, Claude Code aggressively optimizes startup time through parallel prefetch, lazy loading, and compile-time dead code elimination.

Parallel Prefetch

Before heavy module evaluation begins, main.tsx fires multiple prefetch operations as side effects:

main.tsx loads
     │
     ├──► startMdmRawRead()      # MDM/policy settings (async)
     ├──► startKeychainPrefetch() # macOS keychain read (async)
     ├──► API preconnect          # TCP connection warmup
     │
     v
  Heavy imports begin (React, Ink, tools, commands...)
     │
     v
  Prefetch results available (no extra wait)

These operations overlap with module evaluation time, effectively making them "free" in terms of perceived latency.

Dead Code Elimination

Bun's bun:bundle feature flags enable compile-time dead code elimination:

// At build time, feature('VOICE_MODE') resolves to true or false
// The bundler completely strips the dead branch
const voiceCommand = feature('VOICE_MODE')
  ? require('./commands/voice/index.js').default
  : null

Known Feature Flags

Flag Controls
PROACTIVE Proactive/initiative-taking mode
KAIROS Advanced autonomous features
KAIROS_BRIEF Brief tool subsystem
BRIDGE_MODE IDE bridge system
DAEMON Background daemon mode
VOICE_MODE Voice input processing
AGENT_TRIGGERS Cron/scheduled triggers
AGENT_TRIGGERS_REMOTE Remote trigger execution
MONITOR_TOOL System monitoring tool
COORDINATOR_MODE Multi-agent coordinator
TRANSCRIPT_CLASSIFIER Auto-mode permission classifier
CACHED_MICROCOMPACT Cached micro-compaction
EXPERIMENTAL_SKILL_SEARCH Skill discovery tool

This means the npm-distributed binary only includes code for enabled features, significantly reducing bundle size and parse time.

Lazy Loading

Heavy modules are deferred via dynamic import() until actually needed:

Lazy-Loaded Modules

  • OpenTelemetry + gRPC: Only loaded when telemetry is enabled
  • Analytics (GrowthBook): Initialized async, not blocking startup
  • OAuth flow: Only loaded when authentication is needed
  • Compact/summarization: Loaded on first compaction trigger
  • MCP SDK: Loaded when first MCP server connection requested
  • Voice processing: Loaded on voice command activation
  • LSP: Loaded when language server features requested

Lazy Require Pattern

const getTeamCreateTool = () =>
  require('./tools/TeamCreateTool/TeamCreateTool.js').TeamCreateTool

Functions wrapped in closures break circular dependencies AND defer loading until first call.

Token Budget Management

Performance isn't just startup -- it's also about managing LLM costs:

Context Window Management

  • Token estimation tracks prompt size before API calls
  • Warning thresholds trigger proactive compaction
  • Auto-compact summarizes old messages to reclaim context space
  • Deferred tool loading keeps initial prompt small

Cost Tracking

  • Per-model token costs tracked (input, output, cache reads/writes)
  • cost-tracker.ts maintains running totals
  • /cost command exposes current session costs
  • Organization policy limits enforced

Build-Time Optimizations

User Type Gating

process.env.USER_TYPE === 'ant'
  ? require('./internal-tool.js')
  : null

Internal-only tools completely excluded from public builds.

Conditional Imports

Biome's organize-imports rule disabled for files with ANT-ONLY markers, preserving intentional import ordering that enables dead code elimination.

Design Principles

  1. Overlap, don't sequence: Prefetch during module evaluation
  2. Pay for what you use: Feature flags eliminate unused code paths
  3. Defer the heavy stuff: Dynamic imports for rarely-used modules
  4. Budget-aware: Token tracking prevents context window blowups
  5. Build-time, not runtime: Decisions made at compile time when possible