The Big Picture — More Than a CLI Tool

What You’re Actually Running

When you type claude at the terminal, you’re invoking an npm package whose source maps point to ~4756 TypeScript files. The cli.js.map sourcesContent gives you the full picture. This is not a thin wrapper around an API — it’s a production-grade agent runtime that happens to ship as a CLI.

The scale matters: utils/ has 564 files, components/ 389, commands/ 207, tools/ 184, services/ 130, hooks/ 104, ink/ 96, bridge/ 31, skills/ 20, tasks/ 12. The four heaviest files tell you where the complexity lives: main.tsx at 4683 lines (the main loop), toolExecution.ts at 1745 lines (tool dispatch), query.ts at 1729 lines (the state machine), and AgentTool.tsx at 1397 lines (multi-agent dispatch).

Multiple Entry Points, One Runtime

Claude Code has four distinct entry points, all running the same agent core:

cli.tsx — the interactive terminal experience you use daily
init.ts — project initialization, runs once and exits
mcp.ts — exposes Claude Code as an MCP server, so other tools can call it as a resource
sdk/ — programmatic access, used when Claude Code is embedded in IDE plugins or automation pipelines

This is a deliberate design choice. The same tool execution pipeline, permission system, and context management runs whether you’re typing in a terminal, an IDE is calling via SDK, or another agent is orchestrating via MCP protocol. There’s no “lite mode” for non-interactive use — the full runtime runs everywhere.

How `cli.tsx` Dispatches

Before the main agent loop ever starts, cli.tsx handles several fast-path dispatches that skip heavy module loading entirely:

--version exits immediately with zero module initialization
--remote-control enters bridge mode for IDE integration
--daemon starts the background daemon process
ps, logs, attach, kill route to process management utilities
--worktree and --tmux set up environment before handing off

This matters for startup latency. The version flag, for instance, must be instant — loading 4756 TypeScript files worth of agent infrastructure for a version check would be wasteful. The fast-path logic keeps interactive use snappy.

101 Commands

Under src/commands/ there are 101 registered commands. These aren’t shell aliases — they’re structured command definitions that feed into the slash command system, carry metadata about permissions, and can be composed. When you run /compact or /clear inside a session, you’re hitting this layer.

The command system sits above the tool system. Commands are user-facing affordances; tools are the agent’s internal capabilities. A command might invoke multiple tools, modify session state, or trigger lifecycle hooks that the agent itself would never call directly.

Why This Architecture

The multi-entry design solves a real problem: as AI coding assistants move from standalone tools to ecosystem components, the agent runtime needs to be embeddable. An IDE plugin shouldn’t run a separate process — it should call the same agent that the CLI exposes. An MCP host shouldn’t need to know Claude Code’s internals — it should get a clean protocol surface.

The consequence is that Claude Code’s architecture is more like a server that happens to have a terminal frontend than a traditional CLI tool that happens to call an AI API. The agent runtime is the core; the CLI is one interface to it.

What This Series Covers

The rest of this series digs into the internals systematically:

Ch2: the main loop and how prompts get assembled
Ch3: the tool system — 42 tools and the governance pipeline that controls them
Ch4: multi-agent architecture and the six built-in agent roles
Ch5: the three-layer security model
Ch6: skills, plugins, and MCP as an ecosystem layer
Ch7: context as a budget — four compression mechanisms
Ch8: what it takes to turn an agent into a production system

The source is in the npm package. You can read it yourself.

Reference: This chapter draws on Xiao Tan’s (@tvytlx) Claude Code Architecture Deep Dive V2.0 report.