# 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](#1-core-data-structures)
2. [Shell & Process Execution](#2-shell--process-execution)
3. [Bash Parsing & Analysis](#3-bash-parsing--analysis)
4. [Configuration & Settings](#4-configuration--settings)
5. [Authentication & Auth Management](#5-authentication--auth-management)
6. [Permissions System](#6-permissions-system)
7. [File & Filesystem Utilities](#7-file--filesystem-utilities)
8. [Git Utilities](#8-git-utilities)
9. [Session Management](#9-session-management)
10. [Message & Content Utilities](#10-message--content-utilities)
11. [Model Utilities](#11-model-utilities)
12. [MCP Utilities](#12-mcp-utilities)
13. [Swarm / Multi-Agent System](#13-swarm--multi-agent-system)
14. [Task & Output Management](#14-task--output-management)
15. [Process User Input](#15-process-user-input)
16. [Hooks System](#16-hooks-system)
17. [Analytics & Telemetry](#17-analytics--telemetry)
18. [Background & Cron Systems](#18-background--cron-systems)
19. [Computer Use](#19-computer-use)
20. [Claude-in-Chrome](#20-claude-in-chrome)
21. [Deep Link System](#21-deep-link-system)
22. [Plugin Utilities](#22-plugin-utilities)
23. [Swarm Backends](#23-swarm-backends)
24. [Skills & Suggestions](#24-skills--suggestions)
25. [Todo System](#25-todo-system)
26. [Teleport System](#26-teleport-system)
27. [Memory Utilities](#27-memory-utilities)
28. [Sandbox Utilities](#28-sandbox-utilities)
29. [Security & Secure Storage](#29-security--secure-storage)
30. [Native Installer](#30-native-installer)
31. [General Utilities (Top-Level)](#31-general-utilities-top-level)
32. [interactiveHelpers.tsx](#32-interactivehelperstsx)
33. [ink.ts (Top-Level Module)](#33-inkts-top-level-module)
34. [utils/shell/ — Shell Provider Abstraction](#34-utilsshell--shell-provider-abstraction)
35. [utils/ultraplan/ — Ultraplan Remote Session Polling](#35-utilsultraplan--ultraplan-remote-session-polling)

---

## 1. Core Data Structures

### `CircularBuffer.ts`
Fixed-size circular buffer that auto-evicts oldest items when full.

```typescript
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`.

```typescript
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).

```typescript
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.

```typescript
// 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.

```typescript
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:**
```typescript
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:**
```typescript
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.

```typescript
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`
```typescript
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`
```typescript
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`
```typescript
export function subprocessEnv(): NodeJS.ProcessEnv
// Returns filtered process.env suitable for subprocess spawning
```

---

## 3. Bash Parsing & Analysis

### `bash/ParsedCommand.ts`
```typescript
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`
```typescript
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`
```typescript
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:**
```typescript
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:**
```typescript
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:**
```typescript
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`
```typescript
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`
```typescript
export function getManagedFilePath(): string
export function getManagedSettingsDropInDir(): string
```

### `settings/allErrors.ts`
```typescript
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:**
```typescript
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.

```typescript
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).

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

### `aws.ts`
AWS credential management and STS caller identity checking.

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

### `awsAuthStatusManager.ts`
```typescript
export class AwsAuthStatusManager {
  getStatus(): AwsAuthStatus
  // Manages AWS auth lifecycle with refresh
}
```

### `betas.ts`
Beta feature flag management tied to account subscription.

```typescript
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:**
```typescript
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`
```typescript
export type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan'
export function permissionModeTitle(mode: PermissionMode): string
```

### `permissions/PermissionResult.ts`
```typescript
export type PermissionDecision =
  | PermissionAskDecision    // { type: 'ask', message, ... }
  | PermissionDenyDecision   // { type: 'deny', reason, ... }
  | { type: 'allow' }
  | { type: 'allowWithSandbox' }
```

### `permissions/PermissionRule.ts`
```typescript
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.

```typescript
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`
```typescript
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`
```typescript
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.

```typescript
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`
```typescript
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`
```typescript
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.

```typescript
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`
```typescript
export async function createTempFile(suffix?: string): Promise<string>
export function cleanupTempFiles(): void
```

### `lockfile.ts`
File-based distributed locking.

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

### `cleanupRegistry.ts`
```typescript
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:**
```typescript
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.

```typescript
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`
```typescript
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`
```typescript
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:**
```typescript
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`
```typescript
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`
```typescript
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`
```typescript
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:**
```typescript
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).

```typescript
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.

```typescript
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`
```typescript
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`
```typescript
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`
```typescript
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`
```typescript
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`
```typescript
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`
```typescript
export function formatModelPricing(model: ModelName): string
export function getOpus46CostTier(): 'standard' | 'premium'
```

### `context.ts`
Context window management.

```typescript
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`
```typescript
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`
```typescript
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.

```typescript
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`
```typescript
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.

```typescript
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.

```typescript
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`
```typescript
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:**
```typescript
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.

```typescript
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`
```typescript
export function profileCheckpoint(name: string): void
export function getStartupProfile(): StartupProfile
```

### `queryProfiler.ts`
Profiles individual query performance.

### `slowOperations.ts`
```typescript
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.

```typescript
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`
```typescript
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`
```typescript
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`
```typescript
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`
```typescript
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`
```typescript
export async function teleportToRemote(
  options: TeleportOptions,
  root: Root
): Promise<TeleportResult>
// Launches a remote Claude Code session via CCR
```

---

## 27. Memory Utilities

### `memory/types.ts`
```typescript
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).

```typescript
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`
```typescript
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`
```typescript
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`
```typescript
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:**
```typescript
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:**
```typescript
// 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:

```typescript
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`
```typescript
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`
```typescript
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:
```typescript
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:
```typescript
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:
```typescript
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:
```typescript
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:
```typescript
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:

```typescript
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.