claude-code/spec/10_utils.md

Claude Code — Utilities

This document covers the entire src/utils/ directory (564 files across 36 subdirectories) plus src/interactiveHelpers.tsx and src/ink.ts.

Table of Contents

1. Core Data Structures
2. Shell & Process Execution
3. Bash Parsing & Analysis
4. Configuration & Settings
5. Authentication & Auth Management
6. Permissions System
7. File & Filesystem Utilities
8. Git Utilities
9. Session Management
10. Message & Content Utilities
11. Model Utilities
12. MCP Utilities
13. Swarm / Multi-Agent System
14. Task & Output Management
15. Process User Input
16. Hooks System
17. Analytics & Telemetry
18. Background & Cron Systems
19. Computer Use
20. Claude-in-Chrome
21. Deep Link System
22. Plugin Utilities
23. Swarm Backends
24. Skills & Suggestions
25. Todo System
26. Teleport System
27. Memory Utilities
28. Sandbox Utilities
29. Security & Secure Storage
30. Native Installer
31. General Utilities (Top-Level)
32. interactiveHelpers.tsx
33. ink.ts (Top-Level Module)
34. utils/shell/ — Shell Provider Abstraction
35. utils/ultraplan/ — Ultraplan Remote Session Polling

---

1. Core Data Structures

CircularBuffer.ts

Fixed-size circular buffer that auto-evicts oldest items when full.

export class CircularBuffer<T> {
  constructor(private capacity: number)
  add(item: T): void           // Adds item, evicts oldest if full
  addAll(items: T[]): void     // Bulk add
  getRecent(count: number): T[] // N most recent items
  toArray(): T[]               // All items oldest-to-newest
  clear(): void
  length(): number
}

QueryGuard.ts

Synchronous state machine for query lifecycle (idle / dispatching / running). Compatible with React's useSyncExternalStore.

export class QueryGuard {
  reserve(): boolean           // idle → dispatching; returns false if not idle
  cancelReservation(): void    // dispatching → idle
  tryStart(): number | null    // → running; returns generation or null if running
  end(generation: number): boolean  // running → idle; returns false if stale
  forceEnd(): void             // kills any running query
  get isActive(): boolean      // true for dispatching OR running
  get generation(): number
  subscribe: (listener) => () => void  // useSyncExternalStore subscribe
  getSnapshot: () => boolean           // useSyncExternalStore snapshot
}

signal.ts

Lightweight event signal primitive (no state storage, just notifications).

export type Signal<Args extends unknown[] = []> = {
  subscribe: (listener: (...args: Args) => void) => () => void
  emit: (...args: Args) => void
  clear: () => void
}

export function createSignal<Args extends unknown[] = []>(): Signal<Args>

Used ~15× across the codebase for pub/sub of state-change events.

memoize.ts

Advanced memoization utilities beyond lodash.

// Write-through cache with TTL and background refresh
export function memoizeWithTTL<Args, Result>(
  f: (...args: Args) => Result,
  cacheLifetimeMs?: number  // default 5 minutes
): MemoizedFunction<Args, Result>

// Async version with in-flight dedup
export function memoizeWithTTLAsync<Args, Result>(
  f: (...args: Args) => Promise<Result>,
  cacheLifetimeMs?: number
): ((...args) => Promise<Result>) & { cache: { clear() } }

// LRU-eviction memoize (prevents unbounded memory growth)
export function memoizeWithLRU<Args, Result>(
  f: (...args: Args) => Result,
  cacheFn: (...args: Args) => string,  // key generator
  maxCacheSize?: number  // default 100
): LRUMemoizedFunction<Args, Result>

generators.ts

Async generator utilities.

export async function lastX<A>(as: AsyncGenerator<A>): Promise<A>
export async function returnValue<A>(as: AsyncGenerator<unknown, A>): Promise<A>
export async function* all<A>(
  generators: AsyncGenerator<A, void>[],
  concurrencyCap?: number  // default Infinity
): AsyncGenerator<A, void>
export async function toArray<A>(generator: AsyncGenerator<A>): Promise<A[]>
export async function* fromArray<T>(values: T[]): AsyncGenerator<T, void>

array.ts

Array utility helpers (deduplicate, group, etc.).

set.ts

Set utility helpers.

sequential.ts

Sequential execution helpers.

objectGroupBy.ts

Object.groupBy polyfill/wrapper.

---

2. Shell & Process Execution

Shell.ts

Core shell execution engine. The most important utility file.

Exports:

export type ShellConfig = { provider: ShellProvider }
export type ExecOptions = {
  timeout?: number
  onProgress?: (lastLines, allLines, totalLines, totalBytes, isIncomplete) => void
  preventCwdChanges?: boolean
  shouldUseSandbox?: boolean
  shouldAutoBackground?: boolean
  onStdout?: (data: string) => void  // pipe mode callback
}

export async function findSuitableShell(): Promise<string>
// Priority: CLAUDE_CODE_SHELL env > $SHELL > zsh > bash

export const getShellConfig: typeof getShellConfigImpl  // memoized
export const getPsProvider: () => Promise<ShellProvider>  // memoized

export async function exec(
  command: string,
  abortSignal: AbortSignal,
  shellType: ShellType,
  options?: ExecOptions
): Promise<ShellCommand>

export function setCwd(path: string, relativeTo?: string): void
export type { ExecResult } from './ShellCommand.js'

Key Implementation Details:

• DEFAULT_TIMEOUT = 30 minutes
• File mode (bash): stdout+stderr both go to a single file fd (atomic O_APPEND)
• Pipe mode (hooks, onStdout): data flows through StreamWrapper → TaskOutput in-memory
• CWD tracking: captures pwd -P output to temp file after each command
• Sandbox wrapping: calls SandboxManager.wrapWithSandbox() when shouldUseSandbox
• Sandboxed PowerShell uses /bin/sh as outer shell with base64-encoded inner command
• After command: reads cwd file, updates state, notifies hooks, cleans up
• Windows path handling via posixPathToWindowsPath()

ShellCommand.ts

Wraps a child process into a ShellCommand interface.

Exports:

export type ExecResult = {
  stdout: string
  stderr: string
  code: number
  interrupted: boolean
  backgroundTaskId?: string
  backgroundedByUser?: boolean
  assistantAutoBackgrounded?: boolean
  outputFilePath?: string    // when stdout was too large for inline
  outputFileSize?: number
  outputTaskId?: string
  preSpawnError?: string
}

export type ShellCommand = {
  background(backgroundTaskId: string): boolean  // runningbg
  result: Promise<ExecResult>
  kill(): void
  status: 'running' | 'backgrounded' | 'completed' | 'killed'
  cleanup(): void  // removes event listeners
  onTimeout?: (callback: (backgroundFn) => void) => void
  taskOutput: TaskOutput
}

export function wrapSpawn(
  childProcess: ChildProcess,
  abortSignal: AbortSignal,
  timeout: number,
  taskOutput: TaskOutput,
  shouldAutoBackground?: boolean,
  maxOutputBytes?: number
): ShellCommand

export function createAbortedCommand(
  backgroundTaskId?: string,
  opts?: { stderr?: string; code?: number }
): ShellCommand

export function createFailedCommand(preSpawnError: string): ShellCommand

Key Details:

• SIGKILL = 137, SIGTERM = 143
• SIZE_WATCHDOG_INTERVAL_MS = 5,000ms — kills backgrounded processes over disk limit
• Uses treeKill to kill entire process trees
• Abort reason 'interrupt' allows backgrounding instead of killing
• StreamWrapper: thin pipe from ChildProcess stdout/stderr → TaskOutput (pipe mode only)

abortController.ts

Memory-safe AbortController utilities using WeakRef.

export function createAbortController(maxListeners?: number): AbortController

export function createChildAbortController(
  parent: AbortController,
  maxListeners?: number
): AbortController
// Child aborts when parent aborts (not vice versa)
// Uses WeakRef — dropped children can be GC'd
// Auto-removes parent listener when child aborts

combinedAbortSignal.ts

Creates an AbortSignal that fires when any of multiple signals fires.

execFileNoThrow.ts / execFileNoThrowPortable.ts

export async function execFileNoThrow(
  file: string, args?: string[], options?: ExecFileOptions
): Promise<{ stdout: string; stderr: string; code: number }>

export function execSyncWithDefaults_DEPRECATED(
  command: string
): string | null

execSyncWrapper.ts

Synchronous shell execution wrapper with error handling.

genericProcessUtils.ts

Generic child process utilities (spawn, kill, etc.).

gracefulShutdown.ts

export function gracefulShutdown(exitCode?: number): Promise<never>
export function gracefulShutdownSync(exitCode?: number): never
export function registerShutdownHandler(fn: () => void | Promise<void>): void

process.ts

Process-level utilities.

subprocessEnv.ts

export function subprocessEnv(): NodeJS.ProcessEnv
// Returns filtered process.env suitable for subprocess spawning

---

3. Bash Parsing & Analysis

bash/ParsedCommand.ts

export type ParsedCommand = {
  command: string
  args: string[]
  redirects: Redirect[]
  // ... more fields
}
export function parseBashCommand(input: string): ParsedCommand | null

bash/ShellSnapshot.ts

Captures shell environment state (env vars, aliases) for reproduction.

bash/ast.ts

Bash AST node types for the parser.

bash/bashParser.ts

Full bash command parser. Handles pipes, redirections, compound commands.

bash/bashPipeCommand.ts

Represents a pipe-connected command chain.

bash/commands.ts

export function extractOutputRedirections(command: string): string[]
export function getCommandName(command: string): string
export function isDestructiveCommand(command: string): boolean

bash/heredoc.ts

Heredoc detection and parsing.

bash/parser.ts

Low-level token parser for bash syntax.

bash/prefix.ts

Handles shell variable prefix syntax (VAR=value cmd).

bash/registry.ts

Registry of known bash commands and their semantics.

bash/shellCompletion.ts

Shell completion suggestions for partial commands.

bash/shellPrefix.ts

export function formatShellPrefixCommand(command: string, envFile: string): string

bash/shellQuote.ts / bash/shellQuoting.ts

Shell quoting utilities to safely embed strings in shell commands.

bash/specs/

Command-specific completion specs: alias.ts, nohup.ts, pyright.ts, sleep.ts, srun.ts, time.ts, timeout.ts.

bash/treeSitterAnalysis.ts

Tree-sitter based deep bash AST analysis for command classification.

---

4. Configuration & Settings

config.ts

The central configuration file. Manages global config (per-user), project config (per-project), and session config.

Key Types:

export type PastedContent = {
  id: number; type: 'text' | 'image'; content: string
  mediaType?: string; filename?: string; dimensions?: ImageDimensions
  sourcePath?: string
}

export interface HistoryEntry {
  display: string
  pastedContents: Record<number, PastedContent>
}

export type ReleaseChannel = 'stable' | 'latest'

export type ProjectConfig = {
  allowedTools: string[]
  mcpContextUris: string[]
  mcpServers?: Record<string, McpServerConfig>
  // + many more fields
}

export type GlobalConfig = {
  // Account info, oauth tokens, model preferences, theme, etc.
}

export type AccountInfo = {
  emailAddress: string
  // + subscription/billing fields
}

Key Exports:

export function getGlobalConfig(): GlobalConfig
export function saveGlobalConfig(update: (current: GlobalConfig) => GlobalConfig): void
export function getProjectConfig(cwd?: string): ProjectConfig
export function saveProjectConfig(update: (current: ProjectConfig) => ProjectConfig, cwd?: string): void
export function checkHasTrustDialogAccepted(): boolean
export function getCustomApiKeyStatus(): 'user' | 'project' | 'env' | 'none'
export function normalizePathForConfigKey(p: string): string

configConstants.ts

Config-related constants (file names, paths, defaults).

settings/settings.ts

User settings with multi-source merge (user file, project file, MDM, managed settings).

Key Exports:

export function getSettings_DEPRECATED(): SettingsJson
export function getSettingsForSource(source: SettingSource): SettingsJson
export function saveSettings(update: (current: SettingsJson) => SettingsJson, source?: EditableSettingSource): void
export function hasAutoModeOptIn(): boolean
export function hasSkipDangerousModePermissionPrompt(): boolean

settings/types.ts

SettingsJson and SettingsSchema (Zod schema) defining all user-configurable settings.

settings/constants.ts

export type SettingSource = 'userSettings' | 'projectSettings' | 'sessionSettings' | 'managed' | 'mdm' | 'remoteManagedSettings'
export type EditableSettingSource = 'userSettings' | 'projectSettings' | 'sessionSettings'
export const SETTING_SOURCES: SettingSource[]

settings/validation.ts

Settings validation (Zod-based), permission rule filtering, validation tips.

settings/settingsCache.ts

Multi-layer settings cache keyed by source.

settings/changeDetector.ts

Detects when settings change and fires notifications.

settings/applySettingsChange.ts

Applies incremental settings updates.

settings/mdm/

MDM (Mobile Device Management) policy settings:

• settings.ts: reads from Windows HKCU registry and macOS plist
• rawRead.ts: low-level MDM config reading
• constants.ts: MDM-specific constants

settings/managedPath.ts

export function getManagedFilePath(): string
export function getManagedSettingsDropInDir(): string

settings/allErrors.ts

export function getSettingsWithAllErrors(): SettingsWithErrors

settings/permissionValidation.ts

Validates permission rule configurations in settings.

settings/toolValidationConfig.ts

Tool-level validation configuration.

settings/validateEditTool.ts

Validates EditTool-specific settings.

settings/schemaOutput.ts

Generates JSON Schema from the settings Zod schema.

settings/pluginOnlyPolicy.ts

Enforces that certain settings can only be configured via plugins.

---

5. Authentication & Auth Management

auth.ts

Main authentication orchestration. Handles API key, OAuth, and AWS auth.

Key Exports:

export function getSubscriptionType(): SubscriptionType | null
export function isClaudeAISubscriber(): boolean
export function isProSubscriber(): boolean
export function isMaxSubscriber(): boolean
export function isTeamPremiumSubscriber(): boolean
export async function getAuthHeaders(): Promise<Record<string, string>>
export async function logout(): Promise<void>
export async function refreshAuth(): Promise<void>

authPortable.ts

Cross-platform auth utilities.

export function normalizeApiKeyForConfig(key: string): string
export async function maybeRemoveApiKeyFromMacOSKeychainThrows(): Promise<void>

authFileDescriptor.ts

Reads API key / OAuth token from file descriptor (for CI/headless use).

export function getApiKeyFromFileDescriptor(): string | null
export function getOAuthTokenFromFileDescriptor(): OAuthTokens | null

aws.ts

AWS credential management and STS caller identity checking.

export async function checkStsCallerIdentity(profile?: string): Promise<AwsCallerIdentity>
export function isValidAwsStsOutput(output: string): boolean
export function clearAwsIniCache(): void

awsAuthStatusManager.ts

export class AwsAuthStatusManager {
  getStatus(): AwsAuthStatus
  // Manages AWS auth lifecycle with refresh
}

betas.ts

Beta feature flag management tied to account subscription.

export function clearBetasCaches(): void
export async function getBetaFeatures(): Promise<string[]>

billing.ts

Billing-related utilities (subscription type detection, extra-usage checks).

---

6. Permissions System

permissions/permissions.ts

Core permission checking engine.

Key Logic:

• Integrates TRANSCRIPT_CLASSIFIER feature flag for AI-based permission decisions
• Checks permission rules from settings, project config, session config
• Handles bypassPermissionsKillswitch
• Manages permission modes (normal, bypass, plan, auto)
• Returns PermissionDecision with reason for UI display

Key Exports:

export async function getPermissionDecision(
  tool: Tool,
  input: AnyObject,
  context: ToolPermissionContext
): Promise<PermissionDecision>

export async function applyPermissionUpdate(
  update: PermissionUpdate,
  destination: PermissionUpdateDestination
): Promise<void>

export async function applyPermissionUpdates(updates: PermissionUpdate[]): Promise<void>
export async function persistPermissionUpdates(updates: PermissionUpdate[]): Promise<void>
export function deletePermissionRuleFromSettings(rule: PermissionRuleFromEditableSettings): void

permissions/PermissionMode.ts

export type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan'
export function permissionModeTitle(mode: PermissionMode): string

permissions/PermissionResult.ts

export type PermissionDecision =
  | PermissionAskDecision    // { type: 'ask', message, ... }
  | PermissionDenyDecision   // { type: 'deny', reason, ... }
  | { type: 'allow' }
  | { type: 'allowWithSandbox' }

permissions/PermissionRule.ts

export type PermissionBehavior = 'allow' | 'deny'
export type PermissionRuleValue = string  // e.g., "Bash(rm:*)"
export type PermissionRule = {
  ruleValue: PermissionRuleValue
  behavior: PermissionBehavior
  source: PermissionRuleSource
}

permissions/PermissionUpdate.ts / PermissionUpdateSchema.ts

Types and logic for updating permission rules in settings.

permissions/bashClassifier.ts

Classifies bash commands for permission decisions (uses patterns and optionally AI).

permissions/yoloClassifier.ts

Classifier for "bypass permissions" mode — auto-approves most commands.

permissions/classifierDecision.ts

AI-based transcript classifier for permission decisions (feature-gated by TRANSCRIPT_CLASSIFIER).

permissions/classifierShared.ts

Shared types and utilities for classifiers.

permissions/dangerousPatterns.ts

List of dangerous bash patterns that always require explicit approval.

export const DANGEROUS_PATTERNS: RegExp[]
export function hasDangerousPattern(command: string): boolean

permissions/denialTracking.ts

Tracks recent permission denials for UI display in /permissions recent-denials.

permissions/filesystem.ts

export function getClaudeTempDirName(): string
export function validateFilesystemAccess(path: string, mode: 'read' | 'write'): boolean

permissions/getNextPermissionMode.ts

State machine transitions for permission mode cycling.

permissions/pathValidation.ts

Validates file paths against workspace directories.

permissions/permissionExplainer.ts

Generates human-readable explanations for permission decisions.

permissions/permissionRuleParser.ts

export function permissionRuleValueFromString(s: string): PermissionRuleValue
export function permissionRuleValueToString(v: PermissionRuleValue): string

permissions/permissionSetup.ts

Initial permission setup at session start.

permissions/permissionsLoader.ts

Loads and merges permission rules from all sources.

permissions/shadowedRuleDetection.ts

Detects when a permission rule is shadowed/overridden by another rule.

permissions/shellRuleMatching.ts

Matches shell commands against permission rule patterns (glob-style).

permissions/autoModeState.ts

State management for auto-approve mode.

permissions/bypassPermissionsKillswitch.ts

Emergency killswitch for bypass-permissions mode.

---

7. File & Filesystem Utilities

file.ts

Core file utilities.

export async function pathExists(p: string): Promise<boolean>
export function writeFileSyncAndFlush_DEPRECATED(path: string, content: string): void
export async function safeReadFile(path: string): Promise<string | null>

fileRead.ts

export function readFileSync(path: string, options?: { encoding?: 'utf8' }): string
// NFC-normalizes content on read (macOS APFS compat)

fileReadCache.ts

Content-addressed file read cache with invalidation.

fileStateCache.ts

Caches file stat information to avoid repeated fs.stat calls.

fsOperations.ts

export function getFsImplementation(): FsImplementation
// Returns real fs or test mock

export async function readFileRange(
  path: string, start: number, end: number
): Promise<string>

export async function tailFile(
  path: string, maxBytes?: number
): Promise<string>

fileHistory.ts

File edit history tracking for /rewind and undo operations.

fileOperationAnalytics.ts

Tracks file operation analytics (reads, writes, edits per turn).

filePersistence/filePersistence.ts

Persistence of file state across sessions.

filePersistence/outputsScanner.ts

Scans output files for persistence.

readFileInRange.ts

Reads a specific byte range from a file.

readEditContext.ts

Builds context for file read/edit operations (surrounding lines, etc.).

generatedFiles.ts

Detection of generated/auto-generated files (to skip in certain operations).

path.ts

Path manipulation utilities.

export function normalizePathForConfigKey(p: string): string
export function toRelativePath(absolute: string, base?: string): string
export function expandHome(p: string): string

xdg.ts

XDG base directory spec utilities.

systemDirectories.ts

Platform-specific system directory paths.

cachePaths.ts

Cache directory paths for various cached data.

tempfile.ts

export async function createTempFile(suffix?: string): Promise<string>
export function cleanupTempFiles(): void

lockfile.ts

File-based distributed locking.

export async function lock(path: string, options?: LockOptions): Promise<() => void>
export function tryLock(path: string): boolean

cleanupRegistry.ts

export function registerCleanup(fn: () => void | Promise<void>): void
export async function runCleanup(): Promise<void>

cleanup.ts

Session cleanup utilities.

glob.ts

Glob pattern matching utilities (wraps glob library).

ripgrep.ts

Ripgrep integration for file content searching.

---

8. Git Utilities

git.ts

Primary git utility module.

Key Exports:

export function findGitRoot(startPath?: string): string | null
export function findCanonicalGitRoot(startPath?: string): string | null
export async function getGitBranch(cwd?: string): Promise<string | null>
export async function getGitStatus(cwd?: string): Promise<string>
export async function getGitDiff(args?: string[]): Promise<string>
export async function isGitRepo(cwd?: string): Promise<boolean>

Uses LRU memoization (memoizeWithLRU) for root detection. NFC-normalizes paths for macOS APFS compatibility.

git/gitFilesystem.ts

Low-level git filesystem operations.

export function getCachedBranch(cwd: string): string | null
export function getCachedHead(cwd: string): string | null
export function getCachedDefaultBranch(cwd: string): string | null
export function getCachedRemoteUrl(cwd: string): string | null
export function getWorktreeCountFromFs(cwd: string): number
export function isShallowClone(cwd: string): boolean
export function resolveGitDir(cwd: string): string | null

git/gitConfigParser.ts

Parses .git/config files.

git/gitignore.ts

export async function addFileGlobRuleToGitignore(
  pattern: string,
  gitRoot: string
): Promise<void>
export function isIgnoredByGitignore(path: string, cwd: string): boolean

gitDiff.ts

Git diff parsing and formatting utilities.

gitSettings.ts

Git configuration utilities for Claude Code settings.

ghPrStatus.ts

GitHub PR status checking via gh CLI.

github/ghAuthStatus.ts

GitHub authentication status checking.

githubRepoPathMapping.ts

Maps GitHub repo URLs to local filesystem paths.

detectRepository.ts

Detects repository type (git, mercurial, etc.) and metadata.

getWorktreePaths.ts / getWorktreePathsPortable.ts

export async function getWorktreePaths(): Promise<string[]>
// Lists all git worktree paths for the current repo

worktree.ts

Git worktree management utilities.

worktreeModeEnabled.ts

Feature flag check for worktree mode.

commitAttribution.ts

Adds Claude Code attribution to git commits.

---

9. Session Management

sessionStorage.ts

Core session storage — reading/writing JSONL transcript files.

Key Exports:

export function getTranscriptPathForSession(sessionId: string, cwd?: string): string
export function getAgentTranscriptPath(agentId: AgentId, sessionId: string): string
export async function appendToSession(entry: Entry): Promise<void>
export async function readSession(sessionId: string): Promise<Entry[]>
export async function listSessions(cwd?: string): Promise<SessionSummary[]>
export async function deleteSession(sessionId: string): Promise<void>
export function switchSession(newSessionId: string): void

sessionStoragePortable.ts

Portable version of session storage (cross-platform paths).

sessionState.ts

In-memory session state (current session ID, title, etc.).

sessionStart.ts

Session initialization logic.

sessionRestore.ts

Restores a session from its JSONL transcript.

sessionActivity.ts

Tracks session activity for idle detection.

sessionEnvVars.ts

Environment variables injected into the session context.

sessionEnvironment.ts

export function getHookEnvFilePath(): string
export function invalidateSessionEnvCache(): void
export async function getSessionEnvironmentVariables(): Promise<Record<string, string>>

sessionFileAccessHooks.ts

Hooks for tracking which files were accessed in a session.

sessionIngressAuth.ts

Auth for incoming session connections (bridge, remote).

sessionTitle.ts

export async function generateSessionTitle(messages: Message[]): Promise<string>

sessionUrl.ts

URL construction for remote session references.

listSessionsImpl.ts

Implementation of session listing with sorting and filtering.

agenticSessionSearch.ts

Search within session transcripts.

crossProjectResume.ts

Handles resuming sessions across different project directories.

concurrentSessions.ts

Manages multiple concurrent Claude Code sessions.

cwd.ts

export function pwd(): string              // Current working directory
export function getCwd(): string           // Alias
export function isValidCwd(path: string): boolean

---

10. Message & Content Utilities

messages.ts

Core message manipulation — the most-used utility in the codebase.

Key Exports:

export function getContentText(content: ContentBlockParam[]): string
export function normalizeMessages(messages: Message[]): NormalizedMessage[]
export function isUserMessage(msg: Message): msg is UserMessage
export function isAssistantMessage(msg: Message): msg is AssistantMessage
export function extractToolUses(messages: Message[]): ToolUseBlock[]
export function getLastAssistantMessage(messages: Message[]): AssistantMessage | null
export function createSystemMessage(text: string): SystemMessage
export function createUserMessage(content: ContentBlockParam[]): UserMessage

contentArray.ts

Utilities for working with ContentBlockParam[] arrays.

messagePredicates.ts

Type guards and predicates for message types.

messageQueueManager.ts

Queue management for batched message processing.

messages/ (subdirectory)

Message-category-specific utilities:

• messages/ — subdirectory with specialized message handling utilities

attachments.ts

Manages message attachments (images, files, pastes).

export function createAttachmentMessage(content: AttachmentContent): AttachmentMessage
export function getAttachmentMessages(messages: Message[]): AttachmentMessage[]
export type AgentMentionAttachment = { agentId: string; agentName: string }

collapseBackgroundBashNotifications.ts

Collapses multiple bash progress notifications into summaries.

collapseHookSummaries.ts

Collapses hook execution summaries.

collapseReadSearch.ts

Collapses file read/search tool uses for compaction.

collapseTeammateShutdowns.ts

Collapses teammate shutdown messages.

groupToolUses.ts

Groups sequential tool use messages for display.

controlMessageCompat.ts

Compatibility layer for control messages across versions.

directMemberMessage.ts

Direct messaging between swarm members.

images utilities:

• imagePaste.ts — clipboard image paste handling
• imageResizer.ts — resizes/downsamples large images
• imageStore.ts — temporary image storage keyed by UUID
• imageValidation.ts — validates image format/size
• imageProcessor (in FileReadTool) — processes image files for model input

pdf.ts / pdfUtils.ts

PDF file handling — extracts text, validates, handles password protection.

notebook.ts

Jupyter notebook utilities (.ipynb parsing, cell editing).

---

11. Model Utilities

model/model.ts

Model selection and configuration.

export type ModelShortName = string
export type ModelName = string
export type ModelSetting = ModelName | ModelAlias | null

export function getSmallFastModel(): ModelName  // ANTHROPIC_SMALL_FAST_MODEL or haiku
export function isNonCustomOpusModel(model: ModelName): boolean
export function getModelToUse(options?: ModelOptions): ModelName
// Priority: session override > --model flag > ANTHROPIC_MODEL env > settings > default

model/aliases.ts

export type ModelAlias = 'claude-sonnet' | 'claude-haiku' | 'claude-opus' | ...
export function isModelAlias(s: string): s is ModelAlias
export function resolveModelAlias(alias: ModelAlias): ModelName

model/modelStrings.ts

export function getModelStrings(): {
  opus40: string; opus41: string; opus45: string; opus46: string
  sonnet45: string; sonnet46: string
  haiku35: string; haiku40: string
  // ... all model IDs, some conditionally included (ANT-only)
}
export function resolveOverriddenModel(model: ModelSetting): ModelName

model/modelOptions.ts

Model option types and construction.

model/modelCapabilities.ts

export function supportsVision(model: ModelName): boolean
export function supportsExtendedThinking(model: ModelName): boolean
export function supports1MContext(model: ModelName): boolean
export function modelSupportsAdvisor(model: ModelName): boolean

model/configs.ts

Per-model configuration (temperature, top_p, max_tokens, etc.).

model/providers.ts

export type APIProvider = 'anthropic' | 'bedrock' | 'vertex'
export function getAPIProvider(): APIProvider

model/bedrock.ts

AWS Bedrock-specific model ID conversions.

model/antModels.ts

Internal ANT-only model names (dead-code-eliminated in external builds).

model/validateModel.ts

export function validateModel(model: string): ModelName
export function isValidAdvisorModel(model: string): boolean

model/modelAllowlist.ts

Runtime allowlist of models (from settings/GrowthBook).

model/modelSupportOverrides.ts

Per-model support overrides for edge cases.

model/deprecation.ts

Model deprecation notices and migration paths.

model/contextWindowUpgradeCheck.ts

Checks if 1M context upgrade is available.

model/check1mAccess.ts

Validates 1M context access for current subscription.

model/agent.ts

Agent-specific model selection.

modelCost.ts

export function formatModelPricing(model: ModelName): string
export function getOpus46CostTier(): 'standard' | 'premium'

context.ts

Context window management.

export function has1mContext(): boolean
export function is1mContextDisabled(): boolean
export function modelSupports1M(model: ModelName): boolean

---

12. MCP Utilities

utils/mcp/dateTimeParser.ts

Parses date/time values from MCP tool inputs.

utils/mcp/elicitationValidation.ts

Validates MCP elicitation schemas.

mcpInstructionsDelta.ts

Diff-based MCP server instructions management.

mcpOutputStorage.ts

Storage for MCP tool output.

mcpValidation.ts

Validates MCP server configurations.

mcpWebSocketTransport.ts

WebSocket transport implementation for MCP servers.

---

13. Swarm / Multi-Agent System

swarm/constants.ts

Swarm system constants (max workers, timeouts, etc.).

swarm/inProcessRunner.ts

Runs swarm workers in the same process (no separate terminal).

swarm/spawnInProcess.ts

Spawns in-process swarm workers.

swarm/spawnUtils.ts

Common utilities for spawning swarm workers.

swarm/leaderPermissionBridge.ts

Bridges permission decisions from leader to workers.

swarm/permissionSync.ts

Synchronizes permission state across swarm members.

swarm/reconnection.ts

Handles reconnection logic when swarm workers disconnect.

swarm/teamHelpers.ts

Helper utilities for team coordination.

swarm/teammateInit.ts

Initialization sequence for swarm teammates.

swarm/teammateLayoutManager.ts

Manages terminal layout for swarm teammates.

swarm/teammateModel.ts

Model selection for swarm teammates.

swarm/teammatePromptAddendum.ts

Adds context to teammate prompts.

swarm/backends/types.ts

export type PaneBackend = {
  spawn(config: SpawnConfig): Promise<PaneHandle>
  kill(pane: PaneHandle): Promise<void>
  sendInput(pane: PaneHandle, text: string): Promise<void>
  // ...
}

swarm/backends/TmuxBackend.ts

Tmux-based pane backend for swarm.

swarm/backends/ITermBackend.ts

iTerm2-based pane backend for swarm.

swarm/backends/InProcessBackend.ts

In-process (no terminal) backend.

swarm/backends/PaneBackendExecutor.ts

Executes commands in pane backends.

swarm/backends/detection.ts

Detects available pane backends (tmux, iTerm2, etc.).

swarm/backends/registry.ts

Registry of available backends.

swarm/backends/teammateModeSnapshot.ts

Snapshots teammate mode state.

swarm/backends/it2Setup.ts / It2SetupPrompt.tsx

iTerm2 setup flow for swarm.

agentSwarmsEnabled.ts

export function isAgentSwarmsEnabled(): boolean

inProcessTeammateHelpers.ts

Helpers for in-process teammate coordination.

teammate.ts / teammateContext.ts / teammateMailbox.ts

Teammate state, context, and messaging utilities.

teamDiscovery.ts

Discovers available teammates in the session.

teamMemoryOps.ts

Team memory read/write operations.

standaloneAgent.ts

Runs a standalone agent session programmatically.

forkedAgent.ts

Handles forked agent sessions.

---

14. Task & Output Management

task/TaskOutput.ts

Single source of truth for a shell command's output.

export class TaskOutput {
  readonly taskId: string
  readonly path: string          // Output file path
  readonly stdoutToFile: boolean // true = file mode, false = pipe mode

  constructor(taskId: string, onProgress: ProgressCallback | null, stdoutToFile?: boolean)

  writeStdout(data: string): void   // pipe mode only
  writeStderr(data: string): void   // pipe mode only
  async getStdout(): Promise<string>
  getStderr(): string
  get outputFileRedundant(): boolean
  get outputFileSize(): number
  spillToDisk(): void               // flush in-memory buffer to disk

  clear(): void
  async deleteOutputFile(): Promise<void>

  // Static registry for polling
  static startPolling(taskId: string): void
  static stopPolling(taskId: string): void
}

Uses CircularBuffer<string>(1000) for recent lines in file mode. Polling interval: 1000ms for progress callbacks. Max in-memory: 8MB before spilling to disk.

task/diskOutput.ts

export const MAX_TASK_OUTPUT_BYTES: number     // e.g., 5MB
export const MAX_TASK_OUTPUT_BYTES_DISPLAY: string
export class DiskTaskOutput { ... }
export function getTaskOutputPath(taskId: string): string
export function getTaskOutputDir(): string

task/framework.ts

Task execution framework — tracks running/completed/failed tasks.

task/outputFormatting.ts

Formats task output for display (truncation, highlighting).

task/sdkProgress.ts

SDK-level progress reporting for tasks.

tasks.ts (top-level)

Task management utilities.

export function getActiveTasks(): ActiveTask[]
export function getTaskById(id: string): ActiveTask | null

---

15. Process User Input

processUserInput/processUserInput.ts

Main entry point for user input processing.

export async function processUserInput(
  input: UserInput,
  context: ProcessContext
): Promise<ProcessResult>

Handles dispatch to bash, slash command, or text prompt processors.

processUserInput/processBashCommand.tsx

Handles !command syntax — executes shell commands inline.

processUserInput/processSlashCommand.tsx

Handles /command syntax — finds and dispatches slash commands.

processUserInput/processTextPrompt.ts

Handles regular text prompts — creates user messages for the model.

handlePromptSubmit.ts

Orchestrates prompt submission with hooks, attachments, queue management.

slashCommandParsing.ts

export function parseSlashCommand(input: string): { name: string; args: string } | null

promptShellExecution.ts

executeShellCommandsInPrompt() — expands !backtick syntax in prompt commands.

---

16. Hooks System

hooks.ts

Core hooks execution engine. Runs user-configured lifecycle hooks.

Key Exports:

export type HookEvent =
  | 'PreToolUse' | 'PostToolUse'
  | 'UserPromptSubmit' | 'Notification'
  | 'Stop' | 'SubagentStop'

export async function executePreToolUseHooks(
  toolName: string, input: AnyObject, context: HookContext
): Promise<HookResult>

export async function executePostToolUseHooks(
  toolName: string, input: AnyObject, output: AnyObject, context: HookContext
): Promise<HookResult>

export async function executeUserPromptSubmitHooks(
  prompt: string, context: HookContext
): Promise<HookResult>

export function getUserPromptSubmitHookBlockingMessage(result: HookResult): string | null

export async function executeNotificationHooks(
  message: string
): Promise<void>

Implementation:

• Reads hooks from settings (PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop)
• Uses wrapSpawn() for execution (pipe mode)
• Injects env vars: CLAUDE_TOOL_NAME, CLAUDE_TOOL_INPUT, TOOL_OUTPUT, etc.
• Respects shouldAllowManagedHooksOnly() and shouldDisableAllHooksIncludingManaged()
• Plugin options substituted via substituteUserConfigVariables()

hooks/fileChangedWatcher.ts

Watches for file changes triggered by hooks.

export async function onCwdChangedForHooks(oldCwd: string, newCwd: string): Promise<void>

hooks/AsyncHookRegistry.ts

Registry for async hook handlers.

hooks/hooksConfigSnapshot.ts

Cached hooks configuration snapshot.

---

17. Analytics & Telemetry

telemetry/ subdirectory

• telemetry/events.ts — OpenTelemetry event logging
• Related to OTel span/event emission

telemetryAttributes.ts

Standard telemetry attribute names.

headlessProfiler.ts / profilerBase.ts

Performance profiling utilities for headless mode.

startupProfiler.ts

export function profileCheckpoint(name: string): void
export function getStartupProfile(): StartupProfile

queryProfiler.ts

Profiles individual query performance.

slowOperations.ts

export function jsonParse<T>(s: string): T
export function jsonStringify(v: unknown): string
export function clone<T>(v: T): T
// These ops are tracked for performance monitoring

fpsTracker.ts

Frame rate tracking for UI performance.

heatmap.ts

Records usage heatmap data for UX analytics.

unaryLogging.ts

Unary gRPC event logging.

stats.ts / statsCache.ts

Session statistics (token usage, tool calls, etc.).

---

18. Background & Cron Systems

cron.ts / cronScheduler.ts

Core cron job scheduling.

export function scheduleCron(
  id: string,
  schedule: string,
  fn: () => Promise<void>
): void
export function cancelCron(id: string): void

cronTasks.ts

Standard cron task definitions (housekeeping, analytics uploads, etc.).

cronTasksLock.ts

Distributed locking for cron tasks.

cronJitterConfig.ts

Adds jitter to cron schedules to prevent thundering herd.

background/remote/remoteSession.ts

Background remote session management.

background/remote/preconditions.ts

Precondition checks for remote sessions.

backgroundHousekeeping.ts

Background cleanup tasks (temp files, old sessions, etc.).

---

19. Computer Use

computerUse/common.ts

Common computer use types and utilities.

computerUse/executor.ts

Executes computer use actions (mouse clicks, typing, screenshots).

computerUse/gates.ts

Feature gates for computer use (entitlement checks).

computerUse/hostAdapter.ts

Platform-specific host adapters (macOS, Linux).

computerUse/setup.ts / computerUse/setupPortable.ts

Computer use setup and initialization.

computerUse/mcpServer.ts

Exposes computer use capabilities as an MCP server.

computerUse/toolRendering.tsx

React components for rendering computer use tool results.

computerUse/wrapper.tsx

React wrapper for computer use sessions.

computerUse/inputLoader.ts

Loads computer use input configurations.

computerUse/swiftLoader.ts

macOS Swift bridge for computer use.

computerUse/drainRunLoop.ts

Drains the macOS run loop for proper screenshot timing.

computerUse/escHotkey.ts

ESC hotkey handler for computer use sessions.

computerUse/computerUseLock.ts

Prevents concurrent computer use sessions.

computerUse/cleanup.ts

Cleans up computer use resources.

computerUse/appNames.ts

Platform-specific application name detection.

---

20. Claude-in-Chrome

claudeInChrome/common.ts

Common types for Claude-in-Chrome integration.

claudeInChrome/chromeNativeHost.ts

Native host messaging protocol for Chrome extension communication.

claudeInChrome/mcpServer.ts

Exposes Chrome tab content as MCP resources.

claudeInChrome/prompt.ts

System prompt extensions for Chrome integration.

claudeInChrome/setup.ts / setupPortable.ts

Chrome native host setup.

claudeInChrome/toolRendering.tsx

React rendering for Chrome-specific tool results.

---

21. Deep Link System

deepLink/parseDeepLink.ts

export function parseDeepLink(url: string): DeepLinkAction | null
// Parses claude://... URLs

deepLink/protocolHandler.ts

Registers and handles the claude:// protocol.

deepLink/registerProtocol.ts

Registers the deep link protocol with the OS.

deepLink/banner.ts

Shows deep link activation banners.

deepLink/terminalLauncher.ts

Launches terminal sessions from deep links.

deepLink/terminalPreference.ts

export function updateDeepLinkTerminalPreference(terminal: string): void
export function getPreferredTerminal(): string | null

desktopDeepLink.ts

Desktop app deep link integration.

---

22. Plugin Utilities

plugins/ subdirectory (in utils)

• pluginOptionsStorage.ts — stores/retrieves plugin configuration
• pluginDirectories.ts — returns plugin installation directories
• schemas.ts — plugin manifest Zod schemas

dxt/helpers.ts

DXT (Desktop Extension) package helpers.

dxt/zip.ts

ZIP archive utilities for DXT packages.

---

23. Swarm Backends

(Covered in Section 13)

---

24. Skills & Suggestions

skills/ subdirectory

Skill-specific utilities:

• skillUsageTracking.ts — tracks usage frequency per skill

suggestions/commandSearch.ts

export function searchCommands(
  query: string,
  commands: Command[]
): SuggestionItem[]
// Uses Fuse.js with memoized index (keyed by commands array identity)

contextSuggestions.ts

AI-driven context suggestions for the prompt input.

suggestionFiltering.ts

Filters suggestions by relevance.

---

25. Todo System

todo/types.ts

export type TodoItem = {
  id: string
  content: string
  status: 'pending' | 'in_progress' | 'completed'
  priority: 'high' | 'medium' | 'low'
}
export type TodoList = TodoItem[]

---

26. Teleport System

teleport/api.ts

API calls for the Teleport remote execution system.

teleport/environmentSelection.ts

Selects the remote execution environment.

teleport/environments.ts

Available Teleport environments configuration.

teleport/gitBundle.ts

Creates and transfers git bundles for Teleport sessions.

teleport.tsx

export async function teleportToRemote(
  options: TeleportOptions,
  root: Root
): Promise<TeleportResult>
// Launches a remote Claude Code session via CCR

---

27. Memory Utilities

memory/types.ts

export type MemoryType = 'project' | 'user' | 'team'
export type MemoryFile = {
  path: string
  type: MemoryType
  content: string
}

memoryFileDetection.ts

Detects and loads relevant memory files for the current context.

claudemd.ts

CLAUDE.md file management (reading, writing, external includes).

export function getMemoryFiles(cwd?: string): MemoryFile[]
export function getExternalClaudeMdIncludes(cwd?: string): string[]
export function shouldShowClaudeMdExternalIncludesWarning(): boolean

markdownConfigLoader.ts

Loads configuration from CLAUDE.md-style markdown files.

---

28. Sandbox Utilities

sandbox/sandbox-adapter.ts

export class SandboxManager {
  static async wrapWithSandbox(
    command: string,
    shellBin: string,
    options?: SandboxOptions,
    abortSignal?: AbortSignal
  ): Promise<string>
  static cleanupAfterCommand(): void
  static async refreshConfig(): Promise<void>
}

Uses Linux bwrap or macOS sandbox-exec depending on platform.

sandbox/ (other files)

• Sandbox configuration management
• Platform-specific sandbox profile generation

---

29. Security & Secure Storage

secureStorage/ subdirectory

Secure credential storage (macOS Keychain, Windows Credential Manager, Linux secret service).

crypto.ts

export function generateSecureToken(length?: number): string
export function hashString(s: string): string

fingerprint.ts

Device fingerprinting for trust management.

hash.ts

Content hashing utilities.

uuid.ts

export function generateUUID(): string
export function generateSessionId(): string

taggedId.ts

Type-safe tagged ID types (prevents mixing SessionId, AgentId, etc.).

---

30. Native Installer

nativeInstaller/ subdirectory

Native binary installation utilities.

localInstaller.ts

Installs Claude Code to local paths.

autoUpdater.ts

Auto-update checking and installation.

---

31. General Utilities (Top-Level)

Environment & Platform

File	Purpose
env.ts	Environment variable constants and getters
envDynamic.ts	Dynamically-loaded env vars
envUtils.ts	isEnvTruthy(), isBareMode(), isRunningOnHomespace(), getClaudeConfigHomeDir()
envValidation.ts	Validates required env vars
platform.ts	getPlatform(): 'macos' | 'linux' | 'windows'
bundledMode.ts	isBundledMode(): boolean
managedEnv.ts	Managed environment variable injection from settings
managedEnvConstants.ts	Constants for managed env vars

String & Formatting

File	Purpose
stringUtils.ts	capitalize(), plural(), safeJoinLines(), etc.
format.ts	formatDuration(), formatBytes(), etc.
formatBriefTimestamp.ts	Brief timestamp formatting
truncate.ts	Text truncation utilities
words.ts	Word counting and manipulation
sliceAnsi.ts	Slices ANSI-escaped strings without breaking escape codes
cliHighlight.ts	Syntax highlighting for CLI output
markdown.ts	Markdown rendering utilities
hyperlink.ts	Terminal hyperlink (OSC 8) utilities
intl.ts	Internationalization utilities
sanitization.ts	Input sanitization

JSON & Data

File	Purpose
json.ts	safeParseJSON(), JSON read/write
jsonRead.ts	stripBOM(), safe JSON file reading
yaml.ts	YAML parsing utilities
xml.ts	XML parsing utilities
zodToJsonSchema.ts	Converts Zod schemas to JSON Schema
lazySchema.ts	Deferred Zod schema validation
frontmatterParser.ts	Parses YAML frontmatter from markdown
semanticBoolean.ts	Parses "truthy" strings ('true', 'yes', '1')
semanticNumber.ts	Parses number strings with units

HTTP & Networking

File	Purpose
http.ts	Fetch wrappers with timeout and retry
proxy.ts	HTTP proxy configuration
mtls.ts	mTLS certificate management
caCerts.ts	Custom CA certificate loading
caCertsConfig.ts	CA cert configuration
peerAddress.ts	Peer address utilities
mcpWebSocketTransport.ts	MCP WebSocket transport
apiPreconnect.ts	Pre-connects to API for latency reduction
userAgent.ts	HTTP User-Agent string construction

API & Claude Communication

File	Purpose
api.ts	High-level API utilities
queryContext.ts	Query context construction
queryHelpers.ts	Query helper functions
tokenBudget.ts	Token budget management
tokens.ts	Token counting utilities
stream.ts	Streaming response utilities
streamJsonStdoutGuard.ts	Guards against JSON corruption in stream
streamlinedTransform.ts	Transforms streaming API responses
thinking.ts	Extended thinking utilities
sideQuery.ts	Side-channel query execution
sideQuestion.ts	Side-question display
sdkEventQueue.ts	SDK event queue management

Session & Context

File	Purpose
systemPrompt.ts	buildEffectiveSystemPrompt() — assembles the system prompt from multiple sources
systemPromptType.ts	SystemPrompt type and asSystemPrompt()
agentContext.ts	Agent execution context
agentId.ts	Agent ID generation
context.ts	Context window utilities
contextAnalysis.ts	Analyzes context window usage
analyzeContext.ts	Deeper context analysis
workloadContext.ts	Workload context for load balancing
queryContext.ts	Query context construction

Display & UI

File	Purpose
displayTags.ts	UI display tags
logoV2Utils.ts	Logo V2 utilities
status.tsx	Status display utilities
statusNoticeDefinitions.tsx	Status notice type definitions
statusNoticeHelpers.ts	Status notice helpers
treeify.ts	Renders tree structures as ASCII
highlightMatch.tsx	Highlights search matches in text
textHighlighting.ts	Text highlighting utilities
horizontalScroll.ts	Horizontal scroll state management
fullscreen.ts	Full-screen mode utilities
exportRenderer.tsx	Renders sessions for export
staticRender.tsx	Static React rendering (headless)

Config & Meta

File	Purpose
claudeCodeHints.ts	Context-sensitive hints for users
claudeDesktop.ts	Claude Desktop app integration
exampleCommands.ts	Example slash commands for help
releaseNotes.ts	Release notes loading and display
version.ts (referenced)	Version string management
undercover.ts	ANT-only: undercover/internal mode
bundledMode.ts	Detects bundled (desktop) mode

Diagnostics & Debugging

File	Purpose
debug.ts	logForDebugging(), logAntError()
debugFilter.ts	Debug output filtering
diagLogs.ts	logForDiagnosticsNoPII() — diagnostic logs without PII
log.ts	logError() — structured error logging
errorLogSink.ts	Error log collection
warningHandler.ts	Warning deduplication and display
doctorDiagnostic.ts	Diagnostic check implementations for /doctor
doctorContextWarnings.ts	Context-specific doctor warnings
diagLogs.ts	Non-PII diagnostic logging

IDE Integration

File	Purpose
ide.ts	VS Code / JetBrains IDE integration
idePathConversion.ts	Converts paths for IDE display
jetbrains.ts	JetBrains-specific integration
terminalPanel.ts	IDE terminal panel integration

Miscellaneous

File	Purpose
activityManager.ts	Tracks user activity
argom entSubstitution.ts	Substitutes arguments in templates
autoModeDenials.ts	Tracks auto-mode permission denials
autoRunIssue.tsx	Auto-run issue detection
binaryCheck.ts	Detects binary files
browser.ts	Opens URLs in browser
bufferedWriter.ts	Buffered async file writer
classifierApprovals.ts	Classifier-based approval management
classifierApprovalsHook.ts	React hook for classifier approvals
codeIndexing.ts	Code indexing for search
commandLifecycle.ts	Command lifecycle event management
completionCache.ts	Caches shell completions
conversationRecovery.ts	Recovers from corrupted conversations
effor.ts	Effort level management
editor.ts	External editor integration
earlyInput.ts	Captures input before UI is ready
embeddedTools.ts	Embedded tool management
extraUsage.ts	Extra usage tracking
fastMode.ts	Fast mode (sonnet default) management
idleTimeout.ts	Idle session timeout management
immediateCommand.ts	Immediate command execution (no spinner)
keyboardShortcuts.ts	Keyboard shortcut definitions
mailbox.ts	Inter-process mailbox messaging
modifiers.ts	Keyboard modifier key detection
objectGroupBy.ts	Object.groupBy polyfill
pasteStore.ts	Paste content storage
planModeV2.ts	Plan mode state management
plans.ts	Plan data management
preflightChecks.tsx	Pre-launch health checks
privacyLevel.ts	getEssentialTrafficOnlyReason() — privacy mode
promptCategory.ts	Categorizes prompts for analytics
promptEditor.ts	Multi-line prompt editing
queueProcessor.ts	Generic queue processing
renderOptions.ts	getBaseRenderOptions() for Ink
screenshotClipboard.ts	Screenshot clipboard utilities
shellConfig.ts	Shell configuration management
sleep.ts	sleep(ms: number): Promise<void>
timeouts.ts	Timeout utilities
tmuxSocket.ts	Tmux socket communication
toolErrors.ts	Tool error message formatting
toolPool.ts	Tool instance pooling
toolResultStorage.ts	Storage for tool call results
toolSchemaCache.ts	Caches compiled tool schemas
toolSearch.ts	Fuzzy search over available tools
transcriptSearch.ts	Full-text search within session transcripts
user.ts	User info utilities
userPromptKeywords.ts	Extracts keywords from user prompts
which.ts / findExecutable.ts	Finds executables in PATH
windowsPaths.ts	Windows/POSIX path conversion
withResolvers.ts	Promise.withResolvers polyfill
ansiToPng.ts / ansiToSvg.ts	ANSI terminal output to image
asciicast.ts	asciinema recording format
appleTerminalBackup.ts / iTermBackup.ts	Terminal state backup
attribution.ts	Message attribution tracking
ink.ts (in utils)	Ink-related utility helpers

---

32. interactiveHelpers.tsx

High-level interactive session initialization utilities. Runs in the main thread before the REPL starts.

Exports:

export function completeOnboarding(): void
// Sets hasCompletedOnboarding = true in global config

export function showDialog<T = void>(
  root: Root,
  renderer: (done: (result: T) => void) => React.ReactNode
): Promise<T>
// Renders a dialog via Ink and waits for completion

export async function exitWithError(
  root: Root,
  message: string,
  beforeExit?: () => Promise<void>
): Promise<never>
// Renders error message through Ink then exits (avoids console.error being swallowed)

export async function exitWithMessage(
  root: Root,
  message: string,
  options?: { color?: TextProps['color']; exitCode?: number; beforeExit?: () => Promise<void> }
): Promise<never>

Key Imports/Dependencies:

• bootstrap/state — global state management
• services/analytics/growthbook — feature flags
• state/AppState — application state
• utils/claudemd — CLAUDE.md reading
• utils/config — global/project config
• utils/settings/settings — user settings
• services/mcpServerApproval — MCP approval flow
• keybindings/KeybindingProviderSetup — keybinding initialization

---

33. ink.ts (Top-Level Module)

The public API for the Ink terminal rendering framework used throughout Claude Code.

Purpose: Wraps the internal ink/root.ts with a ThemeProvider so every render is automatically themed.

Key Exports:

// Rendering
export async function render(node: ReactNode, options?: NodeJS.WriteStream | RenderOptions): Promise<Instance>
export async function createRoot(options?: RenderOptions): Promise<Root>

// Re-exports from ink/root
export type { RenderOptions, Instance, Root }

// Theme system
export { color } from './components/design-system/color.js'
export type { Props as BoxProps }
export { default as Box }         // ThemedBox
export type { Props as TextProps }
export { default as Text }        // ThemedText
export { ThemeProvider, usePreviewTheme, useTheme, useThemeSetting }

// Core ink components (re-exported from ink/)
export { Ansi }
export { default as BaseBox }
export { default as Button }
export { default as Link }
export { default as Newline }
export { NoSelect }
export { RawAnsi }
export { default as Spacer }
// ... more components

Key Detail: The render() and createRoot() wrappers apply withTheme() which wraps the node in ThemeProvider. This means every call site automatically has access to themed colors, eliminating the need for each component to mount its own ThemeProvider.

---

34. utils/shell/ — Shell Provider Abstraction

The shell/ subdirectory provides a shell-type-agnostic provider interface so BashTool and PowerShellTool can share execution infrastructure.

shell/shellProvider.ts

Defines the ShellProvider interface:

export const SHELL_TYPES = ['bash', 'powershell'] as const
export type ShellType = (typeof SHELL_TYPES)[number]
export const DEFAULT_HOOK_SHELL: ShellType = 'bash'

export type ShellProvider = {
  type: ShellType
  shellPath: string
  detached: boolean
  buildExecCommand(command, opts): Promise<{ commandString, cwdFilePath }>
  getSpawnArgs(commandString): string[]
  getEnvironmentOverrides(command): Promise<Record<string, string>>
}

shell/bashProvider.ts

Factory: createBashShellProvider(shellPath, options?): Promise<ShellProvider>

Key behaviors:

• Snapshot sourcing: Lazy-initializes a shell snapshot and sources it on every command for consistent environment. Falls back to login-shell (-l flag) when snapshot is missing.
• extglob disabling: Injects shopt -u extglob / setopt NO_EXTENDED_GLOB for security against malicious filename glob expansion after snapshot load.
• eval wrapping: Commands are eval-wrapped so aliases sourced from snapshot expand correctly.
• CWD tracking: Appends pwd -P >| <cwdFile> so getCwd() stays synchronized.
• Pipe rearrangement: When a command contains | and needs stdin redirect, calls rearrangePipeCommand() to apply redirect to first pipe segment only.
• Tmux isolation: Lazily initializes Claude's isolated tmux socket when hasTmuxToolBeenUsed() or the command contains tmux.
• Windows compatibility: Rewrites 2>nul to /dev/null and converts paths via windowsPathToPosixPath.
• CLAUDE_CODE_SHELL_PREFIX: Wraps the assembled command string in a custom prefix for shell environment wrappers.

shell/powershellProvider.ts

Factory: createPowerShellProvider(shellPath): ShellProvider

Key behaviors:

• Encodes PS commands as Base64 UTF-16LE (-EncodedCommand) to survive shell-quoting layers.
• Non-detached (PowerShell requires synchronous spawning on Windows).
• CWD tracked to a temp file using PS Set-Content.
• Uses $LASTEXITCODE / $? for exit code capture (handles PS 5.1 quirks).

shell/outputLimits.ts

export const BASH_MAX_OUTPUT_UPPER_LIMIT = 150_000
export const BASH_MAX_OUTPUT_DEFAULT = 30_000
export function getMaxOutputLength(): number
// Reads BASH_MAX_OUTPUT_LENGTH env var; validated and clamped to [1, 150_000]

shell/shellToolUtils.ts

export const SHELL_TOOL_NAMES: string[]   // [BASH_TOOL_NAME, POWERSHELL_TOOL_NAME]
export function isPowerShellToolEnabled(): boolean
// Windows-only gate: ant users default ON (opt-out via env=0),
// external users default OFF (opt-in via env=1)

shell/readOnlyCommandValidation.ts

Exports comprehensive allow-lists for read-only command validation:

• GIT_READ_ONLY_COMMANDS — All safe git subcommands with permitted flags and callbacks
• GH_READ_ONLY_COMMANDS — Ant-only GitHub CLI read commands
• EXTERNAL_READONLY_COMMANDS — Cross-shell safe commands (ls, cat, grep, etc.)
• containsVulnerableUncPath(cmd) — Detects Windows UNC paths that could leak credentials
• FlagArgType — 'none' | 'number' | 'string' | 'char' | '{}' | 'EOF'
• ExternalCommandConfig — { safeFlags, additionalCommandIsDangerousCallback?, respectsDoubleDash? }

shell/specPrefix.ts

Fig-spec-driven command prefix extraction:

export const DEPTH_RULES: Record<string, number>
// Overrides: rg→2, gcloud→4, kubectl→3, docker→3, aws→4, etc.

export async function buildPrefix(
  command: string,
  args: string[],
  spec: CommandSpec | null
): Promise<string>
// e.g. "git -C /repo status --short" → "git status"

shell/prefix.ts

LLM-based (Haiku) command prefix extraction factory:

export type CommandPrefixResult = { commandPrefix: string | null }
export type PrefixExtractorConfig = {
  toolName: string
  policySpec: string
  eventName: string
  querySource: QuerySource
  preCheck?: (command: string) => CommandPrefixResult | null
}

export function createCommandPrefixExtractor(config: PrefixExtractorConfig)
// Returns memoized (LRU 200) async function. Calls Haiku with policySpec.
// Rejects: command_injection_detected, bare shell names, non-prefix responses.

export function createSubcommandPrefixExtractor(getPrefix, splitCommand)
// Extracts prefix for each subcommand in a compound command (e.g. a && b)

shell/powershellDetection.ts

Detects available PowerShell executables (pwsh vs powershell.exe) on Windows.

---

35. utils/ultraplan/ — Ultraplan Remote Session Polling

The ultraplan/ subdirectory supports the /ultraplan command, which launches a plan-mode CCR session and waits for the user to approve a plan in the browser.

ultraplan/ccrSession.ts

Types:

export type PollFailReason =
  | 'terminated' | 'timeout_pending' | 'timeout_no_plan'
  | 'extract_marker_missing' | 'network_or_unknown' | 'stopped'

export class UltraplanPollError extends Error {
  reason: PollFailReason
  rejectCount: number
}

export const ULTRAPLAN_TELEPORT_SENTINEL = '__ULTRAPLAN_TELEPORT_LOCAL__'
// Browser embeds this in the rejection feedback when user clicks "teleport back to terminal"

export type ScanResult =
  | { kind: 'approved'; plan: string }
  | { kind: 'teleport'; plan: string }  // user wants local execution
  | { kind: 'rejected'; id: string }
  | { kind: 'pending' }
  | { kind: 'terminated'; subtype: string }
  | { kind: 'unchanged' }

export type UltraplanPhase = 'running' | 'needs_input' | 'plan_ready'

ExitPlanModeScanner — pure stateful classifier over the CCR event stream:

export class ExitPlanModeScanner {
  get rejectCount(): number
  get hasPendingPlan(): boolean   // ExitPlanMode emitted, no tool_result yet
  everSeenPending: boolean
  ingest(newEvents: SDKMessage[]): ScanResult
  // Tracks ExitPlanMode tool_use IDs and their corresponding tool_results
  // Precedence: approved > terminated > rejected > pending > unchanged
}

pollForApprovedExitPlanMode — main polling loop:

export type PollResult = {
  plan: string
  rejectCount: number
  executionTarget: 'local' | 'remote'
}

export async function pollForApprovedExitPlanMode(
  sessionId: string,
  timeoutMs: number,
  onPhaseChange?: (phase: UltraplanPhase) => void,
  shouldStop?: () => boolean
): Promise<PollResult>

Polls pollRemoteSessionEvents() every 3 seconds. MAX_CONSECUTIVE_FAILURES = 5 before giving up on transient network errors. Plan text is extracted from tool_result.content via:

• "## Approved Plan:\n" or "## Approved Plan (edited by user):\n" markers (remote execution)
• ULTRAPLAN_TELEPORT_SENTINEL + "\n" marker (local execution)

ultraplan/keyword.ts

Detects ultraplan / ultrareview keyword triggers in user input, with smart exclusion:

export function findUltraplanTriggerPositions(text: string): TriggerPosition[]
export function findUltrareviewTriggerPositions(text: string): TriggerPosition[]
export function hasUltraplanKeyword(text: string): boolean
export function hasUltrareviewKeyword(text: string): boolean
export function replaceUltraplanKeyword(text: string): string
// Replaces first triggerable "ultraplan" with "plan" for the forwarded CCR prompt

Does NOT trigger when the keyword is inside paired delimiters (backticks, quotes, brackets, braces), in a path/identifier context, followed by ?, or in a slash command. Apostrophe-aware: "let's ultraplan" still triggers.