How Claude Code works: context, tools, permissions, and sessions
Trace Claude Code from a terminal prompt through context, model tool calls, permissions, extensions, persistence, and Remote Control.
The whole story in 6 lines
Claude Code is a local agent harness that repeatedly gives a remote model bounded context and guarded access to tools.
- The CLI, workspace access, tool execution, and session files live locally while model inference is remote.
- Documented instructions, memories, conversation, files, and tool results share one bounded context window.
- Claude proposes a tool call, the local harness executes it, and the result informs the next model turn.
- Hooks, permission rules, and sandboxing guard different points before or around local execution.
- Skills add guidance, MCP adds connections, subagents isolate work, and plugins package extensions.
- CLI transcripts persist locally, Remote Control relays to that process, and web sessions execute in cloud infrastructure.
The command that keeps working
You type one request: build this app and fix any failure. Claude Code reads files, runs commands, edits code, and checks the result without receiving each step from you.
Four terms will keep the story grounded. A harness coordinates work, context is what the model can currently use, a tool call requests an action, and a session saves the conversation.
Our route follows that request through six boundaries: the local process, context assembly, the tool loop, safety gates, extensions, and persistence. Each stage answers what crosses a boundary and what stays put.
The product feels continuous because the harness carries state between many small exchanges. Now let us start with the most fundamental idea, where the session actually runs.
The local process and the remote model
We begin inside your machine because a normal terminal session starts there. The Claude Code process receives your request from the shell and inherits the project directory you trusted.
The local process can inspect workspace files, git state, project settings, and commands. These capabilities belong to the harness and its tools, not to a model directly browsing your disk.
When reasoning is needed, the harness sends a request across the network to the selected Claude model service. The exact backend implementation beyond that documented API boundary remains opaque.
The response returns to the local runner, which can translate a model request into a guarded local action. This split explains how remote inference can cooperate with files and tools that never relocate.
Keep the split clear: the local harness owns execution while the remote model produces decisions from supplied context. Next, we will unpack what the harness supplies on each turn.
What fits inside the context window
Now that we know where execution lives, let us inspect what reaches the model. Claude Code assembles a bounded context window rather than sending your whole computer. Only selected material enters, which is the first privacy boundary to remember.
Documented ingredients include system instructions, CLAUDE.md files, auto memory, conversation history, loaded file contents, tool results, and invoked skills. MCP tool names can load before their full schemas. Descriptions arrive sooner than full schemas, which reduces their starting cost.
As files and results accumulate, the bounded tray approaches its limit. Which project instruction is deliberately reloaded after conversation compaction?
Claude Code first clears older tool output, then may replace conversation detail with a compact summary. Project-root CLAUDE.md returns, while exact hidden prompt assembly and private reasoning stay undocumented.
Context is a managed working set, not perfect memory. Persistent rules belong in durable instruction files. Next, we will follow one model decision as it becomes a local tool action.
The tool result closes the loop
★ If you remember one thing · A tool result returns to Claude as fresh context before the next decision is made.
The context envelope now carries our build task into a model turn. Official docs describe the larger rhythm as gathering context, taking action, and verifying results.
Claude can answer with a structured tool request instead of final prose. The local harness interprets that request and prepares the matching file, search, shell, web, or extension tool. The model proposes the action while the harness executes it.
The local terminal finishes the requested build command and produces output. What must return before Claude can decide whether the task is complete?
The green tool result returns through the harness and enters the next model turn. That returned evidence can trigger another search, an edit, a verification command, or a final response.
The agentic loop is repeated evidence gathering and action, not one enormous command. The harness owns execution between turns. Verification uses returned evidence rather than trusting the first plan. Next, we will place the safety gates along that path.
Three guards before local execution
We just closed the tool loop, but local power needs boundaries. A proposed command travels through lifecycle hooks and the effective permission policy before the harness executes it. A convincing model request is still only a proposal.
A PreToolUse hook can inspect and block the request before the permission prompt. Permission rules then resolve deny before ask before allow, so a stricter rule wins.
The policy gate changes the command’s physical outcome. An allowed packet reaches the tool, an asked packet waits for you, and a denied packet stops before execution.
Switch the Policy rule control through every option. Compare whether the command reaches the tool, pauses at the human checkpoint, or falls away before execution.
Hooks automate checks, permissions govern tool access, and sandboxing constrains Bash at the operating-system layer. These guards complement one another. A permission decision cannot replace operating-system containment. Next, we will map the extension boundaries.
Extensions are not interchangeable
Now that the core loop is guarded, we can extend it. CLAUDE.md adds durable instructions every session, while a skill loads detailed guidance when its workflow becomes relevant. Both add knowledge rather than external access. That distinction matters in practice.
MCP crosses a different boundary. A configured server exposes external tools or data, and its tool output returns through the same model and permission loop as other tools.
A subagent receives its own context window, prompt, tools, and permission mode. It works separately, then returns a summary so large investigations do not fill the parent conversation.
The four paths now diverge clearly: guidance enters context, MCP joins the tool bus, subagents isolate work, and plugins package skills, agents, hooks, servers, and related components.
Choose an extension by the boundary you need, not by which name sounds powerful. Next, we will follow what survives after the current turn and what remote interfaces change.
Sessions persist, surfaces move
Extensions change capabilities, while persistence changes what survives. Interactive CLI messages, tool uses, and metadata are continuously written into a project-scoped local JSONL transcript. The default cleanup period is thirty days unless you change it.
Resume and continue reopen saved sessions, while clear starts a fresh context without deleting the previous conversation. Compact keeps the session but replaces older detail with a summary.
Remote Control lets a phone or browser continue that active terminal session. When the remote screen sends a message, where do the tools still execute?
The local process opens outbound HTTPS to Anthropic and receives relayed messages over TLS, without opening an inbound port. A separate web session runs inside Anthropic-managed infrastructure instead.
A surface can move while execution stays local, or execution can move into a cloud environment. That boundary is the final piece. Now let us step back and see the whole picture together.
The whole Claude Code system
We started by separating the local harness from the remote model. Files and tools stay with the harness while model inference receives selected context.
Then we learned that instructions, memory, conversation, files, and tool results share one bounded context. Compaction preserves meaning selectively rather than storing everything forever.
Next, the tool loop connected model decisions to local evidence. A result returns before Claude chooses another action or writes the final response.
We placed hooks, permission rules, and sandboxing at their distinct boundaries. Together they can inspect, ask, block, and constrain local execution.
We separated instructions and skills from MCP tools, isolated subagents, and plugin packaging. Each extension changes a different part of the running system.
Finally, we followed local transcripts, resumption, compaction, Remote Control, and cloud sessions. The interface alone does not tell us where execution lives.
Put the pieces together and Claude Code becomes understandable: a local harness manages context, permissions, tools, extensions, and sessions around repeated remote model decisions.
The whole story in 6 lines
Claude Code is a local agent harness that repeatedly gives a remote model bounded context and guarded access to tools.
- The CLI, workspace access, tool execution, and session files live locally while model inference is remote.
- Documented instructions, memories, conversation, files, and tool results share one bounded context window.
- Claude proposes a tool call, the local harness executes it, and the result informs the next model turn.
- Hooks, permission rules, and sandboxing guard different points before or around local execution.
- Skills add guidance, MCP adds connections, subagents isolate work, and plugins package extensions.
- CLI transcripts persist locally, Remote Control relays to that process, and web sessions execute in cloud infrastructure.