Utils Module

220 files · ~60K lines

The Foundation — 220 files depended on by everything. No inbound dependencies. Contains files large enough to be standalone npm packages: a full Bash AST parser, a Claude message library, and more.

utils/utils/messages.ts utils/bash/

🏗️

The Dependency Paradox

Utils has zero dependencies on other modules — but every other module depends on it. It's the foundation that never looks up.

The 'Everything Depends on Me' Diagram

7 modules point inward. Utils points at nothing. This is the rarest shape in software — a true foundation layer.

utils/

220 files

Query/Engine

Tools

Permissions

Components

Services

Commands

Bridge

All 7 arrows point inward → utils has no outbound arrows

Query/Enginemessages.ts is the foundation for every API call

ToolsBashTool calls bashParser.ts for every command

PermissionsPermission rules live in utils/permissions/

Componentshooks.ts provides all UI state binding

ServicessessionStorage.ts powers persistence layer

CommandsShared formatters and session utilities

BridgeforkedAgent.ts and cache params live here

The Giant Files — Bar Chart

Several utils files are larger than most npm packages. Each bar is proportional to actual line count.

utils/messages.ts5,512 lines

Claude API message construction and transformation — the entire message pipeline in one file

utils/sessionStorage.ts5,105 lines

Session persistence, YAML serialization, eval replay support

utils/hooks.ts5,022 lines

React hooks for terminal state, streaming, and input handling

utils/bash/bashParser.ts4,436 lines

Tree-sitter Bash AST parser for security analysis

utils/attachments.ts3,997 lines

Attachment prefetch, image resize, PDF/notebook handling

These files aren't accidents — each is a complete domain (message pipeline, bash parsing, session storage) kept inline to avoid package overhead and benefit from tight TypeScript type integration.

utils/messages.ts — 5512 Lines Explained

The entire Claude API message pipeline lives in one file. Here's what those 5512 lines contain.

utils/messages.ts

Message Construction~800 lines

buildUserMessage(), buildAssistantMessage(), buildToolResultMessage() — factories for every message type

Context Window Projection~1200 lines

trimMessages(), projectToWindow() — how conversation is trimmed to fit the context limit

Message Merging~600 lines

mergeMessages() — combines consecutive same-role messages (Anthropic API requires alternating roles)

Tool Result Formatting~900 lines

Converts tool outputs into the format the LLM expects next turn — text, JSON, error messages

Attachment Injection~700 lines

Injects image/PDF content into message turns using multi-content blocks

Type Definitions~1300 lines

Message, ContentBlock, SDKMessage — TypeScript types for the entire message system

Bash AST Pipeline — From Command to Security Decision

bashParser.ts isn't regex — it's a full Tree-sitter AST parser. Here's the pipeline from raw string to allow/deny.

utils/bash/

⌨️

Raw Command

rm -rf /tmp/../etc

→

✂️

Tokenize

['rm', '-rf', '/tmp/../etc']

→

🌳

Parse Tree

AST via Tree-sitter (not regex)

→

🔍

Security Analysis

recursive_delete=true, path_traversal=true

→

🚫

Allow / Deny

BLOCK: recursive delete detected

Why AST, not regex? — Regex can be fooled by comments, strings, and quoted arguments. An AST parser understands the actual command structure — 'rm' inside a string literal is not the same as 'rm' as a command.

Recursive delete detection

Detects rm -r, rm -rf, find -delete patterns and flags them HIGH_RISK regardless of path.

Network access detection

Identifies curl, wget, nc, ncat, ssh, scp — flags commands that exfiltrate data or establish connections.

Subshell injection

Detects $(cmd), `cmd`, and heredoc patterns that could hide injected commands from simple string analysis.

Operator chaining analysis

Understands && and || chains — 'safe_cmd && rm -rf ~' is still flagged despite the leading safe command.

Path escape detection

Identifies ../../../ traversal patterns and absolute paths pointing outside the project root.

Privilege escalation

Flags sudo, su, chmod 777, and similar privilege escalation commands for explicit user approval.

Key Files

utils/messages.ts5512 lines

Message creation, formatting, Claude API message manipulation

utils/sessionStorage.ts5105 lines

Session persistence, YAML serialization, replay support

utils/hooks.ts5022 lines

React hooks for state, terminal input, streaming

utils/bash/bashParser.ts4436 lines

Tree-sitter Bash AST parser for security analysis

utils/attachments.ts3997 lines

Attachment prefetch, image resize, PDF/notebook handling

utils/git.ts~800 lines

Git helpers: branch detection, diff, staging, repo root resolution

Tools Module

BashTool calls bashParser.ts (which lives in Utils) for every command it runs.

Permissions Module

The entire permissions system (yoloClassifier, rule matching, path checks) lives in utils/permissions/.

Query/Engine Module

utils/messages.ts is the foundation for every message the query loop sends and receives.