Claude Code from the inside

This is not a list of Claude Code features. The docs already have that, and it changes every week. This guide is about mechanisms: why Claude reads five files before it edits one, why a long session gets worse, why a rule in CLAUDE.md is a request and a hook is a guarantee. When you understand the mechanism, every new feature is just a new knob on a machine you already know.

The path goes from zero to expert in four stages. Chapters 1–3 build the mental model (loop, terminal, context). Chapters 4–8 are the daily-driver skills (memory, permissions, planning, prompting, rewinding). Chapters 9–12 are the extension layer (skills, subagents, hooks, MCP, plugins). Chapters 13–16 are the expert layer (parallel sessions, CI, model choice, habits). Each chapter has one interactive figure: click the buttons, break things, press ↺ Reset.

A chat model answers. An agent acts. Claude Code wraps a Claude model in a loop with tools: the model reads your request, decides which tool to call (read a file, grep, edit, run a shell command, fetch a URL), sees the result, and decides again. It repeats until it thinks the job is done — or until you interrupt.

The docs describe three phases that blend into each other: gather context, take action, verify results. The single most important sentence in this whole guide follows from that loop: Claude is only as good as its ability to check its own work. If there is a test, a build, a linter, or a screenshot it can look at, the loop closes itself. If not, you are the verification step.

Install with the native installer and start it inside a project directory:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

cd my-project
claude            # interactive session
claude "explain the auth flow"   # start with a prompt
claude -c         # continue the latest conversation in this directory
claude -r         # pick an older session to resume

The same engine runs in several surfaces: the terminal CLI, VS Code and JetBrains extensions, the Desktop app, the web at claude.ai/code (cloud sessions in a sandbox), the mobile app, and Slack. They share your repo's CLAUDE.md files, settings and MCP servers. With a claude.ai subscription you can move a session between them: /desktop hands a terminal session to the Desktop app, --teleport pulls a cloud session into your terminal, and /remote-control lets you steer a local session from your phone.

Inside the prompt, a few characters change what you type into something else. Learn these and you already use Claude Code better than most people:

Everything Claude “knows” in a session lives in its context window: the system prompt, tool definitions, your CLAUDE.md, skill descriptions, every message, every file it read, every command output. The window has a fixed size. When it fills, Claude Code compacts: it replaces older history with a summary. Details get lost in summaries.

And there is a quieter problem before the window is full: noise. The more irrelevant stuff sits in context — a debugging tangent, three unrelated questions, a 2,000-line log — the worse Claude follows your instructions. Expert users treat context like RAM on a small machine.

Each session starts blank — except for files Claude Code loads automatically. The main one is CLAUDE.md: plain markdown with build commands, conventions and “never do X” rules. Run /init once and Claude writes a first version by reading your repo. There are several levels, and they add up (they don't override each other):

What goes in a good project CLAUDE.md? Only what Claude can't guess and will need in most sessions:

# Build & test
- `pnpm dev` starts the app, `pnpm test -- path/to/file` runs one test file
- Always run `pnpm typecheck` after changing types

# Conventions
- Use pnpm, never npm. ES modules only.
- API handlers live in src/api/, one file per resource. See @docs/api-style.md

# Gotchas
- The `legacy/` folder is frozen. Never edit it.
- When compacting, preserve the list of modified files and test commands.

Every tool call passes a gate. Two things decide the outcome: your permission rules (explicit allow / ask / deny lists) and the session's permission mode (the default behavior for anything no rule matches).

Shift+Tab cycles default → acceptEdits → plan, and optional modes you have enabled slot in after plan. dontAsk is never in the cycle; start it with --permission-mode dontAsk. Rules live in settings.json under permissions and are checked in a fixed order: deny, then ask, then allow. First match wins; specificity does not matter.

// .claude/settings.json  (shared with the team — commit it)
{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git commit *)"],
    "ask":   ["Bash(git push *)"],
    "deny":  ["Read(./.env)", "Read(./secrets/**)", "Bash(curl *)"]
  }
}

Settings come in layers too. For a single key the higher layer wins — but list keys such as permissions.allow and deny are merged across layers: managed policy > command-line flags (--settings) > .claude/settings.local.json (you, this project) > .claude/settings.json (team) > ~/.claude/settings.json (you, everywhere). Not sure where a key belongs? Ask: /update-config allow npm test — or run /fewer-permission-prompts, which scans your history and proposes an allowlist of safe read-only commands.

The most common beginner move is “implement feature X” as the first prompt. Claude will — and it will solve the problem it guessed, not the one you have. The recommended workflow separates research from execution:

1. Explore (plan mode): “read src/auth and explain how sessions are refreshed.” No edits.
2. Plan: “plan how to add Google login. Which files change? What's the migration?” Press Ctrl+G to edit the plan yourself in your editor. Approving the plan exits plan mode.
3. Code: Claude implements against the plan, checking it off.
4. Verify & commit: tests, typecheck, a look at /diff, then “commit with a clear message and open a PR”.

Claude can infer a lot, but not what's in your head. Every fact you leave out becomes a guess, and every guess is a chance to solve the wrong problem. A good prompt is not long — it's specific: where to look, what's wrong, what “done” means, and what not to touch.

Claude Code saves a checkpoint before each prompt: the conversation state plus snapshots of the files Claude edited. Press Esc Esc on an empty prompt (or run /rewind), pick a message, and choose: restore code, restore conversation, or both — or summarize from that point. That makes experiments cheap: let Claude try a bold approach, and rewind if you don't like it.

A skill is a folder with a SKILL.md: YAML frontmatter plus markdown instructions, optionally with scripts and reference files next to it. You invoke it as a command (/deploy staging), or Claude loads it by itself when your task matches its description. Custom slash commands were merged into skills: an old .claude/commands/deploy.md still works and creates /deploy too.

The trick is progressive disclosure. At session start only each skill's name and description sit in context. The full body loads when the skill is used; files it links load only if Claude opens them. So you can have fifty skills and pay for fifty short descriptions.

.claude/skills/release-notes/SKILL.md
---
name: release-notes
description: Draft release notes from merged PRs since the last tag. Use when asked for a changelog or release notes.
disable-model-invocation: true      # only I can trigger it (/release-notes)
allowed-tools: Bash(git log *) Bash(gh pr list *)
context: fork                       # run in a forked subagent, return a summary
---
1. Find the last tag with `git describe --tags --abbrev=0`.
2. List merged PRs since then …
3. Group by feat / fix / chore. Output markdown. See [template.md](template.md).

Where skills live: ~/.claude/skills/ (you, all projects), .claude/skills/ (the repo — commit it), managed (your company), and plugins (namespaced like /my-plugin:review). Claude Code also bundles skills you get for free: /code-review, /simplify, /debug, /batch, /loop, /run, /verify, /doctor, /fewer-permission-prompts and more.

A subagent is a separate Claude instance with its own context window, its own system prompt, and optionally its own tools, model and permissions. The main session hands it a task; it reads, searches, runs things, and returns only a summary. The 40 files it read never enter your main context.

Claude uses built-in subagents on its own: Explore (read-only codebase search), Plan (research during plan mode) and general-purpose (explore + modify, multi-step). You can also ask: “use subagents to investigate how payments, auth and emails each handle retries.” Several can run in parallel.

.claude/agents/security-reviewer.md
---
name: security-reviewer
description: Reviews diffs for injection, authz and secret-handling bugs. Use after changes to auth or API code.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan        # read-only
memory: project             # keeps its own notes across sessions
---
You are a senior application security engineer. For each finding give file:line,
the exploit scenario, and the minimal fix. No style comments.

Other useful fields: skills (preload full skills), mcpServers, hooks, maxTurns, effort, isolation: worktree (work on its own copy of the repo), background: true. Put agents in .claude/agents/ (team) or ~/.claude/agents/ (you). The easiest way to write one: ask Claude to create it.

Everything so far is advice the model interprets. A hook is different: Claude Code itself runs your shell command (or HTTP call, MCP tool, prompt, or subagent) when a lifecycle event fires. It always runs. It can block actions, inject context, or just log. Configure hooks in settings.json; /hooks lets you browse them (read-only).

{
  "hooks": {
    "PreToolUse": [{ "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous.sh" }] }],
    "PostToolUse": [{ "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "npx prettier --write \"$(jq -r .tool_input.file_path)\"" }] }]
  }
}

The hook gets a JSON payload on stdin (tool name, input, session info). Exit code 0 = go on; exit code 2 = block, and stderr goes back as the reason (for PreToolUse, Claude reads it and adjusts). For finer control, print JSON with a decision.

MCP (Model Context Protocol) connects Claude to external systems as tools: GitHub, Sentry, Linear, Notion, your database, a browser. If you keep copying data from a browser tab into the chat, that system wants to be an MCP server.

# remote HTTP server (OAuth in /mcp)
claude mcp add --transport http notion https://mcp.notion.com/mcp
# local stdio server: everything after -- is the server command
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgresql://readonly:…@localhost:5432/app"
# share with the team via .mcp.json
claude mcp add --scope project --transport http sentry https://mcp.sentry.dev/mcp

MCP scopes override by name: local > project > user. Local and user servers are stored in ~/.claude.json; project servers in .mcp.json at the repo root, which teammates approve on first use. Never commit secrets there — use ${ENV_VAR} expansion.

Plugins are the packaging layer: one installable unit bundling skills, subagents, hooks, MCP servers (and LSP code-intelligence servers). Add a marketplace once, then install from it:

/plugin marketplace add your-org/claude-plugins
/plugin install commit-commands@claude-plugins-official
/plugin            # browse, enable, disable, choose scope

Once one session works well, the next bottleneck is you waiting. Claude Code has several ways to run more than one thing at once. The question that separates them: who holds the plan?

claude -p "prompt" runs one task non-interactively and prints the result. Everything you learned still applies — CLAUDE.md, skills, hooks, MCP — so it slots into scripts, pre-commit checks, and CI.

# one-off, pipe in, JSON out
git diff main | claude -p "review for bugs; reply as a list" --output-format json

# structured output validated against a schema (the root must be an object)
claude -p "list TODOs" --output-format json \
  --json-schema '{"type":"object","properties":{"todos":{"type":"array","items":{"type":"string"}}},"required":["todos"]}' \
  | jq '.structured_output'

# locked down for CI: listed tools + reads / read-only commands; anything that would prompt is denied
claude -p "run the tests and fix failures" \
  --permission-mode dontAsk --allowedTools "Read" "Edit" "Bash(npm test *)" \
  --max-turns 20 --max-budget-usd 5

# fan out over files
git ls-files -z 'src/*.js' | while IFS= read -r -d '' f; do   # git's * also matches across /
  claude -p "migrate $f from CommonJS to ESM, keep behavior" --allowedTools "Read" "Edit"