Claude Code Architecture
Understand Claude Code as an agentic harness: the central loop, context system, tools, extensions, parallel work, and observability.
The Short Version
Claude Code is not just a terminal wrapper around a model. It is an agentic harness: a runtime that assembles context, asks a model to reason, executes tool calls, records the results, and repeats until the task is done.
The model is important, but it is only one node inside the loop. The leverage comes from the layers around it: context loading, permissions, tools, skills, MCP servers, hooks, subagents, worktrees, and session state.
Mental model, not a private implementation contract
This page describes Claude Code using a practical six-layer model. The layer names are useful for reasoning about the product, but they are not a promise that Anthropic implements the CLI with exactly these module names or boundaries.
The Central Agent Loop
Every Claude Code turn follows the same basic shape:
- Claude Code assembles the prompt: system instructions, project context, conversation history, loaded skills, visible tools, and your new message.
- The model reasons over that context and returns either text or a tool request.
- Claude Code checks permissions and dispatches the tool.
- The tool result is added back to the conversation.
- The loop continues until Claude responds or the task completes.
This loop is intentionally simple. The "intelligence" is in the model and in the surrounding harness that controls what the model can see, what it can do, and how much state survives across time.
Six Layers Around the Loop
| Layer | What it handles | User-facing features |
|---|---|---|
| Input | Session startup, trust, permissions, command parsing | claude, /resume, permission modes, workspace trust |
| Knowledge | Project instructions, memory, context loading, compaction | CLAUDE.md, AGENTS.md, .claude/rules/, auto memory, /context, /compact |
| Execution | Built-in tools and tool dispatch | Read/Edit/Write, Bash, search, web, checkpoints, code intelligence |
| Integration | External systems and extension boundaries | MCP servers, plugins, channels, hooks |
| Parallel work | Isolated workers, scripted orchestration, and independent sessions | Subagents, dynamic workflows, worktrees, agent view, agent teams |
| Automation | Continued work without constant prompting | /goal, /loop, scheduled tasks, routines, channels |
| Cloud output | Cloud planning, deep review, and shareable pages | Ultraplan, ultrareview, artifacts |
| Observability | Auditability and lifecycle control | JSONL transcripts, hooks, /cost, /doctor, monitoring integrations |
Input Layer
Before a request reaches the model, Claude Code decides what session you are in, what project is trusted, and what actions can run without asking.
The most important controls are:
- Session identity: new, resumed, forked, or named session.
- Permission mode:
default,acceptEdits,plan,auto,dontAsk, orbypassPermissions. - Settings scope: managed, command-line, local, project, and user configuration.
- Workspace trust: whether Claude Code is allowed to operate in the current directory.
This layer is why the same prompt can behave differently in plan mode, in CI, in a trusted local repo, or inside a sandbox.
Knowledge Layer
Claude Code needs more than your latest prompt. It builds a working context from several sources:
- Project instructions from
CLAUDE.md,.claude/CLAUDE.md, nested CLAUDE.md files, and AGENTS.md. - Rules from
.claude/rules/, including path-scoped rules that load when matching files are read. - Auto memory from the repository's Claude memory store.
- Skill descriptions at startup and full skill bodies only when invoked.
- MCP tool names at startup, with larger tool definitions deferred until needed.
- The conversation history, file reads, tool outputs, and compaction summary.
When the context window gets full, Claude Code compacts automatically. Do not treat any exact threshold or extraction sequence as an API contract. The practical rule is simpler: persistent rules belong in files, noisy exploration belongs in subagents, and long sessions need explicit /compact or /clear hygiene.
Execution Layer
The execution layer is the tool runtime. Tools turn reasoning into action:
- File tools read, edit, create, and reorganize code.
- Search tools find files, symbols, and text.
- Bash runs tests, build commands, git commands, and local scripts.
- Checkpoints snapshot file edits so you can rewind.
- Code intelligence plugins add language-server navigation and diagnostics.
Each tool call feeds its result back into the loop. A good Claude Code session is usually not "one big answer"; it is many small observe-act-verify cycles.
Integration Layer
Claude Code becomes more useful when it can connect to systems outside the repo:
- MCP servers expose external tools and resources such as databases, issue trackers, docs, browsers, and internal APIs.
- Hooks run deterministic automation at lifecycle events.
- Plugins package skills, agents, hooks, and MCP servers for reuse across projects or teams.
- Channels and remote integrations can push events into a running session.
Use MCP when Claude needs external data or actions. Use hooks when something must happen every time. Use plugins when a setup has become reusable.
Parallel Work Layer
Claude Code now has several parallelism models. They solve different problems:
| Model | Isolation | Communication | Best for |
|---|---|---|---|
| Subagent | Separate context inside one session | Summary returns to parent | Noisy research, test runs, focused specialists |
| Dynamic workflow | Script runtime coordinates many agents | Script aggregates results | Large audits, research, migrations, cross-checking |
| Agent view | Separate background sessions | Human supervises sessions | Managing many independent tasks |
| Worktree session | Separate directory and branch | Human coordinates | Independent branches or experiments |
| Agent team | Separate Claude Code instances | Shared task list and direct messages | Complex work where teammates must coordinate |
Subagents are the default answer for context isolation. Worktrees are the default answer for file isolation. Agent teams are heavier and experimental, but useful when multiple agents need to talk to each other while working.
Observability Layer
Claude Code records and exposes what happened so you can debug behavior:
- Session transcripts are stored locally as JSONL.
/cost,/context,/doctor,/hooks, and/mcpexplain runtime state.- Hooks can audit or block lifecycle events.
- Monitoring integrations can export usage, traces, and operational signals.
This matters because an agent is not only judged by whether it produced a diff. You also need to know what it saw, what it tried, what it changed, and where it needed human approval.
What This Means in Practice
- Put durable facts in CLAUDE.md or rules, not in chat.
- Keep repeated procedures in skills, not giant CLAUDE.md sections.
- Put noisy exploration in subagents, not your main context window.
- Put broad, repeatable fan-out in dynamic workflows or ultracode.
- Put parallel edits in worktrees.
- Use agent teams only when workers need peer communication.
- Use agent view when you supervise many independent sessions.
- Use hooks for deterministic enforcement.
- Use MCP for external systems.
- Use
/goal,/loop, routines, and channels when work should continue without constant prompting. - Use plugins when your setup should travel across repos.
Official References
- How Claude Code works
- Extend Claude Code
- Explore the context window
- Run agents in parallel
- Dynamic workflows
- Orchestrate teams of Claude Code sessions
Continue with practice
You have finished the core ideas of Claude Code Architecture.
If you want to turn the idea into something reusable, continue practicing on AgentWay.