Non-Obvious Design Decisions, Traps, And Day-One Debugging Risks
Startup is intentionally front-loaded with safe parallel side effects. main.tsx starts MDM reads and keychain prefetch before most imports so later config and auth reads are faster.
Trust is a first-class boundary. Interactive startup applies only safe config environment variables before the trust dialog; riskier work such as git context prefetch, plugin LSP servers, and full environment injection waits until trust is granted. Headless --print mode treats trust as implicit.
This TypeScript source imports .js specifiers everywhere because the runtime build expects emitted .js paths. When reading imports, mentally map back to or .
There are two startup paths that share most core logic: interactive REPL and headless runHeadless. The shared core lives in query.ts, QueryEngine.ts, Tool.ts, tools.ts, and the tool execution services.
commands.ts is the human command registry. If a behavior feels global, check there before hunting through UI components.
tools.ts is the tool registry and uses feature flags plus lazy require() calls to keep dead-code elimination working. A missing tool can be a flag problem, environment problem, or permission and filtering problem.
Permission decisions are layered. Static rules, enterprise policy, auto-mode safety stripping, hooks, classifier checks, interactive dialogs, and remote permission bridges all participate. hasPermissionsToUseTool() is only one step.
The codebase distinguishes command availability from tool availability. Commands are human-triggered flows. Tools are model-callable units emitted in API schemas.
Settings are merged from multiple sources with precedence, validation, caching, and preservation of unknown fields. The effective value can come from user, project, local, flag, policy, managed, or remote managed settings.
Managed settings support both a base file and a drop-in directory. Alphabetical drop-in ordering matters because later files win.
Worktree mode changes cwd, originalCwd, and sometimes projectRoot. Bugs that only happen under --worktree usually come from reading one of those values at the wrong time.
Plugin loading differs between interactive and headless paths. Interactive startup does more background work; headless often awaits plugin work so the process does not exit before bookkeeping finishes.
MCP servers come from explicit flags, settings, .mcp.json, plugins, enterprise config, and Claude.ai connectors. Dedup happens by signature, not just by name.
The remote-control bridge and remote session viewer are related but different. bridge/* exposes the local machine or session outward. remote/* attaches to a hosted remote session.
The codebase has both React state and process-global bootstrap state. Session IDs, meters, counters, and certain flags live in bootstrap/state.ts; UI and session state lives in AppState and the store.
Background tasks, agents, and teammates are first-class. Many helpers under tasks/*, tools/AgentTool/*, utils/swarm/*, and components/tasks/* exist to keep those long-lived units visible and controllable.
A large share of performance work is about avoiding module-evaluation cost. Lazy imports, cache warming, and startup comments usually exist because someone measured a regression already.
Temp settings files use content-hash-based names instead of random UUIDs. That preserves prompt-cache stability because tool descriptions and sandbox prompts include those paths.
The giant utils/ directory is the platform layer. If a feature touches config, files, session logs, git, telemetry, hooks, plugins, or model plumbing, the implementation usually lands there.
Some apparent dependency cycles are type-only or UI-wrapper cycles. The clearly visible runtime cycle is main.tsx -> dialogLaunchers.tsx -> interactiveHelpers.tsx -> main.tsx.
There is no single database module. Persistent state is mostly file-backed plus OS keychain and remote services.
If something fails only in --print or SDK mode, check cli/print.ts first. If it fails only in the interactive REPL, check screens/REPL.tsx and the hooks it mounts.
If a feature exists in the UI but not in the API-facing session, confirm whether it is REPL-only, hidden behind USER_TYPE === "ant", or controlled by a bun:bundle feature gate.
