Claude Mastery Hub

Claude is one family of models you reach three ways — a chat app, a coding agent, and an API — and mastery is just knowing which one to grab.

Most people only ever open the chat box and stop there. The real wins come from picking the right surface for the job, then giving Claude the context it needs to nail it on the first try.

This hub builds you up in four layers: Foundations Core Power Features Mastery. Start here, then go in order or jump to what you need.

The three surfaces

Each surface runs the same underlying models (Opus, Sonnet, Haiku) but is tuned for a different kind of work.

The 60-second "you can do X" tour

A taste of what each surface unlocks. The rest of the hub goes deep on every one of these.

In the web app

Drop in a messy spreadsheet and get back a clean chart, or have Claude build a working mini-app you can share.

In Claude Code

Ask in plain English and Claude edits your actual files. Start interactive, or run it headless in a script.

# Interactive: open the agent in your repo
claude

# One-shot: ask a question and exit (headless)
claude -p "Find and fix the off-by-one bug in pagination.py"

# Pipe a file in and let Claude explain it
cat error.log | claude -p "What caused this crash?"

With the API

A few lines wires Claude into anything you build. Pick a model by name and send a message.

from anthropic import Anthropic

client = Anthropic()
msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarize this ticket in one line."}],
)
print(msg.content[0].text)

Pick the right model

All three surfaces let you choose a model. The rule of thumb: start cheap and fast, move up only when you hit a wall.

The mindset that makes Claude great

The difference between a frustrating session and a magical one is rarely the model — it is how you talk to it. Four habits carry almost all the weight.

How this hub is organized

1. Foundations — the surfaces, models, and core mindset (you are here).
2. Core — everyday moves: prompting well, Projects, slash commands, managing context.
3. Power Features — subagents, skills, MCP servers, hooks, and plan mode.
4. Mastery — automation, plugins, prompt caching, and multi-agent orchestration.

Work through it in order for a clean ramp, or jump straight to the layer that matches what you need today.

Four Claude tiers, one rule: cheap for simple, balanced for daily work, deepest reasoning when it pays off — and Fable 5 when the job is genuinely hard.

In 2026 the lineup is Opus 4.8 for hard reasoning, Sonnet 4.6 as the everyday coding workhorse, and Haiku 4.5 for fast, high-volume work. Picking right saves money and time without hurting quality. The official advice is blunt: use Haiku for simple tasks, Sonnet for most production workloads, Opus only for the most complex reasoning.

Meet the lineup

Side-by-side comparison

The routing cheat sheet

When in doubt, follow this. Start cheap and upgrade only when you hit a real capability gap.

How to switch models

In Claude Code

Use /model inside a session. Run it bare to open a picker, or name a model to switch and save it as your default.

/model              # open interactive picker
/model opus         # switch to Opus and save as default
/model sonnet       # switch to Sonnet
/model haiku        # switch to Haiku
/model default      # recommended default; may auto-route Opus for hard tasks

Press s in the picker to switch for the current session only without changing your saved default.

At launch from the CLI

The --model flag sets the session model and overrides both the model setting and the ANTHROPIC_MODEL env var. Add --fallback-model for automatic failover.

claude --model sonnet
claude --model claude-opus-4-8 --fallback-model sonnet
claude -p "summarize these logs" --model haiku   # headless, cheap

In the Claude.ai app

Use the model picker near the chat input to choose Opus, Sonnet, or Haiku per conversation. Switching is per-chat and instant.

Big context windows (1M tokens)

Opus 4.6/4.7/4.8 and Sonnet 4.6 carry a 1M-token context window; Haiku 4.5 has 200k. Best of all, there is no surcharge tier — a 900k-token request costs the same per token as a 9k one, and caching plus batch discounts apply across the full window.

Squeeze more value per dollar

Two built-in levers cut cost hard. Prompt caching is automatic in Claude Code — cache reads are 90% cheaper than fresh input. The Batch API gives a flat 50% off when latency does not matter.

Route per sub-agent, not just per session

You don't have to pick one model for everything. Give each sub-agent its own model so cheap workers stay on Haiku while the main thread reasons on Opus or Sonnet.

# .claude/agents/researcher.md frontmatter
---
name: researcher
description: Searches the codebase, use proactively
model: haiku
tools: Read, Grep, Glob
---

The model field accepts an alias (sonnet, opus, haiku), a full id, or inherit (the default). For one-off overrides, set the CLAUDE_CODE_SUBAGENT_MODEL env var, which wins over frontmatter.

Heads-up on dates

Claude Code is a terminal tool that turns your codebase into a workspace you can talk to.

This section gets you installed, signed in, and running your first session safely. You only do the install and login once; after that you just type claude in any project.

Step 1 — Install the CLI

Claude Code runs from your terminal. The fastest way to install it is the official script, which works on macOS and Linux.

# macOS / Linux
curl -fsSL https://claude.com/install.sh | bash

# Or via npm (any OS with Node 18+)
npm install -g @anthropic-ai/claude-code

Step 2 — Sign in

The first time you launch Claude Code it walks you through login in your browser. You can sign in with a Claude subscription (Pro or Max) or an Anthropic Console API account.

# Start Claude, then follow the browser prompt
claude

# Or trigger login directly any time
/login

Step 3 — Run Claude in a project

Always cd into a real project folder before starting. Claude reads files relative to where you launch it, so the folder you start in becomes its working directory.

1. Open a terminal in your project root.
2. Type claude and press Enter.
3. Type a question in plain English and press Enter.

cd ~/Projects/my-app
claude

Three ways to start

# Pipe a file in and get a quick answer back
cat error.log | claude -p "explain this stack trace"

The interactive REPL

The REPL is the prompt box where you type. Anything that does not start with / is a message to Claude; anything starting with / is a built-in command. Try these first.

Step 4 — Generate CLAUDE.md with /init

Run /init once per project. It scans your repo and writes a CLAUDE.md file describing the structure, build and test commands, and conventions. Claude reads this file at the start of every future session, so it remembers how your project works.

/init

You can edit memory any time with /memory, or append a quick note by starting a line with # in the prompt box.

Trust and permissions (read this)

Claude Code asks before it edits files or runs shell commands. The first time you open a new folder it also asks you to confirm you trust that directory. This is your safety net, so do not blindly approve everything.

Permission modes

Press Shift+Tab to cycle modes during a session, or start in one with a flag. plan mode is the safest place to begin: Claude can read and think, but cannot change anything.

# Start a session in plan mode
claude --permission-mode plan

To see or change which tools are auto-allowed, run /permissions. Approved rules are saved so you are not asked the same thing twice.

How to exit

When you are done, leave the REPL cleanly. Your conversation is saved so you can pick it back up later.

# Inside the REPL, any of these exit:
/exit
# or press Ctrl+D
# or press Ctrl+C twice

Your first five minutes, recap

1. Install with the script, verify with claude --version.
2. cd into a project and run claude, then /login if prompted.
3. Run /init to create CLAUDE.md, then prune it.
4. Start in Shift+Tab plan mode and read each permission prompt.
5. Exit with /exit; resume later with claude -c.

The claude command is two tools in one: a live coding partner and a scriptable engine you can pipe, loop, and bake into CI.

Run it plain for a chat session, or add -p to get one answer and exit. Everything in between is flags that tell Claude which model, which session, and how much it's allowed to touch.

Three ways to start

# Interactive, with an opening prompt
claude "Walk me through the auth module"

# Headless one-shot: print and exit
claude -p "List the top 3 risks in this repo"

# Pipe content in, ask about it
cat error.log | claude -p "Explain the root cause in 2 sentences"

Resuming work: continue vs resume

When: you closed the terminal but want to pick up where you left off. --continue grabs the latest; --resume lets you choose.

# Reopen the most recent conversation in this directory
claude --continue          # alias: claude -c

# Scripted continuation (combine with -p)
claude -c -p "Now check for type errors"

# Pick a specific past session by name or ID
claude --resume auth-refactor       # alias: claude -r
claude -r abc123 "Pick up the review"

# No argument = interactive picker of past sessions
claude --resume

Picking a model

Why: match the model to the job — Haiku for speed, Sonnet for most work, Opus for the hardest reasoning. --model overrides both the model setting and the ANTHROPIC_MODEL env var.

# Use an alias
claude --model opus
claude --model sonnet

# Or a full model id
claude --model claude-sonnet-4-6

# Add a fallback if the primary is unavailable
claude --model opus --fallback-model sonnet

Permission modes: how much can it touch?

When: you want Claude to plan without editing, auto-accept edits, or lock things down for automation. --permission-mode overrides the defaultMode from your settings.

# Read, search, and think only — no edits, no destructive commands
claude --permission-mode plan

# Auto-approve file writes + mkdir/touch/mv/cp
claude --permission-mode acceptEdits

# Locked-down automation: deny anything not in your allow rules
claude -p --permission-mode dontAsk "Run the test suite"

Adding extra working directories

Why: let Claude read and edit files outside the current folder (a sibling app, a shared lib). Each path is validated as an existing directory.

claude --add-dir ../apps ../lib

One-shot scripting that survives turns

How: use --output-format json to capture a session_id, then feed it back with --resume. This is the backbone of multi-step automation.

# Capture the session id from a headless run
session_id=$(claude -p "Start a code review" \
  --output-format json | jq -r '.session_id')

# Continue that exact session in a later step
claude -p "Now summarize the findings" --resume "$session_id"

The flags that matter most

Two flags to handle with care

# Skip ALL permission prompts (use with caution)
claude --dangerously-skip-permissions

# Safer: start in plan mode, but make bypass available later
# via the Shift+Tab mode cycle
claude --permission-mode plan --allow-dangerously-skip-permissions

Monitoring parallel agents

claude agents opens a view to monitor and dispatch background sessions; claude agents --json prints live sessions as a JSON array for scripting. It shares --model, --permission-mode, --add-dir, and --mcp-config with the top-level command.

Slash commands are the steering wheel of the Claude Code REPL: type / and a menu of built-in controls and your own custom commands appears.

Built-in commands manage your session, context, models, and tools. Custom commands are just Markdown files you drop in a folder. Master both and you stop fighting the tool and start flying it.

Context control: /clear vs /compact

This is the single most important pair. Claude's context window fills fast, and quality drops as it fills. These two commands are how you fight back.

/compact takes optional focus instructions so the summary keeps what matters.

/compact focus on the API changes and the failing test

Pick the right model: /model

Switch the active model without restarting. Run it bare to open a picker, or pass an alias.

/model opus      # deepest reasoning, hard refactors
/model sonnet    # best all-round speed + intelligence
/model haiku     # fastest, cheap, simple tasks
/model default   # recommended default; may auto-route Opus on hard work

Session lifecycle: /resume and friends

Your conversations are saved. Pick one back up instead of starting cold.

/resume          # lists past conversations; pick one to continue
/resume auth-fix # resume a session you named earlier

From the shell, the same idea works via flags: claude --continue (alias -c) reopens the most recent conversation, and claude --resume <id-or-name> targets a specific one.

# Scriptable continuation
claude -c -p "Check for type errors"

Inspect spend and tools

Project memory: /init, /memory, /config

These shape how Claude understands your repo and behaves across sessions.

Memory files load hierarchically: enterprise, then user (~/.claude/CLAUDE.md), then project (./CLAUDE.md), then local. Type # at the start of a prompt to quickly append a memory line.

Quality and editing helpers

Custom slash commands

Here is where power users pull ahead. A custom command is just a Markdown file. The filename (minus .md) becomes the command name. The body is the prompt Claude runs.

Pass arguments with $ARGUMENTS (all args) or $1, $2 for positional ones. Here is .claude/commands/fix-issue.md:

---
description: Fix a GitHub issue by number
argument-hint: <issue-number>
model: sonnet
allowed-tools: Bash(gh issue view:*), Read, Edit
---
Fix issue #$1. First read it:

!gh issue view $1

Then locate the bug, apply a fix, and explain your change.

Invoke it with the argument inline:

/fix-issue 482

Frontmatter fields you can set: description, argument-hint, model, and allowed-tools to restrict which tools the command may use.

Namespacing

Subdirectories namespace commands for organization. A file at .claude/commands/frontend/component.md is still invoked as /component but shows a project:frontend label.

.claude/commands/
  optimize.md            -> /optimize        (project)
  frontend/component.md  -> /component        (project:frontend)
~/.claude/commands/
  standup.md             -> /standup          (user)

The REPL is a cockpit: @ pulls files into context, ! pushes shell output back, and a handful of keys let you steer mid-task without losing your place.

Three in-prompt prefixes do most of the heavy lifting. @ references a file or directory as context, ! runs a shell command and feeds its output into the chat, and # at the very start of a prompt appends a line to memory. Learn these and you stop copy-pasting forever.

@ — reference files and folders as context

The @ prefix tells Claude exactly which files to read instead of making it search. Be specific: pointing at the right files is the single biggest way to cut corrections. It tab-completes, so start typing the path and press Tab.

> Refactor the auth flow in @src/auth/login.ts and keep it consistent with @src/auth/session.ts

> Summarize what changed across @docs/changelog.md

> Use the patterns in @examples/ when you write the new handler

! — run a shell command inline

Prefix any line with ! to execute it in your shell and drop the output straight into the chat. When: you want Claude to see real state — a failing test, git status, a directory listing — without describing it yourself. Why: the output becomes context Claude can act on immediately.

> !git status

> !npm test 2>&1 | tail -40

> !ls -la src/ && cat package.json

A common combo: run a command with !, then ask Claude to fix what it sees.

> !pytest -x
> The first failure above is in test_kelly.py. Fix the implementation, not the test.

Drag, drop & paste images

Claude Code reads images. Paste a screenshot or drag an image file into the terminal and ask about it — great for UI bugs, error dialogs, diagrams, or design mockups.

> Here's the broken layout [paste screenshot]. The sidebar overflows on mobile — fix the CSS in @src/styles/sidebar.css

Keyboard shortcuts that matter

The keys below are the difference between fighting the tool and flowing with it. The two most valuable are Esc (stop without losing context) and Shift+Tab (cycle permission modes).

Multi-line input

To write a prompt that spans several lines, use one of these:

Steering mid-task

You don't have to wait for Claude to finish a bad path. Steering early saves context and time.

1. Hit Esc the moment it heads the wrong way — it stops with context intact.
2. Type a correction and submit; Claude resumes with your new direction.
3. If the whole attempt was wrong, press Esc Esc and rewind — this erases the failed attempt from context entirely.

Putting it together

A realistic loop using all three prefixes plus a key: gather state with !, scope the fix with @, plan it, then execute.

> !git diff --stat
> Review the changes in @src/api/routes.py against @CLAUDE.md conventions.
>   [Shift+Tab to enter plan mode first, then let it execute]
> !curl -s localhost:8000/health | jq .

The VS Code extension and JetBrains plugin wire Claude Code straight into your editor, so plans, edits, and diffs show up right next to your code.

The IDE integration is not a different product. It drives the exact same Claude Code engine as the terminal, just with a graphical surface for selections, diffs, and diagnostics. You get inline-diff review, automatic selection sharing, and live error feedback without leaving your editor.

Two integrations, one engine

Install: VS Code

1. Open the Extensions panel with Cmd+Shift+X (Mac) or Ctrl+Shift+X (Windows/Linux).
2. Search for Claude Code and click Install (or use the marketplace 'Install for VS Code' link).
3. Open the panel and sign in. The CLI is bundled, so there is nothing else to set up.

The VS Code extension panel is the integration. You do not run any attach command. Quick-launch or focus it from the editor with Cmd+Esc (Mac) or Ctrl+Esc (Windows/Linux).

Install: JetBrains

1. Install and authenticate the CLI first: run claude once in a terminal and sign in.
2. In the IDE, go to Settings -> Plugins -> Marketplace and search Claude Code.
3. Click Install, then fully restart the IDE (a reload is not enough).

JetBrains settings live under Settings -> Tools -> Claude Code [Beta]: the claude command path, the 'command not found' notification toggle, Option+Enter for multi-line prompts (macOS, needs a terminal restart), and auto-updates.

What the IDE adds

File-reference keys

Connecting the terminal to the editor

Run claude inside the IDE's integrated terminal and it auto-connects: diff viewing and diagnostic sharing turn on by themselves. From an external terminal, attach with one command.

# In an external terminal, after launching claude:
/ide
# attaches the running session to your open editor

Choose where diffs render with the config command. Keep them in the IDE for visual review, or push them back to the terminal.

# Open diffs in the editor's native viewer:
/config diff tool auto

# Or keep diffs in the terminal:
/config diff tool terminal

Permission modes in the editor

In VS Code the mode indicator at the bottom of the prompt box switches behavior. Plan mode opens the plan as a full markdown document you can comment on inline before any edit happens.

Set the default mode in VS Code settings so every new session starts the way you want.

// VS Code settings.json
"claudeCode.initialPermissionMode": "plan"
// values: default | plan | acceptEdits | bypassPermissions

Settings: what lives where

Editor-specific options live in the extension settings, but the rules that matter for safety and tooling are shared with the CLI. The same precedence applies across CLI, VS Code, and JetBrains.

Under the hood: the 'ide' MCP server

When the VS Code extension is active it runs a local MCP server named ide that the CLI connects to automatically. It binds to 127.0.0.1 on a random high port and writes a fresh auth token to a lock file under ~/.claude/ide/ with 0600 permissions.

It hosts about a dozen tools, but only two are exposed to the model: mcp__ide__getDiagnostics and mcp__ide__executeCode. The rest are internal RPC for opening diffs, reading selections, and saving files.

When the IDE flow beats the terminal

Reach for the editor flow when the work is visual or edit-heavy. Stick with the pure terminal for headless runs, CI, and tight keyboard loops.

Quick-start in 60 seconds

1. Install the extension or plugin and sign in.
2. Open Claude with Cmd+Esc / Ctrl+Esc.
3. Highlight the function you want changed so it becomes context.
4. Ask: 'Add input validation here and run the tests.'
5. Review the side-by-side diff, tweak it inline if needed, then accept.

The two cheapest upgrades to your results: make Claude plan before it touches code, and let it think harder only when the problem is actually hard.

Plan mode and extended thinking solve different problems. Plan mode controls what Claude is allowed to do. Extended thinking controls how much it reasons before it acts. Used together, they turn a guess-and-check session into a deliberate one.

Plan Mode: explore, propose, approve, then execute

Plan mode is enforced at the tool level. Claude literally cannot edit files or run destructive commands while in it. It can only read, search, and think, then hand you a written plan to approve.

Toggle it with Shift+Tab, which cycles through normal, plan, and auto-accept modes. You can also start a session already in plan mode from the CLI.

claude --permission-mode plan

Why it prevents wasted work

When Claude edits first and reasons later, a wrong assumption becomes ten wrong file changes you have to unwind. A plan surfaces that assumption in one paragraph you can correct in one sentence, before any code is written.

There is also a hidden performance win. Front-loading context (reading files, fixing the plan, stating constraints) writes a stable prefix to the prompt cache once. Every later execution turn then reads from that cached prefix, which is the documented cause of very high (90%+) cache-hit rates.

How to ask for a plan first

Be specific. Name the files, state the constraints, and tell Claude not to write code yet. Vague requests cause endless exploration that floods your context.

Read src/auth/session.ts and src/auth/tokens.ts.
Propose a plan to add refresh-token rotation.
Do NOT edit anything yet — show me the plan and wait for approval.

For a larger change, ask Claude to write the plan to disk so it survives any context reset or /clear between phases.

Investigate the checkout flow and write a phased plan to PLAN.md.
Keep each phase to one session of work. List files touched per phase.

Behind the scenes: the Plan subagent

In plan mode Claude uses a built-in read-only Plan subagent. Like the Explore agent, it skips CLAUDE.md and the git-status snapshot so it stays focused on reading and proposing. You don't configure it; it's part of the mode.

Extended Thinking: spend reasoning where it pays

Extended thinking is on by default with roughly a 31,999-token reasoning budget. You escalate that budget with keywords right inside your prompt. More thinking buys reasoning depth, not magic.

ultrathink: our BGP failover drops sessions for ~30s on link flap.
Walk through the timers, the convergence path, and propose fixes
ranked by blast radius. Don't change configs yet.

Toggling and capping it

Flip thinking on or off mid-session with Option+T on Mac (Alt+T elsewhere). Cap the budget with an env var, or set a coarse effort level with a slash command.

# Hard cap the thinking budget for a whole session
export MAX_THINKING_TOKENS=10000

# In-session: dial reasoning effort up or down
/effort high      # low | medium | high
/effort auto      # back to default

A model note worth knowing

The thinking story differs by model. Opus 4.x uses adaptive thinking rather than the standard extended-thinking toggle, while Sonnet 4.6 and Haiku 4.5 support extended thinking. The practical workflow is the same either way; the model decides how to apply the reasoning.

Putting them together

The highest-leverage habit is to combine them: enter plan mode, ask Claude to think hard about the approach, approve the plan, then drop back to normal mode to execute.

1. Press Shift+Tab until you see plan mode.
2. Prompt: think hard and propose a plan to refactor the payment retry logic. Read the relevant files first.
3. Read the plan. Correct any wrong assumption in one line.
4. Approve, then let Claude execute against the now-cached plan.

A good CLAUDE.md is the single highest-leverage upgrade you can make: it loads at the start of every session so Claude stops guessing your conventions.

CLAUDE.md is a plain Markdown file Claude reads automatically before it does anything else. Put your build commands, code style, and gotchas there once, and they apply to every conversation in that repo. It is the difference between Claude inferring your setup and Claude knowing it.

The memory hierarchy

Memory files load in layers: enterprise, user, project, and local. More specific layers take precedence, so a project file beats your personal defaults.

Get started fast

You almost never write CLAUDE.md from scratch. Let Claude scan the repo and draft one, then trim it.

1. Run /init in a repo. Claude reads the codebase and generates a starter CLAUDE.md with structure, build/test commands, and conventions.
2. Run /memory to open your memory files in your editor and clean up the draft.
3. Prune ruthlessly (see the rule below), then commit it.

The # shortcut: add a memory mid-flow

When Claude makes a mistake or you spot a convention worth saving, start a prompt with #. Claude appends it to a memory file for you, so you never lose the lesson.

# Always run tests with `pnpm test`, never `npm test`
# The staging deploy script must be run from the repo root

It lets you pick which memory file to write to (user vs project), so a one-off correction becomes a permanent rule in seconds.

What to put in (and leave out)

The golden test for every line: "Would removing this cause Claude to make a mistake?" If no, delete it. A bloated CLAUDE.md gets ignored because the real rules drown in noise.

Make rules stick

Claude weights emphatic instructions more heavily. Use IMPORTANT or YOU MUST for rules that really matter.

A real CLAUDE.md snippet

Concrete, scannable, and every line earns its place:

# Project: Acme API

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 3000)
- Test: `pnpm test` (Vitest) — NEVER use npm
- Typecheck: `pnpm typecheck`
- Lint+fix: `pnpm lint --fix`

## Code style
- TypeScript strict mode; no `any`.
- Immutable data only — never mutate inputs, return new objects.
- Prefer async/await over `.then()`.

## Architecture
- API routes live in `src/routes/`, business logic in `src/services/`.
- DB access goes ONLY through `src/repos/` (repository pattern).

## Gotchas
- IMPORTANT: run `pnpm db:migrate` after pulling — schema drifts often.
- The `legacy/` folder is frozen. YOU MUST NOT edit files there.

Inspect what loaded

Not sure which memory files Claude is actually using? Two commands give you ground truth.

/memory    # opens loaded CLAUDE.md files for editing
/context   # live token breakdown — see how much memory costs

Treat CLAUDE.md as a living document. Every time Claude repeats a mistake, capture the fix with # — over a few weeks your repo trains itself.

A Skill is a folder with a SKILL.md that Claude auto-loads the moment your request matches it, then forgets again to keep context lean.

Think of a skill as a reusable playbook on disk. Claude reads only the name and description at startup, and pulls in the full instructions only when they are actually relevant. This is called progressive disclosure, and it is why skills scale where giant prompts do not.

Anatomy of a skill

Every skill is a directory containing one SKILL.md file. That file has YAML frontmatter (between --- markers) plus markdown instructions. You can bundle extra scripts, reference docs, or data files alongside it.

.claude/skills/
└── deploy-staging/
    ├── SKILL.md          # frontmatter + instructions
    ├── deploy.sh         # bundled script (run via bash)
    └── checklist.md      # reference, loaded only if needed

A minimal SKILL.md

Only description is recommended; every field is technically optional. The description is what Claude reads to decide whether to activate the skill, so make it state both what it does and when to use it.

---
name: deploy-staging
description: Deploy the app to the staging environment. Use when
  the user asks to ship, deploy, or push a build to staging.
---

# Deploy to staging

1. Run the test suite: `npm test`
2. Build the bundle: `npm run build:staging`
3. Run the bundled script: `bash deploy.sh staging`
4. Confirm the health check at /healthz returns 200.

Never deploy if tests fail. Report the deployed commit SHA.

Where skills live

How activation works

You get the skill two ways. Claude can auto-activate it when your wording matches the description, or you can fire it directly by typing the slash command. Both reach the same instructions.

1. At session start, Claude preloads only metadata: each skill's name + description (~100 tokens each).
2. When your request matches a description, Claude reads the full SKILL.md from disk.
3. If the body points to other files or scripts, those load (or run via bash) only when actually needed.

Progressive disclosure: the three levels

Controlling who can invoke

Two frontmatter switches tune visibility. They trade off context budget against convenience.

When skills beat plain prompts

Reach for a plain prompt instead when the task is a one-off, or so simple that a sentence does the job. Skills earn their keep on repeated, structured work.

Authoring rules that matter

1. Keep the SKILL.md body under ~500 lines; split overflow into separate files.
2. Keep file references one level deep, and use forward slashes in paths.
3. Add a table of contents to any reference file longer than 100 lines.
4. Prefer a deterministic bundled script over asking Claude to write code each time.
5. Put the most important instructions near the top — skill bodies are re-injected after /compact but capped at 5,000 tokens each.

Subagents are disposable specialists with their own fresh context window, so dirty research and verbose output never pollute your main chat.

A subagent is just a Markdown file with YAML frontmatter. The frontmatter sets identity and limits; the body is the subagent's system prompt. Claude can call them automatically or you can invoke them by name.

Why delegate at all

The core constraint of Claude Code is that context fills fast and quality drops as it fills. A subagent runs in its own window, does the noisy work, and returns only a short summary, keeping your main thread clean.

Where they live

Project agents go in .claude/agents/ (shared with your team). Personal agents go in ~/.claude/agents/. When names collide, the higher-priority location wins; project beats user.

A real agent definition

Only name and description are required. The tools line is an allowlist; omit it and the subagent inherits every tool from the main chat. Adding 'use proactively' to the description nudges Claude to delegate on its own.

---
name: code-reviewer
description: Reviews code for bugs, security, and style. Use proactively after writing or changing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. When invoked:
1. Run `git diff` to see what changed.
2. Flag bugs, security issues, and missing error handling.
3. Group findings as CRITICAL / HIGH / MEDIUM / LOW.
4. Suggest concrete fixes. Do NOT edit files yourself.
Return a short, scannable summary only.

How to invoke one

Three ways to call a subagent, from least to most explicit.

1. Auto-delegation — describe the task and Claude picks an agent based on its description.
2. Natural language — name it: "Use the code-reviewer to check my last commit."
3. @-mention — guarantees that exact agent runs.

# @-mention forces the named subagent to run
@agent-code-reviewer check the auth changes in src/auth/

# Or run an entire headless session AS a subagent
claude --agent code-reviewer -p "review the staged diff"

Pick the right model per agent

The model field takes an alias (haiku, sonnet, opus), a full id like claude-opus-4-8, or inherit. It defaults to inherit (same model as your main chat) when omitted.

Running several in parallel

For independent investigations, spawn multiple subagents at once. Each gathers its own context; Claude synthesizes the results. This works best when the paths truly don't overlap.

Investigate three things in parallel, one subagent each:
1. How is auth wired in src/auth/ ?
2. Where are database migrations defined?
3. What does the CI pipeline run on push?
Report each as a short summary.

When delegation helps vs hurts

Two power features

Add memory: project to give an agent persistent notes across sessions (stored in .claude/agent-memory/<name>/). Add skills: to preload full skill content into the subagent at startup — subagents get the entire skill injected, not just its description.

---
name: test-runner
description: Writes and runs tests; use proactively on new features.
tools: Read, Edit, Bash
model: sonnet
memory: project
skills: python-testing
isolation: worktree
---
Write failing tests first, then implement until green. Verify 80%+ coverage.

Restricting who can spawn what

In settings or an agent definition, control delegation with the Agent tool syntax. List allowed agents in parens, allow any with a bare Agent, or omit it to block spawning entirely.

# Only let this agent spawn the named workers
# (Task is the old name for Agent — still works as an alias)
Agent(researcher, test-runner)

# Disable a built-in subagent for the session
claude --disallowedTools "Agent(Explore)"

Built-ins worth knowing: Explore (Haiku, read-only search), Plan (read-only, used in plan mode), and general-purpose (all tools). Explore and Plan skip CLAUDE.md and git status for speed; every other agent loads the full memory hierarchy.

MCP (Model Context Protocol) is the universal adapter that lets Claude talk to outside tools and data — GitHub, browsers, databases, docs, and your own scripts.

Without MCP, Claude only has its built-in tools (read, edit, bash). With MCP, you bolt on new tools that show up right inside the session. One claude mcp add command wires a server in for good.

When and why to add an MCP

Add a server when Claude keeps needing data or actions it can't reach on its own. The goal is fewer copy-pastes and more real work done in-session.

The three transports

A transport is just how Claude talks to the server. Pick based on where the server lives.

stdio: local process

Claude launches the server as a child process and talks over stdin/stdout. The -- separates Claude's flags from the command that starts the server — everything after it is passed through untouched.

claude mcp add playwright -- npx -y @playwright/mcp@latest

HTTP: remote server

Best for hosted/cloud services. Pass a name and a URL.

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

Auth and environment variables

Use --env to pass secrets to a local server and --header to send auth on a remote one.

# Local server with an env var
claude mcp add github --env GITHUB_TOKEN=ghp_xxx -- npx -y @modelcontextprotocol/server-github

# Remote server with a bearer token
claude mcp add --transport http my-api --header "Authorization: Bearer $TOKEN" https://api.example.com/mcp

For remote servers that use OAuth, just run /mcp in-session and authenticate through the browser prompt — no manual token needed.

Scopes: who sees this server

Scope decides where the config is stored and who can use it. Set it with --scope.

# Share a server with your team via version control
claude mcp add --scope project --transport http docs https://code.claude.com/docs/mcp

The .mcp.json file

Project-scoped servers live in .mcp.json at your repo root, checked into git so the whole team gets them. Claude reads it only at session start — restart after editing.

{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

The type field accepts streamable-http as an alias for http, so configs copied straight from a server's docs work unchanged.

No secrets in the file

Use variable expansion so committed configs never hold real tokens. Supports ${VAR} and ${VAR:-default} in command, args, env, url, and headers.

{
  "mcpServers": {
    "my-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer ${API_TOKEN}" }
    }
  }
}

The /mcp command

Run /mcp in any session to see configured servers, their connection status, and the tools each one exposes. It's also where you authenticate (OAuth) to remote servers.

Managing servers from the CLI

claude mcp list                 # all configured servers
claude mcp get github           # show details + which scope holds it
claude mcp remove github        # remove (add --scope if in several)
claude mcp add-json db '{"type":"stdio","command":"..."}'
claude mcp add-from-claude-desktop   # import (macOS/WSL only)

Example servers to start with

Using MCP tools in automation

MCP tools are namespaced mcp__<server>__<tool>, which is how you reference them in --allowedTools for non-interactive runs.

claude -p "Open a PR for the fix" --allowedTools "mcp__github__create_pull_request"

Security: trust before you connect

1. Prefer official servers and the Anthropic connector directory over random forks.
2. Pin versions for stdio servers rather than always pulling @latest from strangers.
3. Never hardcode secrets in .mcp.json — use ${VAR} expansion.
4. Treat tool descriptions and returned data as untrusted input (prompt-injection risk).
5. Keep project servers reviewed in code review, since they ship to the whole team via git.

Hooks run your own shell commands at fixed moments in Claude's lifecycle, giving you control the model cannot talk its way around.

A hook is a command that fires automatically on an event like a file edit or a finished response. Because the harness runs it (not Claude), the behavior is deterministic and reliable. Use hooks to auto-format code, block edits to protected files, or inject fresh context.

The lifecycle events

Events fire at three cadences: once per session, once per turn, and once per tool call. Pick the event that matches when you want to act.

How the config nests

The structure has three levels: event name, then matcher groups, then handler objects. A matcher filters which tool triggers the hook.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "echo ran" }
        ]
      }
    ]
  }
}

Exit codes: how a hook talks back

A command hook receives event JSON on stdin and communicates through its exit code. This is the contract you must get right.

Use case 1: Auto-format after every edit

The classic PostToolUse hook. It reads the edited file path from the event JSON with jq and pipes it to a formatter.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs -r prettier --write"
          }
        ]
      }
    ]
  }
}

Swap prettier for black, gofmt, or rustfmt depending on your stack. Add an "if": "Edit(*.py)" field to scope it to one file type.

Use case 2: Block edits to protected files

A PreToolUse hook can inspect the proposed tool call and refuse it. Exit 2 cancels the edit and tells Claude why.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "f=$(jq -r '.tool_input.file_path'); case \"$f\" in *.env|*/secrets/*) echo 'Protected file, blocked.' >&2; exit 2;; esac"
          }
        ]
      }
    ]
  }
}

Use case 3: Inject context at session start

For UserPromptSubmit and SessionStart, stdout is injected straight into Claude's context. That makes them perfect for feeding in live state like the current git branch.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          { "type": "command", "command": "echo \"Branch: $(git branch --show-current)\"" }
        ]
      }
    ]
  }
}

The SessionStart matcher filters by source: startup, resume, clear, or compact.

Use case 4: Forced verification on Stop

A Stop hook runs when Claude thinks it's done. Run your tests there and return decision: "block" to push Claude to keep fixing until they pass.

Handler types beyond shell

Manage and inspect your hooks live with the /hooks slash command, which shows what is configured across all your settings files.

On June 9, 2026 Anthropic released Claude Fable 5 — its most capable model yet — plus Claude Mythos 5, the same model with safeguards lifted for vetted research.

What launched

The numbers

Why it's a big deal

What it means for you

• Reach for Fable 5 when a task is genuinely hard — large refactors, deep research, multi-step agentic runs — where a better answer is worth the higher token price.
• Keep routing cheap, high-volume work to Haiku and everyday coding to Sonnet. Fable 5 is the premium tier, not the default for everything (see Pick the Right Brain).
• In Claude Code, switch with /model claude-fable-5. Front-load context once so prompt caching keeps the cost down.

Source: anthropic.com/news/claude-fable-5-mythos-5

A plugin packages commands, agents, skills, hooks, and MCP servers into a single thing you install once and reuse everywhere.

Building a great Claude Code setup takes work: custom skills, subagents, format-on-save hooks, the right MCP servers. A plugin wraps all of that into one directory you can share. Install it on a new machine, hand it to a teammate, or drop it into every repo and your capabilities travel with you.

What lives inside a plugin

A plugin is a self-contained folder. Components are auto-discovered from the directory layout at the plugin root, so you rarely have to wire anything up by hand.

The /plugin manager

Run /plugin to open the manager — a tabbed interface you cycle with Tab / Shift+Tab.

Recent versions also show a Context cost estimate, a Last updated date, and a 'Will install' breakdown listing exactly which commands, agents, skills, hooks, and MCP/LSP servers a plugin adds before you commit.

Install your first plugin

Anthropic ships a curated marketplace, claude-plugins-official, that is available automatically in every install — no setup needed.

# Install the official GitHub plugin (user scope by default)
/plugin install github@claude-plugins-official

# Activate it this session without restarting
/reload-plugins

The syntax is always plugin-name@marketplace-name. That @marketplace suffix is how Claude knows which catalog the plugin came from.

Add a marketplace

A marketplace is just a repo (or hosted file) with a .claude-plugin/marketplace.json catalog at its root. Add one, then install from it.

# Add Anthropic's community marketplace
/plugin marketplace add anthropics/claude-plugins-community

# Now install any plugin it lists
/plugin install commit-commands@claude-community

Sources are flexible. Use whichever fits where your plugins live.

Share a plugin with your whole team

This is the real payoff. Install at project scope and the plugin is recorded in enabledPlugins in .claude/settings.json — which you commit. Every teammate who clones the repo gets the same setup.

# Write the plugin into the shared project settings file
/plugin install lint-suite@claude-community --scope project

One reviewer agent, one format hook, one test command — defined once, used by everyone. No more 'works on my machine' tooling drift.

Scripted install (CLI, non-interactive)

For CI, dotfiles, or onboarding scripts, use the non-interactive claude plugin subcommands.

# Add a marketplace and install without the UI
claude plugin marketplace add anthropics/claude-plugins-community
claude plugin install commit-commands@claude-community

# Audit what's installed (machine-readable)
claude plugin list --json

Build a plugin in five steps

1. Run plugin init (or make a folder) and drop components into skills/, agents/, hooks/, and .mcp.json at the root.
2. Reference bundled files with ${CLAUDE_PLUGIN_ROOT} in hooks and MCP configs — plugins are copied to a cache, so absolute paths break.
3. Optionally add .claude-plugin/plugin.json with a name, version, and author. Skip version and the git commit SHA is used.
4. Run claude plugin validate to catch frontmatter and manifest errors.
5. Push to a repo, add a .claude-plugin/marketplace.json catalog, and share the owner/repo as a marketplace source.

Why plugins win

Skills, agents, and hooks scattered across ~/.claude/ and individual repos are hard to move and easy to forget. A plugin makes that whole stack portable: version it, audit its context cost in /plugin, enable it per project, and update it when the source changes.

One agent is a worker; many agents are an assembly line that you steer from a single chair.

Subagents each run in their own fresh context window with their own tools. They do the heavy reading, then hand back a short summary. That is the whole trick: keep your main context clean while the noisy work happens elsewhere.

When orchestration is worth it (and when it is not)

The core constraint never changes: context fills fast and quality drops as it fills. Multi-agent setups exist to protect that budget, not to look clever. Spending more tokens only pays off when the work is parallelizable or verbose.

Pattern 1: Parallel fan-out (research)

Spin up several agents at once on independent slices of a problem. Each explores in its own context; the main thread then synthesizes their summaries. This works best when the paths truly do not overlap.

Investigate our auth system. Run three subagents in parallel:
1. Explore: map every login/session file and how tokens are issued
2. Explore: list all places that read or write user roles
3. Explore: find rate-limiting and lockout logic
Then summarize the attack surface in one page.

The built-in Explore agent is perfect here: it is Haiku-backed, read-only, and skips CLAUDE.md and git status to start lean. Cheap, fast, disposable.

Pattern 2: The pipeline (research → compose → verify)

Some work is a relay, not a sprint. Each stage runs as a separate subagent so a bloated research phase never pollutes the writing phase. Define small, single-purpose agents in .claude/agents/.

---
name: researcher
description: Gathers facts and returns a tight brief. Use proactively.
tools: Read, Grep, Glob, Bash
model: haiku
---
You investigate, then return ONLY a bulleted brief with file paths.
Never edit files. Never speculate beyond what you found.

A reviewer agent caps cost the same way by restricting tools and using a cheaper model:

---
name: verifier
description: Checks work against the brief and the tests.
tools: Read, Bash
model: sonnet
disallowedTools: Write, Edit
---
Run the test suite. Report PASS/FAIL plus the smallest fix list.

Pattern 3: Find → fix → test loops

An autonomous loop repeats a step until a quality gate passes. The cleanest gate in Claude Code is a Stop hook: it fires when Claude finishes and can refuse to let it stop until tests are green.

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "npm test --silent || { echo 'TESTS FAILED' >&2; exit 2; }"
      }]
    }]
  }
}

Have the hook script exit 2 on failure: that blocks the stop and feeds stderr back to Claude as a to-do, so it keeps fixing. Exit 0 lets it finish.

Headless loops for scripts and CI

Drive Claude non-interactively with -p (print mode). Capture the session ID as JSON, then resume it to chain steps without losing state.

sid=$(claude -p "Find the failing test and its cause" \
        --output-format json | jq -r '.session_id')

claude -p "Fix it, then run the suite until green" \
        --resume "$sid" \
        --permission-mode acceptEdits \
        --allowedTools "Edit,Bash(npm test)"

For reproducible CI runs, add --bare to skip auto-discovery of hooks, skills, MCP, and CLAUDE.md, then load only what you need explicitly. It is the recommended mode for scripted and SDK calls.

Monitoring and backgrounding agents

Long jobs do not have to block you. Press Ctrl+B to background a running task, or set background: true in an agent's frontmatter. Backgrounded agents run concurrently and auto-deny anything that would prompt.

Token discipline for any multi-agent run

1. Plan in plan mode first (Shift+Tab) so a stable prefix caches once and every execution turn reads from it.
2. Delegate broad searches to subagents; let only their short summaries enter main context.
3. Write the plan to a file like PLAN.md so it survives /clear between phases.
4. /clear between unrelated tasks — fresh context is free.
5. Check spend with /cost and live usage with /context.

There are two ways to build on Claude: call the model directly with the Messages API, or reuse Claude Code's whole agent loop with the Agent SDK.

Pick the layer that matches your job. The Messages API is one stateless HTTP call where you own everything. The Agent SDK wraps the API in a ready-made agent loop with tools, memory, and MCP. Claude Code is the interactive CLI built on that same SDK.

Layer 1 — The Anthropic Messages API

Every request is a POST to /v1/messages at https://api.anthropic.com. It is stateless: you resend the full conversation on each call (up to 100,000 messages). Three headers are required.

Current models & list pricing

Minimal Python request

pip install anthropic   # Python 3.9+, reads ANTHROPIC_API_KEY from env

from anthropic import Anthropic

client = Anthropic()
msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="You are a terse senior network engineer.",
    messages=[{"role": "user", "content": "Explain BGP route reflectors in 2 sentences."}],
)
print(msg.content[0].text)

Minimal TypeScript request

npm install @anthropic-ai/sdk   // 4.9+, Node 20+; also Deno/Bun/browser

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // reads ANTHROPIC_API_KEY
const msg = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  system: "You are a terse senior network engineer.",
  messages: [{ role: "user", content: "Explain BGP route reflectors in 2 sentences." }],
});
console.log(msg.content[0].type === "text" && msg.content[0].text);

Tool use (function calling) & the agentic loop

Pass a tools array — each tool has a name, description, and JSON-Schema input_schema. When Claude wants a tool it returns stop_reason: "tool_use". You run the tool and feed the result back as a tool_result block, then loop.

tools = [{
    "name": "get_weather",
    "description": "Current weather for a city",
    "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}]

messages = [{"role": "user", "content": "Weather in Detroit?"}]
while True:
    resp = client.messages.create(
        model="claude-sonnet-4-6", max_tokens=1024, tools=tools, messages=messages
    )
    messages.append({"role": "assistant", "content": resp.content})
    if resp.stop_reason != "tool_use":
        break
    results = []
    for block in resp.content:
        if block.type == "tool_use":
            out = run_my_tool(block.name, block.input)   # your code
            results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": out,
            })
    messages.append({"role": "user", "content": results})

Loop while stop_reason == "tool_use"; exit on end_turn, max_tokens, stop_sequence, or refusal. Control calls with tool_choice (auto, any, named tool, or none) and disable_parallel_tool_use: true to force at most one call.

Streaming, vision & PDFs

Set stream: true for SSE. The event flow is message_start then per-block content_block_start / _delta / _stop, then message_delta and message_stop. SDK helpers hide the plumbing.

with client.messages.stream(
    model="claude-sonnet-4-6", max_tokens=1024,
    messages=[{"role": "user", "content": "Write a haiku about subnets."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_message()

All current models accept images via {"type":"image","source":{...}} (base64 with media_type, or a URL source). PDFs go through document blocks and Claude reads both text and visuals.

messages=[{"role": "user", "content": [
    {"type": "image", "source": {"type": "url", "url": "https://example.com/diagram.png"}},
    {"type": "text", "text": "What VLAN topology is this?"},
]}]

Prompt caching — cut repeat cost ~90%

Mark stable, reused content (big system prompts, docs, tool defs) with cache_control. Cache reads cost about 1/10th of base input. Place the breakpoint after the static prefix.

system=[
    {"type": "text", "text": LONG_STYLE_GUIDE,
     "cache_control": {"type": "ephemeral"}},
]

TTL is 5 minutes by default or 1 hour (now GA, no beta header). Minimum cacheable length is 1,024 tokens on Opus 4.8 / Sonnet 4.6 (4,096 on Haiku 4.5). Usage reports cache_creation_input_tokens and cache_read_input_tokens.

Batch API — 50% off, async at scale

For non-urgent bulk jobs (evals, backfills, large extractions), submit many requests at once for half price. Poll until done, then read results.

batch = client.messages.batches.create(requests=[
    {"custom_id": "job-1",
     "params": {"model": "claude-haiku-4-5", "max_tokens": 256,
                "messages": [{"role": "user", "content": "Classify: ..."}]}},
])
# poll batch.processing_status until == "ended", then:
for r in client.messages.batches.results(batch.id):
    print(r.custom_id, r.result)

Extended thinking & structured outputs

Turn on deeper reasoning with thinking. Claude 4/4.5 and Sonnet 4.6 use {"type":"enabled","budget_tokens": N} (N must be < max_tokens); Opus 4.6/4.7/4.8 use {"type":"adaptive"} with interleaved thinking auto-enabled. With tool use, only tool_choice auto or none are allowed, and you must pass thinking blocks back.

Structured outputs are GA on Sonnet 4.5 / Opus 4.5 / Haiku 4.5 via output_config.format (no beta header) when you need guaranteed JSON shapes.

Official SDKs also cover Java 8+, Go 1.23+, Ruby 3.2+, C#, and PHP 8.1+, plus an ant CLI. Companion endpoints: Models API, Token Counting API, Files API, and the Admin API.

Layer 2 — The Claude Agent SDK

The Agent SDK (formerly the Claude Code SDK) runs the exact same agent loop that powers Claude Code, inside your process. It handles tool execution, context management, retries, and prompt caching so you don't write the tool loop yourself.

# Python (3.10+)
pip install claude-agent-sdk

# TypeScript — bundles a native Claude Code binary, no CLI install needed
npm install @anthropic-ai/claude-agent-sdk

Tiny Python agent

import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(
        prompt="Find every TODO in src/ and summarize them."
    ):
        print(message)

anyio.run(main)

Python has two entry points: query() creates a fresh session per call and returns an async iterator; ClaudeSDKClient reuses one session across exchanges with manual lifecycle (connect / query / receive_response / interrupt / disconnect) and supports interrupts.

Tiny TypeScript agent

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find every TODO in src/ and summarize them.",
})) {
  console.log(message);
}

In TypeScript, query() returns an async generator (the Query object) that maintains the session and exposes interrupt(), setPermissionMode(), setModel(), setMcpServers(), and close().

Built-in tools — nothing to implement

Read-only tools (Read, Glob, Grep, read-only MCP) can run concurrently; state-mutating tools (Edit, Write, Bash) run sequentially.

Permission modes — the safety dial

Custom tools, MCP & subagents

Define in-process tools with the @tool decorator (Python) or tool() helper (TypeScript, Zod schema), bundle with create_sdk_mcp_server() / createSdkMcpServer(), and pass via mcpServers. Return isError: true to signal failure without halting the loop; an uncaught exception stops it.

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("add", "Add two numbers", {"a": float, "b": float})
async def add(args):
    return {"content": [{"type": "text", "text": str(args["a"] + args["b"])}]}

server = create_sdk_mcp_server(name="math", tools=[add])
# pass server via the mcp_servers option of query()/ClaudeSDKClient

External MCP servers go through mcpServers/mcp_servers or a .mcp.json file, over stdio, HTTP/SSE, or in-process. Tool names follow mcp__{server}__{tool}; auto-approve with wildcards like mcp__github__*.

Hooks, sessions & cost caps

Hooks fire at lifecycle points (PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, PreCompact, and more). A PreToolUse hook can return permissionDecision allow/deny/ask/defer and even rewrite the input.

Capture ResultMessage.session_id to resume later via resume. The SDK also supports forking sessions, file checkpointing (rewind files to a prior message), reasoning effort (low→max), and guardrails max_turns and max_budget_usd.

Headless / CI automation

For pipelines, drive Claude Code non-interactively with claude -p.

claude -p "run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit" \
  --permission-mode acceptEdits \
  --output-format json

Which layer should I use?

Claude can infer intent, but it can't read your mind — the more precise your instructions, the fewer corrections you'll need.

Great results come from clear inputs. Tell Claude what to do, give it context, show it an example, and set the rules for "done." Then iterate in small steps and fix course early.

The seven habits of a strong prompt

Before and after: vague vs strong

The same goal, written two ways. The strong version names the file, the rule, and the test that proves success.

Vague (forces guessing)

fix the login bug

Strong (one-shot ready)

In @src/auth/login.ts, users with expired sessions get a
500 instead of a 401 redirect to /login.

Reproduce: call loginHandler() with an expired token.
Constraint: don't change the token schema; reuse the
existing redirectToLogin() helper.
Done when: the expired-token test in auth.test.ts passes
and `npm test auth` is green.

Point at files with @

Typing @ opens a file picker so Claude reads the exact file — no broad searching that floods context. Reference the real path instead of describing the code.

Refactor @src/api/users.py to use the repository pattern
in @src/api/orders.py as the reference. Keep public
function signatures unchanged.

Ask for a plan first

Plan Mode is the highest-leverage habit. Toggle it with Shift+Tab (cycles normal / plan / auto-accept). In plan mode Claude can read, search, and think — but it literally cannot edit files until you approve.

1. Enter plan mode with Shift+Tab or launch with claude --permission-mode plan.
2. Let Claude explore the relevant files and propose a plan.
3. Read the plan, correct the approach, then approve it.
4. Claude executes against a stable, cached context.

Dial reasoning with thinking keywords

Extended thinking is on by default. Escalate the budget with keywords when a problem is genuinely hard.

Correct course early

The moment an answer drifts, stop it. Don't let a wrong approach pile up in context.

Do / Don't grid

Delegate research to keep context clean

Unscoped "investigate" requests cause endless exploration that floods your main window. Hand research-heavy work to a subagent that runs in its own fresh context and returns only a short summary.

Use the Explore subagent to find every place we call the
Stripe API, then report back a one-paragraph summary with
file paths. Don't edit anything.

The Claude.ai app is more than a chat box: Projects give Claude a memory for your work, Artifacts give it a canvas, and styles give it your voice.

Most people just type into the chat and start over every time. Power users wire up Projects, Artifacts, and custom instructions so Claude shows up already knowing the context. This section shows how those pieces snap together into a real coworking setup.

Projects: a memory for a body of work

A Project is a self-contained workspace. It keeps its own chat history plus a knowledge base of files you upload once and reuse in every chat inside it. Projects are on every plan, including Free, which is capped at 5 projects.

The two pillars are project knowledge (uploaded docs, text, and code) and project instructions (custom instructions that set tone and role for every chat in that project).

When knowledge gets big: RAG

On paid plans (Pro, Max, Team, Enterprise), when your knowledge base nears the context limit, Claude automatically switches to Retrieval Augmented Generation. RAG expands capacity up to 10x by pulling only the relevant chunks per question instead of stuffing everything into context.

Project instructions: set the role once

Project instructions are the single highest-leverage Project setting. They tell Claude who it is and how to answer for the whole project, so you stop repeating yourself.

You are my senior network architecture reviewer.
Audience: enterprise infra teams (Juniper, Arista, Palo Alto).
Always: cite the config file by name, flag security risks first,
and give a one-line summary before the detail.
Never invent interface names — ask if a config is missing.

Styles: control the voice

Styles change how Claude writes, independent of any Project. Open the Search and tools menu and pick Use style. Four presets ship in: Normal Concise Formal Explanatory. Normal and Concise are always visible and can't be hidden.

Custom styles are where it gets useful. You can build one two ways:

1. Upload or paste a writing sample (pdf, doc, or txt) so Claude matches your voice.
2. Or pick Describe style for a starting point, then use Use custom instructions (advanced) to give exact rules.

Styles can be renamed, previewed, edited (by Claude or via Set Instructions Manually), and deleted.

Artifacts: the coworking canvas

Artifacts are a dedicated side window for standalone content: code, documents, data visualizations, and full apps that render live beside the chat. They're generally available on every plan and on iOS and Android, with their own Artifacts space in the sidebar.

The workflow is conversational. You ask, the artifact appears, you point at what's wrong, and Claude edits it in place — no copy-paste loop.

AI-powered Artifacts

You can build a shareable app with Claude intelligence baked in. It runs on Anthropic's infrastructure, needs no API keys, and — importantly — usage counts against each end-user's own subscription, not yours. So you can share a tool without paying for everyone's calls.

On Pro, Max, Team, and Enterprise (web and desktop), Artifacts also support MCP integration and persistent storage (personal or shared). That lets an artifact read and write to external tools like Asana, Google Calendar, Slack, and custom MCP servers.

File uploads and file creation

Drop files straight into a chat for analysis: CSV, TSV, PDFs, images, and more. Multiple files work in one chat and stay downloadable for the whole conversation.

Claude can also create files. On all plans (web, Desktop, Mobile), it generates downloadable .xlsx, .pptx, .docx, and PDF files, plus PNG charts and Python data analysis. Turn it on at Settings > Capabilities > Code execution and file creation.

Web search and Research

Web search must be turned on by you (toggle it in chat settings/tools). Once on, Claude decides when a prompt needs fresh data, searches, and answers with citations to its sources.

Research mode is a paid-only (Pro/Max/Team/Enterprise) agentic step up. It runs many progressive searches across the web and connected internal sources like Gmail, Google Calendar, and Google Docs. It needs web search on, and you enable it from the + button > Research.

Putting it together: a coworking session

The real power is the combination. Here's a typical flow that uses all four surfaces at once.

1. Create a Project, upload your reference docs, and write a role instruction.
2. Pick (or build) a custom style so output lands in your voice.
3. Open a chat, turn on web search, and ask Claude to draft something.
4. Claude renders the draft as an Artifact you can preview live.
5. Refine by pointing at the artifact; export it as .docx or .pptx when done.

The cheapest token is the one you never send — route smart, cache big, and keep context lean.

Two levers control your bill: which model runs the task, and how many tokens it reads each turn. Master both and you cut cost 5–10x without losing quality. The single rule under everything: the context window fills up fast, and quality drops as it fills.

Pick the right model for the job

Opus 4.8 costs 5x more per token than Haiku 4.5. Using Opus to fix a typo is like renting a crane to hang a picture. Match the model to the difficulty, not your mood.

Switch the active model mid-session with /model. Use /model default to let Claude auto-route harder turns to Opus for you.

/model haiku      # cheap, fast turns
/model sonnet     # the workhorse
/model opus       # bring out the heavy reasoning
/model default    # let Claude pick per task

Route from the command line

Set the model per run for scripts and one-offs. A headless triage pass on Haiku, then escalate only the hard cases.

# Cheap, scripted lint check on Haiku
cat build.log | claude -p "summarize the errors" --model haiku

# Escalate one tough bug to Opus
claude --model opus "think hard about the race condition in worker.py"

Push cheap, verbose work to subagents

A subagent on Haiku can churn through a noisy codebase search and hand back a short summary — the verbose output never pollutes your main (pricier) context. Set model: haiku in the agent frontmatter.

---
name: log-scanner
description: Use proactively to grep logs and return a short summary
tools: Read, Grep, Glob, Bash
model: haiku
---
Search the logs, extract only the failing requests, and report a 5-line summary.

Prompt caching: pay once for stable context

Caching is automatic in Claude Code — you never add cache_control yourself. The API caches by exact prefix match, so a cache hit costs just 0.1x base input (90% cheaper). The catch: any change anywhere in the prefix recomputes everything after it.

Keep context lean

File reads dominate context, and a bloated window both costs more and degrades quality. Fresh context is free — use it.

Be specific to avoid re-work

Vague prompts cause endless exploration that floods context and burns tokens. "Investigate the auth bug" can spiral; a scoped request lands in one pass.

# Costly: unscoped, invites infinite exploration
claude "investigate why login is slow"

# Lean: names the file, states the constraint
claude "in src/auth/session.ts, find why validateToken() does a DB call per request; propose a cache"

Batch and reuse work

Stop paying startup costs over and over. Reuse sessions in scripts instead of cold-starting each time, and let the cache stay warm across follow-ups.

# Capture a session id, then continue it cheaply
session_id=$(claude -p "Start a review of the diff" --output-format json | jq -r '.session_id')
claude -p "Now check for type errors" --resume "$session_id"

Trim CLAUDE.md ruthlessly

CLAUDE.md loads on every session and re-loads after every compaction — every line is a recurring tax. For each line ask: "Would removing this cause Claude to make mistakes?" If not, cut it. A bloated file also makes Claude ignore the rules that matter.

Watch the meter

You can't optimize what you don't measure. Check spend and usage as you go.

/cost       # token usage + estimated cost this session
/context    # live token breakdown by category
/mcp        # per-server tool cost — prune noisy servers

Your cost-saving habits, in order

1. Default to Haiku or Sonnet; reach for Opus only on hard reasoning.
2. Plan first (Shift+Tab) to write one stable, cached prefix.
3. Avoid mid-task model switches and CLAUDE.md edits — they nuke the cache.
4. /clear between unrelated tasks; /compact at logical breakpoints.
5. Scope prompts and @ files; rewind failures instead of correcting them.
6. Reuse sessions in scripts; batch non-urgent jobs at 50% off.
7. Check /cost and /context to catch waste early.

Claude Code is powerful enough to edit files, run shells, and call external servers — so the question isn't whether to trust it, but how to scope that trust.

Security in Claude Code is enforced by the harness itself, not by the model. A prompt or CLAUDE.md can never widen what Claude is allowed to do — only your settings, permission modes, and hooks can. That separation is the whole game.

The permission model

Every tool call is matched against three rule types. They are evaluated deny → ask → allow, and the first match wins, so a deny always beats an allow at any other level.

Rules use the format Tool or Tool(specifier). Manage them interactively with /permissions or write them into settings.json.

{
  "permissions": {
    "allow": [
      "Read(src/**)",
      "Bash(npm test)",
      "Bash(npm run lint)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Read(.env)",
      "Read(./secrets/**)",
      "Bash(curl:*)"
    ]
  }
}

Settings precedence

When rules conflict, this order decides (highest to lowest). A deny at any level cannot be overridden by an allow at any other level.

1. Managed (admin) settings — not even CLI flags override these
2. Command-line arguments
3. Local project settings (.claude/settings.local.json)
4. Shared project settings (.claude/settings.json)
5. User settings (~/.claude/settings.json)

Permission modes

Modes set the default posture for unmatched tools. Cycle them with Shift+Tab or set permissions.defaultMode.

The truth about --dangerously-skip-permissions

This flag (and the bypassPermissions mode) removes per-action review completely and skips protected-path checks. The only thing left is a circuit breaker that still prompts on rm -rf / and rm -rf ~ — and it offers no protection against prompt injection.

The flag is blocked when running as root or via sudo on Linux/macOS (that check is skipped inside a recognized sandbox). The safer move is almost always a scoped allowlist instead.

# Risky: blanket bypass on your laptop
claude --dangerously-skip-permissions   # don't do this on the host

# Safer: pre-approve exactly the tools you need
claude -p "run the test suite and fix failures" \
  --allowedTools "Read" "Edit" "Bash(npm test)" "Bash(npm run lint)"

Protected paths

In every mode except bypassPermissions, Claude Code refuses to auto-approve edits to sensitive locations. You don't configure these — they're built in.

Sandboxing risky autonomy

The sandboxed Bash tool gives OS-level filesystem and network isolation — Seatbelt on macOS, bubblewrap on Linux/WSL2. It covers Bash commands and their children only (not Read, Edit, WebFetch, or MCP). Turn it on with /sandbox or sandbox.enabled: true.

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/.aws", "~/.ssh", "~/.config/gcloud"],
      "denyWrite": ["~/"]
    },
    "network": {
      "allowedDomains": ["api.anthropic.com", "registry.npmjs.org"]
    }
  }
}

The default read policy still allows credential dirs, so Anthropic recommends adding denyRead for ~/.aws and ~/.ssh yourself. For org-wide enforcement, managed settings can set failIfUnavailable: true (refuse to start without a sandbox) and allowUnsandboxedCommands: false (kill the dangerouslyDisableSandbox escape hatch).

Whole-process isolation

For maximum autonomy, two options wrap more than just Bash:

Secret handling

Claude Code stores its own API keys encrypted via credential management, and blocks web-fetching commands like curl and wget by default. Your job is to keep your project's secrets out of reach.

1. Never hardcode keys — read them from environment variables (ANTHROPIC_API_KEY, etc.).
2. Add secret files to .gitignore and add Read deny rules for them.
3. Run a pre-commit secret scan as a hard gate before any commit.

# .gitignore
.env
.env.*
secrets/
*.pem

Trusting MCP servers

MCP servers are separate processes that run unconstrained on your host unless the whole Claude Code process is sandboxed. A server you add can read your data and run code — treat adding one like installing a dependency with full machine access.

First-time codebase runs and new MCP servers require trust verification. Note that verification is disabled in non-interactive -p mode (except --worktree, which still requires accepted trust) — so don't pipe an untrusted repo straight into headless mode.

When you do auto-approve MCP tools, scope them with wildcards rather than reaching for bypassPermissions. Note that acceptEdits does not auto-approve MCP tools at all.

{
  "permissions": {
    "allow": ["mcp__github__*"],
    "deny": ["mcp__github__delete_repository"]
  }
}

Hooks as guardrails

Hooks are your programmable safety net. A PreToolUse hook runs before the permission prompt and can deny a call, force a prompt, or skip it. Across the evaluation flow, hooks run first — even before deny rules — making them the strongest enforcement point you control.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | grep -qE '(^|/)(\\.env|secrets/)' && { echo 'Blocked: protected path' >&2; exit 2; } || exit 0"
          }
        ]
      }
    ]
  }
}

An exit code of 2 tells Claude Code to block the call and feed the message back to Claude. Use the same pattern to scan a diff for secrets before a commit, or to protect any path your team treats as off-limits.

Hardening checklist

1. Default to plan mode for unfamiliar work; switch to edit only after reviewing the plan.
2. Maintain a least-privilege allow list — specific tools and commands, not blanket grants.
3. Add deny rules for secret files, credential dirs, and dangerous commands (curl, rm *).
4. Never run --dangerously-skip-permissions on your host — only inside a container, VM, or dev container.
5. Enable the sandbox (sandbox.enabled: true) with denyRead for ~/.aws and ~/.ssh on autonomous runs.
6. Keep secrets in env vars; .gitignore them; gate commits with a secret scan.
7. Add only trusted MCP servers; scope tool approval with wildcards, never bypassPermissions.
8. Use PreToolUse hooks to block protected paths and scan diffs before commit.
9. Run a fresh-context /security-review on the diff before treating work as done.

Great code from Claude is not luck — it comes from a tight loop: plan first, change small, verify always, commit clean.

The goal is not code that runs. It is code that is correct, readable, and maintainable. Every habit below points at that.

The Core Loop

Use the same four-phase workflow Anthropic recommends. It keeps each change small enough to review and reversible if it goes wrong.

1. Explore in plan mode — read-only, no edits. Claude reads the code and asks questions.
2. Get a written plan — ask for a step-by-step approach before any code.
3. Implement & verify — leave plan mode, build it, run the checks against the plan.
4. Review the diff & commit — read every change, then commit with a clear message.

1. Ask for a Plan First

Plan mode is enforced at the tool level, not just a polite request. In plan mode Claude can only read, search, and think — it cannot edit files or run destructive commands. Enter it with Shift+Tab to cycle modes, or the /plan command.

# Start a session locked to read-only planning
claude --permission-mode plan

When to skip it: Anthropic's rule of thumb is simple. If you could describe the diff in one sentence (a typo, a log line, a rename), skip the plan. Plan when the approach is uncertain, the change spans multiple files, or the code is unfamiliar.

2. Point Claude at the Right Files

Don't make Claude guess where code lives. Reference exact files with @ so it loads only what matters and keeps context lean.

# Mention specific files and a line range
Review @src/auth/login.ts#L40-95 and the test in
@src/auth/login.test.ts. The session cookie isn't
being set on success. Find the root cause.

In the IDE, Option+K (VS Code) or Cmd+Option+K (JetBrains) inserts an @-mention for the current selection with its path and line range automatically.

3. Make Small, Testable Changes

The Common Workflows guidance is explicit: do refactoring in small, testable increments, and keep backward compatibility when it matters. Small diffs are easy to read, easy to test, and easy to revert.

Give yourself a safety net with git. Have Claude branch per feature so a bad turn is throwaway.

# Discardable safety net before a risky change
git checkout -b fix/session-cookie

4. Test-Driven Development

Claude defaults to writing implementation first — you have to invert that on purpose. Tell it to write failing tests first, give concrete examples, and run the tests after implementing.

Write failing tests FIRST for isValidEmail(), then implement.
Cases: "user@example.com" -> true, "nope" -> false,
"" -> false, "a@b.c" -> true.
Run the tests after implementing and show me the output.

5. Anchor Conventions in CLAUDE.md

CLAUDE.md is read at the start of every conversation, before anything else. It is the most reliable channel for your project's conventions — build commands, test runner, code-style rules, and gotchas. Generate a starter with /init, then trim it.

# CLAUDE.md (excerpt)
## Commands
- Test:  pytest -q
- Lint:  ruff check . && mypy src
- Build: make build

## Style (YOU MUST)
- Type hints on every function signature
- Immutable data — never mutate in place
- Async/await for all IO

6. Review the Diff Before You Trust It

This is where correctness is won or lost. Read the diff — don't just accept it. Watch for the "trust-then-verify gap": plausible-looking code that misses edge cases.

# Open the interactive diff viewer
/diff

For a second opinion, run the bundled review skills. They review the current diff in a fresh subagent that sees only the change and the criteria — not Claude's own reasoning.

7. Run It, Then Commit

Code that compiles is not code that works. Run the build and the test suite, address the root cause of any failure (don't suppress the error), then commit.

pytest -q && ruff check . && git add -A
git commit -m "fix: set session cookie on successful login"

Do / Don't Grid

A Tight Example Loop

Putting it together on a real bug fix — small, verified, committed:

1. Shift+Tab into plan mode: Bug: @api/cart.py#L20-60 double-charges on retry. Diagnose only.
2. Approve the plan, then leave plan mode and ask for a failing test that reproduces the double charge.
3. Let Claude implement the fix and run pytest -q until the new test passes.
4. Run /code-review on the diff, then /diff and read it yourself.
5. Run the full suite + linter, then commit: fix: make checkout idempotent on retry.

Claude writes its best docs when you hand it a role, an audience, a goal, hard constraints, and a sample of the voice you want.

Vague prompts produce vague prose. The fix is a simple frame you reuse for every writing task: who Claude is, who it's writing for, what success looks like, and the rules it must follow. Add your own source material and a voice sample, and quality jumps immediately.

The five-part writing prompt

Every strong writing request answers five questions. Skip one and Claude guesses, which is where bland output comes from. Keep them explicit and up front.

Lock a consistent style

If you write the same kinds of docs often, stop re-pasting style rules. Save them once so every session starts from your house style.

In the Claude app: Projects + custom instructions

Create a Project, drop your style guide and example docs into its knowledge, and put the rules in the Project's custom instructions. Every chat in that Project inherits them.

In Claude Code: CLAUDE.md

CLAUDE.md is read at the start of every session, so it is the most reliable place for writing conventions. Keep it short; bloated files get ignored.

# Writing style
- Audience: external developers integrating our API.
- Voice: direct, second person, present tense. No marketing fluff.
- Format: Markdown. H2/H3 headings. Code in fenced blocks with language tags.
- IMPORTANT: every code sample must be copy-pasteable and runnable as-is.
- Sentences under 25 words. Define an acronym on first use.

Work section by section, not all at once

Long documents drift when generated in one shot. Ask for an outline first, approve it, then fill one section at a time. You catch structure problems before any prose is written.

1. Ask for an outline only: "Draft a section outline for this README. No prose yet."
2. Edit the outline directly and paste it back as the agreed structure.
3. Request one section at a time, feeding the relevant source for each.
4. After the draft, run a self-critique pass before you accept it.

Make Claude critique its own draft

A fresh-eyes review catches what the drafting pass missed. Tell Claude exactly what to look for so it doesn't just rewrite for the sake of it.

Review the draft above as a skeptical editor. Flag ONLY:
1. Claims that need a source or are unverifiable
2. Sentences over 25 words or with passive voice
3. Steps a beginner could not follow
4. Anything off-tone vs. the voice sample
List issues as a numbered table, then give a revised version.

Generate tables, diagrams, and structured output

Claude is strong at turning messy notes into clean structure. Ask for the exact format you need.

Tables and comparison grids

Turn these release notes into a Markdown table with columns:
Feature | What changed | Action needed | Breaking?
Sort breaking changes to the top.

Diagrams as code (Mermaid)

Ask for Mermaid and you get a diagram that renders in GitHub, many docs tools, and Markdown viewers, and stays editable as text.

Draw the auth flow as a Mermaid sequenceDiagram:
user -> web app -> auth service -> token -> protected API.
Return only the fenced ```mermaid block.

Strict structured output via the API

When another program consumes Claude's output, enforce a schema. Structured outputs are GA on Claude API via output_config.format (no beta header) on recent models.

output_config={
  "format": {
    "type": "json_schema",
    "schema": {
      "type": "object",
      "properties": {
        "title": {"type": "string"},
        "summary": {"type": "string"},
        "tags": {"type": "array", "items": {"type": "string"}}
      },
      "required": ["title", "summary", "tags"]
    }
  }
}

Artifacts: draft documents live

In the Claude app, ask for an Artifact when you want an editable, self-contained document you can iterate on in a side panel instead of scrolling chat. Great for a README, a spec, or an email you'll keep refining.

Before / after: a real prompt upgrade

Same task, two prompts. The second wins because it supplies role, audience, goal, constraints, and a voice anchor.

Before vague

Write a README for my CLI tool.

After framed

You are a developer-experience writer. Audience: developers who
found this tool on GitHub and have 2 minutes to decide if it fits.
Goal: they can install and run their first command without leaving
the page.

Constraints: Markdown; under 350 words; sections = What it does /
Install / Quickstart / Config. Tone: terse and friendly, like the
sample below. Every command must be copy-pasteable.

Voice sample: "No config, no daemon. Point it at a folder and go."

Source (use only these facts):
- Installs via: npm i -g foldermap
- First command: foldermap ./src
- Reads a .foldermaprc for ignore globs

Output the outline first and wait for my OK before drafting.

Quality checklist before you ship a doc

Power users don't write better prompts — they run a better system around the prompts.

One goal per thread. Break it into a task list, sequence the steps, and feed Claude only the context that step needs. Everything else in this section is in service of that one idea.

Orchestrate the goal, not the prompt

For anything with 3+ distinct steps, Claude Code already tracks a todo list for you. As of Claude Code v2.1.142 it uses structured Task tools (TaskCreate, TaskUpdate, TaskList) instead of the old TodoWrite. Your job is to set the scope and let the list keep the work honest.

Anthropic's recommended rhythm for non-trivial work is four phases: explore, plan, implement, commit. Stay read-only while you explore so nothing changes before you have a plan.

1. Explore in plan mode (read-only) — press Shift+Tab or run /plan.
2. Plan — ask for a detailed, file-by-file implementation plan.
3. Implement — leave plan mode and build, verifying against the plan.
4. Commit — descriptive message, then open a PR.

Durable context: where memory lives

A focused thread is short-lived. Durable context is what survives a /clear or a new session. You have three layers — use the right one.

CLAUDE.md lives in a few places, and they stack. Use /memory to see which files are actually loaded.

~/.claude/CLAUDE.md      # applies to every session, all projects
./CLAUDE.md              # project root, checked into git (team shares it)
./.claude/CLAUDE.md      # project, alternate location
./CLAUDE.local.md        # personal, gitignored
src/api/CLAUDE.md        # per-directory, loads on demand when you touch that dir

Manage context deliberately

The context window is the resource that matters most. Performance drops as it fills, and Claude starts forgetting early instructions. Treat free context like a budget you spend on purpose.

/context          # see what is eating your context window
/mcp              # per-server token cost (MCP schemas are deferred until used)
/clear            # full reset between unrelated tasks
/compact          # summarize history, preserving key decisions
/compact focus on the auth refactor and the failing tests   # targeted compact

For long single tasks Claude Code auto-compacts near the limit — it drops old tool output first, then summarizes while keeping code, file paths, and decisions. You can also bias what survives with a Compact Instructions section in CLAUDE.md.

For broad exploration, delegate to a subagent. It runs in its own fresh context window and returns only a summary, so the research, logs, and doc-reads never touch your main thread.

Which mechanism do I reach for?

This is the question power users get wrong most often. Match the job to the lightest tool that does it.

Patterns for repeatable work

Anything you do more than twice should become a command. Custom slash commands are just markdown files — drop one in .claude/commands/ and it becomes /name.

# .claude/commands/ship.md
Review the current diff with /code-review, fix any CRITICAL
or HIGH issues, run the test suite, then write a conventional
commit message and open a PR. Verify the build passes first.

Define reusable subagents the same way, in .claude/agents/, with frontmatter to route cheap work to a faster model and scope its tools.

---
description: Reviews diffs for correctness. Use proactively after edits.
model: haiku                # route cheap, frequent work to Haiku 4.5
tools: Read, Grep, Bash
isolation: worktree         # run in its own git worktree
---
You are an adversarial reviewer. You see only the diff and the
acceptance criteria. Flag ONLY gaps that affect correctness.

An operating rhythm you can adopt

Put it together into a loop you run for every meaningful goal.

1. Frame — one goal, fresh thread. /clear if reusing a session.
2. Explore + plan — plan mode, then a written plan saved to a file.
3. Scope context — @ only the files in play; delegate wide research to a subagent.
4. Implement in increments — small, testable steps; give Claude a check it can run.
5. Verify — run /code-review in a fresh context before calling it done.
6. Capture — commit, and fold any new lesson into CLAUDE.md.
7. Reset — /compact for a long task, /clear before the next goal.

A full walkthrough of "Mastering Claude Code in 30 Minutes" by Boris Cherny — the creator of Claude Code — turned into slide-by-slide notes you can act on.

Source: Mastering Claude Code in 30 Minutes — Boris Cherny (Code w/ Claude, Anthropic). Quotes paraphrased.

From the Source: Boris Cherny on Claude Code

This section distills a talk by Boris Cherny — a member of technical staff at Anthropic and the creator of Claude Code — titled "Mastering Claude Code in 30 Minutes." Everything here comes straight from his words at Code w/ Claude.

Slide 1 — What Claude Code Is

A new kind of AI assistant

Past coding assistants completed a line, or a few lines, at a time — autocomplete on steroids. Claude Code is different: it is fully agentic. It is meant to build whole features, write entire functions and files, and fix entire bugs in one go.

Works with ALL your tools — no workflow change

A core design goal: you don't change how you work to use it. Claude Code slots into your existing setup instead of replacing it.

A power tool, intentionally un-opinionated

When you open Claude Code, you just see a prompt bar — nothing else. That minimalism is deliberate.

Slide 2 — Recommended First-Time Setup

Boris recommends a short setup pass the first time you run Claude Code. Each step is a one-time investment that makes everything afterward smoother.

1. Run /terminal-setup to fix multi-line input.
2. Run /theme to pick a theme that's comfortable for your eyes.
3. Run /install-github-app to bring Claude into your GitHub flow.
4. Customize your allowed tools so you stop getting prompted for routine actions.
5. (macOS) Turn on Dictation so you can speak your prompts.

1. /terminal-setup — better multi-line input

By default, adding a new line in a terminal prompt is awkward. This command wires up Shift+Enter for new lines instead of forcing you to type trailing backslashes.

/terminal-setup
# now: Shift+Enter = newline (no more \ at line ends)

2. /theme — light, dark, and colorblind-friendly

Set the theme to match your environment and accessibility needs, including a Daltonize option for colorblind users.

/theme
# choose: light  |  dark  |  Daltonize (colorblind)

3. /install-github-app — @mention Claude on GitHub

This installs the new GitHub app. Once it's set up, you can @mention Claude on any GitHub issue or pull request and have it respond right there in the GitHub UI.

/install-github-app
# then on any issue/PR:  @claude please review this and suggest a fix

4. Customize your allowed tools

Claude Code asks for approval before taking certain actions. If there's something you get prompted about constantly, allow-list it once so you're not interrupted every time.

5. Pro tip — talk to Claude Code (macOS Dictation)

Enable Dictation in System Settings > Accessibility > Dictation, then hit the dictation key twice and just speak your prompt out loud.

Slide 3 — Tip 1: Start with Codebase Q&A

This is Boris's number-one recommendation and the single best way to begin with Claude Code. Before you ask it to write anything, just point it at your repo and ask questions. It is also exactly what Anthropic teaches every new hire on day one of technical onboarding.

The onboarding result

Codebase Q&A collapsed the time it takes a new engineer to become productive at Anthropic.

Zero setup — and your code stays yours

There is nothing to configure before you can ask questions. Unlike tools that build a search index or upload your repo to a server, Claude Code reads the code locally, in place, on demand.

Deeper than text search

Plain text search (grep / Ctrl-F) only finds literal string matches. Claude Code goes a level deeper — it actually understands the code, so it can answer relational questions and surface real examples, at the quality of a wiki or internal docs.

> How is the AuthSession class instantiated and used?

Instead of listing every line containing AuthSession, it finds the real call sites and shows you how the class is actually used in practice.

Ask about git history

This is where it shines. The model knows git — it was never system-prompted to do this; "the model is awesome" and reaches for git on its own.

> Why does this function have 15 arguments named this weird way?

It looks through the git history to find who introduced those arguments, what issues the commits link to, and summarizes the whole story back to you.

Ask about GitHub issues

Using web fetch, Claude Code can read a linked GitHub issue and pull that context into its answer — connecting the code in front of you to the discussion behind it.

The Monday standup trick

Boris asks this every Monday before standup. It reads the git log, already knows his username, and produces a readout he pastes straight into a doc.

> What did I ship this week?

Slide 4 — Tip 2: Editing Code with a Small Toolset

Claude Code is fully agentic. Agentic means: you give the model tools, and it figures out how to use them to accomplish your goal — you don't micromanage the steps.

The whole toolset is tiny

There are only a handful of core tools. The power comes from how Claude strings them together to explore, brainstorm, and then edit.

> Add rate limiting to the /login endpoint and update the tests.

From that one sentence, Claude will search the codebase to find the endpoint, read the surrounding code, edit the handler, and run the tests — chaining its small toolset together on its own.

Slide 5 — Brainstorm & Plan Before Big Features

The most common failure mode: handing Claude an enormous task cold. People ask it to "implement this 3,000-line feature" in one go. Sometimes it nails it — but sometimes it builds the wrong thing, because it guessed at decisions you never spelled out.

The easiest fix: just ask it to think first

You do not need plan mode or any special tool. Plain language in your prompt is enough.

> Brainstorm a few approaches for this feature, make a plan,
  run it by me, and ask for my approval before you write any code.

1. Explore the relevant code
2. Brainstorm a few options
3. Write a plan
4. Get your approval
5. Then — and only then — write the code

Slide 6 — The "Commit, Push, PR" Incantation

Once a change is done, one short phrase hands the whole git wrap-up to Claude.

> commit, push, and open a PR

From that, Claude makes a commit, creates a branch, pushes it, and opens a pull request — the full ship sequence.

It matches your conventions automatically

Claude reads your code, your history, and your git log to figure out how your team writes commit messages — and then matches that format. This is not system-prompted; the model works it out from context.

Slide 7 — Plug in your team's tools: bash/CLI and MCP

Claude Code is agentic: you give it tools, it figures out how to use them. Tip 3 in the talk is about extending its tiny built-in toolset (edit files, run bash, search files) with the tools your team already lives in. There are two kinds.

Teaching Claude a CLI

You don't pre-program specific tools — you just describe what you want and let Claude explore. The "made-up Barley CLI" example: introduce a tool by name and let it read its own help text.

> We use the `barley` CLI for deploys. Run `barley --help` to
  learn it, then deploy the staging environment.

Adding an MCP server

MCP (Model Context Protocol) lets Claude talk to external systems — issue trackers, design tools, browsers, internal services. Boris's headline example: a Puppeteer MCP server that lets Claude drive a real browser and screenshot the result.

# Register an MCP server, then just ask Claude to use it
claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer

> Use the Puppeteer server to open localhost:3000 and screenshot it.

Slide 8 — Workflows: explore → plan → confirm, then let Claude CHECK its work

The most common effective workflow is simple: let Claude explore a bit, plan a bit, and ask for confirmation before it writes code. You don't need a special mode — just ask.

> Before you write any code: brainstorm a few approaches,
  make a plan, run it by me, and wait for my approval.

The big one: give Claude a way to check its own work

This is the most powerful pattern in the talk. When Claude has a feedback tool to verify what it built, it can iterate by itself — running, looking, fixing, re-running — until the result is near-perfect. No human in the loop between passes.

1. Give Claude a mock and say "build this web UI."
2. It gets close on the first pass.
3. Give it a check (tests / screenshot tool) and let it iterate 2–3 times.
4. It converges to near-perfect on its own.

Slide 9 — CLAUDE.md: the simplest way to give Claude context

More context = smarter decisions. As an engineer you carry tons of unwritten context; CLAUDE.md is how you hand some of that to Claude. It's a special filename in the project root (the same directory you start Claude in), and it's auto-read into context at the start of every session — it rides along on your first user turn.

Local vs checked-in

What to put in it

Nested CLAUDE.md

You can drop a CLAUDE.md into child directories. Unlike the root file (always loaded), nested ones are pulled in on demand — only when Claude is working in that subtree. Great for module-specific guidance without bloating the global context.

repo/
├── CLAUDE.md            # root — always loaded
├── frontend/
│   └── CLAUDE.md        # loaded when Claude works in frontend/
└── services/payments/
    └── CLAUDE.md        # loaded on demand for payments work

Slide 10 — The context & config hierarchy

It's not just CLAUDE.md — everything in Claude Code is hierarchical. Config flows from your repo, up to your personal global settings, up to org-wide enterprise policy. This applies to CLAUDE.md, slash commands, permissions, and MCP servers alike.

Permissions: auto-approve AND block, org-wide

Permissions work in both directions at the enterprise level:

.mcp.json — ship MCP servers with the repo

Check a .mcp.json into the repository and anyone who runs Claude Code there is prompted to install those MCP servers automatically.

// .mcp.json (checked into the repo)
{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Slide 11 — /memory and the # shortcut

Because memory is hierarchical, you need a way to see and edit it. Two tools do that.

/memory            # list & edit all active memory files

# always run the test suite with `pnpm test --silent`
   ↑ press '#', type the note, choose the destination file

Slide 12 — Recommendation: start with shared project context

If you're unsure where to begin in the hierarchy, Boris's answer is clear: shared project context. Write your CLAUDE.md, slash commands, permissions, and .mcp.json once, check them into the repo, and share them with the team.

Slide 13 — Key Bindings: The Hidden Keyboard Layer

Boris flags these because most people never discover them — Claude Code looks like a single prompt bar, but a handful of keystrokes unlock its real power. Each one is about steering Claude mid-flight or feeding it exactly the context it needs.

Resuming work across sessions

You don't lose a session when you close the terminal. Two startup flags bring you right back.

# Pick a previous session to resume
claude --resume

# Continue the most recent session
claude --continue

Slide 14 — The SDK Is Already On Your Machine

There's no separate package to install. The -p / --print flag is the Claude Code SDK. Pass a prompt, get a result back, and exit — non-interactive, scriptable, composable.

The shape of a call

You control the prompt, which tools Claude is allowed to use (including specific bash commands), and the output format — plain text, a JSON blob, or a stream of JSON you can process as it arrives.

# Basic one-shot
claude -p "summarize the failing tests"

# Constrain the toolset (allow-list specific tools/commands)
claude -p "triage this build" --allowedTools "Bash(git log:*)" "Read"

# Structured output for programmatic consumption
claude -p "list the changed files and why" --output-format json

# Streaming JSON to process incrementally
claude -p "analyze this log" --output-format stream-json

Piping: in and out

Because it reads stdin and writes stdout, claude -p slots into any shell pipeline.

# Feed it command output, parse the result with jq
git status | claude -p "which of these files are risky to commit?" --output-format json | jq '.result'

# Pull a giant log from a GCP bucket and find what's interesting
gsutil cat gs://my-bucket/prod.log | claude -p "what looks anomalous here?"

# Fetch data from the Sentry CLI and let Claude act on it
sentry-cli issues list | claude -p "group these by likely root cause"

Slide 15 — Advanced Parallelism: Many Claudes at Once

Boris calls himself a "Claude normie" — one Claude at a time, a few terminal tabs for a few repos. But the power users he sees, inside and outside Anthropic, almost always run many Claudes in parallel.

How the power users scale up

# Spin up an isolated worktree so a parallel Claude can't collide with your main checkout
git worktree add ../feature-x -b feature-x
# ...then start Claude inside that directory

Slide 16 — Q&A Gems

The hardest thing to build: safe bash

Boris named making bash commands safe as the single hardest part of building Claude Code. Bash is inherently dangerous — it changes system state in unexpected ways — yet approving every command by hand kills productivity, and not everyone runs inside Docker.

1. Read-only detection — some commands are recognized as read-only and treated as low risk.
2. Static analysis — figures out which commands can be safely combined (e.g. chained commands) before running them.
3. Tiered permissions — a layered allow-list / block-list system that operates at different levels (project, global, enterprise).

Fully multimodal from day one

Claude Code has always been multimodal — it's just hard to discover in a terminal. There are three ways to give it an image.

Why a CLI and not an IDE?

At Anthropic people use a huge range of editors — VS Code, Zed, Xcode, Vim, Emacs. The terminal is the common denominator that works for everyone. And given how fast the model is improving, there's a real chance people won't be using IDEs the same way by year's end — so they deliberately avoid over-investing in UI layers that may not matter.

How much does Anthropic itself use it?

▶︎ Watch the full talk: youtube.com/watch?v=B_KAEqiC-0Q

Most Claude Code problems are context problems in disguise — know the recovery move and you stay fast.

Performance degrades as the context window fills, so almost every fix below is about protecting that one resource. Learn the symptom, the cause, and the keystroke that resets it.

The fast triage table

When context is full

Two moves, two situations. Use /clear when you are starting something unrelated — fresh context is free and gives the cleanest results. Use /compact when you need to keep working on the same thread but reclaim room.

/clear                       # wipe history, start a fresh task
/compact                     # summarize history, keep key facts
/compact focus on the API changes   # steer what the summary keeps

Re-anchor after a reset

Project-root CLAUDE.md and MEMORY.md are re-injected from disk after a compact, but skill descriptions and path-scoped rules are lost until re-triggered. Persist plans to a file so they survive any reset.

echo "Goal: migrate auth to OAuth. Constraints: no schema change." > PLAN.md
# after /clear or /compact:
# "Read PLAN.md and continue from step 3."

When output drifts

Drift means the model lost the thread, not that it got dumber. First, re-state the goal in one specific sentence with the file names involved. Second, drop into plan mode so it must read and think before it touches anything.

If a correction fails twice, stop correcting. Rewinding erases the failed attempt entirely; correcting leaves the bad approach in context where it keeps misleading the model.

Esc          # stop Claude mid-action, context preserved
Esc Esc      # open rewind menu (or /rewind) to restore prior state

Permission & sandbox issues

Prompts are a feature, but you can tune the friction. Add durable allow rules with /permissions, or start the session in a looser mode for trusted work.

claude --permission-mode acceptEdits   # auto-approve file writes + mkdir/mv/cp
claude --permission-mode plan          # read-only until you approve a plan
claude --allowedTools "Bash(git*),Edit" # auto-approve specific tools only

For “outside allowed directories” errors, grant access to the extra path. Note that --add-dir grants file access but does not load that dir’s .claude/ config.

/add-dir ../shared-lib              # in-session
claude --add-dir ../apps ../lib    # at launch

MCP server not connecting

Start with /mcp — it shows every server, its connection status, available tools, and is where you complete OAuth for remote servers. From there, check the three usual causes: transport, scope, and restart timing.

1. Run /mcp and read the status. Red usually means a crashed subprocess or an unfinished OAuth.
2. Verify the transport. Cloud servers need --transport http; sse is deprecated; omit the flag for local stdio servers.
3. If you just edited .mcp.json, restart — it is read only at session start.
4. For a project-scoped server, approve it at the first-use prompt (a guard against cloned repos auto-launching processes).

claude mcp add --transport http docs https://code.claude.com/docs/mcp
claude mcp add playwright -- npx -y @playwright/mcp@latest
claude mcp get docs           # shows which scope holds it
claude mcp reset-project-choices   # re-trigger project approval prompts

High-leverage pro habits

Every flag, command, shortcut, and "which tool when" call in one scannable place.

CLI Flags (the daily ten)

Copy-paste launches

# Interactive with a starting prompt
claude "refactor the auth module"

# Headless, pipe content in
cat logs.txt | claude -p "explain the errors"

# Scripted continuation in the current dir
claude -c -p "Check for type errors"

# Start in plan mode (read-only until you approve)
claude --permission-mode plan

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

Slash Commands

Context & cost

Models & agents

Project & review

REPL Shortcuts

Thinking Budget

Keywords escalate reasoning depth in your prompt. More thinking means deeper reasoning, not better rule-following.

think  <  think hard  <  think harder  <  ultrathink (max)

Model Picker

Which Tool When

Config-File Map

Quick Recipes

# Add a remote MCP server (project-shared, checked in)
claude mcp add --transport http --scope project docs https://code.claude.com/docs/mcp

# Add a local stdio MCP server
claude mcp add playwright -- npx -y @playwright/mcp@latest

# Auto-format every edit (PostToolUse hook in settings.json)
{"hooks": {"PostToolUse": [{"matcher": "Edit|Write",
  "hooks": [{"type": "command",
  "command": "jq -r .tool_input.file_path | xargs prettier --write"}]}]}}

Custom Slash Command (60 seconds)

1. Create .claude/commands/optimize.md (filename becomes /optimize).
2. Add YAML frontmatter: description, argument-hint, optional allowed-tools, model.
3. Write the prompt body. Use $ARGUMENTS, $1, @path, and !cmd for dynamic content.

---
description: Optimize a file for performance
argument-hint: [file path]
allowed-tools: Read, Edit, Bash(git diff:*)
---
Review @$1 for performance issues and apply safe fixes.
Current diff:
!git diff $1

Before we touch a single buzzword, let's nail down what "AI" actually means. Short version: it's software that does tasks we used to assume needed a human brain. That's it. No glowing red eyes required.

One plain sentence

Artificial Intelligence is software that performs tasks we once thought required human intelligence — spotting spam, suggesting a song you'll like, finding the fastest route, answering a messy question in plain English. When you put it that way, "AI" stops sounding like science fiction and starts sounding like Tuesday.

The two ways software can be smart

This next idea is the spine of the entire track, so it's worth slowing down for. There are really only two ways to build something "intelligent," and the difference is who writes the rules.

The nesting dolls

Here's where the jargon usually gets confusing — AI, ML, Deep Learning, Generative AI, LLMs. They sound like rivals. They're not. They're Russian nesting dolls (matryoshka): open the big one and a smaller, more specialized one sits inside.

Each doll is a more specific kind of the one wrapped around it. So Claude is a Large Language Model, which is Generative AI, which is Deep Learning, which is Machine Learning, which is AI. All true at once. No contradiction.

Narrow vs general — set your expectations

Today's AI is narrow: brilliant at one job. A spam filter can't drive a car. Claude can write a poem but can't water your plants. AGI — Artificial General Intelligence, a do-anything, human-level mind — does not exist yet, no matter what a flashy demo implies.

The whole story in one breath

You don't need the full history — just the shape of it. Read this as a single timeline:

1. 1950 — Alan Turing asks "can machines think?" The field gets its name a few years later, in 1956.
2. 1980s — Expert systems: giant hand-written rulebooks. Clever, but brittle.
3. 1990s–2000s — Machine Learning takes over: let the data write the rules.
4. 2012 — Deep learning explodes after neural nets crush an image-recognition contest.
5. 2017 — The transformer is invented — the engine behind every modern LLM.
6. 2022 — ChatGPT launches and suddenly everyone's grandma knows the word "AI."
7. Today — Agents: AI that doesn't just answer, but takes actions for you.

It's already in your pocket

If "AI" still feels abstract, look around — you've been using it for years:

Here's the big flip this section owns: instead of a human painstakingly hand-coding rules, machine learning lets the computer learn the patterns straight from data. You don't tell it what a cat is — you show it, and it works the rest out itself.

The cat-photo story

Imagine teaching a child what a cat is. You don't hand them a rulebook saying "pointy ears, whiskers, four legs, smug expression." You just point at cats over the years and say "cat." Eventually the child recognizes a cat they've never seen before — even a weird hairless one.

Machine learning does the same thing. Show a model a giant album of labeled cat photos and it learns "cat-ness" on its own. Nobody writes the rules; the rules emerge from the examples. That's the whole shift.

The working vocabulary

Four words unlock almost every ML conversation. Learn these and you're fluent enough to follow along.

Three ways a machine can learn

There are three big "learning styles," called paradigms. One line each:

The cat-album example is supervised learning — every photo came with a label. That's the most common starting point, and the one to keep in your head.

Two phases of a model's life: training vs inference

This split shows up everywhere in AI, so it's worth nailing now.

Memorizing vs actually understanding

Here's the trap every model can fall into. We don't want it to memorize the album — we want it to understand cats well enough to handle ones it's never seen. That ability to handle new data is called generalization, and it's the entire point.

The failure is called overfitting. Overfitting is the student who memorizes every past exam word-for-word, then panics when the teacher changes the numbers. They aced the practice test and bombed the real one — because they learned the answer key, not the subject.

So far we've treated "the model" as a magic box that tunes dials. The most powerful ML models are built from layered networks of these dials stacked together — let's look under that hood next.

Remember the nesting doll from earlier? Open the "machine learning" doll and inside sits deep learning. Let's crack that one open too — because it turns out to be built from millions of copies of one tiny, almost embarrassingly simple gadget: the artificial neuron. Build one, stack a bunch, and you've got the engine behind nearly every modern AI.

Step one: build a single neuron

An artificial neuron is basically a tiny calculator. It does three things in a row:

1. Take some inputs — numbers coming in (say, the brightness of pixels, or "was it raining?").
2. Multiply each by a weight, then add them up — the weight says how much that input matters. Big weight = "pay attention to this." Near-zero weight = "ignore it."
3. Push the total through an activation function — a gate that bends the result so the network can learn curvy, non-straight-line patterns. Loosely: a bouncer who decides how much of the signal gets waved through.

That's the whole neuron. Inputs in, one number out. Not magic — arithmetic.

Step two: stack neurons into layers

One neuron makes one little decision. The power comes from wiring thousands of them together in layers, where each layer's output feeds the next.

And "deep" learning? It just means there are many hidden layers stacked between input and output. That's the entire secret behind the scary-sounding word. Deep = lots of layers. That's it.

The knobs: weights are everything

Here's the anchor image to keep in your head. Picture a giant sound-mixing board covered in dimmer-switch sliders. Each weight is one slider. The activation function is the gate each signal passes through after the sliders set its level. A real network has millions (or even billions) of these sliders.

When people say a model is "trained," they mean exactly one thing: all those sliders got nudged up and down until the output came out right. Training is just tuning the knobs. And here's the kicker — no human touches them by hand. The network adjusts its own sliders, which is the next thing to explain.

How it actually learns (the loop)

So how do you tune millions of sliders with nobody touching each one? You let the network do it, in a repeating four-beat loop:

Gradient descent is the all-time favorite analogy here: imagine a hiker descending a foggy mountain, feeling which way is downhill and taking one careful step at a time. "Downhill" means "less error." Do that enough and you reach a valley floor — a network that's usually right.

Why deep beats hand-crafted features

Before deep learning, humans had to hand-engineer the clues a program looked for — "an edge here, a curve there." Tedious, brittle, and capped by human imagination.

Deep networks flip that. Given enough examples, they discover their own hierarchy of clues: early layers find edges, middle layers assemble edges into shapes, deeper layers assemble shapes into things like faces or wheels. Nobody programmed those stages — they emerged from turning the knobs.

One honest caveat

Where this is heading

You now know the whole engine: neurons, layers, weights as knobs, and a learning loop that tunes them by chasing lower error. Now take a network like this and make it enormous — billions of knobs — then feed it a huge chunk of all the text humans have ever written. Do that, and what you get is a Large Language Model. That's exactly where we go next.

You've used an LLM if you've ever talked to Claude, ChatGPT, or Gemini. But under the hood, the thing doing all that brilliant work is doing something almost comically simple: guessing the next chunk of text, over and over.

The one-line definition

A Large Language Model (LLM) is a very large neural network (remember those from the last section?) trained to do one simple thing: predict the next token — a token being a small piece of text, roughly a word or part of a word. That's it. Everything else — the essays, the code, the patient explanations — grows out of that single skill done at an absurd scale.

What does "large" actually mean?

Two things are large here, and both matter:

"Predict" doesn't mean "look up"

When we say it predicts, we mean it models probabilities over what comes next. Type "I'll be there in ___" and your phone suggests five minutes. An LLM does the same basic trick — just trained on a huge chunk of the internet instead of your text history, and scaled up enormously. Same idea, wildly more power.

How it writes: the autoregressive loop

Here's the surprising part — the model doesn't compose a whole answer at once. It builds every response one token at a time, in a tight loop:

1. Predict a probability for every possible next token, given everything so far.
2. Pick one token from that distribution (often, but not always, a top-ranked one).
3. Append it, feed the whole thing back in, and predict again.
4. Repeat — sometimes thousands of times — until the answer is complete.

This predict-pick-append-repeat cycle is called autoregressive generation. Every answer you've ever gotten from an LLM is this loop run over and over. It's a bit like writing a sentence where each word is chosen knowing only the words before it.

The plot twist: emergence

Here's what made LLMs a genuinely big deal. At small scale, a next-token predictor is just a clever autocomplete. But push the size up far enough — more parameters, more data — and abilities that weren't obvious at small scale start to show up: translating languages, writing working code, multi-step reasoning. Nobody hand-coded those in.

Meet the players

You already know the names. Claude (Anthropic), GPT (OpenAI), Gemini (Google), and Llama (Meta) are all LLMs. Different companies, different training, same core machine: a giant neural net predicting the next token.

Here's the plot twist nobody tells beginners: a language model never actually reads words, or even letters. It reads tokens — bite-sized chunks of text. Everything else in this guide is built on top of that one fact.

What's a token?

A token is a sub-word chunk: sometimes a whole word, sometimes a piece of one, sometimes just a space or a punctuation mark. As a rough rule of thumb for English, one token is about 4 characters, or roughly 0.75 of a word. So 100 words lands somewhere near 130 tokens.

Why chop words up? Because keeping a separate entry for every word ever written would be wildly inefficient. Instead, the model learns a kit of reusable pieces. Take unbelievable — it can split into un / believ / able. Those same pieces snap back together to build unthinkable, believer, readable, and thousands more. Think of tokens as the LEGO bricks of text. (Different models slice slightly differently, so the exact pieces vary — but the idea is identical.)

From token to meaning: the embedding

A model can't do math on the letters c-a-t. So each token gets converted into an embedding — a long list of numbers (a vector) that captures its meaning. Not the spelling. The meaning.

On its own, a token's embedding captures its general meaning, the dictionary-ish gist. The richer, in-context meaning (is "bank" a river or a vault?) gets layered on later by the transformer — that's the next section.

The anchor idea: GPS coordinates for meaning

Think about how GPS works. Two numbers — latitude and longitude — pinpoint any place on Earth. Grand Blanc, Michigan is just a pair of coordinates, and so is Detroit, and because they're close in real life, their numbers are close too.

An embedding does the same trick, but for meaning instead of geography. Its list of numbers pinpoints a word in an imaginary "meaning-space." Words with similar meanings land near each other, like houses in the same neighborhood: cat, kitten, and feline cluster together, while helicopter sits way across town.

Meaning even has direction

The famous demo: take the vector for king, subtract man, add woman, and you land remarkably close to queen.

king − man + woman ≈ queen

That's not a parlor trick — it hints that meaning is geometric and directional: a rough "royalty" direction and "gender" direction actually exist as movements through the space.

Why you should care: cost and the clock

Tokens aren't just an internal detail — they're the unit of money and the unit of memory. You're billed per token (in and out), and the model can only hold so many at once.

We'll come back to the context window when we talk about inference — for now, just hold the picture: it's a token budget, and you spend it as you go.

Back at our 2017 stop on the timeline, a paper with the cheeky title "Attention Is All You Need" introduced the transformer — the architecture humming under the hood of virtually every modern LLM. The title was a flex, and for once it held up: attention really was the key idea, and it kicked off the entire ChatGPT era.

The heart of it: self-attention

Here's the one idea that matters. As the model reads, every token (a word or word-piece) looks at the other tokens and decides how much each one matters to its own meaning. That's it. That's self-attention.

Picture a sentence: "The trophy didn't fit in the suitcase because it was too big." What does "it" mean — the trophy or the suitcase? You knew instantly. Self-attention is how the model figures it out too: the word "it" glances at the other words, scores which one is most relevant, and locks onto "trophy." Swap "big" for "small" and the answer flips to "suitcase" — and the model's attention flips right along with it.

Why it crushed the old way (RNNs)

Before transformers, models called RNNs (recurrent neural networks) read text the way you'd read with a finger under each word — one word at a time, left to right, trying to remember everything that came before. Slow, and forgetful: by the end of a long paragraph, the start had faded.

Attention reads the whole input at once. Two huge wins fall out of that:

Multi-head attention: several viewpoints at once

One round of attention is good. Transformers run several in parallel — called heads — and each head can learn to notice a different kind of relationship. Back at the dinner party: one guest tracks grammar (who's the subject, who's the verb), another tracks topic (which words are about the same thing), another tracks who-refers-to-whom (that "it" → "trophy" link). Combine all those viewpoints and you get a far richer read of the sentence than any single pass could give.

Stacked deep — the "deep" in deep learning

One block of attention isn't the whole model. These blocks are stacked many layers high, each one's output feeding into the next. Early layers tend to catch simple patterns; later layers build toward grammar, meaning, and intent — the same hierarchy-of-abstraction idea from the neural-networks section, just taller. That stacking is the "deep" in deep learning.

So now we have the architecture. But an empty transformer knows nothing — it's a brilliant student who hasn't opened a single book yet. How do you actually teach it? That's training, and it's our next stop.

A finished AI assistant isn't built in one step — it's educated in three. Picture a model going to school: first it reads the entire library, then it takes a class on answering questions, then mentors coach it until it's genuinely useful.

The three-class education of a model

Everything in this section happens during training — the slow, expensive "studying" phase where the model's internal numbers (its weights) get tuned. Once training wraps up, those weights are locked in and the model ships out to do its job (that's inference, covered elsewhere). Here are the three classes it takes, in order.

Stage 1: Pretraining (self-supervised next-token prediction)

The model chews through a colossal pile of text and repeatedly guesses the next token. Because the right answer is simply whatever actually came next, no human grading is needed — that's why it's called self-supervised. The result is a base model: a raw text-completer that has absorbed grammar, facts, and patterns but isn't yet a polite assistant.

Stage 2: Supervised fine-tuning (SFT)

Here the base model keeps training, but now on hand-picked examples of good instruction-and-answer pairs. It's the difference between someone who has read every cookbook and someone who's taken a class on actually answering "what should I make for dinner?" SFT teaches how to respond — the helpful format, the tone, the do-what-was-asked behavior. It generally doesn't pour in new knowledge; that came from Stage 1.

Stage 3: RLHF and preference tuning

Some things are hard to capture with example answers — "be honest," "don't be smug," "refuse this politely." So instead of writing perfect answers, humans look at two model replies and pick the better one. A reward model learns to predict those human preferences, and reinforcement learning gently steers the main model toward answers the reward model scores highly. It's coaching: try, get ranked, adjust, repeat.

The cost reality

The three stages are wildly unequal in price. Pretraining is the budget-buster; the later stages are cheap by comparison but disproportionately decide how the model behaves.

Training built the brain. Inference is what happens when you actually use it — and understanding this one moment explains why models are so fluent, so fast, and occasionally so confidently, spectacularly wrong.

Inference: using the frozen brain

Remember training — millions of examples nudging billions of dials until the model got good? Inference is the exam, not the studying. The dials are now locked. Every time you chat with a model, you're running that finished, frozen brain forward to generate text. The weights don't change, the skills are fixed in place. It doesn't learn from your conversation, and it won't remember you tomorrow.

The context window: its tiny working memory

The model has no memory of your last chat and no private notebook. All it can "see" is what fits in its context window right now — think of it as the model's short-term working memory, or the desk it's allowed to spread papers on.

Here's the catch beginners always miss: that desk holds everything at once — your prompt, the entire back-and-forth history, the system instructions, and the answer it's currently writing. Anything that doesn't fit on the desk is simply gone. Not "kind of forgotten" — invisible. If a detail scrolled off the top, the model isn't ignoring it; from where it sits, that detail never existed.

Temperature: the creativity dial

When the model generates, it's choosing the next word from a list of likely candidates. Temperature (and related sampling settings) decides how adventurous that choice is.

Why models hallucinate

A hallucination is when the model states something false with total confidence — a fake citation, a made-up date, a plausible-sounding "fact" that isn't. Beginners assume this is a bug. Mostly, it's the core mechanism working exactly as designed.

The model doesn't look up facts in a database. It predicts plausible text, one word at a time, based on patterns from training. When it has seen the answer often, the most plausible continuation happens to be correct. When it hasn't, the most plausible continuation is a confident-sounding guess — because in its training data, confident sentences almost never trail off with "...but honestly I'm not sure."

The fix is shockingly effective

Here's the rule of thumb worth memorizing. When a model answers open-ended questions purely from memory, it can be wrong a meaningful chunk of the time — and you often can't tell which chunk. Hand it a source document to work from — and ask it to answer using that document — and accuracy improves dramatically, because now it's reading instead of guessing.

The takeaway every pro repeats: models are best as editors and synthesizers, not as knowledge sources. Don't ask "what does the contract say?" — paste the contract in and ask "according to this, what does it say?"

Your practical mitigation toolkit

The knowledge cutoff

Every model was trained up to a certain date and then frozen. On its own, it knows nothing that happened after its knowledge cutoff — last week's news, today's prices, a result from this morning. Ask about recent events and it'll either admit the gap or, worse, confidently improvise. The fix is the same one as above: don't rely on stale memory, drop the fresh information straight into the context window.

A chatbot answers and stops. An agent reads a goal, takes a real action, looks at what happened, and keeps going until the job is done. That loop is the whole difference.

The leap: from chatting to doing

So far we've treated an LLM as something you talk to: prompt in, text out, done. An agent takes that same model and drops it into a loop where it can take actions in the world — search the web, run code, edit a file — and then react to the results. One single model call is not an agent. The loop is what earns the name.

The core loop, one trip around

Every agent runs the same four-beat cycle, over and over, until the goal is met:

1. Perceive — read the goal and the current state ("the tests are failing; here's the error").
2. Think — plan the next single step ("I should open the file the error points to").
3. Act — call a tool or run code (open the file, run the test, search the docs).
4. Observe — read the result, then loop back to step 1 with that new information.

The anchor: a chef tasting the sauce

Picture a cook who never tastes anything — they just follow a fixed recipe and pray. Now picture a real chef: taste the sauce (observe), decide it needs salt (think), add a pinch (act), taste again (loop). That feedback cycle — not one frozen recipe — is exactly what makes an agent an agent.

What's a "tool," really?

A tool is just a function the model is allowed to call. Each one comes with three things: a name, a plain-English description of what it does, and a typed input schema (what arguments it expects). The model reads those descriptions and picks the right tool for the moment. Without tools, an LLM can only produce text — it can say "I'll search for that," but it can't actually do it.

Why the loop is the entire point

Feeding each result back into the next step lets the model check its own work and self-correct. Wrote a function? Run the test. Test failed? Read the error, fix the line, run it again. That tight perceive-act-observe rhythm is exactly how Claude Code operates — it doesn't just suggest a change, it makes the change, runs your tests, and reacts to what breaks.

Memory and a leash

Two practical pieces keep the loop sane. First, working memory: every tool result gets added to the conversation, so the model carries what it learned into the next step. Second, a budget — a maximum number of iterations — so it can't spin forever chasing a goal it can't reach.

Where loops go wrong

Here's the good news and the catch in one breath: AI is genuinely useful and genuinely limited. Knowing exactly where it falls short is what turns you into a power user instead of a worrier.

Picture a brilliant, fast new intern. Incredibly capable, worth handing real work to — but you still review the important stuff, you don't give them the company passwords, and you don't let them sign the contract alone. That's the exact posture to take with AI. Trust, but verify.

The real limits (none of these are dealbreakers — just things to know)

The ethics surface, briefly

Alignment: making AI do what we actually want

Alignment is the engineering effort to make AI behave the way we genuinely intend — not just the literal words we typed. The shorthand is HHH: Helpful, Honest, and Harmless. Sounds simple. The hard part is all three at once — a model that refuses everything is harmless but useless; one that answers anything is helpful but unsafe. Balancing them is the open challenge.

Your practical user rulebook

1. Keep a human in the loop. AI drafts and suggests; you decide and approve. You're the editor, not the audience.
2. Verify high-stakes output. Medical, legal, financial, or anything you'd put your name on? Double-check it against a real source.
3. Never paste secrets. No passwords, API keys, client data, or anything you wouldn't hand to a stranger.
4. Cite and check sources. Ask for references — then actually confirm they exist and say what the AI claims.

The calm takeaway

None of this is doom. These are solvable, ongoing engineering problems, and a lot of smart people are actively working on every one of them. The right stance is caution, not fear — the same everyday judgment you'd use with any powerful new tool.

You just toured the whole country of AI. This is the pocket card of key phrases to point at when one slips your mind — no memorizing required, just a quick "oh right, that's what that means." Each definition deliberately echoes the analogy from its home section, so it should feel like running into an old friend.

How to use this page

Read top to bottom and the terms build on each other; or just Ctrl+F for the one word that's bugging you. Definitions are one plain line each — zero jargon hiding inside the jargon.

Foundations

AI AGI ML Deep Learning Neural Network Parameter / Weight

Language plumbing

Token Embedding Vector Context Window

Architecture

Transformer Attention LLM

Training

Pretraining Fine-tuning RLHF

Using it

Inference Temperature Hallucination Prompt RAG

Frontier

Agent Multimodal Open vs Closed weights

The glossary