11. Key Files Map
A priority-ordered list of files to read. If you only read 10 files, read the first 10.
Tier 1 — must read
| # | Path | Why |
|---|---|---|
| 1 | Tool.ts |
The Tool contract — the atomic abstraction of the whole system. |
| 2 | query.ts |
The agent loop. Generator-based, 1,729 lines, handles streaming, parallel tool execution, recovery branches. |
| 3 | QueryEngine.ts |
Per-conversation state machine wrapping query() for SDK/headless callers. |
| 4 | constants/prompts.ts |
The whole system prompt, assembled from modular sections. Read every bullet. |
| 5 | services/api/claude.ts |
Streaming, retries, thinking, beta headers, prompt cache. |
| 6 | services/compact/compact.ts + services/compact/prompt.ts + services/compact/autoCompact.ts |
Compaction — triggers, prompt, tail preservation, re-injection. |
| 7 | tools/AgentTool/prompt.ts + tools/AgentTool/AgentTool.tsx + tools/AgentTool/forkSubagent.ts + tools/AgentTool/built-in/generalPurposeAgent.ts |
How subagents and forks work. |
| 8 | memdir/memoryTypes.ts + memdir/memdir.ts |
Memory type taxonomy, prompt sections, directory layout. |
| 9 | tools/BashTool/BashTool.tsx + tools/BashTool/prompt.ts + tools/BashTool/bashPermissions.ts |
How the most complex tool is shaped; big prompt with Git Safety Protocol. |
| 10 | tools/ToolSearchTool/ToolSearchTool.ts + tools/ToolSearchTool/prompt.ts |
Deferred-tools architecture. |
Tier 2 — when you go deeper
| Area | Files |
|---|---|
| Permissions | hooks/useCanUseTool.tsx, utils/permissions/permissions.ts, utils/permissions/PermissionResult.ts, tools/BashTool/bashPermissions.ts |
| Skills | skills/bundledSkills.ts, skills/loadSkillsDir.ts, tools/SkillTool/SkillTool.ts, types/command.ts |
| Slash commands | commands.ts, types/command.ts, individual files under commands/* |
| Agents | tools/AgentTool/loadAgentsDir.ts, tools/AgentTool/runAgent.ts, tools/AgentTool/built-in/*.ts, tools/AgentTool/builtInAgents.ts |
| Memory & extraction | services/extractMemories/, services/SessionMemory/, memdir/findRelevantMemories.ts, utils/claudemd.ts |
| MCP | services/mcp/client.ts, services/mcp/elicitationHandler.ts, services/mcp/channelPermissions.ts, tools/MCPTool/MCPTool.ts |
| File I/O tools | tools/FileReadTool/FileReadTool.ts, tools/FileEditTool/FileEditTool.ts, tools/FileWriteTool/FileWriteTool.ts |
| State | state/AppStateStore.ts, state/store.ts, state/AppState.tsx, bootstrap/state.ts |
| UI / hooks | components/App.tsx, components/Messages.tsx, components/Message.tsx, hooks/useTextInput.ts, hooks/useCommandQueue.ts, hooks/useQueueProcessor.ts |
| Session & resume | utils/sessionStorage.ts, utils/conversationRecovery.ts, utils/sessionRestore.ts |
| Bridge / remote | bridge/bridgeMain.ts, bridge/types.ts, remote/RemoteSessionManager.ts, remote/SessionsWebSocket.ts |
| SDK types | entrypoints/agentSdkTypes.ts, entrypoints/sdk/coreSchemas.ts, entrypoints/sdk/coreTypes.ts, entrypoints/sdk/controlSchemas.ts |
| Thinking & fastmode | utils/thinking.ts, utils/fastMode.ts |
| File state & history | utils/fileStateCache.ts, utils/fileHistory.ts |
| Attribution | utils/attribution.ts, utils/commitAttribution.ts |
| Hooks (user-configured) | query/stopHooks.ts, services/extractMemories/, utils/hooks/hookHelpers.ts |
| Shell / bash parsing | utils/bash/ast.ts, utils/bash/commands.ts, tools/BashTool/sedEditParser.ts |
Tier 3 — niche but instructive
| Topic | Files |
|---|---|
| Plan mode | tools/EnterPlanModeTool/, tools/ExitPlanModeTool/ |
| Coordinator mode (ant-only) | coordinator/coordinatorMode.ts |
| Proactive / Kairos | proactive/index.ts, tools/BriefTool/ |
| Cron / scheduling | utils/cron.ts, utils/cronScheduler.ts, utils/cronTasks.ts, tools/ScheduleCronTool/ |
| Voice | voice/, services/voice.ts, hooks/useVoice.ts |
| Cost tracking | cost-tracker.ts, costHook.ts, services/api/logging.ts |
| Telemetry | services/analytics/index.ts, services/diagnosticTracking.ts, utils/sinks.ts |
| Sandbox | utils/sandbox/sandbox-adapter.ts, utils/sandbox/* |
| Plugin system | plugins/, utils/plugins/pluginLoader.ts |
| File history / rewind | commands/rewind/, utils/fileHistory.ts |
| Teammate / swarm / team memory | utils/teammate.ts, services/teamMemorySync/, utils/agentSwarmsEnabled.ts |
File size reference
| File | Lines |
|---|---|
main.tsx |
4,683 |
services/api/claude.ts |
3,419 |
query.ts |
1,729 |
services/compact/compact.ts |
1,705 |
tools/AgentTool/AgentTool.tsx |
1,397 |
QueryEngine.ts |
1,295 |
tools/BashTool/BashTool.tsx |
1,143 |
Tool.ts |
792 |
commands.ts |
754 |
setup.ts |
477 |
services/compact/prompt.ts |
374 |
tools/BashTool/prompt.ts |
369 |
entrypoints/init.ts |
340 |
entrypoints/cli.tsx |
302 |
tools/AgentTool/prompt.ts |
287 |
Reading paths by goal
Goal: Understand how the agent works end-to-end.
constants/prompts.ts → Tool.ts → query.ts → services/api/claude.ts → services/compact/compact.ts.
Goal: Build a similar agent system.
Add QueryEngine.ts, tools/AgentTool/prompt.ts, tools/AgentTool/forkSubagent.ts, memdir/memoryTypes.ts, hooks/useCanUseTool.tsx, tools/ToolSearchTool/.
Goal: Learn prompt-engineering tricks.
constants/prompts.ts (all of it) → tools/AgentTool/prompt.ts → tools/BashTool/prompt.ts → services/compact/prompt.ts → memdir/memoryTypes.ts.
Goal: Add a new tool.
Tool.ts → any existing tool in tools/<Name>/<Name>.ts → tools.ts registry → hooks/useCanUseTool.tsx for permission flow.
Goal: Add a new skill or slash command.
types/command.ts → commands.ts → skills/loadSkillsDir.ts → tools/SkillTool/SkillTool.ts.
Goal: Understand production concerns (retries, caching, fallbacks).
services/api/withRetry.ts → services/api/claude.ts → query.ts (recovery branches) → services/compact/autoCompact.ts.
Goal: Understand the UI.
components/App.tsx → components/Messages.tsx → components/Message.tsx → hooks/useTextInput.ts → hooks/useCommandQueue.ts → state/AppStateStore.ts.