Every key term, and the misconception it corrects
744 terms, aggregated from the Key Terms table of every lesson. The middle column is the point: it names the wrong intuition in the same breath as the definition.
Phase 00 — Setup & Tooling
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
| working directory | "the project folder" | One specific folder a command runs in. Not a default. Not negotiable per command. | 1 |
| repo root | "wherever I ran git init" | The top folder of the repo, found with git rev-parse --show-toplevel. Subfolders are inside it but are not it. | 1 |
| git config | "git settings" | Identity and defaults, stored per-machine globally and per-repo locally. Without identity, commits fail. | 1 |
| prompt | "the thing with the cursor" | The text your shell prints before each command. Make it carry path and branch, and you stop needing to check. | 1 |
| Working tree | "The folder where my code is." | The files on disk right now, as your editor sees them. Uncommitted changes live here and only here. | 2 |
| Staging area | "A place to review changes before committing." | A snapshot of selected working-tree files, prepared for the next commit. The staging area is not a backup — it is a holding pen. | 2 |
| Local repository | "Where commits are stored." | A database on your machine that records every commit. This is the safety net. Once a change is committed, it is recoverable until you delete the .git directory. | 2 |
| Remote | "Where I push code so others can see it." | A copy of your repository on another machine. For solo AI-agent work, the remote is insurance against losing your laptop, not a way to collaborate. | 2 |
| Commit | "A saved change." | A snapshot of specific files at a specific moment, with a message describing why. Commits are the unit of recovery. | 2 |
git restore | "Undo." | Reverts a working-tree file to its state at the last commit. Use it when an agent — or you — has wrecked something and you want the last known-good version. | 2 |
| shell | "the terminal" | The program that interprets what you type. The terminal is the window; the shell is what runs inside it. | 3 |
| command | "a line of code" | One verb the shell runs, with arguments after it. grep -rn "x" src/ is one command, not five. | 3 |
redirect > | "save output" | Overwrite the file on the right with the left side's output. If the file existed, it is gone. | 3 |
redirect >> | "append output" | Add to the end of the file. The old contents survive. | 3 |
| flag | "option", "switch" | A single-letter or single-word argument after the verb that changes its behaviour. -r in rm -rf means recursive; -f means no confirmation. | 3 |
| working directory | "the project folder" | One specific folder a command runs in. The agent inherits yours; if it cds, it does so only inside its own tool call. | 3 |
| Format-on-save | The editor pipes the file through a formatter every time you save | Some people treat formatting as a manual chore, or as "what the agent should remember." It is neither. The editor does it, invisibly, every save — and with an agent in the loop, "what the agent should remember" is the worst possible plan. | 4 |
| Integrated terminal | A shell pane inside the editor window, sharing its working directory | People think of terminals as separate apps. With agents, you spend half your time in shell and half reading code. A switch costs attention, not seconds, and attention is what you are trying to spend on the change. | 4 |
| Project-wide search | A single-keystroke regex search across every file in the project, with a jumpable hit list | People confuse it with "find in current file." Current-file search finds text. Project-wide search finds code — including hits in files you did not know mattered. With agents, you almost always want the latter. | 4 |
| Test runner | A program that runs the project's tests and reports pass/fail per file or per case, bound to one key | People treat tests as something you "remember to run." A test runner bound to one key is the difference between remembering and not — and between verifying and trusting the agent's word. | 4 |
| Save | A signal to the editor that the buffer is ready, plus a trigger for hooks like formatters and linters | Save is no longer just "write the file to disk." In an agent workflow, save is the moment the diff stops being dirty, the formatter runs, and you cross from "agent is still typing" to "agent is done, and you can review." | 4 |
Phase 01 — Foundations of AI
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
| hallucination | "it made something up" | Correct. It produced the most plausible continuation given its input. Plausibility was the training objective; truth was never a term in the loss. | 6 |
| weights | "the learned knowledge" | Enormous learned numbers encoding statistical regularities of text. Not a database, not searchable, not inspectable as facts. | 6 |
| training data | "what it knows" | Text it was fitted on. It cannot cite it, cannot check whether it is still current, and has no access to your repo. | 6 |
| temperature | "creativity" | How flat or peaked the next-piece distribution is. Low is repetitive, high is scattered. Introduced properly in Lesson 9. | 6 |
| confident | "it's sure" | The writing, not the model. Tone is generated, never calibrated. | 6 |
| ground truth | "the right answer" | Whatever you can verify independently — a file, a test, a doc. The model is not a source of it. | 6 |
| token | "a word" | A sub-word unit from a trained tokenizer. Roughly four English characters, but a split point inside a word, so length in characters does not predict it reliably. | 7 |
| tokenizer | "the splitter" | The trained program producing those units. Each model family has its own, which is why token counts are not portable across models. | 7 |
| input tokens | "the prompt" | Everything sent, including conversation history, file contents, tool definitions, and system instructions — not just what you typed. | 7 |
| output tokens | "the reply" | What the model generated, including thinking where extended thinking is on. | 7 |
| context | "the chat" | The full body of text the model sees on the next turn. Grows with every message, read, and tool result. | 7 |
| re-send | "it remembers" | The entire conversation is transmitted again on every request. Long sessions tax each new message. | 7 |
| context window | "the chat history" | Every token the model sees next turn: instructions, tool definitions, files, command output, and the conversation. One budget for all of it. | 8 |
| context | "what it remembers" | The whole re-sent body. It is re-transmitted, not recalled from a store. | 8 |
| compaction | "it forgot" | Automatic or manual summarization of older history to make room. Loses detail by design. | 8 |
| survives compaction | "it's still in context" | Depends on how it got there. Files and root instructions are re-read; the middle of the conversation is not. | 8 |
/clear | "new chat" | Empty window, new conversation. /resume reopens a cleared one. | 8 |
| window size | "how much it can hold" | A per-model, sometimes per-configuration number. Move it and you break this lesson — check /context and the docs. | 8 |
| prompt | "what I typed" | The whole assembled input: your text, system instructions, tool definitions, project files, and all history. | 9 |
| inference | "the model thinking" | One forward run producing output from input. The only thing you pay for. | 9 |
| training | "when it learns" | Fitting the weights, offline, before you ever prompted. Not something you trigger. | 9 |
| API | "the model" | A network interface with a request, a response, and token counts. Something can break at either end. | 9 |
| temperature | "how creative it is" | How much the sampling distribution is flattened. Low is repeatable, high is varied. | 9 |
| max output tokens | "the length cap" | The ceiling on one response. Hitting it truncates mid-answer. | 9 |
| system prompt | "its instructions" | Harness-supplied behaviour rules, injected every request. Not yours, and often larger than yours. | 9 |
| agentic | "it's autonomous" / "it's smart" | A loop: model decides, tool executes, result returns, model decides again. No magic adjective. | 10 |
| agentic loop | "the magic" | That repeat. Gather context, take action, verify, repeat until done. | 10 |
| harness | "the CLI" | The layer around the model: tools, context management, permissions, the loop itself. | 10 |
| tool | "the agent's hands" | A named action the model can request. Every tool result becomes the next input. | 10 |
| tool result | "the output" | New information fed back in. An empty or wrong result corrupts every step after it. | 10 |
| verification | "it checked" | Running something capable of detecting the problem. Most self-checks cannot. | 10 |
| surface | "it should have known" | The set of tools available. Missing a tool looks exactly like missing capability. | 10 |
| checkpoint / rewind | "undo" | Harness-level restore of file contents, separate from git. Does not cover actions against remote systems. | 10 |
| latency | "the model is slow" | Wall time per turn: many network round trips plus generation. Usually round trips, not thinking. | 11 |
| round trip | "a step" | One request to the model and back. Each one re-sends context. Cost and latency both scale with the count. | 11 |
| rate limit | "quota" | The provider's ceiling. Requests are refused or queued; nothing you write changes it. | 11 |
| prompt cache | "it remembered" | Previously-processed content served at a reduced rate. Expires on a TTL, then costs full price again. | 11 |
| cache read | "free" | Reduced-rate reuse. High proportions mean efficient work; misses mean something invalidated. | 11 |
| tokens per million | "the price" | Unit pricing for input and output. Changes — read it live, never from memory. | 11 |
/usage | "the bill" | Session cost, plan limits, and a usage breakdown. Estimated from token counts, not an invoice. | 11 |
Phase 02 — Git Deep
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
| commit | "saving my changes" | A frozen full tree with a message and a parent. Content-addressed. | 12 |
| diff | "the commit" | The difference between two trees. Useful to read; never what is stored. | 12 |
| staging area / index | "the thing before the commit" | A draft tree. git add edits the draft; git commit freezes it. | 12 |
git add -p | "partial staging" | Choose change-by-change inside one file instead of all or nothing. | 12 |
| commit hash | "the commit id" | A digest of the commit's contents. Change any byte, including the message, and it changes. | 12 |
--amend | "fixing the last commit" | Replaces the last commit. Fine locally, disruptive once pushed. | 12 |
git revert | "undo" | New commit that undoes an old one. History stays honest. | 12 |
| branch | "a copy of the project" | A file containing one commit hash. Creating it copies nothing. | 13 |
| HEAD | "my current branch" | A label that usually points at a branch. Points at a commit directly = detached HEAD. | 13 |
| detached HEAD | "broken git" | HEAD points straight at a commit. Valid, but commits made here are only reachable via reflog. | 13 |
git branch -d | "delete a branch" | Deletes the label. Refuses if the branch holds unmerged commits. | 13 |
git branch -D | "force delete" | Deletes the label anyway. Commits survive until garbage collection, then may not. | 13 |
| reflog | "undo for branches" | Local record of every HEAD and branch move. Your first stop when a branch "disappeared". | 13 |
git switch | "checkout but better" | Moves between branches only. restore handles files. | 13 |
| merge | "joining branches" | Combine two lines and record the join. Adds a merge commit with two parents when needed. | 14 |
| rebase | "cleaning up history" | Replay your commits on another base. New hashes, same changes. Safe only on history nobody else has. | 14 |
| fast-forward | "a merge" | A merge where one line has no new commits, so the label just slides. No merge commit. | 14 |
| merge commit | "the merge" | A commit with two parents. The explicit record that two lines joined. | 14 |
git pull | "getting the latest" | fetch plus a merge or rebase you did not choose. Use --rebase / --no-rebase. | 14 |
| rebasing shared history | "fixing the branch" | Produces two incompatible versions of the same commits. Every later merge sees the change twice. | 14 |
git rebase --abort | "undo" | Bails out of an in-progress rebase. Nothing was committed yet. | 14 |
| conflict | "git broke my file" | Both sides changed a region and git declined to guess. The markers are the question. | 15 |
ours | "my change" | The branch you are on right now. Not "the change I like". | 15 |
theirs | "their change" | The branch you merged in. Reversed during a rebase. | 15 |
| resolved | "the markers are gone" | The file has been git added. Until then the merge cannot complete. | 15 |
| unmerged path | "broken file" | A path git still considers unresolved. git status names them. | 15 |
| merge driver | "smart merge" | Configured handling for files that should never need human resolution. | 15 |
git merge --abort | "start over" | Returns to the pre-merge state. Only while the merge is in progress. | 15 |
| recovery | "undoing my mistake" | Moving a label back. The commits were never deleted. | 16 |
reset --soft / --mixed | "soft reset" | Moves the branch; keeps your working tree. Safe. | 16 |
reset --hard | "starting over" | Moves the branch and overwrites tracked files. The only command here that can destroy uncommitted work. | 16 |
git revert | "undo" | A new commit that undoes an old one. Correct on shared history. | 16 |
| reflog | "undo for git" | Every position each label has held, in order. HEAD@{n} indexes it. | 16 |
ORIG_HEAD | "the backup" | Where HEAD was before the last merge or reset. | 16 |
| garbage collection | "cleanup" | When unreachable objects are actually reclaimed. Gives "recoverable" a shelf life. | 16 |
| untracked file | "my file" | Not in git's object store. reset --hard will not delete it; git clean will. | 16 |
| stash | "hiding my work" | A commit on a hidden branch holding uncommitted changes. Restorable, and subject to gc. | 17 |
git stash -u | "stash" | The variant that also takes files never added to git. The plain one skips them. | 17 |
pop vs apply | "the same" | pop restores and deletes the entry; apply keeps it. Keep it when the restore conflicted. | 17 |
| working tree | "my files" | The live folder. The only place uncommitted work exists, and the only thing reset --hard can destroy. | 17 |
| destructive delete | "the agent cleaned up" | An agent removed a file it never read. Cheap to undo if committed. | 17 |
| thrash | "it iterated" | Multiple rewrites of one file in a turn. Only the diff shows whether it improved. | 17 |
| scope creep | "it helped while it was there" | Changes outside the ask. git status is the only reliable detector. | 17 |
| remote | "the copy on GitHub" | A label for a URL. Git does not sync to it automatically. | 18 |
origin | "the remote" | The conventional name for the one you cloned from. Renameable. | 18 |
upstream | "the original" | The conventional name for the original when you cloned a fork. | 18 |
origin/main | "main on the server" | Your cached record of it, from your last fetch. Can be stale. | 18 |
git fetch | "getting updates" | Updates the record only. Never touches your tree or branches. | 18 |
git pull | "getting updates" | fetch + a merge or rebase you did not choose. | 18 |
| fork | "a copy I made" | A server-side copy of someone's repo, so you have push access. | 18 |
| pull request | "a git merge" | A review request on the hosting platform. The merge itself is a git operation. | 18 |
--force-with-lease | "safe force push" | Force-push that refuses if the remote moved since your last fetch. | 18 |
Phase 03 — Models & Families
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
| Open-weight | "Open source AI" | The weights are a downloadable file. The training data and code may not be public. "Open weight" and "open source" are not synonyms. | 19 |
| Frontier | "The biggest model" | The model with the best capabilities at a given time, typically large and run by a major lab. Size correlates, but the defining trait is capability leadership, not parameter count. | 19 |
| Weights | "The brain of the model" | The millions or billions of numeric parameters learned during training. Public weights mean anyone can run the model. | 19 |
| Fine-tune | "Train the model again" | Continue training a downloaded model on your own data so it behaves the way you want. Only possible with open-weight models. | 19 |
| Quantized | "Compressed model" | The weights stored at lower precision (e.g. 4-bit instead of 16-bit) so the model fits in less memory. Slight quality loss for a big size drop. | 19 |
| alias | "a shortcut" | A name for a family and a job that resolves to the current model on your provider. Survives version bumps. | 20 |
| model ID | "the model name" | One exact version, frozen in time. Correct to reproduce a run; rots as a default. | 20 |
| resolution | "it just picks one" | Alias → provider → concrete model. The provider decides, and it can differ between providers. | 20 |
default | "the default model" | A special value that clears an override and returns you to your account's runtime default. It is not a family. | 20 |
opusplan | "Opus for everything" | Opus in plan mode, Sonnet in execution. Two models, one session, two caches (Lesson 22). | 20 |
| pin | "hardcoding" | Naming a specific version deliberately. Legitimate with a written reason; a bug without one. | 20 |
| effort level | "how smart it is" | How much adaptive reasoning the model is willing to spend, decided per step. A cost dial, not an intelligence dial. | 21 |
| adaptive reasoning | "thinking" | The model deciding, step by step, whether thinking is worth it. Effort sets the appetite; the step decides. | 21 |
| extended thinking | "the reasoning" | The tokens the model emits before its answer, billed as output. Visible with Ctrl+O. | 21 |
| thinking tokens | "free scratchpad" | Output tokens like any other. You pay for thinking even when it is collapsed or redacted. | 21 |
ultrathink | "a magic word" | A keyword that requests deeper reasoning for one turn without moving the session's level. | 21 |
max | "the best setting" | The deepest level, session-only unless set through the environment. Prone to overthinking; test it before adopting it. | 21 |
| prompt cache | "it remembered" | Server-side reuse of a request prefix you recently sent. Not memory between turns. | 22 |
| prefix | "the start" | The exact beginning of the request matched against the cache. A change anywhere in it recomputes everything after. | 22 |
| cache read | "free" | Reduced-rate reuse of cached tokens. High read-to-write means caching is working. | 22 |
| cache write (creation) | "the miss" | Tokens written into the cache on this turn, at the cache-write rate. High every turn means your prefix keeps changing. | 22 |
| invalidation | "cold cache" | The prefix no longer matches, so the next turn reprocesses the whole request and writes a new cache entry. | 22 |
| TTL | "how long it lasts" | The idle period the cache survives. Every hit resets it; a long gap means the next turn can miss. | 22 |
| quantization | "compressing the model" | Storing the same weights at lower precision. Smaller and faster, knowledge unchanged, slight quality loss. | 23 |
| precision / bit-width | "how many bits" | How many bits store each weight. Eight, four, and smaller are common; lower means smaller and a little lossier. | 23 |
| distillation | "shrinking the model" | Training a small student to imitate a large teacher's outputs. A new, smaller model with the teacher's behaviour on covered inputs. | 23 |
| teacher / student | "the big one and the little one" | The capable model producing training targets, and the small model learning from them. | 23 |
| fine-tuning | "training it more" | Continuing training on your own data so the model picks up your domain. Needs the weights, and a check set. | 23 |
| check set | "the tests" | Held-out examples with known good answers, scored before and after, so you can tell improvement from drift. | 23 |
| confidently wrong | "hallucinating" | A fluent, wrong answer. The failure mode fine-tuning can amplify, because it learns your data's errors too. | 23 |
| SLM | "a weak model" | A small language model, roughly hundreds of millions to a few billion parameters. Weak at open-ended reasoning; often enough for a narrow task. | 24 |
| parameter count | "how big it is" | The number of learned weights. A description, not a definition of capability (Lesson 19). | 24 |
| narrow task | "simple task" | A task with a small, fixed set of correct answers. Narrow is about the output space, not the difficulty of the input. | 24 |
| throughput | "how fast" | Calls handled per unit time, locally and without a network round trip. Why small models win at volume. | 24 |
| crossover | "the break-even" | The volume at which a per-call cost difference outweighs an accuracy difference. It is arithmetic, not taste. | 24 |
| confidently wrong | "hallucinating" | Fluent and incorrect. The failure a small model hits hardest when the task is open-ended and unchecked. | 24 |
| decision model | "a classifier" | A model built to return a label, score, or choice rather than open-ended text. Small, fast, cheap. | 25 |
| generation model | "the chatbot" | A model that produces open-ended text. Right for writing, wasteful for a yes/no. | 25 |
| decision call | "a simple call" | A call whose answer is one of a fixed set. Cost is dominated by the output you did not need. | 25 |
| label set | "the options" | The fixed choices a decision can return. A small, closed set is what makes a small model viable. | 25 |
| output tokens | "the reply" | What the model generated. The cost driver when a decision is answered with a paragraph. | 25 |
| confidence gate | "escalate when unsure" | Sending only the uncertain decisions to a bigger model. Phase 14 builds this; here you only need the pattern. | 25 |
| LLM | "the model" | A large language model. A size description; says nothing about output shape or where it runs. | 26 |
| SLM | "the weak one" | A small language model. A size band, mostly on the open-weight side, most useful for narrow decisions. | 26 |
| decision model | "a classifier" | A model that returns a label or choice. An output-shape category, independent of size. | 26 |
| generation | "talking to the model" | Open-ended text output. The category that needs a larger, broader model to do well. | 26 |
| open-weight | "you can download it" | The weights are public, so you run it yourself (Lesson 19). A serving category. | 26 |
| frontier | "the best model" | The most capable model at a given time, hosted for you. A serving category, and it moves. | 26 |
| output shape | "the answer type" | Label versus open-ended text. The axis that decides which model to use. | 26 |
| routing | "picking a model" | Choosing a tier per call from task shape, and defending the choice. | 26 |
Phase 04 — Claude Code
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
| "Chatbot" | A program you talk to in turns, one prompt at a time | Claude Code looks like a chatbot in the terminal, but it is shaped for goals, not turns. Calling it a chatbot trains you to use it like a chat box. | 27 |
| "AI assistant" | The assistant is you; the tool is the thing doing the work | When you call it an assistant, you picture yourself giving instructions. When you call it a tool, you picture yourself choosing when to use it. Different verb shapes the work. | 27 |
| "Agent" (here) | A program that takes a goal, picks its own steps, and uses tools to make progress | In casual use "agent" means any AI that acts. In this course it means specifically: it decides what to do next, you approve. That distinction is the whole point of Phase 04. | 27 |
| "Completion" | The model finishes the text you started | Chat interfaces are completion-shaped. You write, it writes. Claude Code is goal-shaped. You describe the destination, it picks the route. | 27 |
| "Terminal tool" | A program you launch from a shell, that runs with your project's files and permissions | Some "AI tools" are websites that look technical. A terminal tool can actually touch the project you are in. That is the affordance none of the others have. | 27 |
Phase 05 — Commands & Skills
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
| slash command | "a shortcut" | Any entry invoked by typing /name. One surface, two mechanisms. | 38 |
| built-in command | "a command" | Fixed logic the harness runs. Same input, same result. | 38 |
| bundled skill | "a command" | Prompt-based: instructions the model follows using its tools. | 38 |
| invocation | "running the command" | Putting the slash-name at the start of a message. Mid-sentence is not invocation. | 38 |
| alias | "the other name" | A second name for one entry, e.g. /review for /code-review. | 38 |
| "it doesn't exist" | "it's broken" | Usually it was never a name. Open the menu and read. | 38 |
| merged | "slash commands are gone" | They produce the same command. Legacy files still work; skills are the direction. | 39 |
| legacy command | "the old format" | A single .md in .claude/commands/. Works. Loses name and paths. | 39 |
| skill | "the new format" | A directory with a SKILL.md. Same invocation, plus a folder to put things in. | 39 |
| soft migration | "it's deprecated" | Backward compatible, with a preferred direction. No removal date. | 39 |
| automatic invocation | "the model finds it" | Skills only, matched against description. Command files wait for your slash. | 39 |
| skill | "a plugin" | A directory with SKILL.md. No plugin, no manifest, no install step. | 40 |
| listing | "loading the skill" | Name + description, present in every session whether or not you use it. | 40 |
| body | "the skill" | The SKILL.md markdown. Loads on invocation only. | 40 |
| supporting file | "an attachment" | Any file in the skill folder, loaded only if the body points at it. | 40 |
| invoked | "called" | Slash-name at the start of a message, or Claude deciding the description matches. | 40 |
| "it didn't trigger" | "it's broken" | Often the description doesn't contain the words a human would say. | 40 |
| frontmatter | "metadata" / "the YAML header" | The only text read before the decision to load. It is a contract, not a label. | 41 |
description | "a summary" | The match target. Needs the words a human would type. | 41 |
| 1,536-character cap | "it's too long" | Per-entry truncation of description + when_to_use in the listing. | 41 |
| silent failure | "it's broken" | Two different causes, one appearance. --debug is the only way to tell. | 41 |
| refused name | "bad skill" | A character in the name Claude Code will not accept. [names] in the debug log. | 41 |
inherit | "use the session model" | The literal value that means "don't override". | 41 |
disable-model-invocation | "don't auto-run" | Claude can't pick it. You can still type it. Also drops the description from the listing. | 42 |
user-invocable | "hidden" | You can't type it. Claude still can. | 42 |
| manual only | "user-invocable: true" | Cell 2 — the disable-model-invocation side. The default for user-invocable is true. | 42 |
| background only | "auto-only" | Cell 3 — reference knowledge Claude absorbs. | 42 |
| preloaded into subagents | "it works everywhere" | Cell 2 skills are explicitly excluded. Phase 06. | 42 |
/apps/web:deploy | "a weird command" | Name collision handling: the path is prefixed to the command. | 42 |
| install | "adding a plugin" | Copying a folder to a documented path. No install step. | 43 |
| personal scope | "global" | ~/.claude/skills/. This machine, this user. Not cloud. | 43 |
| project scope | "repo" | .claude/skills/, committed. What teammates get. | 43 |
| "it's not showing up" | "the install failed" | Four different causes, four different commands. Ask /skills first. | 43 |
.trash/ | "it deleted my skills" | Swept to a timestamped subfolder, recoverable until the retention sweep. | 43 |
claude plugin validate | "the linter" | Finds SKILL.md files whose frontmatter doesn't parse. v2.1.233+. | 43 |
SKILL.md | "the prompt file" | YAML frontmatter, then markdown. One message, kept in the conversation. | 44 |
| standing instruction | "a rule" | Wording that applies for the whole task. The opposite of a step. | 44 |
$ARGUMENTS | "the input" | The raw argument string. $1, $2 are positional. | 44 |
` !cmd ` | "an include" | Runs at invoke time. Output enters the conversation now, not when you wrote it. | 44 |
| supporting file | "an attachment" | Loads only if the body points at it. The cheapest way to hold detail. | 44 |
| first 5,000 tokens | "it got truncated" | Per-skill re-attach budget after compaction. Put the important rule first. | 44 |
| prompt vs hook | "the skill should enforce this" | A prompt asks. A hook enforces. Different phases. | 44 |
Phase 06 — Subagents
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
| subagent | "a second Claude" | A separate agentic loop with its own window, its own tool list, its own model. It returns a summary. | 45 |
| delegation message | "the prompt you gave it" | Written by Claude from your request and the agent's description. You usually don't write it. | 45 |
| body | "the prompt" | Markdown after the frontmatter. It replaces the Claude Code system prompt for that agent. | 45 |
description | "documentation" | The routing input. Read before the decision to delegate. | 45 |
tools | "permissions" | The pool. Not in the list, not callable. Distinct from your permission settings. | 45 |
disallowedTools | "a blacklist" | Applied first; tools resolves against what's left. | 45 |
| silent failure | "it's a bug" | Unrecognized frontmatter fields are ignored with no warning. Check spelling first. | 45 |
| built-in subagent | "a default prompt" | An agent with a shipped body and routing behaviour. Overridable by name. | 46 |
| read-only agent | "told not to edit" | Write and Edit aren't in its tool pool. A capability, not a rule. | 46 |
Explore | "the search agent" | Read-only discovery. No CLAUDE.md, no git status. | 46 |
Plan | "plan mode" | A read-only research agent. Plan mode is the surrounding feature; the agent is one participant in it. | 46 |
general-purpose | "the full agent" | Every tool available to subagents. Loads CLAUDE.md. | 46 |
| restate the rule at delegation | "tell it what to do again" | The only way a rule reaches a no-CLAUDE.md agent. The delegation message is the whole channel. | 46 |
/btw | "ask a side question" | Full conversation context, no tool access, answer not added to history. | 46 |
| narrow subagent | "a focused agent" | One whose tool pool makes out-of-scope work impossible, not merely discouraged. | 47 |
| skill vs subagent | "prompt vs agent" | Where the result lands: interleaved in your window, or summarized back. | 47 |
| delegation message | "the prompt" | Written by Claude from your request. The only channel to a no-CLAUDE.md agent. | 47 |
| fork | "a subagent with context" | Inherits the whole parent conversation, system prompt, tools, model, and prompt cache. No isolation. | 47 |
/subtask | "run it in the background" | Starts a fork yourself, named from the task. | 47 |
| fork mode | "a setting" | On by default interactively; changes what Claude gets when it spawns a subagent with no type. | 47 |
| prompt cache sharing | "it's faster" | A fork's first request reuses the parent's cache. Cheap only because it inherited everything. | 47 |
| silent field ignoring | "it's not supported" | Unknown frontmatter keys are dropped with no warning. Check spelling. | 47 |
skills: on a subagent | "give this agent skills" | Preloads full skill content into its window at startup. Up to 32 names. Not a restriction. | 48 |
context: fork on a skill | "run this in a fork" | Starts a new isolated subagent whose prompt is the skill. Not a fork of your conversation. | 48 |
| preload vs access | "skills controls what it can use" | It controls what's loaded. Access is tools / disallowedTools. | 48 |
disable-model-invocation | "manual-only skill" | Also makes the skill unpreloadable — preloading draws from the invocable set. | 48 |
| guideline vs instruction | "a skill" | Guidelines have no task and fork to nothing. Instructions fork usefully. | 48 |
| backgrounded fork | "running in parallel" | Narrower tool set, outside session checkpoints. /rewind doesn't reach its edits. | 48 |
agent: on a forked skill | "which agent it uses" | Picks the subagent type — which decides model, tools, permissions. Defaults to general-purpose. | 48 |
Phase 07 — MCP
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
| MCP | "the thing that lets Claude use tools" | A protocol. One wire format for a program to advertise actions and for a client to call them. Not a product, not a vendor. | 49 |
| host | "Claude Code" | The app containing the model and the loop. Claude Desktop, an IDE, Claude Code — all hosts. | 49 |
| client | "MCP" / "the connection" | The in-process object that speaks MCP to exactly one server. One per server, per host. | 49 |
| server | "the tool" | A separate program with its own permissions, its own failure modes, and its own author. Not the same process as the host. | 49 |
| transport | "the protocol" | The wire the JSON-RPC messages travel on. Four of them. Lesson 50. | 49 |
tools/list | "discovery" | The handshake that tells the model what actions exist. Runs at session start or on demand. | 49 |
tools/call | "the tool call" | The actual invocation: a name and a JSON object of arguments. | 49 |
| resource | "context" | Content you attach explicitly with @server:protocol://path. The model cannot fetch one on its own. | 49 |
| prompt | "a slash command from a server" | A canned task shape, invoked as /servername:promptname. Listed alongside built-in commands. | 49 |
| JSON-RPC 2.0 | "the message format" | Request has an id and gets a reply. Notification has no id and gets nothing back. | 49 |
| protocol version | "the version" | A string the server and client agree on at initialize. Sending a version your client can't speak is a real failure mode. | 49 |
| transport | "the protocol" | How JSON-RPC messages physically move. Four options; the protocol itself is transport-agnostic. | 50 |
| stdio | "local" | Claude Code spawns the process and talks over its stdin/stdout, one JSON message per line. | 50 |
sse | "the old one" | Deprecated remote transport. Kept for endpoints that only speak it; you tolerate it rather than choose it. | 50 |
http | "the modern one" | Remote request/response. streamable-http is an accepted alias in config. | 50 |
ws | "the streaming one" | Persistent bidirectional socket. The only transport where the server speaks first, unprompted. | 50 |
handshake / initialize | "the connection" | First exchange: versions and capabilities, before any tool call. A failure here is not a tool failure. | 50 |
| startup timeout | "it failed to connect" | MCP_TIMEOUT. Bounds how long the client waits for the server to be ready. | 50 |
| tool timeout | "the tool hung" | MCP_TOOL_TIMEOUT or a per-server timeout. A wall clock on one call. | 50 |
-- | "the separator" | Stops Claude Code parsing flags. Everything after belongs to your command. | 50 |
| stdout is the protocol | — | One stray print and the stream is corrupt. stderr is free for humans. | 50 |
| scope | "where the config lives" | Who the server is for, which decides both the file and who else gets the code | 51 |
local | "my project's settings" | ~/.claude.json under this project. Default. Beats project. | 51 |
project | "shared config" | .mcp.json, committed, and gated behind approval on first use | 51 |
user | "global" | ~/.claude.json top level. Loads in every project, never shared | 51 |
| precedence | "which one wins" | local > project > user > plugin > connectors; managed config above all | 51 |
| no merging | — | The whole highest-precedence entry is used. Fields are never combined across scopes. | 51 |
| matched by name | — | Two entries are rivals only if their mcpServers keys are identical | 51 |
${VAR:-default} | "env interpolation" | Expanded in command, args, env, url, headers — how a committed file holds no secrets | 51 |
| workspace trust | "the trust dialog" | A cloned repo cannot approve its own project servers until you accept it | 51 |
reset-project-choices | "un-approve" | Forgets prior approvals so you read the prompt again | 51 |
initialize | "the handshake" | First message. Version and capabilities agreed before any tool call. | 52 |
| notification | "a message" | JSON-RPC with no id. Never answered. notifications/initialized is the one you'll meet. | 52 |
tools/list | "the manifest" | What the model picks from. The description is the interface. | 52 |
tools/call | "the invocation" | Name plus a JSON object of arguments, validated against the schema. | 52 |
| input schema | "the types" | JSON Schema the API checks before the call reaches you. One bad schema can fail the whole request. | 52 |
isError | "an error response" | A tool failure reported as data. The loop reads it and tries again. | 52 |
instructions | "the readme" | Server-level prose telling the model what your server is for. Load-bearing with tool search. | 52 |
_meta | "extra fields" | Per-tool annotations: size ceiling, always-load, require-interaction. | 52 |
| protocol version | "the version string" | Agreed at initialize. A server speaking a revision the client doesn't will fail at the first tool call. | 52 |
| stdio framing | "the wire format" | One JSON object per line, stdin and stdout, nothing else on stdout. | 52 |
| prompt injection | "jailbreaking" | Instructions hidden in data the model reads, aimed at the model's obedience rather than the task | 53 |
| trust boundary | "the sandbox" | Not the sandbox. It's the line between text you authored and text someone else did | 53 |
| untrusted content | "the tool output" | Anything in the window the model did not get from you | 53 |
| workspace trust | "the trust dialog" | The gate that stops a cloned repo granting itself code execution | 53 |
| least privilege | "sandboxing" | The credentials and verbs a server holds. The only defence that survives a working injection | 53 |
headersHelper | "token helper" | A shell command a config may run to produce a header. Config → code execution. | 53 |
requiresUserInteraction | "always-ask" | Per-tool annotation forcing a permission prompt on every call, with no remember-this option | 53 |
| general-purpose tool | "a flexible tool" | A tool that can do anything. A loaded gun whenever the model may be holding hostile text | 53 |
| Defence in depth | "prompting" | Structural controls stacked so one failing doesn't matter. Prompting is the thinnest layer | 53 |
| enforcement | "the model was told not to" | Phase 08's job. Actions made impossible rather than discouraged | 53 |
| OAuth | "the login" | A flow where a human authorises once and tokens refresh. Config holds clientId, never the secret | 54 |
--header | "the token" | A static credential sent every request. Use ${VAR} so it isn't in a tracked file | 54 |
headersHelper | "dynamic headers" | A shell command a config may run to produce a header. Read it before approving | 54 |
| tool search | "lazy loading" | Deferring tool descriptions until a query suggests one. On by default; costs you nothing at startup | 54 |
| deferred vs upfront | "loaded" | Deferred = found by searching descriptions. Upfront = always in the window, costs every turn | 54 |
ENABLE_TOOL_SEARCH | — | unset defers; auto:N loads eagerly below N% of the window; false loads everything | 54 |
alwaysLoad | "pin it" | Exempt a server (or one tool) from deferral. A context purchase, paid every turn | 54 |
MAX_MCP_OUTPUT_TOKENS | "the output limit" | Session-wide ceiling. Results past it are written to a file, not truncated | 54 |
maxResultSizeChars | "raise the limit" | Per-tool ceiling via _meta. Scoped, and independent of the env var | 54 |
requiresUserInteraction | "always ask" | Per-tool annotation: a permission prompt on every call, no remember-this option | 54 |
Phase 08 — Hooks
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
| hook | "a callback" | Your script, run by the harness at a named point on the agentic loop. Not called by the model. | 55 |
| hook event | "the hook" | A named firing point — PreToolUse, Stop, SessionStart. One event can have many handlers. | 55 |
| matcher | "a filter" | The condition on which handler group activates. Tool name, regex, or * for all. | 55 |
| blocking event | "a real hook" | An event where exit 2 stops the pending action. PostToolUse is not one. | 55 |
${CLAUDE_PROJECT_DIR} | "the cwd" | The project root where the session started. Not the process cwd, and in a worktree it points at the main checkout. | 55 |
| settings merge | "nearest file wins" | They don't. Every level's hooks run. Lesson 34 has the order. | 55 |
| event | "the hook" | A named firing point. Many hooks can share one event. | 56 |
| matcher | "a filter" | The condition activating a handler group. Exact string, `\ | 56 |
| blocking event | "one that stops things" | An event where exit 2 cancels a pending action. PostToolUse is not one. | 56 |
| handler type | "the hook type" | What runs: command, prompt, agent, http, mcp_tool. | 56 |
if | "a second matcher" | One permission-rule expression, on five events only. Silently ignored elsewhere. | 56 |
precedence deny > defer > ask > allow | "the strictest wins" | Right. One deny overrides an allow from another handler. There is no vote. | 56 |
| stdin | "the arguments" | One JSON object. There is no argument list. | 57 |
| stdout | "the output" | Shown only on a few events; parsed as JSON only if the whole thing is one object | 57 |
| stderr | "the error log" | On exit 2, the first line is the blocking reason shown to the user | 57 |
additionalContext | "the hook message" | Goes into the model's context. Capped at 10k chars. | 57 |
systemMessage | "the hook output" | Goes to the user's screen, not the model. | 57 |
suppressOutput | "keeps it quiet" | Accepted and inert. Does nothing. | 57 |
hookSpecificOutput | "the decision object" | Event-specific. Always carries hookEventName. | 57 |
${CLAUDE_PROJECT_DIR} | "the working directory" | Where the session started. In a worktree, the main checkout — not where the agent is. | 57 |
| exit 2 | "an error" | A blocking decision. Cancels a pending action on blocking events. | 58 |
| exit 1 | "a failure" | Correct. A non-blocking error. The action continues. | 58 |
| non-blocking error | "it broke" | Any non-0, non-2 exit, plus a process that can't start, plus a timeout | 58 |
| fail open | "it's broken" | A broken guardrail that permits. The dangerous default. | 58 |
| fail closed | "it's strict" | A broken guardrail that stops. Safer, and it can lock you out of your own session. | 58 |
onFailure: "block" | "strict mode" | Converts failures, timeouts, and invalid output into blocks. Recent feature; check your version. | 58 |
| blocking reason | "the output" | The first line of stderr on exit 2. Not stdout. | 58 |
| guardrail | "a lint rule for the agent" | A hook on a blocking event, before the action. Enforcement, not feedback. | 59 |
| policy as data | "config" | Forbidden things in an array, so adding a rule can't add a failure mode. | 59 |
| self-test | "unit tests" | Fabricated events piped into the script, asserting exit codes. No Claude Code in the loop. | 59 |
| fail open | "it lets things through" | Broken guardrail permits. The default, and dangerous once you trust it. | 59 |
--force-with-lease | "force push, safer" | Force-push that checks the remote hasn't moved. Block plain --force, not this. | 59 |
| generated file | "build output" | Anything under dist/, node_modules/, or minified. Edited by a generator, never by hand. | 59 |
| debug log | "the logs" | claude --debug or --debug-file. Shows registration, matcher evaluation, skips, and crashes. | 60 |
--init-only | "startup check" | Debug-file mode for checking that Setup / SessionStart hooks ran, without a full session. | 60 |
| skipped | "it didn't run" | The log says why. Usually the matcher, not an error. | 60 |
| stale settings | "I edited the file" | Settings load at session start. Edit and restart, or you're debugging the old copy. | 60 |
| async hook | "a background hook" | Can't block. A decision printed after the harness stopped waiting controls nothing. | 60 |
asyncRewake | "async that can block" | Wakes Claude on exit 2 and hands it stderr. The one background mode with teeth. | 60 |
| fail open | "it's not strict" | A timeout or crash lets the action through. The default for every failure mode. | 60 |
Phase 09 — Plugins
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
| plugin | "an extension" | A directory of components Claude Code loads as one unit. Nothing new; a unit. | 61 |
| packaging layer | "it's just a zip" | One install, one update, one uninstall, and names that cannot collide. | 61 |
| namespace prefix | "it's named differently" | Plugin name on the front of every skill and agent it provides. Hooks are excluded. | 61 |
| marketplace | "the plugin store" | A repo or directory with a marketplace.json listing plugins and where to fetch them. A catalog you add, not a hosted store. | 61 |
| loose files | "my setup" | Skills, agents, and hooks in .claude/ or ~/.claude/. Fine when nobody else needs them. | 61 |
| mod | "a JS plugin" | A plugin that ships a JavaScript hooks module. Mentioned in docs; not this lesson. | 61 |
| plugin root | "the plugin folder" | The directory holding .claude-plugin/ and the component folders. Only plugin.json lives in the first one. | 62 |
| manifest | "the config" | .claude-plugin/plugin.json. Optional. name is the only required field, and it becomes the prefix on every skill and agent. | 62 |
| standard layout | "the default folders" | The directories Claude Code scans when the manifest doesn't point elsewhere. | 62 |
| replaces vs adds | "it's a list" | commands/agents/outputStyles/workflows replace their default folder. skills adds to it. hooks/mcpServers merge with it. | 62 |
${CLAUDE_PLUGIN_ROOT} | "the plugin path" | The installed plugin directory — and it moves on every update. Never write state there. | 62 |
${CLAUDE_PLUGIN_DATA} | "the data dir" | Created on first reference, survives updates. This is where node_modules and caches go. | 62 |
| always-on tokens | "the startup cost" | What the plugin's skill and agent names and descriptions add to every session it's enabled in. Paid whether or not anything runs. | 62 |
| validate | "lint the plugin" | claude plugin validate checks the manifest and every component's frontmatter before you load anything. | 62 |
--plugin-dir | "install it" | Loads a directory for one session. Nothing is written to settings. The authoring loop. | 63 |
| marketplace | "the store" | A repo or directory with .claude-plugin/marketplace.json. You add it once; its plugins install by name. | 63 |
name in plugin.json | "the label" | The required prefix on every skill and agent the plugin provides. | 63 |
| scope | "where it's installed" | user (all your projects), project (committed .claude/settings.json, everyone), local (this repo, you). | 63 |
| validate | "test it" | Checks the manifest and every component's frontmatter, from the shell, before load. | 63 |
/reload-plugins | "refresh" | Picks up disk edits in a running session. May decline if it would invalidate the prompt cache. | 63 |
| Errors tab | "the error log" | /plugin → Errors: what failed to load and why. Silent failures are listed here, nowhere else. | 63 |
${CLAUDE_PLUGIN_ROOT} | "the install path" | The plugin's installed directory. Moves on update — never write state there. | 63 |
| always-on cost | "the startup cost" | Tokens a plugin's skill and agent names and descriptions add to every session it's enabled in, whether or not anything runs. | 64 |
Phase 10 — Memory & Instructions
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
CLAUDE.md | "the config file" | Instructions you write, read at the start of every session. Context the agent follows, not configuration that is enforced. | 65 |
| the 200-line rule | "a hard limit" | A target. Past it the file still loads, but adherence drops. The hard skip is 4 MiB, by which point nothing works. | 65 |
| load order | "the project one overrides the user one" | They are concatenated, not overridden. The file closest to your working directory is read last. | 65 |
| Memory files | "the CLAUDE.md" | Every instruction file that actually loaded, listed by /context. If it isn't there, the agent can't see it. | 65 |
CLAUDE.local.md | "a private CLAUDE.md" | Same content, same loading — but gitignored and yours alone. | 65 |
| mid-session edit | "it updated" | It did not. The session read the file once, at the start. | 65 |
AGENTS.md | "the file for other agents" | A shared instruction file Claude Code can read as project instructions — but only when no CLAUDE.md/CLAUDE.local.md is present, unless you change the setting. | 66 |
| Project instructions | "which file wins" | The /config setting that decides whether Claude reads CLAUDE.md, AGENTS.md, both, or managed instructions only. | 66 |
CLAUDE.local.md | "just a private CLAUDE.md" | Loaded exactly like CLAUDE.md — and counted as one, so it suppresses AGENTS.md. | 66 |
| symlink vs import | "the same thing" | A symlink is a link the tools may refuse to write through and Windows may not check out; an import copies the content in at launch. | 66 |
.agents/ directory | "another place for agents" | Not read. Neither is AGENTS.local.md or AGENTS.override.md. | 66 |
| worktree | "another checkout" | A second working copy of the same repo. A gitignored CLAUDE.local.md exists only in the one where you made it. | 66 |
| rule | "a small CLAUDE.md" | An instruction file in .claude/rules/ that can be scoped with paths:. | 67 |
paths: | "a filter" | The only frontmatter field a rule reads. Globs that decide when the rule loads. | 67 |
| path-scoped rule | "a rule for one folder" | A rule that stays out of the window until the agent touches a matching file. | 67 |
| load at launch | "it's always on" | Rules without paths:, loaded every session like .claude/CLAUDE.md. | 67 |
| user vs project rules | "project overrides user" | They concatenate; user rules load first. Conflicts are not resolved for you. | 67 |
| rules vs skills | "both are instructions" | Rules load at launch or on a file match; skills load when invoked. | 67 |
| auto memory | "the agent remembers" | A directory of markdown files Claude writes and reads back. You can edit or delete it. | 68 |
MEMORY.md | "the memory file" | An index. Only its first 200 lines or 25KB load at session start. | 68 |
| topic file | "a memory" | Detail Claude reads on demand, not at startup. | 68 |
type field | "a tag" | Which kind of note it is: user, feedback, project, or reference. | 68 |
| machine-local | "synced" | Auto memory does not cross machines or cloud environments. | 68 |
CLAUDE.md vs auto memory | "the same thing" | You write CLAUDE.md; Claude writes auto memory. Both load every session. | 68 |
| output style | "a prompt preset" | Instructions that set role, tone, and format for every response in a session. | 69 |
keep-coding-instructions | "keep the defaults" | Whether your custom style keeps Claude Code's built-in software-engineering instructions. Defaults to false. | 69 |
| built-in styles | "the four modes" | Proactive, Concise, Explanatory, Learning — each adds to the default. | 69 |
force-for-plugin | "always on" | A plugin style that applies automatically when the plugin is enabled. | 69 |
| style vs hook | "both change behaviour" | A style is an instruction the agent follows; a hook runs regardless of what it decides. | 69 |
| style vs CLAUDE.md | "both set context" | A style shapes how it responds; CLAUDE.md says what it should know. | 69 |
| import | "a link" | The file's contents expanded into context at launch, not fetched on demand. | 70 |
| external import | "a file outside the project" | An import whose path resolves outside your working directory. It needs approval once. | 70 |
| four hops | "recursive imports" | Imported files may import others, to a depth of four. | 70 |
| backtick trick | "escaping" | ` @README stays literal; only a bare @README` imports. | 70 |
| import cost | "it's split up now" | The same as one file — every import loads at launch. Organisation, not economy. | 70 |
| user-scope imports | "trusted" | Imports in ~/.claude/CLAUDE.md and ~/.claude/rules/ load without the dialog (except in Cowork). | 70 |
Phase 11 — Parallelism I
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
| subagent | "a parallel agent" | A worker inside one session. Isolates context, not files. | 71 |
| teammate | "another agent" | A full session in an agent team, coordinated through a shared task list and a mailbox. Not worktree-isolated. | 71 |
| worktree | "a branch" | A second working directory with its own checkout. The only one of the five that isolates files. | 71 |
| workflow | "a big prompt" | A script that holds the plan and runs many subagents. Isolates the plan from your conversation. | 71 |
/batch | "run it everywhere" | A skill that splits one change into units and runs one worktree-isolated subagent per unit. Subagents plus worktrees, packaged. | 71 |
| axis of isolation | "how parallel it is" | The single thing a mechanism keeps from colliding. The word that actually decides your choice. | 71 |
| agent view | "the agent dashboard" | A screen for dispatching and watching background sessions. A monitoring surface, not an isolation axis. Phase 12. | 71 |
| isolation | "the agent can't touch my stuff" | A specific thing kept separate. For a subagent, that thing is its context window — not your files. | 72 |
| context isolation | "separate memory" | The subagent spends its own window on the work and returns only a summary. The reason parallel agents help at all. | 72 |
| shared working directory | "where it runs" | Parallel subagents start in your directory. Same paths, same writes, no guard. | 72 |
isolation: worktree | "make it safe" | Gives that subagent its own git checkout, so its edits land on their own branch. Off by default. | 72 |
| delegation message | "the prompt" | Written by Claude from your request. The only channel into a fresh subagent. | 72 |
| window from its own model | "it has your window" | A subagent's budget comes from the model in its definition, which may be smaller than yours. | 72 |
| summary return | "the answer" | What crosses back into your window. Everything else stays in the subagent's, and is gone. | 72 |
| agent team | "parallel agents that cooperate" | A lead session plus peer sessions sharing a task list and a mailbox. Coordination, not isolation. | 73 |
| team lead | "the main agent" | The one session you talk to. Fixed for the team's life; can't be transferred. | 73 |
| task list | "the plan" | Shared work items with states and dependencies, under ~/.claude/tasks/. Claiming is lock-protected; the files aren't. | 73 |
| mailbox | "the chat" | A per-agent inbox JSON under ~/.claude/teams/. How teammates message each other by name. | 73 |
| self-claim | "picking up work" | A teammate grabbing the next unblocked task without the lead assigning it. | 73 |
| idle notification | "it told me it's done" | The message a teammate sends the lead when it stops, including its result. | 73 |
| task status lag | "it's stuck" | A finished task marked not-done, blocking its dependents. | 73 |
| named subagent | "a teammate" | With teams on, a subagent Claude names launches as a teammate. The cause of teams forming unasked. | 73 |
| worktree | "a branch, but isolated" | A separate working directory with its own files and branch, sharing one .git with the main checkout. | 74 |
--worktree / -w | "open a parallel session" | Starts a session in its own worktree under .claude/worktrees/. | 74 |
| session worktree | "my other window" | A worktree that isolates one whole session. | 74 |
| per-agent worktree | "isolated subagent" | isolation: worktree — a temporary worktree for one subagent. | 74 |
.worktreeinclude | "copy my env" | A gitignore-syntax list of gitignored files to copy into each new worktree. | 74 |
shared .git | "it's copied too" | It isn't. Worktrees share history, refs, and remotes with the main checkout. | 74 |
| cleanup prompt | "it asks to keep the worktree" | Claude Code's check before removal: work present, or state unverifiable. | 74 |
EnterWorktree | "switch worktrees mid-session" | The tool Claude uses to enter a worktree; outside .claude/worktrees/ it asks first. | 74 |
worktree.baseRef | "where the branch starts" | "fresh" (default) from the remote default branch, or "head" from your current local HEAD. Never a branch name. | 75 |
| fresh worktree | "a clean copy" | One branched from the default branch. It does not see unpushed work — the stale-code trap. | 75 |
| retention sweep | "cleanup" | A periodic removal of Claude-created worktrees older than cleanupPeriodDays, skipping any that hold work. | 75 |
| worktree lock | "it won't delete while running" | Held while an agent runs; released on finish, and for exited processes. Never releases a lock you set. | 75 |
/batch | "mass edit" | A skill that decomposes one change into 5–30 units and runs one worktree-isolated subagent per unit. | 75 |
| publish | "push the change" | What each /batch subagent does with its result — a PR in git, or a reported change under a WorktreeCreate hook. | 75 |
cleanupPeriodDays | "how long worktrees live" | The age after which the sweep may remove an idle worktree — unless it holds work. | 75 |
| isolation check | "the worktree protects me" | One of four harness rules that block a tool call reaching the main checkout from an isolated session. | 76 |
| file-edit check | "it can't edit there" | Blocks Edit/Write/NotebookEdit targeting a main-checkout path. | 76 |
| working-directory check | "it can't run there" | Blocks a command whose cwd resolves to the main checkout, or that can't be verified outside it. | 76 |
| git redirect | "it can't touch git there" | Blocks commands that point git at the main checkout via -C, --git-dir, GIT_DIR, GIT_WORK_TREE, or a cd. | 76 |
| command shape check | "it refuses safe commands" | Blocks a command whose text can't prove its git stays inside the worktree. Can't be turned off. | 76 |
| the gap | "isolation is absolute" | Shell writes into the main checkout that don't invoke git (cp, redirects) aren't refused by these checks; permissions and sandboxing govern them. | 76 |
| tool error | "it just failed" | How Claude sees a refusal — it names the worktree and how to proceed. | 76 |
Phase 12 — Parallelism II
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
| cross-session messaging | "chat between agents" | Text pushed into a running session's socket. Not mail, not stored | 77 |
| the inbox socket | "the session's inbox" | A per-session Unix socket or Windows named pipe. Gone when the session exits | 77 |
SendMessage | "the message tool" | Claude's send call. Takes plain text, max ~1M characters same-machine | 77 |
ListAgents | "the address book" | Discovery. Lists subagents, teammates, local sessions, and reachable remote ones | 77 |
notify_when_idle | "ping me when it's done" | A one-shot notice when the watched session next goes idle or exits. 12-hour expiry | 77 |
crossSessionInbound | "a permission setting" | accept / hold / refuse for arriving messages. The default comes from both sessions' permission classes | 77 |
| own-child message | "a message from myself" | A hook or Bash command posting into its own session. Needs process evidence, or the token | 77 |
| reply address | "the return path" | Attached to every message except a one-way cross-machine one | 77 |
| dynamic workflow | "an ultracode thing" | A JavaScript script the runtime executes to orchestrate many subagents | 78 |
agent() | "a subagent call" | Spawns one subagent. Resolves to its result, or null if it was stopped or hit an unrecoverable error | 78 |
pipeline() | "the loop" | One agent per item in a list. Keeps a null in the slot of an item that failed | 78 |
parallel() | "run them all" | A set of tasks at once. Waits for all of them | 78 |
meta | "the header" | A plain object literal with name and description, as the first statement. Non-literals drop it from autocomplete | 78 |
args | "the parameter" | The structured input a saved workflow was invoked with. undefined if omitted | 78 |
ultracode | "a magic word" | The opt-in keyword. Works only in a prompt you typed yourself | 78 |
| size guideline | "a cap" | Advice to Claude about how many agents to aim for. The runtime caps still apply separately | 78 |
| resumable | "it remembers" | Within one session, a relaunched run replays agents and returns saved results for the ones that completed | 78 |
pipeline() | "the parallel loop" | A list plus a function. One agent per item, results in list order | 79 |
parallel() | "run them at once" | A set of tasks. No list behind them. Waits for all | 79 |
agent() | "one subagent" | One task. Resolves to its result, or null if it was lost | 79 |
| awaited directly | "outside the fan-out" | The run ends if that agent fails. The opposite of a null slot | 79 |
null in a slot | "it failed" | The placeholder for a stopped, stalled-out, or unrecoverable agent. The slot stays where it was | 79 |
label | "a nicety" | The only name a fan-out slot has. Without it you have an index | 79 |
| wait-for-all | "how it works" | Both combinators return after every agent finishes. There is no early return | 79 |
| 4,096 | "a big number" | The items-per-call cap. A longer list is rejected, not trimmed | 79 |
| declared order | "the order it ran in" | The order you wrote the task list. The order the returned array follows | 80 |
| finish order | "the order it finished" | When each agent stopped. Visible in /workflows; attached to no result you receive | 80 |
| slot | "an entry" | A position in the returned array. The only identity a result has without a label | 80 |
null in a slot | "it failed" | A lost agent. Stopped, stalled past every attempt, or unrecoverable. Kept in place | 80 |
.filter(Boolean) | "cleaning up the errors" | Removes the holes and shifts every later slot, silently rewiring the join | 80 |
| saved result | "it's cached" | What a relaunch returns for an agent whose call matches the previous run | 80 |
| first divergence | "the change" | The earliest position where the new run's sequence of calls differs. Everything from there reruns | 80 |
| absence vs emptiness | "nothing came back" | A lost agent versus an agent that ran and found nothing. Different facts, different handling | 80 |
| misattribution | "the agents broke it" | Reading a failure's evidence as attached to the work instead of the runner | 80 |
| list cap | "too many files" | 4,096 items per parallel()/pipeline() call. Rejected, never truncated | 81 |
| in-flight cap | "it should be parallel" | 16 concurrent agents by default, fewer with fewer CPUs. The rest queue | 81 |
| run cap | "a safety limit" | 1,000 agents in one run. The backstop against a runaway loop | 81 |
| stall window | "a timeout" | How long an agent may produce no output before the attempt is abandoned and restarted | 81 |
| restart | "a retry" | A new attempt from the same prompt. No transcript, no rollback, tokens still counted | 81 |
stallMs | "a timeout option" | The per-agent override for the stall window, in milliseconds | 81 |
CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS | "the global timeout" | The run-wide stall window. Also applies outside workflows | 81 |
| prefix stagger | "a delay" | Up to 5 seconds of hold so a fan-out's later agents read the first one's prompt cache | 81 |
| stall vs failure | "it failed" | A stall retries without the run noticing; a failure reruns the tail on a relaunch. Different mechanisms | 81 |
Large workflow | "an error" | An advisory warning above 25 agents or 1.5M projected tokens. It does not stop anything | 81 |
/loop | "a cron job" | A session-scoped scheduled prompt. Fires between your turns while the session is open | 82 |
| scheduled task | "the timer" | A CronCreate entry with an 8-character ID, a 5-field cron schedule, and a prompt. Max 50 per session | 82 |
| self-paced loop | "the smart one" | A /loop with no interval. Claude chooses 1–60 minutes after each iteration and prints why | 82 |
loop.md | "the config" | The default prompt for bare /loop. Project file wins over user file. Truncated past 25,000 bytes | 82 |
| catch-up | "it'll run late" | It will not. Missed fires collapse to one when the session next goes idle | 82 |
| jitter | "the drift" | A deliberate shift so sessions do not hit the API together. Recurring tasks run late; */5 runs 15s early | 82 |
| seven-day expiry | "the limit" | A recurring task fires a final time and deletes itself seven days after creation | 82 |
Esc | "stop the loop" | Clears a self-paced loop's pending wakeup. Does not affect tasks you asked for directly | 82 |
| cloud routine | "the durable one" | A schedule that runs without your machine or session. Phase 17 | 82 |
Stop | "the end-of-turn hook" | Fires as a turn is ending. Blocking refuses the end and sends the agent back | 83 |
stop_hook_active | "a flag" | Whether a stop hook has already fired. You need it, or a bad hook never lets a turn end | 83 |
SubagentStop | "the worker's done" | Fires when a subagent stops. Blocking hands it more work | 83 |
PostToolBatch | "after the tools" | Fires between batches. Blocking stops the loop before the next model turn | 83 |
TeammateIdle | "the peer is waiting" | Fires when a team peer goes idle. Blocking keeps it working | 83 |
| handler type | "how the hook runs" | command (milliseconds), agent (a model call), http, mcp_tool, prompt (legacy) | 83 |
| control flow | "an if statement" | The decision about what runs next, moved out of the model and into a script that returns an exit code | 83 |
| own-child message | "talking to myself" | A hook or Bash command posting into its own session's socket. Needs the token where process evidence is missing | 83 |
MessageDisplay | "the output hook" | Observes what a session shows. Cannot block, and only displayContent returns | 83 |
| the plan | "the approach" | The decision about what runs next. Question 1 asks where it lives | 84 |
| subagents | "parallel agents" | Workers in one session, reporting summaries into Claude's window | 84 |
| agent view | "the dashboard" | Dispatching and monitoring background sessions you run. Research preview | 84 |
| agent teams | "agents that talk" | A lead plus peers with a shared task list and peer messaging. Experimental, off by default | 84 |
| dynamic workflow | "the scripting one" | A script the runtime executes. The plan is code, not judgement | 84 |
| projects | "the cloud thing" | Parallel cloud threads sharing a project's instructions across days | 84 |
| support tool | "also a way to parallelise" | Worktrees, messaging, /batch. They answer where and how findings travel | 84 |
| partition | "split the work" | Assign each worker a different set of files, because a team will not isolate for you | 84 |
| maturity label | "fine print" | Research preview and experimental are scheduling information, not marketing | 84 |
| amplifier | "more agents, more work done" | Parallelism multiplies throughput and whatever the loop was already doing, bugs included | 85 |
| verification boundary | "where I split it" | A place where one piece can be judged correct without the others. If none exists, don't split | 85 |
| load-bearing sequential | "it's mostly independent" | B needs A's output, so A and B are one worker's job | 85 |
| shared mutable resource | "a conflict" | Anything only one worker can own at a time. Worktrees fix files, not databases | 85 |
| coordination cost | "some overhead" | Setup + briefs + isolation + merges + review + re-runs, in the same units as the task | 85 |
| merge step | "we'll sort it out" | Branch, commit rule, merge order, conflict handling. Decided before work starts | 85 |
| attribution | "which agent broke it" | Whether a failure can be traced to one contribution. If not, more workers make debugging worse | 85 |
| isolation without a commit | "it's done" | A worktree whose branch points at main. It is not a backup and there is nothing to merge | 85 |
Phase 13 — Context Engineering
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
/context | "the token counter" | The view of what actually loaded and what it cost — the only honest answer to "why is my window full". | 86 |
| startup context | "the preamble" | Everything auto-loaded before your first message. You pay it every session whether you use it or not. | 86 |
| deferred MCP schemas | "MCP servers cost a fortune" | The names load at startup; full schemas load on demand via tool search. The names are cheap. The schemas are not. | 86 |
| skill listing | "the skill" | Only the skill's name and description load at startup. The body loads when the skill is invoked. | 86 |
| auto memory | "it remembers everything" | The first 200 lines or 25 KB of MEMORY.md load at startup. Past that, it does not. | 86 |
| standing charge | "it's just one line" | A cost paid every session. Lines add up across files, skills, and servers faster than anyone expects. | 86 |
| progressive disclosure | "lazy loading for prompts" | Metadata always, body on invoke, supporting files on demand. Three tiers, three times. | 87 |
| the listing | "the skills" | Only name + description load at startup. The body is not loaded until the skill is used. | 87 |
disable-model-invocation | "make it manual" | The skill leaves the startup listing entirely and costs zero until you type its name. | 87 |
references/ | "extra files" | Shipped with the skill, read only when the body points at them. Free until then. | 87 |
| 5,000-token re-attach | "it got truncated" | After compaction, only the first 5,000 tokens of each invoked skill return. Top matters. | 87 |
| standing instruction | "a step" | Wording that applies for the whole task. The body is not re-read, so a step reads as done. | 87 |
| context dump | "a thorough CLAUDE.md" | Everything in one layer, at one priority, loaded always. Volume instead of design. | 88 |
| home / lifetime / owner | "where does this go" | The three properties every fact needs. No answer to all three means it is a dump line. | 88 |
| path-scoped rule | "a rule" | A rule with paths: — it loads when a matching file is read, not at startup. | 88 |
| reload behavior | "it comes back" | What a layer does after /compact or a restart. Skill descriptions do not re-inject; bodies re-attach capped; reads go stale. | 88 |
| derivable | "worth documenting" | Content the code or config already states. Keeping it in the window is a standing charge with no return. | 88 |
| prefix | "the cached part" | The start of each request that the API matches. A change anywhere in it recomputes everything after. | 89 |
| cache read | "a cache hit" | Tokens served from the cache this turn. Billed cheaper than fresh input. | 89 |
| cache creation | "a cache write" | Tokens written to the cache this turn. What goes up when something at the front changed. | 89 |
| model switch | "just trying another model" | A full cache miss. The new model has its own cache and reprocesses the whole history. | 89 |
| cache-safe edit | "changing CLAUDE.md" | It keeps the cache but does not apply until /clear, /compact, or a restart. Two separate facts people merge into one. | 89 |
| TTL | "how long it lasts" | Cache entries expire after inactivity. Keeping the session warm keeps the cache warm. | 89 |
| reduction | "make it smaller" | Relocating facts to homes that load on demand. Deleting instead is a different, usually wrong, move. | 90 |
| relocation | "I moved it" | The fact still loads — just later and only when needed. The evidence is a run where it loaded. | 90 |
| capability test | "it still works" | A named task that fails if the fact is gone. The only honest proof a cut was safe. | 90 |
| standing cost | "the startup number" | What you pay every session regardless of the task. The target of reduction. | 90 |
| on-demand load | "lazy loading" | A skill body, a references/ file, a path rule, a subagent read — each loads only when triggered. | 90 |
| subagent delegation | "run it in a worker" | The reads happen in a separate window; only the summary returns to yours (Lesson 72). | 90 |
Phase 14 — Harness Engineering
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
| harness | "the agent's helper" | everything around the model that assembles state, exposes tools, ends the loop, and verifies | 91 |
| model | "the agent" | the component that picks the next action given the current state | 91 |
| agentic loop | "the agent thinking" | model decides → tool executes → result returns → repeat | 91 |
| stop condition | "when it's done" | the harness rule that ends the loop: success, failure, budget, or cap | 91 |
| boundary test | "is this the model's fault?" | if you can test it without a model, it is harness | 91 |
| decision call | "a small model call" | a call whose output is one of a small, known set | 92 |
| generation call | "the real work" | a call whose output can be any string of any length | 92 |
| closed set | "the options" | the finite list of legal answers a decision may return | 92 |
| triage | "sorting the input" | a decision call that routes work to the right path | 92 |
| one-token essay | "cheap prompt" | a decision paid for at generation prices because it ran on the wrong tier | 92 |
| branch point | "the decision" | a place in the loop where the next node is chosen | 93 |
| node work | "the actual task" | the generation step a loop runs once it knows which path to take | 93 |
| edge decision | "the routing" | a closed-set choice of which node comes next | 93 |
| closed set | "the options" | the finite list of answers a decision model may return | 93 |
| the fence | "validation" | the check that rejects an off-list decision and falls back | 93 |
| confidence gate | "the filter" | a rule that escalates decisions whose score is below a threshold | 94 |
| calibration | "the score is accurate" | evidence that score buckets line up with real accuracy | 94 |
| false accept | "it slipped through" | a wrong decision that passed the gate and shipped | 94 |
| false escalate | "it was too cautious" | a right decision that was sent up the strong path anyway | 94 |
| held-out slice | "a second test" | inputs kept back so a threshold isn't overfit to the tuning set | 94 |
| propose / verify | "the agent checks itself" | two roles: one produces, an independent one checks | 95 |
| verifier independence | "a second opinion" | the checker runs in its own context so it can't inherit the worker's assumptions | 95 |
| observable signal | "the test passed" | a check outside the worker's control: exit code, schema, diff | 95 |
| retry cap | "it keeps trying" | the maximum attempts before the loop gives up | 95 |
| completion-order trap | "first one wins" | mistaking arrival order for correctness when results are parallel (Lesson 80) | 95 |
| instruction | "a rule the agent follows" | natural-language text in the window that the model may or may not obey | 96 |
| guardrail | "a rule the agent follows" | a mechanism outside the model that allows or blocks the action | 96 |
| hook | "a script that watches the agent" | code that runs on a loop event and can veto a tool call (Phase 08) | 96 |
| deny rule | "a permission setting" | configuration that makes a tool or path unreachable | 96 |
| exit-code veto | "the hook returns an error" | the specific exit code that blocks the call rather than only reporting one (Lesson 58) | 96 |
| harness spec | "the architecture doc" | the eight deliberate choices, each with its trade-off | 97 |
| stub model | "a fake model" | a stand-in that lets you test the harness without an API call | 97 |
| trade-off | "the reason we chose it" | the cost you accepted plus the alternative you rejected | 97 |
| budget | "the cost limit" | the spend ceiling the harness enforces before it stops | 97 |
| escalation path | "the fallback" | where an unsure decision goes when the cheap path won't do | 97 |
Phase 15 — Graph Engineering
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
| node | "a task" | A unit of work defined by its output. No output, no node. | 98 |
| edge | "the order" | A dependency: A → B means B needs A's output. Points at the dependent. | 98 |
| DAG | "a workflow" | A directed graph with no cycles. The only kind of task graph that can run. | 98 |
| cycle | "circular dependency" | A path from a node back to itself. Nothing in it can ever start. | 98 |
| entry node | "the first task" | A node with no incoming edges. An initial member of the parallel set. | 98 |
| sink node | "the last task" | A node with no outgoing edges. A final deliverable. | 98 |
| frontier / ready set | "the next tasks" | Unfinished nodes whose parents are all done. Recomputed after every completion. | 99 |
| wave | "a batch" | A static layer: 1 + the deepest wave of a node's parents. Assumes equal node cost. | 99 |
| critical path | "the long pole" | The longest chain of dependencies. Its length is the floor on wall-clock time. | 99 |
| topological order | "the order" | Any linear order that respects every edge. It is one valid order, not the order. | 99 |
| ready | "runnable" | Every parent finished. Not the same as "not started". | 99 |
| stranded node | "it'll run eventually" | A node whose parent can never complete, so it never enters the frontier. Lesson 104. | 99 |
| blocking edge | "a dependency" | B cannot produce correct output until A exists. It adds a wave. | 100 |
| soft edge | "also a dependency" | A preference for order. B can start without A. It adds no wave. | 100 |
| interface | "a stub" | An agreed stand-in for a producer's output, so consumers do not wait for it. | 100 |
| interface-first | "design first" | Build the contract before either implementation, so both sides run in parallel. | 100 |
| critical path | "the long pole" | The longest chain of blocking edges. Its length is your floor. | 100 |
| over-blocking | "being safe" | Marking preferences as hard waits. It costs parallelism and buys nothing. | 100 |
| reconciliation | "merging" | The fan-in cost of running two sides against an interface that may be wrong. | 100 |
| claim | "taking a task" | An atomic transition from ready to claimed by exactly one worker. | 101 |
| atomic | "it just works" | The operation completes for one caller or not at all; no in-between state is observable. | 101 |
| compare-and-swap | "a lock" | "Set only if still ready." A conditional write that reports whether you won. | 101 |
| lease | "a timeout" | An expiry on a claim. When it lapses, the node returns to ready. | 101 |
| idempotent | "safe to retry" | Running it twice has the same effect as running it once. | 101 |
| owner | "who's on it" | The worker named in the claim record. | 101 |
| ready vs claimed | "it's pending" | Publicly runnable versus privately taken. The gap between them is the race. | 101 |
| wayfinding node | "just a task" | A node whose output is a decision: a choice plus its rationale. | 102 |
| decision record | "a note in chat" | The durable output of a wayfinding node: context, options, choice, consequences. | 102 |
| invisible dependency | "everyone knows that" | A blocker that exists in conversation but not on the graph. It blocks silently. | 102 |
| spike | "a research task" | A node that produces knowledge to inform a decision. Not the decision itself. | 102 |
| owner | "someone will figure it out" | The single person or agent accountable for making the call. | 102 |
| re-litigation | "we already decided" | Downstream nodes re-asking because the rationale was never recorded. | 102 |
| fan-out | "spawning agents" | One node launching N parallel children. | 103 |
| fan-in / join | "collecting results" | One node consuming N children. Where "done" is defined. | 103 |
| barrier (all-of) | "wait for everyone" | The join proceeds only when every child has returned. | 103 |
| any-of | "race them" | The join proceeds on the first success. | 103 |
| quorum (k of n) | "most of them" | The join proceeds when k children have returned. | 103 |
| keyed result | "the output" | A child's return tagged with its node id, so the join never trusts order. | 103 |
| map vs broadcast | "fan out" | Same operation over many inputs versus one input through many lenses. | 103 |
| completion order | "they come back in order" | False. Children finish by their own timing; key, do not index. | 103 |
| failure propagation | "it crashed the build" | A failure taints the failed node's descendants, not unrelated branches. | 104 |
| taint / blocked-by-failure | "skipped" | A downstream node whose ancestor failed. Distinct from "not ready yet". | 104 |
| verifier | "the tests" | A structural check that rejects bad output. A stronger failure signal than an exit code. | 104 |
| bounded retry | "just retry" | A fixed number of attempts. Unbounded retry strands descendants forever. | 104 |
| idempotent | "safe to re-run" | A retry does not double-apply its side effect. | 104 |
| orphan | "stuck" | A node whose claimant died; freed when its lease expires. | 104 |
| fail-open / fail-closed | "keep going" / "stop" | Proceed-with-a-marker versus block-the-run, chosen per node. | 104 |
| compensation | "undo" | A deliberate action that reverses a partial effect when a node cannot complete. | 104 |
| critical path | "the long pole" | The longest chain of blocking edges, in waves. Your wall-clock floor. | 105 |
| widest wave | "how parallel it is" | The most nodes that can run at once. Your fan-out ceiling. | 105 |
| busy-write check | "it should be fine" | Two same-wave nodes writing one file is a collision the graph must resolve. | 105 |
| defended edge | "an obvious dependency" | A blocking edge you can justify by naming the artifact it carries. | 105 |
| graph document | "a diagram" | The nodes, labelled edges, joins, failure policy, and computed numbers. | 105 |
| soft edge | "also needed" | A preference. It adds no wave; if deleting it changes nothing, delete it. | 105 |
Phase 16 — Worktrees in Practice
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
| session worktree | "isolation for my agents" | One checkout for the whole session. It isolates the session from other sessions, not its subagents from each other. | 106 |
| agent worktree | "a worktree" | A checkout that belongs to one subagent, created because its frontmatter says isolation: worktree. | 106 |
isolation: worktree | "agent isolation" | A subagent frontmatter field. One line; each run gets its own temporary checkout. | 106 |
| base ref | "where it branches from" | worktree.baseRef: "fresh" = the default branch, "head" = your current local work. | 106 |
EnterWorktree | "opening a worktree" | Claude moving the running session into a worktree mid-session. | 106 |
.worktreeinclude | "copying my env file in" | A list of gitignored files (.env, and so on) copied into every worktree Claude Code creates. | 106 |
| worktree | "a copy of the repo" | A second working folder for one repository, on its own branch, sharing the object store. | 107 |
git worktree add | "checkout into a folder" | Creates that folder and checks out a branch in it. | 107 |
| shared object store | "they're synced" | Every worktree writes commits to the same .git. There is nothing to sync. | 107 |
| one branch per worktree | "git won't let me switch" | Git forbids the same branch in two worktrees. This prevents two folders racing one branch. | 107 |
git worktree remove | "deleting the worktree" | Deletes the folder and its branch bookkeeping. Uncommitted work goes with it. | 107 |
| startup cache | "the tool is broken" | The repository check the session resolved at launch and keeps for the session. | 108 |
| "not in a git repository" | "but git says it is" | Both are true; git reads the folder now, the session reads its launch-time answer. | 108 |
git init mid-session | "I made it a repo" | It did. The session did not notice, and will not re-check. | 108 |
| restart | "closing and reopening" | Launching a new session inside the repo so it caches the right answer. | 108 |
| workspace trust | "a permission prompt" | The first interactive run in a folder asks you to accept it; --worktree needs it. | 108 |
| agent branch | "the agent's work" | A private, short-lived branch created for one agent. Yours until merged. | 109 |
| merge order | "merge as they finish" | Creation or catalog order. Completion order merges stale bases under fresh ones. | 109 |
| rebase before merge | "cleaning up" | Replaying the branch on today's main so it merges from the same base as its siblings. | 109 |
--no-ff | "a real merge" | Forces a merge commit, recording the batch instead of sliding the label. | 109 |
| branch drift | "it got stale" | The time a branch waits while main moves. The cost is rebase size, not the agent's work. | 109 |
| stale-base conflict | "the agents disagreed" | A conflict from two branches cut from an old main. Not a real disagreement. | 109 |
| isolation | "the work is safe" | Separate folders so edits do not collide. It says nothing about whether work is recorded. | 110 |
| empty branch | "the branch is there" | A branch label pointing where it started — usually main — with no commits of its own. | 110 |
| uncommitted work | "the agent's changes" | Edits that live only in one folder. Not in the object store. Not recoverable by git. | 110 |
| WIP commit | "a throwaway commit" | A commit that moves the label. Infinitely better than a folder about to be removed. | 110 |
main..branch | "the diff" | Commits on branch that are not on main. Empty means nothing to merge. | 110 |
| worktree removal | "cleaning up" | Deleting a folder. Uncommitted work goes with it, silently. | 110 |
| reflog | "git's undo" | Recovers committed positions. It cannot see work that was never committed. | 110 |
Phase 17 — Scaling & Operations
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
| headless mode | "the CLI without the UI" | The same context loader and loop, with no person to approve or catch anything | 111 |
-p / --print | "just a flag" | The switch that makes a run do one turn and exit, so it composes like a command | 111 |
--bare | "a faster start" | A start that skips auto-discovery — the same result on every machine, and none of your setup | 111 |
| exit code | "did it work" | The script's contract. 0 success, non-zero failure; a job that ignores it ships garbage | 111 |
| stdout / stdin | "I/O" | The two doors that make a run a Unix command: pipe in, format out | 111 |
--allowedTools | "permissions" | Pre-approval for a run. Not a security boundary — see Lesson 114 | 111 |
--permission-prompts none | "don't ask" | Tell the run nobody is there, so it denies and continues instead of hanging | 111 |
stream-json | "verbose JSON" | Newline-delimited events — tool calls, tokens, retries, denials — as they occur | 111 |
| Agent SDK | "Claude Code in a library" | A library that drives the Claude Code binary as a subprocess, exposing the loop and its capabilities to your program | 112 |
| Client SDK | "the SDK" | A different product: raw access to the Claude API where you write the tool loop. Not this | 112 |
| Managed Agents | "the hosted SDK" | Anthropic runs the harness and the sandbox. Not this | 112 |
query() | "the API call" | The entry point that streams one run's messages back to you | 112 |
canUseTool | "permissions" | The callback that replaces the terminal prompt, so your code approves or denies | 112 |
| in-process MCP server | "a plugin" | Turning a function in your own process into a tool the agent can call | 112 |
| structured output | "JSON mode" | A schema-validated result field, so your caller stops parsing prose | 112 |
| subprocess architecture | "it just works" | The SDK launches the binary. Who supervises, isolates, and scales it is your deployment problem | 112 |
| surface | "the app" | Where the loop runs and how you watch it. The same engine, a different context and feature set | 113 |
| channel | "an integration" | An MCP server that pushes events into an already-open session. Not a place to run | 113 |
| cloud session | "Claude in the cloud" | A run on an Anthropic-hosted clone. It sees the repository, not your uncommitted work | 113 |
Slack @Claude | "a channel" | The opposite: a mention starts a fresh cloud session, it does not feed an open one | 113 |
| Remote Control | "the same as a channel" | You drive a session from elsewhere; a channel pushes input into it | 113 |
| sender allowlist | "permissions" | The gate that decides which IDs may push into a channel; only IDs you add | 113 |
| shared across local surfaces | "synced" | Config, memory, and MCP travel between CLI, Desktop, and IDE — not to the cloud | 113 |
| research preview | "shipped" | Available, allowlisted, and explicitly subject to change | 113 |
| sandbox | "the security model" | An OS-enforced limit on shell commands only. Necessary, not sufficient | 114 |
| permission prompt | "the security boundary" | A per-call approval, model-initiated. A convenience layer; it asks a person | 114 |
| trust dialog | "just a warning" | The gate that stops a checked-out repo running its own code. The actual outer boundary | 114 |
dangerouslyDisableSandbox | "a fallback" | The parameter that retries a blocked command unsandboxed, with your full access | 114 |
| strict sandbox mode | "more sandbox" | allowUnsandboxedCommands: false — it removes the escape hatch | 114 |
| protected paths | "the allow list" | Config files a running command may not write even inside a writable directory | 114 |
failIfUnavailable | "a setting" | When the sandbox can't start, exit instead of silently running unsandboxed | 114 |
| filesystem isolation | "the sandbox" | The half that limits read/write; the network half is separate and can stand alone | 114 |
| runs outside the sandbox | "safe" | File tools, hooks, MCP servers, LSP, status line, apiKeyHelper — governed elsewhere | 114 |
| managed settings | "admin settings.json" | A policy that outranks user, project, local, and --settings. Its own sources also outrank each other | 115 |
| policy key | "any setting" | Any key other than the two control keys. A file with none is not a source | 115 |
first-wins | "the default" | The top-ranked source with a policy key supplies the policy; the rest are skipped and named | 115 |
merge | "combine them" | An opt-in where every admin source contributes, combined by kind of key | 115 |
| fail closed | "a bug" | A restrictive key that is present but invalid reads as its restrictive value, on purpose | 115 |
| refuses to start | "it broke" | What happens when a managed source is present but not parseable — a deliberate hard stop | 115 |
/status line | "a status readout" | The field that tells you which source won and which were skipped | 115 |
policyHelper | "a script" | An executable that computes the managed settings at startup | 115 |
| scoped key | "a normal setting" | A key read only from a managed source; putting it in your own file does nothing | 115 |
Phase 18 — Capstone
| Term | What people say | What it actually means | Lesson |
|---|---|---|---|
| spec | "the requirements" | A list of checks, each a command with an expected result. Prose is not a spec. | 116 |
| acceptance check | "a test" | One command whose exit tells you whether one behaviour holds. The unit a spec is made of. | 116 |
| task graph | "the plan" | Nodes (checks to satisfy) joined by edges (what needs what). A plan without edges is a list. | 116 |
| blocking edge | "A comes before B" | B genuinely needs an output of A. Remove it and B cannot be checked. | 116 |
| frontier | "what's parallel" | Nodes with no unfinished predecessor. Everything else is waiting, by design. | 116 |
| claim | "assigning the ticket" | A written marker that one agent owns one node, so two don't do one job. | 116 |
| verify | "running the tests" | Re-running step one's checks against the merged result, not per branch. | 116 |
| false frontier | "parallel but slow" | Two nodes that share a decision, drawn as independent. Isolated files, colliding meaning. | 116 |
| "Not covered" | "known issues" | The behaviours your spec doesn't check. Naming them is part of the spec, not an apology. | 116 |
| documented | "it's in the docs" | You can quote the sentence on a page you linked, and you checked today. | 117 |
| version-gated | "it works on my machine" | Documented, but only from some version. Useless without your version beside it. | 117 |
| unconfirmed | "I've seen it work" | Observed, uncited. A legitimate state — as long as it's labelled and has a test attached. | 117 |
| contradicted | "the docs are wrong" | The page disagrees with you. The page is usually right; check your version before arguing. | 117 |
| source vs summary | "I read an article" | A doc page is the source. Anything that quotes a version you can't see is a summary. | 117 |
| the index | "the docs site" | llms.txt — titles and URLs only. Answers "does a page exist" without a search. | 117 |
| dated claim | "I linked it" | URL + date + version. Any two of the three is a memory. | 117 |
| narrow claim | "hooks work" | A claim small enough to be wrong. Wide claims are always true and never useful. | 117 |
| empty branch | "the agent didn't do anything" | A branch that exists and points at main while the work sits uncommitted in a worktree. | 118 |
| the witness | "the test suite" | Whatever reports on the work. Check it on known-good code first — it lies in mundane ways. | 118 |
| transaction boundary | "it's saved" | A working tree is not a commit. Until it's committed, cleanup can and will remove it. | 118 |
| semantic collision | "they were in different folders" | Two nodes that share a resource (key, index, name, interface) while sharing no file. Green apart, red merged. | 118 |
| startup-cache trap | "it says not a git repository" | The harness probed the working directory once, at launch. A repo created later is invisible to it. | 118 |
| session-scoped transport | "the worker should have got the message" | Cross-session messaging lives and dies with the session. A closed session receives nothing. | 118 |
| retry masking | "it's green now" | A pass after a failure with no explanation for the difference. Unresolved, not fixed. | 118 |
| preflight | "running the tests first" | A check that runs before the work starts, turning a failure class into something that cannot happen. | 118 |
| mechanism | "the concepts" | Part of the harness that doesn't decay: the loop, the window, isolation, the graph. Bet on these. | 119 |
| surface | "the syntax" | Commands, flags, events, keys, defaults. True this release; re-check on a version bump. | 119 |
| model tier | "which model" | Aliases, effort, limits, capability. Route by alias; a version in prose is a claim with an expiry date. | 119 |
| claims ledger | "my notes" | DRIFT.md: claim, source, date checked, version. The version column is what makes it usable. | 119 |
| version gate | "it needs a newer version" | A behaviour that only exists from some version on. Useless without your version beside it. | 119 |
| alias | "the model name" | sonnet, opus — a route, not a version. What you write when you want it to keep working. | 119 |
| trigger | "staying up to date" | A condition you can test in one command that starts a re-check. Not a resolution to read more. | 119 |
| drift | "the docs changed" | Your note silently stopped being true. Nothing errored, which is what makes it expensive. | 119 |