A visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
docs: sync to Claude Code v2.1.176 (#141)
Luong NGUYENae656f6fb82e
diff --git a/.gitissue.yml b/.gitissue.ymlnew file mode 100644index 0000000..c3ede4d--- /dev/null+++ b/.gitissue.yml@@ -0,0 +1,14 @@+# gitissue / IDD configuration for claude-howto+#+# This is a documentation/tutorial repo. Doc-sync PRs (e.g. "docs: sync to+# Claude Code vX") are not tied to a single tracked issue, so they are treated+# like chore/refactor PRs for traceability: they do not require a `Closes #N`.+# A PR opts in by including a `Type: docs` (or `Type: chore`/`Type: refactor`)+# line in its body.++review:+ # Add `docs` to the built-in refactor/chore exemption so documentation-sync+ # PRs are not hard-blocked on a missing `Closes #N`. The other three+ # traceability checks still run.+ traceability_exempt_pattern: "^\\s*Type:\\s*(refactor|chore|docs)\\s*$"+ traceability_exempt_labels: ["refactor", "chore", "documentation"]diff --git a/04-subagents/README.md b/04-subagents/README.mdindex 786804b..f79081d 100644--- a/04-subagents/README.md+++ b/04-subagents/README.md@@ -901,7 +901,7 @@ graph TB### Key Behaviors-- **No nested spawning** - Subagents cannot spawn other subagents+- **Nested spawning (up to 5 levels)** - As of v2.1.172, subagents can spawn their own subagents, nested up to 5 levels deep. Earlier versions did not allow any nesting. Use the `Agent(agent_type)` restriction syntax (see [Restrict Spawnable Subagents](#restrict-spawnable-subagents)) to control which subagents a given subagent may spawn- **Background permissions** - Background subagents auto-deny any permissions that are not pre-approved- **Backgrounding** - Press `Ctrl+B` to background a currently running task- **Transcripts** - Subagent transcripts are stored at `~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl`@@ -1238,11 +1238,12 @@ See the OpenTelemetry section in [Advanced Features → Telemetry](../09-advance----**Last Updated**: June 2, 2026-**Claude Code Version**: 2.1.160+**Last Updated**: June 15, 2026+**Claude Code Version**: 2.1.176**Sources**:- https://code.claude.com/docs/en/sub-agents- https://code.claude.com/docs/en/agent-teams+- https://code.claude.com/docs/en/changelog#2-1-172- https://github.com/anthropics/claude-code/releases/tag/v2.1.117- https://github.com/anthropics/claude-code/releases/tag/v2.1.131- https://github.com/anthropics/claude-code/releases/tag/v2.1.138diff --git a/06-hooks/README.md b/06-hooks/README.mdindex 01eaffa..d5684ed 100644--- a/06-hooks/README.md+++ b/06-hooks/README.md@@ -77,6 +77,45 @@ Hooks are configured in settings files with a specific structure:| `nested_traversal` | Instructions loaded during nested directory traversal || `path_glob_match` | Instructions loaded via path glob pattern matching |+### Narrowing with `if` conditions (tool-argument paths)++The `matcher` field selects a hook by **tool name** (`"Write"`, `"Edit|Write"`, `"*"`). To filter more narrowly by the tool's **arguments** — for example, to run a hook only when an edit touches `src/`, or to guard reads of secret files — add an `if` condition to an individual hook handler. This is distinct from the tool-name matcher: the `matcher` decides *which tool*, the `if` decides *which call*.++`if` uses [permission-rule syntax](https://code.claude.com/docs/en/permissions) (`ToolName(pattern)`), evaluated against the tool name **and** its arguments together. For `Read`/`Edit`/`Write`, the path pattern follows gitignore semantics, with the same anchors as permission rules: a bare name like `.env` matches at any depth, `src/**` is relative to the current directory, `/src/**` to the project root, `~/...` to your home directory, and `//...` is an absolute filesystem path.++The `if` field sits at the **hook-handler level** — a sibling of `type` and `command`, inside the `hooks` array — not on `matcher`:++```json+{+ "hooks": {+ "PreToolUse": [+ {+ "matcher": "Edit|Write",+ "hooks": [+ {+ "type": "command",+ "if": "Edit(src/**)",+ "command": "./hooks/lint-src.sh"+ }+ ]+ },+ {+ "matcher": "Read",+ "hooks": [+ {+ "type": "command",+ "if": "Read(.env)",+ "command": "./hooks/block-secret-read.sh"+ }+ ]+ }+ ]+ }+}+```++Examples of valid `if` patterns: `Edit(src/**)` (edits under `src/`), `Read(~/.ssh/**)` (reads of any SSH key), `Read(.env)` (any `.env` at or below the current directory), `Bash(git push *)` (only `git push` subcommands).+## Hook TypesClaude Code supports five hook types:@@ -1460,11 +1499,13 @@ Edit `~/.claude/settings.json` or `.claude/settings.json` with the hook configur----**Last Updated**: June 10, 2026-**Claude Code Version**: 2.1.170+**Last Updated**: June 15, 2026+**Claude Code Version**: 2.1.176**Sources**:- https://code.claude.com/docs/en/hooks+- https://code.claude.com/docs/en/permissions- https://code.claude.com/docs/en/changelog+- https://code.claude.com/docs/en/changelog#2-1-176- https://github.com/anthropics/claude-code/releases/tag/v2.1.139- https://github.com/anthropics/claude-code/releases/tag/v2.1.145- https://github.com/anthropics/claude-code/releases/tag/v2.1.152diff --git a/07-plugins/README.md b/07-plugins/README.mdindex 7bfb8cc..802ebbd 100644--- a/07-plugins/README.md+++ b/07-plugins/README.md@@ -525,6 +525,7 @@ Example `blockedMarketplaces` with host/path regex (v2.1.119):### Additional Marketplace Features+- **Marketplace search bar (v2.1.172)**: When browsing a marketplace's plugins in `/plugin`, a search bar lets you filter the marketplace's plugins by name or keyword — handy for large marketplaces where scrolling the full list is slow.- **Default git timeout**: Increased from 30s to 120s for large plugin repositories- **Custom npm registries**: Plugins can specify custom npm registry URLs for dependency resolution- **Version pinning**: Lock plugins to specific versions for reproducible environments@@ -1115,10 +1116,11 @@ The following Claude Code features work together with plugins:----**Last Updated**: June 10, 2026-**Claude Code Version**: 2.1.170+**Last Updated**: June 15, 2026+**Claude Code Version**: 2.1.176**Sources**:- https://code.claude.com/docs/en/plugins+- https://code.claude.com/docs/en/changelog#2-1-172- https://code.claude.com/docs/en/slash-commands- https://code.claude.com/docs/en/plugin-marketplaces- https://github.com/anthropics/claude-code/releases/tag/v2.1.117diff --git a/09-advanced-features/README.md b/09-advanced-features/README.mdindex e2fd9a8..3ae0aba 100644--- a/09-advanced-features/README.md+++ b/09-advanced-features/README.md@@ -1994,6 +1994,7 @@ Since v2.1.83, administrators can deploy multiple managed settings files into a|---------|-------------|| `disableBypassPermissionsMode` | Prevent users from enabling bypass permissions || `availableModels` | Restrict which models users can select |+| `enforceAvailableModels` | (v2.1.175) When `true`, the `availableModels` allowlist *also* constrains the **Default** model — if the configured default is not in the list, Claude Code falls back to the first allowed model. User and project settings can no longer widen a managed `availableModels` list. || `allowedChannelPlugins` | Control which channel plugins are permitted || `autoMode.environment` | Configure trusted infrastructure for auto mode || `wslInheritsWindowsSettings` | Windows/WSL only (v2.1.118+): when `true`, Claude Code running inside WSL inherits managed settings from the Windows host, so enterprise policies deployed via Registry/MDM apply uniformly across the Windows and WSL shells |@@ -2327,10 +2328,11 @@ For more information about Claude Code and related features:----**Last Updated**: June 10, 2026-**Claude Code Version**: 2.1.170+**Last Updated**: June 15, 2026+**Claude Code Version**: 2.1.176**Sources**:- https://code.claude.com/docs/en/troubleshooting+- https://code.claude.com/docs/en/changelog#2-1-175- https://code.claude.com/docs/en/permission-modes- https://code.claude.com/docs/en/interactive-mode- https://code.claude.com/docs/en/settingsdiff --git a/10-cli/README.md b/10-cli/README.mdindex f201837..441e478 100644--- a/10-cli/README.md+++ b/10-cli/README.md@@ -845,6 +845,26 @@ The "ultrathink" keyword in prompts activates deep reasoning. The `/effort` menu---+## Settings.json Keys++These keys live in a `settings.json` file (`~/.claude/settings.json` for user scope, `.claude/settings.json` for project scope) rather than being passed as flags or env vars. The table below covers a few recently added UI/UX keys; for the managed `enforceAvailableModels` key, see [Advanced Features → Managed Settings](../09-advanced-features/README.md#available-managed-settings).++| Key | Description |+|-----|-------------|+| `wheelScrollAccelerationEnabled` | (v2.1.174) Set to `false` to disable mouse-wheel scroll acceleration in the fullscreen renderer. Useful when fast wheel flicks overshoot. |+| `footerLinksRegexes` | (v2.1.176) Array of regexes that render matched links as badges in the footer row. Configurable in user or managed settings. |+| `language` | Sets Claude's preferred response language and voice-dictation language (e.g. `"french"`, `"japanese"`). As of **v2.1.176** it also pins the language used for auto-generated session titles. |++```json+{+ "wheelScrollAccelerationEnabled": false,+ "language": "french",+ "footerLinksRegexes": ["https://jira\\.example\\.com/.*"]+}+```++---+## Quick Reference### Most Common Commands@@ -947,10 +967,12 @@ claude -p --output-format json "query"----**Last Updated**: June 10, 2026-**Claude Code Version**: 2.1.170+**Last Updated**: June 15, 2026+**Claude Code Version**: 2.1.176**Sources**:- https://code.claude.com/docs/en/cli-reference+- https://code.claude.com/docs/en/changelog#2-1-174+- https://code.claude.com/docs/en/changelog#2-1-176- https://code.claude.com/docs/en/settings- https://code.claude.com/docs/en/changelog- https://code.claude.com/docs/en/troubleshootingdiff --git a/CATALOG.md b/CATALOG.mdindex ab395c4..3870bdf 100644--- a/CATALOG.md+++ b/CATALOG.md@@ -82,7 +82,7 @@ Commands are user-invoked shortcuts that execute specific actions.| `/teleport` | Transfer session to another machine | Continue work remotely || `/desktop` | Open Claude Desktop app | Switch to desktop interface || `/theme` | Change color theme; v2.1.118 added custom named themes via `~/.claude/themes/<name>.json` (plugins can ship a `themes/` dir) | Customize appearance |-| `/usage` | Canonical command for usage/cost/stats — merged `/cost` and `/stats` into a single tabbed view (v2.1.118); as of v2.1.149 the cost view breaks spending down by category (skills, subagents, plugins, per-MCP-server) | Monitor quota and costs |+| `/usage` | Canonical command for usage/cost/stats — merged `/cost` and `/stats` into a single tabbed view (v2.1.118); as of v2.1.149 the cost view breaks spending down by category (skills, subagents, plugins, per-MCP-server). In the **VSCode extension** (v2.1.174), the `/usage` (Account & usage) dialog adds an attribution breakdown — cache misses, long-context cost, subagents, and per-skill / per-agent / per-plugin / per-MCP usage over 24h and 7d windows | Monitor quota and costs || `/focus` | Toggle focus view (distraction-free output display) | Reduce visual noise during long tasks || `/fork` | Fork current conversation | Explore alternatives || `/stats` | Shortcut alias that opens the stats tab of `/usage` (v2.1.118+) | Review session metrics |@@ -144,6 +144,8 @@ Claude Code supports 6 permission modes that control how tool use is authorized.Specialized AI assistants with isolated contexts for specific tasks.+> **Nested spawning (v2.1.172)**: Subagents can spawn their own subagents, nested up to 5 levels deep. Earlier versions did not allow nesting. See [04-subagents/README.md](04-subagents/README.md#restrict-spawnable-subagents) for the `Agent(agent_type)` syntax that restricts which subagents a given subagent may spawn.+### Built-in Subagents| Agent | Description | Tools | Model | When to Use |@@ -543,12 +545,14 @@ chmod +x ~/.claude/hooks/*.sh----**Last Updated**: June 2, 2026-**Claude Code Version**: 2.1.160+**Last Updated**: June 15, 2026+**Claude Code Version**: 2.1.176**Sources**:- https://code.claude.com/docs/en/overview- https://code.claude.com/docs/en/commands- https://code.claude.com/docs/en/hooks+- https://code.claude.com/docs/en/changelog#2-1-172+- https://code.claude.com/docs/en/changelog#2-1-174- https://github.com/anthropics/claude-code/releases/tag/v2.1.145- https://github.com/anthropics/claude-code/releases/tag/v2.1.154- https://code.claude.com/docs/en/pluginsdiff --git a/claude_concepts_guide.md b/claude_concepts_guide.mdindex ffc7651..c27aa78 100644--- a/claude_concepts_guide.md+++ b/claude_concepts_guide.md@@ -217,6 +217,8 @@ sequenceDiagramSubagents are specialized AI assistants with isolated context windows and customized system prompts. They enable delegated task execution while maintaining clean separation of concerns.+As of **v2.1.172**, subagents can spawn their own subagents, nested **up to 5 levels deep** — so the hierarchy is not limited to the single main → subagent layer shown below. Earlier versions did not allow any nesting.+### Architecture Diagram```mermaid@@ -3146,12 +3148,13 @@ Claude Code supports the following models with adaptive reasoning effort:- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook)----**Last Updated**: June 2, 2026-**Claude Code Version**: 2.1.160+**Last Updated**: June 15, 2026+**Claude Code Version**: 2.1.176**Sources**:- https://code.claude.com/docs/en/overview- https://code.claude.com/docs/en/hooks- https://code.claude.com/docs/en/model-config+- https://code.claude.com/docs/en/changelog#2-1-172- https://platform.claude.com/docs/en/about-claude/models/overview- https://www.anthropic.com/news/claude-opus-4-8- https://github.com/anthropics/claude-code/releases/tag/v2.1.154diff --git a/scripts/check_links.py b/scripts/check_links.pyindex 487d623..1e55040 100644--- a/scripts/check_links.py+++ b/scripts/check_links.py@@ -96,6 +96,17 @@ def main(strict: bool = False) -> int:# Strip trailing Markdown/punctuation characters the regex may over-capture# from link syntax like [text](https://url/) or **https://url)**clean_url = raw_url.rstrip(")>*_`':.,;").split("#")[0]+ # Skip bare-hostname partials. URL_RE stops at backslashes, so a+ # regex string inside a JSON config example like+ # "footerLinksRegexes": ["https://jira\\.example\\.com/.*"] is+ # captured as just "https://jira" — a hostname with no dot that is+ # not a resolvable URL but a truncated pattern. Real public URLs+ # have a dotted host; localhost-style single-label hosts are in+ # SKIP_DOMAINS already, so dropping dotless hosts here loses no+ # genuine link coverage.+ host = clean_url.split("/", 3)[2] if "://" in clean_url else ""+ if host and "." not in host.split(":", 1)[0]:+ continueurls.setdefault(clean_url, []).append(str(file_path))if not urls: