How Claude Code Works
The high-level architecture behind a Claude Code turn
A code-backed explanation of how Claude Code assembles context, runs the agent loop, invokes tools, and keeps long sessions moving.
The turn starts with context assembly
Claude Code does not start from a blank prompt. It prepends system context, user context, repository state, and date information before the main loop begins.
The context layer also decides whether Git status, CLAUDE.md instructions, and other session metadata should be injected or skipped.
- System context can include a git snapshot and cache-breaking prompt injection.
- User context can include discovered CLAUDE.md content and the local date.
- The context snapshot is intentionally memoized so a single conversation stays coherent.
The query loop is the real engine
The `query` path orchestrates the main Claude Code turn. It normalizes messages, streams assistant output, detects tool use, runs tools, and feeds tool results back into the loop.
This means a single user request can become a multi-step trajectory rather than a one-shot model completion.
- Messages are normalized before the API call.
- Tool-use blocks can trigger a second or third assistant step within the same turn.
- Recovery paths exist for prompt pressure and max-output-token failures.
Tools are curated and mode-sensitive
Tool availability is centrally assembled, then filtered by user type, feature flags, mode, and agent context.
That is why the same conceptual assistant can behave differently in normal mode, plan mode, coordinator mode, worktree mode, or sub-agent contexts.
- Base tools include read/edit/write, shell, web, search, plans, tasks, and agents.
- Some tools are explicitly blocked for async agents or coordinator mode.
- Feature flags expose more specialized tools such as workflows, browser control, or background session features.
Long sessions rely on compaction and budgeting
The query path contains explicit token-budget and compaction logic because long-running development sessions will otherwise hit context and output ceilings.
Claude Code therefore treats context pressure as an expected operating condition, not an exception.
- Auto-compaction tracks long histories.
- Reactive recovery exists for max-output-token failures.
- Context pressure handling is a first-class part of the architecture.
Learn next
These guides are adjacent to the current topic and make the learning path easier to follow.
Permissions and Tools
How Claude Code decides what it can do and when it should ask
A practical guide to built-in tools, permission checks, and why tool availability changes across modes and agent types.
Sessions, Resume, and Compaction
How Claude Code persists work across long conversations
A guide to transcript storage, session resume behavior, cross-project boundaries, and why long-lived conversations need compaction.
Agents and Plan Mode
How Claude Code separates planning, coordination, and delegated execution
Understand the difference between the main thread, plan mode, coordinator behavior, and constrained sub-agents.
Related resources
These directory entries connect the concept guide to concrete tools, docs, and integrations.
Claude Code Getting Started Guide
Official getting started documentation for Claude Code
Comprehensive getting started guide for Claude Code. Covers installation, configuration, basic commands, MCP setup, and best practices for new users. The essential first read for anyone starting with Claude Code.
Claude Code Best Practices
Community-driven best practices for Claude Code
Collection of best practices learned from real-world Claude Code usage. Covers CLAUDE.md optimization, effective prompting, workflow organization, and common pitfalls to avoid. Continuously updated by the community.
Context7 MCP Server
Real-time documentation lookup for libraries and frameworks
Community MCP server that provides up-to-date documentation for popular libraries and frameworks. Instead of relying on potentially outdated training data, fetch current documentation directly. Supports npm packages, Python libraries, and more.
Sequential Thinking MCP Server
Structured step-by-step reasoning and problem decomposition
MCP server that enables structured sequential thinking and reasoning. Break down complex problems into manageable steps, maintain thought chains, and improve Claude's problem-solving capabilities with explicit reasoning traces.