Reference · Canonical Language

Mastering Claude Code — Glossary

The working vocabulary for this course. Once a term lives here, every lesson uses this word for it. Grows as we go.

Plan First

Plan mode: A permission mode that blocks every file write and state-changing shell command, leaving the agent free to read, search, and analyse but unable to modify anything. It separates understanding from implementation so you catch a wrong approach in a plan, where the fix costs minutes, instead of in a broken diff. Activate with Shift+Tab, --permission-mode plan, or "defaultMode": "plan".; Source: plan-mode · Lesson: Plan Mode
Permission mode · the Shift+Tab cycle: The session-wide setting that decides how tool calls are gated — Normal, Auto-Accept (acceptEdits), Plan, and, where eligible, Auto and bypassPermissions. It is the top-level dial every other permission rule sits underneath; Shift+Tab cycles it mid-session and --permission-mode sets it at launch.; Source: plan-mode · Lesson: Plan Mode
Explore-plan-code loop · the four-phase workflow: The discipline of running Explore and Plan in read-only plan mode, then Implement in normal mode, then Verify — looping back to Plan when verification surfaces issues. Designing before coding turns a 30-second plan review into the cheapest place to correct course.; Avoid: "just implement it" on a multi-file change — the first viable approach often conflicts with existing patterns and costs more in rework than a plan would.; Source: plan-mode · Lesson: Plan Mode
Read-only exploration: The Explore phase done under plan mode's constraints: the agent maps the relevant files, functions, and dependencies without the ability to change them. The read-only floor forces it to ask questions and propose steps rather than run them, making its understanding visible before any commitment.; Source: plan-mode · Lesson: Plan Mode
Plan review checklist: The fixed set of questions you run a proposed plan through before approving: correct files identified, approach matches existing patterns, no scope creep, edge cases and error handling addressed, and tests accounted for. The checklist is what turns "looks fine" into a deliberate gate.; Source: plan-mode · Lesson: Plan Mode

Delegation & Teams

Sub-agent · child agent, delegated agent: An ephemeral agent that runs a focused task in its own fresh context window and returns only its final result to the parent. Defined as a Markdown file with YAML frontmatter (name, description, optional tools and model) or inline through the Agent SDK. Fire-and-forget delegation: the parent never sees the intermediate reasoning.; Avoid: a sub-agent for work that takes fewer tokens to do inline than to describe and delegate — the overhead loses.; Source: sub-agents · Lesson: Sub-Agents & Agent Teams
Context isolation: The structural property that a sub-agent sees only its prompt — no inherited conversation history, no parent reasoning, no sibling tool outputs. Enforced by the runtime, not by convention. It is what lets sub-agents run in parallel without coordination overhead, and the same boundary that makes a misbehaving sub-agent hard to debug.; Source: sub-agents · Lesson: Sub-Agents & Agent Teams
Agent team · team mode: An experimental mode where multiple full Claude Code sessions coordinate as a team — a shared task list, direct mailbox messaging, and a team lead. Unlike sub-agents, teammates talk to each other, share findings, and challenge each other. The cost is roughly one full context window per teammate, so a five-person team burns about five sessions' worth of tokens.; Avoid: a team for sequential work or same-file edits — without an up-front split of file ownership, parallel teammates race and destroy each other's work.; Source: agent-teams · Lesson: Sub-Agents & Agent Teams
Team lead: The one session in an agent team that assigns tasks from the shared list and synthesises the results. Leadership is fixed — it cannot be transferred, teammates cannot spawn their own teams, and team agents inherit the lead's model. Its unique signal is cross-task coherence the individual teammates cannot see.; Source: agent-teams · Lesson: Sub-Agents & Agent Teams
Tool restriction: Limiting which tools a sub-agent can call via its tools frontmatter, so a reviewer gets Read, Grep, and Glob and nothing that writes. Least privilege at the agent layer — the smallest blast radius is the one where dangerous tools are simply absent during the risky task.; Source: sub-agents · Lesson: Sub-Agents & Agent Teams

Watching the Work

Agent view · claude agents: One full-terminal screen for every background session, grouped by the attention each one needs (Pinned → Ready for review → Needs input → Working → Completed), with a dispatch input at the bottom and a peek panel for the selected row. It is the dispatch-attach-monitor surface that keeps you in the orchestrator role across N parallel sessions.; Avoid: agent view at concurrency ≤ 1 — a single session pays the dashboard round-trip without the scannability gain.; Source: agent-view · Lesson: Watching the Work
Needs input state: The first-class, elevated session state (yellow) for a session blocked on a specific question or permission decision. Because a blocked agent stops emitting tokens, blocked-on-input is otherwise a latent state; surfacing it as its own group turns finding the row that needs you from an O(N transcript-scan) into O(1).; Source: agent-view · Lesson: Watching the Work
Monitor tool: A tool that streams a background process's stdout to Claude line by line — each line arrives as a notification and Claude reacts mid-conversation, no polling loop. Session-scoped, uses the same permission rules as Bash, and forwards stdout only. Best for deploy logs, CI watchers, and test streams where events are rare and meaningful.; Avoid: pointing it at a chatty process (verbose test runner, webpack rebuild) — it floods context and Claude auto-stops it; filter through grep --line-buffered first.; Source: monitor-tool · Lesson: Watching the Work
Attach-and-detach: The one-key loop of agent view: Enter/→ attaches you to a session as if you had run claude in that directory, and ← on an empty prompt detaches back to the list. Detaching never stops a session — only /stop, Ctrl+X twice, or claude stop end it. The loop lets you drop into one conversation only when judgment is required.; Source: agent-view · Lesson: Watching the Work
Push vs poll: The contrast between Monitor (the process pushes each stdout line to Claude as a notification) and the older Bash run_in_background + Read pattern (the agent polls an output file). Push wins for zero-latency reaction to rare events; poll, or scheduled checks, win for low-cadence or silent-failure work where stderr and exit codes matter.; Source: monitor-tool · Lesson: Watching the Work

Hooks & the Lifecycle

Lifecycle event: One of the 25+ fixed points in Claude Code's request loop where a hook can fire — session, prompt, tool, subagent, task, compaction, worktree, config, and file-change phases. Hooks are deterministic precisely because the harness invokes them at these points, independent of the model's sampling.; Source: hooks-lifecycle · Lesson: Hooks & the Lifecycle
PreToolUse: The hook event that fires before a tool call is dispatched. Because the action has not yet run, a PreToolUse hook can block it — exit code 2 cancels the call and feeds the stderr message back to Claude as feedback. The right place for guardrails that must run before damage is possible.; Source: hooks-lifecycle · Lesson: Hooks & the Lifecycle
PostToolUse: The hook event that fires after a tool call succeeds, receiving tool_input.file_path on stdin for file-editing tools. It is a side-effect hook, not a gate — the file already exists, so it cannot block. The canonical home for auto-formatting and linting after every write.; Avoid: trying to block a write from PostToolUse — the write already happened; use PreToolUse for gating.; Source: hooks-lifecycle · posttooluse-auto-formatting · Lesson: Hooks & the Lifecycle
Matcher: The string that decides which instances of an event a hook handler runs for. "*" or empty matches everything; a plain name or pipe-separated list ("Write|Edit") matches exactly; anything else parses as a regex. What it filters depends on the event — tool name for PreToolUse/PostToolUse, session source for SessionStart, and so on. It filters tool name, never file path.; Source: hooks-lifecycle · Lesson: Hooks & the Lifecycle
Exit code 2: The hook return code that means "block and send feedback." For pre-action events (PreToolUse, PermissionRequest, UserPromptSubmit, Stop, config changes, and the team events TeammateIdle/TaskCreated/TaskCompleted) it cancels the action and pipes stderr back to Claude. For post-action and notification events the action has already run, so exit 2 only feeds stderr back without blocking.; Source: hooks-lifecycle · Lesson: Hooks & the Lifecycle

Permission Gating

Auto mode · classifier-based gating: A permission mode where a two-stage classifier (a fast single-token filter, then chain-of-thought reasoning only when the filter flags) evaluates each tool call — auto-approving safe operations and blocking destructive patterns. It fills the gap between rubber-stamped manual approval and --dangerously-skip-permissions: 0.4% false-positive rate on real traffic, but a probabilistic floor, not a deterministic one.; Avoid: trusting it as deterministic — the ~17% overeager rate lets roughly one in six unsanctioned destructive actions through on consent-scope misjudgment.; Source: auto-mode · Lesson: Permission Modes
hard_deny: The autoMode.hard_deny list — natural-language rules that block unconditionally inside the auto-mode classifier. Unlike soft_deny, neither an allow exception nor explicit user intent can lift a match. It is the inside-classifier floor: still LLM-interpreted, but un-arguable.; Source: hard-deny-classifier-rule · Lesson: Permission Modes
permissions.deny: The deterministic, pre-classifier deny layer — tool-pattern rules (Bash(rm -rf /*), WebFetch(domain:…), or parameter-scoped Tool(param:value)) evaluated with deny-first precedence before the classifier is consulted, and even when auto mode is off. Use it for tool-shaped, compliance-grade rules; use hard_deny for intent- or destination-shaped ones.; Source: hard-deny-classifier-rule · Lesson: Permission Modes
disallowed-tools: A skill (or slash-command) frontmatter field that removes the listed tools from the model's pool while the skill is active — the deny-side complement to allowed-tools. A removed tool cannot be seen, approved, or invoked, so it dominates allowed-tools for any overlapping tool. Subtract-only and turn-scoped: it clears on the next user message.; Avoid: treating it as a durable session lock — a follow-up prompt re-exposes the tool; for persistent denial use permission settings.; Source: skill-disallowed-tools · Lesson: Permission Modes
$defaults sentinel: The literal string "$defaults" that splices Anthropic's built-in rules into an autoMode list at that position. Omitting it replaces the entire default list — silently deleting the built-in data-exfiltration and bypass rules. The single most common auto-mode configuration mistake; print the built-ins with claude auto-mode defaults before you take ownership.; Source: hard-deny-classifier-rule · Lesson: Permission Modes
Channels permission relay · --channels: An MCP-server bridge that forwards a tool-use approval prompt from a running session to your phone (Telegram, Discord, iMessage) and resumes the moment you reply yes <id> or no <id>. It lets a long-running agent pause on ambiguous actions without blocking at the terminal; the local dialog stays open and whichever answer arrives first wins.; Avoid: treating a phone reply as equal to terminal access — the relay forwards only a tool name, a short description, and 200 chars of arguments, and the allowlist sender becomes a tool-approval path.; Source: channels-permission-relay · Lesson: Permission Modes

Managed Settings

Managed settings: The top, admin-owned tier of the settings hierarchy, delivered through a system-directory managed-settings.json (or MDM) that user and project settings cannot override. The layer where an organisation pins permission rules, deny lists, and policy that must hold regardless of what a developer or a checked-in repo sets.; Source: managed-settings-drop-in · Lesson: Managed Settings
Drop-in directory · managed-settings.d/: A .d/ directory beside managed-settings.json whose *.json fragments are parsed alphabetically and merged on top of the base, following the systemd drop-in convention. It lets each team (security, platform, product) deploy its own policy fragment independently — no shared file, no merge-conflict bottleneck. Use numeric prefixes to make merge order explicit.; Source: managed-settings-drop-in · Lesson: Managed Settings
allowManagedPermissionRulesOnly: The managed-settings flag that, when true, makes the merged managed permission rules the only ones that apply — user and project settings cannot add their own. The mechanism that turns a managed deny list from a default into a hard ceiling.; Source: managed-settings-drop-in · Lesson: Managed Settings
Server-managed settings: Policy delivered from the Claude.ai admin console rather than from on-device files. It occupies the same top tier as endpoint-managed (file-based) settings but does not merge with them: if server-managed delivers any non-empty config, Claude Code ignores all endpoint-managed settings, including managed-settings.d/ fragments. Pick one delivery channel per org.; Source: managed-settings-drop-in · Lesson: Managed Settings
Silent scalar conflict: The main hazard of drop-in fragments: when two fragments set the same scalar key, the alphabetically later file wins with no warning. Arrays concatenate and de-duplicate, objects deep-merge, but scalars overwrite quietly. The defence is to keep teams to non-overlapping settings domains.; Source: managed-settings-drop-in · Lesson: Managed Settings

Evaluating Skills

Eval-driven development: Treating a skill the way you treat code under test: define cases, run with-skill against a baseline, grade outputs against specific assertions, and iterate from the failures. It brings measurement to skill authoring without writing test harness code — you often cannot define "good" until you see what the first run produces.; Source: skill-eval-loop · Lesson: The Skill Eval Loop
Trigger precision: The second, independent failure axis of a skill: does it activate at the right time? Tuned with a query set of 8–10 should-trigger phrasings and 8–10 should-not-trigger near-misses, scoring the description against both to cut false positives and false negatives. Output quality only matters if the skill fires.; Source: skill-eval-loop · Lesson: The Skill Eval Loop
Comparator agent · blind A/B: A grader that receives the A and B outputs unlabelled and scores each criterion without knowing which is which. It removes the anchoring bias of sequential evaluation, where the second version is judged relative to the first. Extends to comparing versions, competing skills, or the same skill across models.; Source: skill-eval-loop · Lesson: The Skill Eval Loop
Benchmark delta: The per-configuration difference the eval loop reports across three metrics — pass rate, time, and tokens. It quantifies a skill's cost against its benefit: a 13-second overhead for a 50-point pass-rate gain is a very different trade than doubling tokens for two points.; Source: skill-eval-loop · Lesson: The Skill Eval Loop

Building Plugins

Reload-skills mid-session · /reload-skills: Re-scanning skill directories inside a running session — via /reload-skills or a SessionStart hook returning reloadSkills: true — so edited or newly installed skills go live without a restart. It decouples cheap capability discovery from expensive context accumulation, collapsing the authoring loop to edit → reload → test while the transcript, loaded files, and task list survive.; Avoid: relying on it when you need the skill reachable by name from the command line — the / parser index isn't rebuilt until a full restart.; Source: reload-skills-mid-session · Lesson: Building Plugins
skills-dir plugin · <name>@skills-dir: Any folder under a skills directory that contains a .claude-plugin/plugin.json manifest. Since v2.1.157 it auto-loads as <name>@skills-dir with no marketplace — discovered in place, not copied into the plugin cache. The unit to reach for when a bundle includes components beyond a single skill, or versioning and distribution matter.; Source: local-plugin-scaffolding · Lesson: Building Plugins
claude plugin init: The command (alias claude plugin new) that scaffolds a skills-directory plugin in one step — a .claude-plugin/plugin.json manifest and starter SKILL.md, with author defaults pulled from git config. --with hooks|agents|mcp|lsp|… adds starter folders for extra components. It removes both the scaffold ceremony and the marketplace round-trip.; Source: local-plugin-scaffolding · Lesson: Building Plugins
monitors manifest key: A top-level monitors key in a plugin manifest (or monitors/monitors.json) declaring background watchers the harness arms automatically — at session start (when: "always") or on first skill invoke. It moves "did the agent remember to arm the watcher?" out of model reasoning and into the harness; consumers install once and every session is supervised.; Source: plugin-background-monitors · Lesson: Building Plugins
Plugin scope · personal vs project: Where a skills-directory plugin lives, which decides who sees it and what it may do. Personal (~/.claude/skills/) loads in every project with no restrictions; project (<cwd>/.claude/skills/) loads only after the workspace trust dialog, and because its content ships with the repo, MCP and LSP servers face extra approval and background monitors do not load at all.; Source: local-plugin-scaffolding · Lesson: Building Plugins
Background monitor: A persistent background process whose stdout becomes notifications to Claude for the lifetime of a session. Plugin-declared monitors auto-arm; the Monitor tool starts one imperatively. Both are session-scoped, unsandboxed at hook trust level, and forward stdout only — not a substitute for systemd or cron when cross-session or reboot-surviving enforcement is the goal.; Avoid: treating a marketplace-supplied monitor as safe — it runs arbitrary shell at hook trust; vet it like any installed script.; Source: plugin-background-monitors · Lesson: Building Plugins

Worktrees & Monorepos

Git worktree: A second working directory that shares one repository's object database while keeping its own HEAD, branch, index, and checkout. Parallel edits cannot collide on disk, yet all commits stay visible from the main history. The isolation primitive that backs every background and --worktree session; EnterWorktree/ExitWorktree manage one mid-conversation.; Source: batch-worktrees · Lesson: Parallel Worktrees & Monorepos
/batch: A bundled skill that decomposes a large change into 5–30 independent units, presents the plan for approval, then spawns one background agent per unit — each in its own worktree, each implementing, testing, and opening a pull request. Parallel execution at scale.; Avoid: /batch when the units aren't truly independent or review throughput is the bottleneck — twelve small PRs cost more attention than one, and coupled slices race on merge.; Source: batch-worktrees · Lesson: Parallel Worktrees & Monorepos
worktree.sparsePaths: The setting that restricts a --worktree checkout to a list of monorepo subtrees — only those directories are written to disk. Files outside the cone are not present, so the agent cannot read, glob, or write them. The scope constraint is enforced by the filesystem, not the agent: it cannot widen its own view.; Avoid: a narrow cone for cross-service work — any read or write outside the declared paths fails; recreate the worktree with wider paths.; Source: sparse-paths-monorepo-isolation · Lesson: Parallel Worktrees & Monorepos
Sparse-checkout cone mode: The git mechanism (git sparse-checkout set --cone) that worktree.sparsePaths runs under the hood. Cone mode writes only the listed directories and their parents to disk, trading repo-wide visibility for a smaller, faster, lower-noise working tree.; Source: sparse-paths-monorepo-isolation · Lesson: Parallel Worktrees & Monorepos
symlinkDirectories: The companion worktree setting that symlinks large shared directories — node_modules, .cache — from the main repo into each worktree instead of copying them. It keeps fan-out cheap on disk and avoids re-installing dependencies per worktree.; Source: sparse-paths-monorepo-isolation · Lesson: Parallel Worktrees & Monorepos

Scheduling Across Time

Session scheduling · /loop, CronCreate: Re-running a prompt automatically within an active session — /loop for interactive recurring prompts, the CronCreate/CronList/CronDelete tools for programmatic control, or a natural-language one-time reminder. Session-scoped and minute-granular: closing the terminal cancels everything, and recurring tasks expire seven days after creation.; Avoid: treating it as durable infrastructure — for schedules that survive a restart, reach for a cloud routine, a desktop task, or a GitHub Actions trigger.; Source: session-scheduling · Lesson: Scheduling & Cloud Routines
Cloud routine · /schedule: A saved Claude Code configuration — prompt, repos, connectors, environment — that runs on Anthropic-managed infrastructure on a schedule, API call, or GitHub event. It fixes the host-uptime and env-drift failures of local scheduling at the cost of working-tree fidelity, mid-run approval, and sub-hour cadence (the floor is one hour).; Source: cloud-scheduled-routines · Lesson: Scheduling & Cloud Routines
Default branch clone: The defining constraint of a cloud routine: each run clones the repo fresh from the default branch, so in-flight feature work is invisible unless the prompt checks it out. A scheduled audit that reads a file from main never sees the unmerged edit on your branch — the cloud snapshot is the default branch at clone time.; Source: cloud-scheduled-routines · Lesson: Scheduling & Cloud Routines
Identity collapse: The intrinsic risk that a cloud routine acts as its creator on every connector and on GitHub — so commits, PRs, Slack messages, and tickets all carry one person's name. It concentrates attribution, departure risk, and credential exposure into a single point. Not a bug to fix but a property to plan around: trim the connector list and keep branch-push restrictions.; Source: cloud-scheduled-routines · Lesson: Scheduling & Cloud Routines

Choosing & Composing

Decision table · extension-point selection: The framework for picking the right extension point — CLAUDE.md, .claude/rules/, skills, hooks, sub-agents, MCP servers, agent teams, or plugins — by enforcement need, context cost, and portability. The load-bearing split is deterministic (hooks, run at the infrastructure layer, the model cannot skip them) versus probabilistic (anything routed through model reasoning).; Source: extension-points · Lesson: The Claude Code Decision Table
Lethal trifecta: The threat condition where one agent holds all three of: access to private data, exposure to untrusted input, and an egress path. Any unattended run that combines them — a routine with a private-data connector, a web-fetch or issue-body input, and a push or Slack connector — lets an injected instruction produce an immediate exfiltration with no human in the loop to interrupt it.; Avoid: closing the trifecta in an autonomous run — break one leg (drop the connector, sandbox the input, or remove egress) rather than relying on the model to resist.; Source: cloud-scheduled-routines · Lesson: The Claude Code Decision Table
Agent SDK: The Claude Code runtime packaged as a library (@anthropic-ai/claude-agent-sdk, claude_agent_sdk). Its core is query(), an async generator of typed messages running the same agent loop as the CLI, with the same instructions, skills, hooks, permissions, and sub-agents. Use it to embed an agent in CI, internal tools, or products.; Avoid: shipping production runs without maxTurns and max_budget_usd set — both default to unlimited, so an agent can loop and burn cost with no circuit breaker.; Source: agent-sdk · Lesson: The Claude Code Decision Table
Bare mode · --bare: The flag that strips Claude Code to its core tools (Bash, file read, file edit) and skips all local configuration discovery — hooks, MCP servers, skills, plugins, auto-memory, and CLAUDE.md. The recommended mode for scripted and CI calls: behaviour is reproducible across machines because only the flags you pass take effect, and it is ~14% faster to first API request.; Avoid: assuming a bare run honours repo conventions — project CLAUDE.md doesn't load, so re-inject it with --append-system-prompt-file if the task needs it.; Source: bare-mode · Lesson: The Claude Code Decision Table
Dynamic workflow: A JavaScript script Claude writes and a background runtime executes to orchestrate sub-agents at scale — the loop, branching, and intermediate results live in script variables, so the orchestrator's context holds only the final answer. The decision axis is who holds the plan: Claude turn-by-turn (sub-agents, skills) versus the script. Scales to up to 1,000 agents per run and is itself repeatable.; Avoid: a workflow for linear work one conversation can hold — it earns its cost only when scale or repeatability is the point.; Source: dynamic-workflows · Lesson: The Claude Code Decision Table
settingSources: The Agent SDK option controlling which filesystem locations the agent reads — "user", "project", "local" — and therefore whether CLAUDE.md, skills, and hooks load. The omit-default has flipped between releases, so set it explicitly: [] for full isolation, ["user","project","local"] for CLI parity.; Source: agent-sdk · Lesson: The Claude Code Decision Table