CONCEPTS
What the pieces are and how they fit together.
- PARTP1
- SECTIONS2
- PLATFORMWINDOWS 11
- REVISIONB ยท 7 OCT 2026
SECTION 02
Mental model and core vocabulary
An agent is a model that takes actions in a loop. Everything else in this guide controls one of three things: where that loop runs, what it can reach, and what instructions it carries.
The loop, as Claude Code's docs describe it:
- You give a task.
- The model picks an action: read a file, search the web, run a command, call a connector.
- The app (not the model) runs that tool and hands back the result.
- The model reads the result and either picks the next action or answers you.
- Steps 2 to 4 repeat until the task is done or Claude needs your input.
The model never touches your files directly. It can only ask for a tool, and the app decides whether to run it, which is why permission prompts exist.
| Term | What it is | Example |
|---|---|---|
| Model | The language model itself: Claude Opus, Sonnet, Haiku. Text in, text out | The model answering a chat |
| Tool | One named action the model can request; the app executes it | Web search, reading a file, creating a document |
| Agent | Model plus tools plus the loop above | A chat that searches the web before answering |
| Environment (surface) | Where the loop runs and what it can touch | claude.ai's cloud sandbox; Claude Code inside a folder on your computer |
| Prompt | Your message | "Summarise this report in five bullets" |
| System prompt | Instructions the app gives the model before your message | Project instructions, the app's own rules |
| Context window | Everything the model sees on one turn: system prompt, chat history, files, tool results, skill descriptions | Very long chats drift because early details get crowded out |
| Token | The unit the model counts text in. Anthropic's pages give about 3.5 to 4 characters of English per token, and add that Claude 4.7 and later models produce about 30% more tokens for the same text, so expect nearer 3 with current models (derived) | Usage limits and context size are measured in tokens |
| Compaction | Summarising older parts of a long session to free context space | Claude Code's /compact command |
Where the add-ons attach, per Anthropic's "Extend Claude Code" page:
- Standing instructions, loaded every session: CLAUDE.md files in Claude Code; project instructions and saved preferences in claude.ai.
- Knowledge and procedures, loaded on demand: skills.
- New tools: MCP servers, which claude.ai calls connectors.
- Extra workers with their own clean context: subagents.
- Automatic actions that fire at fixed moments in the loop: hooks.
- Packaging: a plugin bundles skills, subagents, hooks and MCP servers into one install.
- I
- Instructions and skills shape what the model chooses: CLAUDE.md, Project instructions, profile preferences, skills.
- T
- Tools, MCP servers and connectors add actions the app can run for the model.
- H
- Hooks run at fixed moments, including around every tool call, and can block it.
- S
- Subagents are a tool call that starts a separate loop with its own context and hands back a summary.
- P
- A plugin is one install that can bring several of the above at once.
The model in the middle only chooses actions. Instructions and skills shape those choices, tools carry them out, and hooks sit on every tool call where they can stop it. A plugin is one install that brings several of these boxes at once.
One distinction matters more than the rest. Instructions (CLAUDE.md, project instructions, skills) are requests Claude interprets, so results can vary. Hooks run every time their event fires, so they are the tool for rules that must always hold. The docs' own example: "never edit .env" written in CLAUDE.md is a request; a hook that blocks the edit is enforcement.
SECTION 03
The surfaces: where Claude runs
Use claude.ai for work whose inputs you can upload and whose output is text, a doc or a deck. Use Claude Code when the work lives in a folder of files on your computer or needs code run on them.
claude.ai's tools run in a private cloud workspace, so it sees your files only when you upload them, connect an app, or link the Claude desktop app on your computer.
| Surface | Runs on | Can touch | Good for | Requirement |
|---|---|---|---|---|
| claude.ai (web, desktop chat, mobile) | Anthropic's cloud | Uploads, connectors, the web | Writing, research questions, docs, decks | Any plan; features vary by plan |
| Claude desktop app, Code tab | Your computer | Local project folders you open | Claude Code with a graphical interface, visual diff review | Download from claude.com/download; paid plan for Code |
| Claude Code CLI | Your terminal, in one folder | Files in that folder; commands you approve | Data scripts, website code, automation; the most complete Claude Code surface | Pro, Max, Team, Enterprise or Console account |
| Claude Code in VS Code or JetBrains | Inside your code editor | As the CLI | Coding without switching windows | Editor extension |
| Claude Code on the web (claude.ai/code) | Anthropic's cloud | A connected GitHub repository | Long tasks that continue after you close the laptop | GitHub repository |
| Claude mobile app | Your phone | Cloud sessions; remote control of a local session | Starting and checking tasks away from your desk | Same account |
| API and Agent SDK | Your own program | Whatever your code gives it | Building your own AI app | Console account, billed per token |
Points from Anthropic's setup and platforms pages worth knowing:
- The free claude.ai plan does not include Claude Code.
- Scripting and the Agent SDK are CLI-only. The desktop app and IDE extensions trade some CLI features for visual review.
- Settings, project memory and MCP servers are shared across the local Claude Code surfaces, so a setup made in the terminal also shows up in the desktop app and VS Code on the same computer.
- Claude Code on the web runs in the cloud, so a task keeps going after you disconnect.
A rule of thumb: reading and writing stay in claude.ai; data analysis and code that lives in a folder are Claude Code jobs. You can skip the API and SDK unless you decide to build an app.