utils — Core Utility Library

Core Utility Library

Massive 300+ utility library providing foundational functions for every other module. Categories include: git operations, file system helpers, token counting/estimation, permissions engine, sandbox isolation, config management, session storage, telemetry, MCP validation, shell execution, diff processing, and more.

Architecture

The utils module is organized into cohesive category clusters, each serving specific consumer modules throughout the application.

flowchart LR
  subgraph Consumers["Consumer Modules"]
    Tools["Tool Execution
(BashTool, FileEditTool)"]
    Session["Session Manager"]
    API["API Client"]
    UI["UI / Renderer"]
  end

  subgraph UtilsCore["utils — Core Categories"]
    direction TB
    subgraph FSCluster["File System"]
      file["file.ts"]
      fsOps["fsOperations.ts"]
      path["path.ts"]
      glob["glob.ts"]
    end
    subgraph ShellCluster["Shell Execution"]
      Shell["Shell.ts"]
      ShellCmd["ShellCommand.ts"]
      process["process.ts"]
    end
    subgraph ConfigCluster["Configuration"]
      config["config.ts"]
      env["env.ts"]
      settings["settings/"]
    end
    subgraph AuthCluster["Auth & Security"]
      auth["auth.ts"]
      perms["permissions/"]
      secure["secureStorage/"]
      sandbox["sandbox/"]
    end
    subgraph MsgCluster["Messages & Tokens"]
      messages["messages.ts"]
      tokens["tokens.ts"]
      context["analyzeContext.ts"]
    end
    subgraph GitCluster["Git Operations"]
      git["git.ts"]
      worktree["worktree.ts"]
      gitDiff["gitDiff.ts"]
    end
  end

  subgraph Infra["Infrastructure"]
    telemetry["telemetry/"]
    memory["memory/ & claudemd.ts"]
    model["model/"]
    mcp["mcp/"]
  end

  Tools --> ShellCluster
  Tools --> AuthCluster
  Tools --> FSCluster
  Session --> ConfigCluster
  Session --> MsgCluster
  API --> MsgCluster
  API --> model
  UI --> memory
  UI --> telemetry

  ShellCluster --> FSCluster
  AuthCluster --> ConfigCluster
  MsgCluster --> ConfigCluster
  GitCluster --> FSCluster

Data Flow — Git Operation Trace

Trace a findGitRoot() call from a tool invocation through the utils git cluster, showing memoization and filesystem probing.

sequenceDiagram
    participant Tool as BashTool
    participant Git as git.ts
    participant Cache as LRU Cache
    participant FS as fsOperations.ts
    participant Path as path.ts
    participant Telem as telemetry/

    Tool->>Git: findGitRoot(cwd)
    Git->>Cache: lookup(cwd)
    alt Cache HIT
        Cache-->>Git: cachedRoot
        Git-->>Tool: "/repo/root"
    else Cache MISS
        Cache-->>Git: null
        Git->>Path: normalize(cwd)
        Path-->>Git: normalizedPath
        loop Walk up directory tree
            Git->>FS: stat(dir + "/.git")
            FS-->>Git: exists / not found
        end
        Git->>Cache: store(cwd, foundRoot)
        Git->>Telem: logEvent("git_root_found", duration)
        Git-->>Tool: "/repo/root"
    end

🚶 Step-by-Step Narrated Walkthrough

Follow a single file permission check as it flows through the utils permission engine:

Tool Invocation — FileEditTool receives a request to write /etc/hosts. Before any I/O, it must consult permissions/.
Rule Set Loading — permissions/ruleLoader.ts reads the active rule set from settings/ (managed, project, and user-level rules merged by priority).
Tool Name Matching — The engine matches the tool identifier (file_edit) against rule patterns — exact matches are tried first, then wildcards.
Path Pattern Evaluation — Each rule that matched the tool is tested against the target path /etc/hosts. Glob patterns like /etc/** are evaluated via glob.ts.
Priority Resolution — Rules are sorted by priority (managed > project > user > default). The first matching rule wins — in this case, a managed rule blocks /etc/* writes.
Dangerous Pattern Detection — Even without an explicit rule, the classifier checks a built-in deny list (e.g., rm -rf /, writes to /etc). This is a safety net.
Decision Assembly — The engine builds a result: { allowed: false, reason: "Managed rule blocks /etc/** writes", source: "managed" }.
Telemetry Emission — telemetry/ records the decision: tool name, path, outcome, rule source, and latency (~2 ms typical).
User Notification — The decision propagates back to the tool, which surfaces a permission-denied message to the user with the reason string.
Audit Trail — sessionStorage.ts appends the permission event to the session log for post-session review and compliance reporting.

Key Components

#	Component	File	Role
1	`Shell`	Shell.ts	Shell initialization, command execution, session management, provider selection
2	`ShellCommand`	ShellCommand.ts	Command wrapping, streaming output, exit code handling (~14k lines)
3	`getConfig()`	config.ts	Global/project config loading with re-entrancy guards; imported by 60+ files
4	`normalizeMessagesForAPI()`	messages.ts	Converts internal messages to Anthropic SDK format; handles tool results
5	`analyzeContextWindow()`	analyzeContext.ts	Token budget estimation, context compaction trigger, tool overhead calculation
6	`getSecureStorage()`	secureStorage/	Platform-adaptive credential storage (macOS Keychain → plaintext fallback)
7	`findGitRoot()`	git.ts	Cached git root detection; handles worktrees and submodules
8	`parseClaudeMarkdown()`	claudemd.ts	Memory file parsing with include directives and priority hierarchy
9	`loadSessionState()`	sessionStorage.ts	Session recovery, persistent state deserialization (~5k lines)
10	`memoizeWithTTL()`	memoize.ts	Write-through cache with background async refresh (stale-while-revalidate)
11	`ripgrepCommand()`	ripgrep.ts	Resolves ripgrep executable (system / builtin / embedded modes)
12	`findExecutable()`	findExecutable.ts	PATH-based executable lookup with platform-specific logic
13	`safeParseJSON()`	json.ts	LRU-bounded JSONC parsing with 50-entry cache and error handling
14	`auth`	auth.ts	OAuth / API key management, token refresh, credential verification
15	`permissions engine`	permissions/	24-file rule engine: pattern matching, classifier, mode enforcement

Sub-Modules

git/

Git operations, repository detection, worktree management, and diff generation.

Cached findGitRoot() with LRU memoization
Worktree activation / deactivation lifecycle
Structured diff generation with context lines
Shallow clone detection and branch operations

permissions/

Fine-grained permission rule engine governing tool and file access control.

24 files — rule loading, pattern matching, classifier
Priority-based resolution (managed → project → user)
Dangerous-pattern deny list as safety net
Audit trail integration with telemetry

sandbox/

Sandbox adapter for secure, isolated command execution environments.

Process isolation boundary enforcement
Adapter pattern for pluggable sandbox backends
Integration with permissions engine
Resource limit configuration

model/

Model options, capabilities, cost estimation, and provider selection.

16 files covering model metadata and pricing
Provider-aware capability detection
Cost estimation for token budgeting

shell/

Shell provider abstraction — Bash, Zsh, PowerShell detection and configuration.

Platform-adaptive shell selection algorithm
Output size limits and stream management
Subprocess environment setup

telemetry/

Event logging, tracing (Perfetto format), session tracing, and analytics export.

Structured event emission with attributes
Perfetto-compatible trace generation
Statistics collection and BigQuery export

Configuration

Setting / Constant	Location	Default	Purpose
`TOOL_TOKEN_COUNT_OVERHEAD`	analyzeContext.ts	500	Fixed token cost added when tools are present
`PARSE_CACHE_MAX_KEY_BYTES`	json.ts	8 KB	Max JSON string length eligible for LRU cache
`KILL_RING_MAX_SIZE`	Cursor.ts	10	Maximum entries in Emacs-style kill ring buffer
`DEFAULT_TIMEOUT`	Shell.ts	30 min	Maximum shell command execution time
`MAX_OUTPUT_SIZE`	shell/	0.25 MB	Maximum file output capture size
`CHECK_INTERVAL_MS`	cron.ts	1000 ms	Cron scheduler check frequency
`AUTOCOMPACT_BUFFER`	analyzeContext.ts	12%	Context window threshold triggering auto-compaction
`cacheLifetimeMs`	memoize.ts	5 min	Default TTL for memoized function results
`LRU cache size`	json.ts	50 entries	Bounded JSON parse cache to prevent memory growth
`CLAUDE_CODE_SHELL`	env.ts	(unset)	Override shell provider selection

Directory Map

Source tree for utils (30 categories, 564 files)

utils/
├── git/                        ← Git filesystem ops, cached reads, worktree paths
│   ├── git.ts                  ← Root detection, branch/commit operations (926 lines)
│   ├── worktree.ts             ← Worktree management, activation (1519 lines)
│   ├── gitDiff.ts              ← Diff generation
│   └── gitSettings.ts          ← Git configuration reading
├── permissions/                ← Permission rule engine (24 files)
│   ├── ruleLoader.ts           ← Rule set loading and merging
│   ├── classifier.ts           ← ML-based operation classifier
│   └── patterns.ts             ← Glob pattern matching for rules
├── sandbox/                    ← Sandbox adapter for secure execution
├── model/                      ← Model options, costs, providers (16 files)
├── bash/                       ← Bash-specific specs (15 files + specs/)
├── shell/                      ← Shell provider abstraction (10 files)
│   ├── bashProvider.ts         ← Bash shell provider
│   └── powershellProvider.ts   ← PowerShell provider
├── mcp/                        ← Model Context Protocol support
├── memory/                     ← Memory type definitions (User, Project, Local)
├── settings/                   ← Settings loader, MDM, per-source tracking (16 files)
├── telemetry/                  ← Event logging, Perfetto tracing (9 files)
├── background/                 ← Background task management
├── hooks/                      ← Hook utilities
├── plugins/                    ← Plugin system, loading, validation (44 files)
├── swarm/                      ← Agent swarm management (13 files)
├── secureStorage/              ← Platform-specific credential storage (6 files)
├── computerUse/                ← Computer use tool integration (15 files)
├── task/                       ← Task persistence, output management (5 files)
├── deepLink/                   ← Deep link parsing and handling (6 files)
├── teleport/                   ← Session teleporting (4 files)
├── filePersistence/            ← Persistent file storage (2 files)
├── messages/                   ← Message mappers, utilities (2 files)
├── config.ts                   ← Global/project config (1817 lines)
├── env.ts                      ← Environment variables (10k lines)
├── auth.ts                     ← OAuth/API key management (2002 lines)
├── messages.ts                 ← Message normalization (5512 lines)
├── sessionStorage.ts           ← Session persistence (5105 lines)
├── claudemd.ts                 ← Memory file loading (1479 lines)
├── Shell.ts                    ← Shell management (1530 lines)
├── ShellCommand.ts             ← Command wrapping (14k lines)
├── analyzeContext.ts           ← Token budget analysis (1382 lines)
├── file.ts                     ← Core file operations (1519 lines)
├── memoize.ts                  ← TTL/LRU memoization
├── json.ts                     ← Safe JSONC parsing with LRU cache
├── diff.ts                     ← Structured diff generation (4.8k lines)
├── ripgrep.ts                  ← Ripgrep integration (679 lines)
└── ...                         ← 91+ additional utility primitives

Design Patterns

Pattern	Example	Purpose
Factory Function	`getSecureStorage()`, `Shell.create()`	Platform/context-dependent object creation
LRU Cache	`memoizeWithLRU()`, `fileReadCache.ts`	Bounded memory caching with eviction
Stale-While-Revalidate	`memoizeWithTTL()`	Return instantly with cached value, refresh async
Provider Pattern	`ShellProvider`, `SecureStorage`	Pluggable implementations behind interfaces
Fallback Chain	Keychain → plaintext in `secureStorage/`	Graceful degradation across platforms
Re-entrancy Guard	`insideGetConfig` flag in `config.ts`	Prevent infinite recursion in config loading
Discriminated Union	`{ ok: true, value }` vs `{ ok: false }`	Type-safe error handling without exceptions