Claude Code, Deciphered — A Field Guide to the Vocabulary

No terms match that filter. Try clearing the search or selecting All.

CLUSTER 01 / 07

Core concepts

The seven primitives that everything else in Claude Code is built from. Internalise these and the rest reads as application of pattern.

FIG. 01 The agentic loop

Each pass through the loop appends to the conversation history. Claude either calls more tools or emits a terminal response — the harness has no other states.

001 / Core

Agentic loop

Core

The iterative cycle in which Claude reads its current context, decides what to do next, optionally calls one or more tools, observes the results, and either calls more tools or emits a final reply. Every Claude Code turn is one trip around this loop — sometimes spanning dozens of tool calls.

Used for

Driving any non-trivial task: gathering context, performing actions, adapting to feedback, and recovering from errors without leaving the session.

When to use

Always — the loop is the engine. The interesting question is how much autonomy you give a single iteration (plan mode, hooks, permissions).

When NOT to use

If you only need a one-shot completion with no tools, you don't need Claude Code — call the model directly via the API. The loop has overhead.

002 / Core

Context window

Core

The total span of tokens Claude can attend to in a single turn: system prompt, tool definitions, conversation history, file contents, and tool results. Opus 4.7 supports up to 1M tokens; Sonnet and Haiku have their own ceilings. Once the window fills, older content must be summarised, dropped, or both.

Used for

Holding everything Claude reasons over — including large file reads and long tool transcripts. The shape of your context drives output quality more than prompt wording.

When to manage actively

Long sessions, repos with very large files, batch operations. Reach for /compact, /clear, or a fresh subagent before quality degrades.

When NOT to micro-manage

Short sessions; let auto-compaction do its job. Premature compaction discards nuance you may need.

Verify in docs: exact token ceilings vary by model and contract. Check current model limits at docs.claude.com.

003 / Core

Tool use

Core

The mechanism by which Claude invokes capabilities outside the language model itself. Claude emits a tool_use block; the harness executes it (Read, Edit, Bash, MCP servers, custom tools); a tool_result is appended to context for the next turn.

Used for

Reading files, editing code, running shell commands, querying databases, calling APIs — anything the model cannot do with text alone.

When to use

Effectively always — Claude Code is built around tool use. The control surface is which tools are exposed and under what permissions.

When NOT to use

For pure ideation or rephrasing, restrict to read-only tools or use --print mode so Claude can't surprise you with a side effect.

004 / Core

System prompt

Core

The instructions injected at the very top of Claude's context that define its role, capabilities, and constraints. In Claude Code this is composed automatically: harness identity, tool catalog, environment metadata, and your CLAUDE.md content.

Used for

Setting the standing rules for every turn — tone, conventions, what counts as "done", which patterns to favour.

When to customise

Through CLAUDE.md (project-specific) or ~/.claude/CLAUDE.md (personal). Keep it concrete: file paths, commands, conventions, gotchas.

When NOT to use

Don't store secrets, ephemeral state, or rapidly changing data in the system prompt. Don't try to override harness identity or jailbreak it.

005 / Core

Slash commands

Core

User-invoked shortcuts typed as /name [args]. Built-ins handle session control (/clear, /compact, /help); custom commands live in .claude/commands/*.md (project) or ~/.claude/commands/*.md (user) and inject a prompt template into the conversation.

Used for

Reusable workflows you invoke by hand: /review, /security-review, project-specific scaffolds, repeated prompt templates.

When to use

Anything you've copy-pasted as a prompt three times. Slash commands are the cheapest abstraction Claude Code offers.

When NOT to use

For automatic, event-driven behaviour use hooks. For complex independent tasks with their own context budget, use subagents.

# .claude/commands/spike.md
---
description: Quick exploratory spike on a topic
argument-hint: <topic>
---
Spike a 30-minute exploration of: $ARGUMENTS
Capture findings in scratch/SPIKE.md. Do not modify src/.

006 / Core

Subagents

Core

Independent Claude sessions spawned from the parent session via the Agent tool. Each subagent has its own context window, its own tool restrictions, and returns a single message back to the parent — nothing else leaks across the boundary. Defined in .claude/agents/*.md.

Used for

Parallel research, large grep / read jobs, isolated explorations, specialist roles (code-reviewer, debugger). Protects the main context from output bloat.

When to use

Independent tasks with no shared state mid-flight. Two or more such tasks — dispatch them in parallel in one message.

When NOT to use

When you need ongoing back-and-forth, when the parent must observe intermediate steps, or when the work fits comfortably in the main loop.

007 / Core

Hooks

Core

Shell commands the harness runs automatically on lifecycle events: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop, SubagentStop, and others. Hooks are executed by the harness, not by Claude — that's their power and their danger.

Used for

Linting on save, formatting after writes, blocking risky bash commands, injecting context on session start, posting notifications when work stops.

When to use

Anything deterministic that must happen at a known moment, regardless of model judgement. "Whenever X" requirements always become hooks.

When NOT to use

Anything requiring reasoning, taste, or context — that's a slash command or subagent. Hooks should be simple, fast, and side-effect-explicit.

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command",
                  "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\"" }]
    }]
  }
}

CLUSTER 02 / 07

Configuration & setup

Where Claude Code reads its standing instructions from, who can override whom, and how secrets stay out of the wrong files.

FIG. 02 Configuration hierarchy — precedence cascade

A higher layer fully overrides a lower one for the same key. Permissions are merged additively; an enterprise policy with defaultMode: "deny" cannot be reopened from below.

008 / Config

`CLAUDE.md`

Config

A markdown file Claude Code automatically loads into the system prompt at session start. The project file lives at the repo root; the user file lives at ~/.claude/CLAUDE.md. Sub-directory CLAUDE.md files are also loaded when files in that directory are read.

Used for

Coding conventions, build / test / lint commands, architecture overview, "always do this first" rules, gotchas a newcomer would trip over.

When to use

Anything Claude needs to know every session. The project file should be terse and concrete — not a wiki dump.

When NOT to use

Secrets (use .env), per-task notes (just say them), or runtime state. Long CLAUDE.md files dilute the signal.

009 / Config

`.claude/` directory

Config

The project-local folder where Claude Code looks for shareable configuration: settings.json, commands/, agents/, hooks/, skills/, and the local-only settings.local.json. Mirror exists at ~/.claude/ for user-level equivalents.

Used for

Versioned, team-shared Claude Code config. Anything you want every contributor to inherit when they clone the repo.

When to use

Project-wide hooks, allowlists, custom slash commands and subagents that everyone should have available.

When NOT to use

Personal preferences (statusline, theme, personal hooks) — those belong in ~/.claude/.

.claude/
├── settings.json          # committed, team-wide
├── settings.local.json    # gitignored, your overrides
├── commands/              # /custom slash commands
├── agents/                # subagent definitions
├── hooks/                 # shell scripts referenced from settings
└── skills/                # bundled, invokable skills

010 / Config

`settings.json`

Config

The single JSON document where Claude Code's behaviour is configured: permissions, hooks, environment variables, status line, MCP servers, model selection. Three scopes — user, shared project, local project — plus an enterprise policy file at the OS level.

Used for

All persistent configuration. Treat it as code: review it, version it, lint it.

When to use

Whenever a behaviour should persist across sessions or be enforced across teammates. Especially: permissions and hooks.

When NOT to use

Per-session toggles — pass them as CLI flags. Secrets — reference env vars, don't paste values.

{
  "permissions": {
    "allow": ["Bash(git status)", "Bash(git diff:*)", "Read"],
    "deny":  ["Bash(rm -rf:*)", "Bash(git push --force:*)"],
    "defaultMode": "acceptEdits"
  },
  "env": { "NODE_ENV": "development" },
  "model": "claude-opus-4-7"
}

011 / Config

`.env` file placement

Config

Claude Code does not load a .env file automatically. Conventionally .env sits at the repo root for the application itself; pass values into Claude Code's process environment via your shell, or surface specific keys via the env map in settings.json.

Used for

Local secrets — API keys, database URLs, OAuth client secrets — that the application (and any tools Claude runs) needs at runtime.

When to use

Local development. .env belongs in .gitignore; pair with a committed .env.example that documents the keys.

When NOT to use

Production secrets (use a secrets manager). Never store them inside .claude/ or CLAUDE.md — those flow into prompts.

Verify in docs: some MCP servers and integrations have first-class .env support — check each server's loader behaviour separately.

012 / Config

Permissions model

Config

The system that decides whether a tool call runs, prompts you, or is blocked. Four modes: default (prompt for new tools), acceptEdits (auto-accept file edits), plan (read-only, must propose a plan), and bypassPermissions (no prompts — dangerous). Allow / deny / ask lists in settings.json refine the defaults.

Used for

Controlling blast radius. Each tool call is checked against the active mode plus the merged permission rules from every settings layer.

When to use

Always — explicit allowlists for read-only commands cut prompt fatigue without weakening safety. Use plan mode for unfamiliar territory.

When NOT to use

Don't leave bypassPermissions on as a default. Reserve it for sandboxed environments where you've thought hard about what could happen.

013 / Config

Allowed / denied tools

Config

String patterns in permissions.allow, permissions.deny, and permissions.ask that match tool calls by name and arguments. Patterns include Read, Edit, Bash(git status), Bash(npm test:*), and mcp__<server>__<tool>.

Used for

Pre-approving safe operations (read-only bash, common npm / git commands, specific MCP tools) and hard-blocking dangerous ones (force push, recursive delete, prod credential reads).

When to use

Once you've used Claude Code in a project for a few days, the prompts you keep approving become an allowlist; the prompts that scare you become a denylist.

When NOT to use

Don't allow broad wildcards on destructive commands — Bash(rm:*) is almost always wrong. Prefer specific commands or none.

CLUSTER 03 / 07

Model Context Protocol

An open standard for plugging tools, data sources, and prompts into any LLM client. The same MCP server works in Claude Code, Claude Desktop, Cursor, and beyond.

FIG. 03 MCP architecture — client, transport, server, external system

The transport layer is the only thing that meaningfully differs between local and remote MCP servers. Authentication (OAuth + DCR) is layered onto the transport for remote, network-reachable servers.

FIG. 04 Transport comparison — stdio · SSE · HTTP

	Where it runs	Authentication	Best for	Trade-offs
stdio	Local subprocess of the client	none Inherits user's machine context	Filesystem, git, sqlite, anything per-user and local	fastestsimple single-user only; client must launch the binary
SSE	Remote HTTP server, server → client streaming	OAuth per-user, optional	Existing SSE deployments, legacy remote servers	legacy being superseded by Streamable HTTP; long-lived connections
HTTP	Remote, "Streamable HTTP" — bidirectional over HTTP/POST	OAuth + DCR recommended for any non-trivial server	New remote MCP deployments, multi-user SaaS integrations	modernscales needs proper auth and TLS; more moving parts than stdio

For new servers: pick stdio if it's a personal local tool, Streamable HTTP if it's remote and shared. Reach for SSE only when integrating with an existing deployment.

014 / MCP

MCP server

MCP

A program that exposes tools, resources, and prompts via the Model Context Protocol. It can wrap a database, a SaaS API, a file format, or your in-house service. The same server is usable by any MCP client — that's the point of the standard.

Used for

Extending Claude with domain-specific capabilities you want available across many sessions and projects, without bespoke wiring per client.

When to use

When the integration will be reused, shared, or audited. Building one server beats writing the same Bash glue ten times.

When NOT to use

A one-off task — just have Claude run the command directly. Don't build a server until you've felt the friction it would relieve.

015 / MCP

MCP client

MCP

The side of an MCP connection that consumes capabilities — in this context, Claude Code itself. The client discovers what a server offers, surfaces those tools to the model with a mcp__<server>__<tool> naming convention, and routes calls back to the server.

Used for

Letting an LLM use any MCP-compliant capability. Claude Code, Claude Desktop, Cursor, and others are all MCP clients.

When to use

Whenever you want a server's tools available in your AI tool. Configuration is per-client (in settings.json for Claude Code).

When NOT to use

If a tool only ever runs in one client environment, the MCP wrapping is overhead — a slash command or hook may be enough.

016 / MCP

stdio transport

MCP

The simplest MCP transport: the server runs as a local subprocess of the client; the client communicates with it over stdin / stdout using newline-delimited JSON-RPC. No network, no auth, no certificates.

Used for

Local servers operating on local resources — filesystem, git, sqlite, your machine's keychain.

When to use

Default choice for any server that's installed per-user and operates on local data. Fast, predictable, easy to debug.

When NOT to use

Anything multi-user, anything shared, anything you don't want to install on every developer's laptop.

# add a stdio server
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/work

017 / MCP

SSE transport

MCP

Server-Sent Events over HTTP — the older remote MCP transport. The server pushes streaming responses to the client over a long-lived text/event-stream connection; the client posts requests separately.

Used for

Remote MCP servers built before the Streamable HTTP transport landed.

When to use

When you're connecting to an existing SSE deployment that you don't control. Most popular MCP servers still ship an SSE endpoint.

When NOT to use

For new server projects — build them on Streamable HTTP instead. SSE is functional but no longer the recommended forward path.

Verify in docs: SSE deprecation status and exact replacement timing — check the MCP spec at modelcontextprotocol.io.

018 / MCP

HTTP transport

MCP

"Streamable HTTP" — the modern remote MCP transport. A single HTTP endpoint accepts JSON-RPC requests via POST and can stream responses back when needed. Replaces SSE for new deployments and pairs naturally with OAuth.

Used for

Remote, multi-user MCP servers — especially those fronting authenticated SaaS APIs.

When to use

Any new remote server. Pair with OAuth + DCR so any client can authorize without bespoke registration.

When NOT to use

Local-only tools (use stdio — less surface area, less to break).

019 / MCP

OAuth Dynamic Client Registration

MCP

RFC 7591. An OAuth 2.0 extension that lets an MCP client register itself with a server's authorization endpoint at runtime, rather than relying on a pre-shared client ID. The MCP spec recommends DCR so any new client can connect to any compliant server without an out-of-band setup step.

Used for

Letting Claude Code (or any other MCP client) connect to a remote OAuth-protected MCP server with no manual app registration.

When to use

Building any remote MCP server intended for multiple clients or organisations — DCR is the path of least friction.

When NOT to use

Stdio (local) servers — no auth needed. Internal-only servers behind a corporate IdP may use a fixed client registration instead.

020 / MCP

Local vs remote MCP servers

MCP

Local: stdio subprocess, single-user, ambient access to that user's machine, no auth. Remote: HTTP / SSE, multi-user, network-bound, requires authentication, can be operated centrally and updated without redeploying to every laptop.

Used for

Choosing the right deployment shape for the integration's audience — one developer or a whole company.

When local

Filesystem, git, sqlite, ad-hoc personal tools. Anything that depends on the local user's environment.

When remote

Shared business systems — ticketing, CRM, billing, observability — especially when central audit and rotation matter.

021 / MCP

Tool discovery

MCP

The handshake in which the client asks the server tools/list (and similarly resources/list, prompts/list) and receives back the catalog of capabilities, complete with JSON schemas. Claude Code uses these schemas to expose tools to the model.

Used for

Late-binding capability detection. Servers can change their toolset; clients pick it up on the next discovery cycle.

When to use

Automatic on connection — usually you don't think about it. Worth checking explicitly when debugging "why isn't this tool showing up?"

When NOT to use

Workflow

Claude Code running non-interactively — no TTY, no human in the loop. Use claude -p "…" (or --print) to get a single completion to stdout, ideal for scripts, scheduled jobs, and CI tasks like PR review.

Used for

Automated PR review, batch lint / refactor passes, scheduled audits, scripted scaffolding.

When to use

Repeatable, well-scoped tasks where a human approval per step would defeat the point.

When NOT to use

Anything requiring human judgement mid-flow. Lock down permissions tightly before pointing it at production data.

# headless one-shot summary in CI
claude -p "summarise the diff against main and flag risky changes" \
  --permission-mode=plan \
  --output-format=json > review.json

When the same task needs to run on every PR or comment without human attention. Always pair with a tight permission profile.

When NOT to use

For tasks that require nuance or interactive clarification — CI is the wrong place to negotiate.

Verify in docs: action input names and trigger wiring are evolving — check the official action README before adopting.

032 / Integrations

Mobile remote control

Integration

Monitor and steer running Claude Code sessions from a phone via the Claude mobile app. The session keeps executing on its host (laptop, dev container, cloud sandbox) and you intervene from anywhere — especially useful for long-running agentic work.

Used for

Long jobs that don't need full attention, on-call check-ins, approving permission prompts when you're away from your desk.

When to use

When you've kicked off something patient (a refactor across many modules, a research dive) and want to keep an eye on it.

When NOT to use

Hands-on coding — the form factor isn't built for it.

Verify in docs: mobile remote-control feature scope and availability vary by plan and region — check current rollout.

033 / Integrations

Slack integration

Integration

Claude in Slack channels — either via the first-party Anthropic app for Q&A and light agentic work, or via custom MCP / GitHub Action plumbing that posts back into Slack from Claude Code sessions running elsewhere.

Used for

The unit of distribution for everything else on this page. Bundle skills, slash commands, subagents, hooks, and MCP servers into one installable artifact — share it, version it, govern it.

FIG. 07 Plugin anatomy — from marketplace to installed bundle

A plugin packages any subset of {skills, commands, subagents, hooks, MCP servers} behind a single manifest. The marketplace publishes a catalog; /plugin install resolves it; /plugin enable makes it active in your sessions.

040 / Plugins

Plugin

A versioned bundle of Claude Code customisations — any combination of skills, slash commands, subagents, hooks, and MCP servers — behind a single manifest. The unit of distribution: install once, get every artifact the author packaged together.

Used for

Sharing reusable Claude Code capabilities across projects, teams, or the wider community without copy-pasting .claude/ contents around.

When to use

Whenever a set of skills, commands, agents, or hooks goes together — ship them as one unit so users get a coherent experience and predictable upgrades.

When NOT to use

A single ad-hoc command or hook used in one repo — just check it into .claude/. The plugin overhead pays off only when something is reused.

041 / Plugins

Plugin marketplace

Plugin

A source Claude Code can pull plugins from — typically a git repository (public or private), a local directory, or a packaged archive. The marketplace publishes a catalog (a marketplace.json at .claude-plugin/marketplace.json) listing the plugins it offers and where their bundles live.

Used for

Discovery and distribution. Anthropic operates a first-party marketplace; teams run private internal ones; individuals point Claude Code at any GitHub repo that follows the convention.

When to use

When you have more than one or two plugins to share, or want versioning and discovery for a team. Add a marketplace once; install many plugins from it.

When NOT to use

A single plugin you just want to try — you can install directly from a git ref without registering a marketplace.

# add a marketplace, then install from it
/plugin marketplace add anthropics/claude-code-plugins
/plugin install code-reviewer@anthropics
# or install ad-hoc from a git repo
/plugin install github.com/jamesbuckett/my-plugin

Verify in docs: exact CLI syntax for marketplace registration and ad-hoc install evolves — confirm against current Claude Code release notes.

042 / Plugins

`.claude-plugin / plugin.json`

Plugin

The structural convention every plugin follows. The .claude-plugin/ directory at the bundle root holds the plugin.json manifest — name, version, description, author — and the rest of the bundle (commands/, agents/, skills/, hooks.json, mcp.json) sits alongside.

Used for

Telling Claude Code (and a marketplace) what this plugin is, what version it is, and where its components live. The manifest is the contract.

When to use

Anytime you author a plugin. Keep plugin.json small and accurate; bump the version on every meaningful change.

When NOT to use

Don't try to use the plugin layout for project-only customisations — .claude/ in your repo is simpler and doesn't need a manifest.

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # { "name", "version", "description" }
├── commands/                # /slash command markdown files
├── agents/                  # subagent definitions
├── skills/                  # SKILL.md bundles
├── hooks.json               # lifecycle hook config
└── mcp.json                 # MCP servers shipped with the plugin

Verify in docs: exact filenames inside .claude-plugin/ and the schema of plugin.json are still settling — check the current authoring guide.

043 / Plugins

`/plugin` command

Plugin

The built-in slash command for managing plugins from inside Claude Code. Subcommands cover the lifecycle: marketplace registration, install / uninstall, enable / disable, list, update. Equivalent operations are available from the claude CLI for headless contexts.

Used for

Day-to-day plugin management without leaving the session. Discover what's installed, toggle a noisy plugin off, pull an update.

When to use

Whenever you need to change what's available in the current Claude Code instance. The interactive picker is friendlier than hand-editing config.

When NOT to use

In CI — pin plugins via committed config so installs are reproducible, not interactive.

/plugin                       # open the interactive picker
/plugin marketplace list      # registered sources
/plugin install <name>        # install a plugin
/plugin enable  <name>        # activate it for this scope
/plugin disable <name>        # keep installed but inactive

044 / Plugins

Plugin scope

Plugin

Where a plugin is installed and where it's enabled. Installation is typically per-user (the binaries live under ~/.claude/); enablement can be scoped per project via .claude/settings.json, so a plugin you have installed only activates for repos that explicitly request it.

Used for

Keeping a personal toolkit broad while keeping each project's surface area narrow. Different projects can opt into different subsets of what you have installed.

When to use

Any time you want a plugin available in some projects but not others — especially security-sensitive ones with restricted tool surfaces.

When NOT to use

Don't enable everything everywhere — more active plugins means more tool definitions in context, which dilutes the model's attention. Curate.

Verify in docs: the exact settings.json keys for project-level plugin enable/disable are evolving — cross-check against current docs.

The vocabulary of Claude Code, decoded for engineers and architects.

Core concepts

Configuration & setup

Model Context Protocol

Workflows & patterns

Integrations & surfaces

Context management

Plugins & marketplaces

Authoritative sources for the moving parts.

Official documentation

Support & troubleshooting

Model Context Protocol