What Claude Code Actually Is (an Agent in Your Terminal)
Not autocomplete. A full agent that reads your repo, plans, edits, runs, and verifies.
Claude Code is a local agent runtime that connects to Anthropic’s cloud models and gives them controlled access to your terminal, filesystem, and tools. It runs a reason, act, observe loop: the model plans, the runtime executes tools like reading files or running shell commands, and the results feed back into the next step. The same runtime powers the CLI (command-line interface), IDE (integrated development environment) plugins, desktop app, and the Agent SDK (software development kit).
The surprising part? Understanding one surface teaches you how they all work. The CLI, the VS Code extension, the desktop app’s “Code” tab, and the Python SDK all share a single underlying engine. Once you see that engine, the whole product family becomes a set of interchangeable shells around the same loop.
Think of It as a Remote-Controlled Bulldozer
Before we dig into the mechanics, a mental model helps. Imagine a construction site. You are the foreman. You tell an operator in a remote control room, “Dig a trench from the fence to the shed.” The operator cannot touch the dirt directly. Instead, they send commands to a bulldozer on site. The bulldozer’s onboard computer receives those commands, moves the blade, and reports back what happened. The operator sees the new state and sends the next command. The bulldozer has a safety cage that stops it from driving into the neighbor’s yard. That cage is the permission model.
Claude Code works the same way. You are the foreman giving high-level goals. The cloud model is the remote operator, reasoning about what to do next. The local runtime is the bulldozer’s control system, executing tool calls on your actual files and shell. The safety cage is the permission and sandboxing layer. Every action the model “wants” to take must go through that cage.
This separation is the key to understanding the whole system. The model never touches your machine. It only emits tool requests. The runtime decides whether to honor them.
How Does Claude Code Run an Agent Loop Internally?
Claude Code runs a continuous loop of reasoning, acting, and observing. When you give it a task, the runtime packages your instruction with system prompts, available tools, and any relevant context. It sends that to the model. The model responds with a plan and often one or more tool calls. The runtime executes those tools, feeds the results back, and the cycle repeats until the goal is met.
This loop is not a single pass. The model might first use Glob to find files, then Read to inspect them, then Write to make changes, then Bash to run tests. Each step produces new information that changes the next decision. The runtime manages this flow, keeping the conversation history and compacting it when it gets too long. The model is stateless between calls; the runtime is the stateful component.
A diagram makes the loop concrete:
The loop stops when the model decides the goal is done. That decision is often based on a verifiable condition: tests pass, a build succeeds, or a specific command exits cleanly. The runtime does not impose a stop condition; the model learns to check its own work.
How Does Claude Code Understand My Codebase?
Claude Code does not slurp your entire repository into a single prompt. It uses tools to explore on demand. At the start of a task, it typically runs Glob to discover file patterns and Grep to search for symbols or TODO comments. Then it uses Read to fetch only the files that look relevant. This is an iterative, tool-driven code search, not a static index.
Two mechanisms help it stay oriented. First, CLAUDE.md is a project-specific instruction file the agent reads at the start of every conversation. You can put architecture notes, coding conventions, and test commands there. Second, the runtime compacts context as the conversation grows. When the history nears the model’s limit, older messages are summarized, preserving key decisions while discarding transient details. After compaction, the runtime re-reads CLAUDE.md so the foundational guidance stays fresh.
The agent can also use skills and subagents. Skills are markdown files that describe reusable workflows, like “how to run our deployment pipeline.” Subagents are separate agent definitions with their own prompts and tool restrictions. The main agent spawns them via a Task tool for focused work, receiving only the final result. This keeps the main loop clean while offloading complex subtasks.
The net effect is that “understanding” is the product of repeated, targeted exploration guided by persistent instructions. The better your scaffolding, clear directory structure, well-named tests, a good CLAUDE.md- the faster the agent converges.
What Tools Does Claude Code Have, and How Are They Executed?
The tool layer is what makes Claude Code an agent instead of a chatbot. The runtime exposes a fixed set of operations the model can request. The most important ones are:
Read: fetch file contentsWrite: create or overwrite filesBash: run shell commandsGlob: find files by patternGrep: search file contentsWebSearchandWebFetch: access the internetAskUserQuestion: request clarification from youTask: spawn a subagent
The model never calls these directly. It emits a tool-use message with a name and arguments. The runtime intercepts it, checks permissions, and executes the operation. For Read and Write, the runtime touches the local filesystem. For Bash, it spawns a subprocess. For web tools, it makes network calls. The results are serialized and fed back as tool-result messages.
This architecture turns the model into an adaptive RPC client. The runtime is the server. The model’s “intelligence” is in choosing which endpoints to call and how to interpret the responses. The runtime’s job is to enforce safety and provide accurate feedback. If a tool fails, the error goes back to the model so it can course-correct.
Where Can I Run Claude Code? The Runtime and Its Surfaces
The same agent runtime runs under many different shells. The CLI is the most direct: install @anthropic-ai/claude-code via npm, run claude in a project directory, and start giving instructions. The runtime lives in that terminal session. You can also use claude -p "prompt" for non-interactive, one-shot tasks in scripts or CI.
IDE extensions for VS Code and JetBrains embed the same runtime. The agent can edit files through the editor’s file system abstraction, but the tool execution still happens locally. If you use a dev container, the runtime runs inside the container, isolating it from your host while still giving it access to the project’s toolchain.
The desktop app adds two modes. The “Code” tab is an interactive coding assistant with a graphical diff review. The “Cowork” tab runs the agent in a cloud VM, streaming results back while you do other work. This shows that “Claude Code” is really the harness; whether it runs locally or remotely is a deployment choice.
The web surface at claude.ai/code connects to repositories via GitHub. The agent can propose or apply edits through pull requests and monitor CI pipelines. It uses the same loop to iterate on test failures until they pass. Finally, the Agent SDK exposes the runtime to Python and TypeScript programs. Your script configures tools and goals, then calls a query() function that yields messages as the agent works. The SDK launches the same runtime as a subprocess and controls it over IPC.
All these surfaces share one engine. Learn the loop once, and you understand every entry point.
How Does the Permission Model Keep Things Safe?
Because Claude Code can read files, write code, and run shell commands, the runtime gates every tool call through a permission system. By default, it starts in a read-only mode: file reads and a small set of safe commands are allowed without prompting. File writes, network access, and arbitrary shell commands require explicit approval.
The permission model distinguishes between operation types and scopes. Writes are constrained to the working directory and its subdirectories. Reads can extend outside that boundary, which is often necessary for debugging, but such reads are logged. Network tools like WebSearch and Bash commands that call curl are treated as sensitive. You can configure auto-approval for specific patterns, like allowing npm test or git status without prompts, while keeping dangerous operations gated.
Permissions are the first gate. Sandboxing is the second. You can run the runtime inside a Docker container or an OS-level sandbox like Bubblewrap. That way, even if a tool is approved, its blast radius is limited to the container’s filesystem and network. Anthropic’s security documentation describes a model where the agent can read the project directory and essential system binaries but cannot touch SSH keys, browser data, or other home directory contents. Network egress can be restricted to the Claude API (application programming interface) and outbound SSH for git.
The runtime also sanitizes inputs to prevent command injection. The model is trained to treat environment instructions with skepticism when they conflict with safety rules. The documentation is clear: Claude Code only has the permissions you grant it. The runtime is a safety layer, not a formal proof.
Quick Reference
| Property | Value |
|---|---|
| Default model | Claude 3.5 Sonnet (configurable) |
| CLI install | npm install -g @anthropic-ai/claude-code |
| Config file | .claude/settings.json |
| Project instructions | CLAUDE.md (root of project) |
| Sandboxing tools | Docker, Bubblewrap, Firejail |
| Permission modes | Default (ask), Accept Edits, custom allowlists |
| Agent SDK languages | Python, TypeScript |
| Non-interactive flag | claude -p "prompt" |
Frequently Asked Questions
Q: What is the difference between Claude Code and the Claude API? The API gives you raw access to the model’s text generation. Claude Code wraps that model in a runtime that manages tools, permissions, context, and the agent loop. You get a working agent out of the box instead of building the loop yourself.
Q: Can I use Claude Code in CI/CD (continuous integration and continuous delivery) pipelines?
Yes. Use claude -p "fix the failing tests" in a script. The agent will read error logs, edit code, run tests, and exit. You can also use the Agent SDK to embed the runtime in a larger pipeline with custom stop conditions.
Q: How does Claude Code handle large codebases?
It does not load everything at once. It uses Glob and Grep to find relevant files, then reads only what it needs. Context compaction summarizes older messages. A well-written CLAUDE.md helps it stay oriented without re-reading the whole repo.
Q: Is Claude Code safe to use on production servers? The default permissions restrict writes to the working directory and require approval for shell commands. For production, run the agent inside a sandbox or dev container with minimal filesystem and network access. Never give it unrestricted root access.
Q: How does the Agent SDK relate to the CLI? The SDK launches the same runtime as a subprocess and controls it programmatically. Your script receives structured messages as the agent works and can inject additional instructions. It is the same engine, driven by code instead of a human at a terminal.
Test Yourself
You are building a web app side project. You ask Claude Code to add authentication. It keeps trying to read files outside the project root, like /etc/passwd or system configuration files. What is happening, and how do you fix it?
Answer: The agent is exploring broadly to understand the environment, which is normal because reads outside the working directory are allowed by default. To restrict it, you can run Claude Code inside a sandbox (like a Docker container or Bubblewrap) that hides those paths. Alternatively, use a .claude/settings.json to set allowedReadPaths to the project directory only. You can also add a CLAUDE.md instruction: “Only read files inside this project root.” The agent will respect that guidance while still using tools to search within the allowed scope.
If you want this kind of breakdown every week, how real systems actually work under the hood, subscribe to Internals Decoded at internalsdecoded.com. Next in the series: setting up Claude Code for a real project, with a custom CLAUDE.md and sandbox.
Sources
- Claude Code overview
- CLI installation
- Desktop app
- Sandboxing with Bubblewrap
- Security overview
- Permission model
- Agent SDK overview
- CLAUDE.md and skills
- Agent SDK Python
- Claude Code product page
- Hooks