What Claude Code Actually Is (an Agent in Your Terminal)

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 engine sits behind the CLI (command-line interface), the IDE (integrated development environment) extensions, the desktop app and the web version, and the Agent SDK (software development kit) packages it as a library for your own programs.

That means understanding one surface teaches you how they all work. Anthropic's overview of Claude Code says each surface "connects to the same underlying Claude Code engine", so your project's instruction files, settings and MCP servers carry across. 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. Anthropic's page on how Claude Code works names three phases that blend together: gather context, take action, and verify results. 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 search for files, then Read to inspect them, then Edit 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. In an interactive session you are part of the loop too: you can interrupt at any point and steer. In scripts you can cap the loop with the --max-turns flag, which has no limit by default.

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 searches for file names and for symbols or TODO comments, then uses Read to fetch only the files that look relevant. On Windows it searches with its own Glob and Grep tools. On macOS, Linux and WSL those two tools are left out of the default set, and Claude runs find and grep through the Bash tool instead, as the tools reference explains. Either way, 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, Claude Code re-reads the project-root CLAUDE.md from disk 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 starts them through its Agent tool for focused work and receives only the final result. That tool was called Task until version 2.1.63, and the old name still works as an alias, according to the subagents documentation. 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. A clear directory structure, well-named tests and a good CLAUDE.md all help the agent converge faster.

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 built-in set of operations the model can request, and MCP servers can add more. The ones you will see most often are:

• Read: fetch file contents
• Edit: change part of an existing file
• Write: create a file or overwrite a whole one
• Bash: run shell commands (on Windows without Git Bash, a PowerShell tool does this job)
• Glob and Grep: find files by name and search inside them, where they are part of the tool set
• WebSearch and WebFetch: access the internet
• AskUserQuestion: ask you multiple-choice questions to clear up what you want
• Agent: start 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, Edit 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.

The model's "intelligence" is in choosing which tool to call next and how to interpret what comes back. 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.

How Do I Install It and Run a First Session?

You need a supported computer and an account. The setup guide lists macOS 13 or later, Windows 10 version 1809 or later, and Linux distributions such as Ubuntu 20.04 or later and Debian 10 or later, with at least 4 GB of memory. For the account, the quickstart asks for a paid Claude plan (Pro, Max, Team or Enterprise) or a Claude Console account with API credits; companies can also reach it through a cloud provider such as Amazon Bedrock.

The recommended way to install is Anthropic's native installer, which keeps itself up to date in the background. On macOS, Linux or WSL:

curl -fsSL https://claude.ai/install.sh | bash

In Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Homebrew (brew install --cask claude-code) and WinGet (winget install Anthropic.ClaudeCode) work too, but they do not update on their own. The older npm route still works as a fallback: npm install -g @anthropic-ai/claude-code needs Node.js 22 or later, and the docs warn never to run it with sudo. On native Windows, installing Git for Windows lets Claude use Bash; without it, Claude runs commands through PowerShell.

Then open a new terminal, check the install, and start a session in your project folder:

claude --version
cd path/to/your/project
claude

A working install prints a version number. The first run asks you to log in through your browser. If something looks wrong later, claude doctor checks the installation and your settings files.

A good first session takes five minutes and shows you the whole loop:

1. Ask a question, such as "what does this project do?" Claude reads the files it needs; you do not paste anything in.
2. Ask for a small change, such as "add a test for the date parser." Claude shows the change, and if it asks before editing, you approve it.
3. Look at what changed. Ask "what files have I changed?" or run git diff yourself.
4. Undo it if you do not like it. Press Esc twice on an empty prompt, or run /rewind, to go back to the checkpoint taken before your prompt. Checkpoints cover edits made by Claude's file tools, not changes a shell command made.
5. Run /init. Claude writes a first CLAUDE.md with the build and test commands it discovers, which Part 2 explains.

Where Else Can I Run It?

The CLI is the most direct surface: 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 run the same engine on your machine. The VS Code extension gives you a graphical chat panel with inline diffs and bundles its own copy of the CLI; the JetBrains plugin runs Claude Code in the IDE's terminal. Part 10, Claude Code + Your IDE: A Workflow That Compounds, covers both.

The desktop app has three tabs: Chat, Cowork and Code. The Code tab is Claude Code with a graphical diff review, and each Code session can run on your machine, in Anthropic's cloud, or over SSH on a machine you manage. This shows that "Claude Code" is really the harness; whether it runs locally or remotely is a deployment choice.

Claude Code on the web, at claude.ai/code, runs sessions in the cloud. Once you connect GitHub, a cloud session clones your repository, works on a branch and pushes it, and when it finishes you can open a pull request from the same page. It keeps running after you close your laptop. Cloud sessions come with Pro, Max and Team plans and some Enterprise seats. Finally, the Agent SDK gives Python and TypeScript programs the same tools, agent loop and context management. Your script calls a query() function that yields messages as the agent works, and under the hood the SDK runs the Claude Code binary it bundles.

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, and how often it asks you depends on the permission mode. In Manual mode (its config name is default), Claude reads files in your project without asking, along with a built-in set of read-only commands such as ls and git status. It asks before it edits files, runs other commands, or searches and fetches from the web, as the permissions guide describes. Since version 2.1.283, interactive terminal and VS Code sessions start in auto mode instead, where a separate classifier model reviews each action and blocks the ones it judges unsafe, so you see far fewer prompts. Press Shift+Tab to cycle through the permission modes; the status bar shows which one is on.

The permission model also has a boundary: the folder where you started Claude, plus any directories you add with --add-dir or /add-dir. In Manual mode, Claude's file tools ask you before they read or write outside that boundary, according to Anthropic's security page. If you never want those outside reads, set permissions.blockReadsOutsideWorkingDirectories to true, and the file tools refuse them in every mode. You can also write rules of your own: allow npm test without a prompt, or deny reads of .env files, while keeping everything else gated.

Permissions are the first gate. The Bash sandbox is the second, and it is off until you turn it on with /sandbox. When it is on, the operating system itself fences in the shell commands Claude runs: Seatbelt does it on macOS and bubblewrap on Linux and WSL2, and the sandbox is not available on native Windows. By default a sandboxed command can write only inside your project folder and a temp folder, and its network access starts from an empty list of allowed domains. Reads are the part people get wrong. A sandboxed command can still read most of your machine, including credential files such as ~/.ssh, until you add denyRead rules or credential protection. The sandbox also covers shell commands only: Claude's own file tools, MCP servers and hooks run outside it and follow your permission rules instead. For a boundary around everything, run Claude Code itself inside a dev container or a virtual machine.

Claude Code is also careful with commands it cannot read clearly. In Manual mode it asks before running a Bash command it cannot fully analyze, even when you allowed part of it with a rule such as Bash(git *). And the documentation is plain that you stay responsible for reviewing the code and commands you approve. The runtime is a safety layer, not a formal proof.

Quick Reference

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. claude -p runs one task and exits. Nobody is there to approve anything, so a call that would ask for permission is denied. Pre-approve what the task needs, for example claude -p "fix the failing tests" --allowedTools "Read,Edit,Bash(npm test *)". Part 9, Headless Claude Code: CI, Scripts, and Automation, covers CI in depth, and the Agent SDK lets you embed the same runtime in a larger program.

Q: How does Claude Code handle large codebases? It does not load everything at once. It searches for 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? Treat it like any tool that can run commands as your user. Permission prompts and the auto mode classifier are a check, not a wall: a shell command you approve can reach anything your account can. For anything near production, run Claude Code inside a container or virtual machine with only the files and network access the task needs, and never give it root.

Q: How does the Agent SDK relate to the CLI? The SDK runs the same Claude Code engine and drives it from your code. Your script receives structured messages as the agent works and can send follow-up messages. 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 in Manual mode. You ask Claude Code to add authentication, and it keeps asking to read files outside the project folder, such as /etc/hosts and a config file in your home directory. What is happening, and how do you keep it inside the project?

Answer: Claude is exploring to understand your environment, which is normal. Reads inside the project folder run without asking, but in Manual mode a read outside it asks you first, so the prompts mean the boundary is working. You can answer no each time. To stop it for good, set permissions.blockReadsOutsideWorkingDirectories to true in .claude/settings.json or your user settings; Claude's file tools then refuse those reads in every mode. To block one place only, add a deny rule such as "deny": ["Read(//etc/**)"] (two slashes mean an absolute path). These settings govern Claude's file tools. A shell command such as cat is a separate road, so if you want the operating system to block it too, turn on the Bash sandbox with /sandbox and add denyRead entries. A line in CLAUDE.md asking Claude to stay in the project helps, but it is guidance, not enforcement.

Next: CLAUDE.md: How Claude Code Thinks About Your Project. It covers the instruction file Claude reads at the start of every session and how to write one that helps.

If you want this kind of breakdown every week, how real systems actually work under the hood, subscribe to Internals Decoded at internalsdecoded.com.

Sources

• Claude Code overview
• Quickstart
• Advanced setup
• How Claude Code works
• Tools reference
• Configure permissions
• Choose a permission mode
• Configure the sandboxed Bash tool
• Security
• Model configuration
• Desktop application
• Use Claude Code in the cloud
• Agent SDK overview
• How Claude remembers your project
• Create custom subagents
• Checkpointing
• Run Claude Code programmatically