From 6117145837111815b95477168c0020788e040ffc Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Mon, 23 Feb 2026 12:59:28 +0100 Subject: [PATCH] docs: integrate veille hebdo Anthropic 17-23 fev 2026 (+177 lignes guide) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit P1 - Prompt caching + env vars: - Strategy 6 cost optimization: cache_control API, pricing (write 1.25x, read 0.1x), break-even 2 hits - CLAUDE_CODE_DISABLE_1M_CONTEXT + CLAUDE_CODE_SIMPLE ajoutés à la table env vars principale P2 - Model deprecations + agents: - Warning claude-3-haiku-20240307 deprecated 19 fev / retirement 20 avril 2026 - Frontmatter fields: background: true (v2.1.49+) + isolation: worktree (v2.1.50+) - Section Background Agents: comportement non-blocking, gestion (ctrl+f, double ESC) - Section claude agents CLI: commande + output annoté P3 - Worktree isolation native + security cross-ref: - Native worktree features: --worktree flag, isolation declaratif, WorktreeCreate/WorktreeRemove hooks - §7.4 Security Hooks: cross-ref Claude Code Security scanner (research preview) Eval: docs/resource-evaluations/2026-02-22-veille-hebdo-anthropic-17-23-fev.md (score 3/5) Stats: 19K → 20K lignes (20 440 total) Co-Authored-By: Claude Sonnet 4.6 --- CHANGELOG.md | 20 ++ CLAUDE.md | 2 +- README.md | 2 +- .../2026-02-22-fp-dev-issue-tracker.md | 108 +++++++++++ ...-02-22-veille-hebdo-anthropic-17-23-fev.md | 55 ++++++ docs/resource-evaluations/watch-list.md | 1 + guide/third-party-tools.md | 1 + guide/ultimate-guide.md | 177 ++++++++++++++++++ 8 files changed, 364 insertions(+), 2 deletions(-) create mode 100644 docs/resource-evaluations/2026-02-22-fp-dev-issue-tracker.md create mode 100644 docs/resource-evaluations/2026-02-22-veille-hebdo-anthropic-17-23-fev.md diff --git a/CHANGELOG.md b/CHANGELOG.md index afe8c23..3c87118 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added +- **guide/ultimate-guide.md** — 7 sections ajoutées suite à veille hebdo Anthropic 17-23 fev 2026 (éval: `docs/resource-evaluations/2026-02-22-veille-hebdo-anthropic-17-23-fev.md`, score 3/5) + + **P1 — Prompt caching + env vars manquantes** + - §1.7 Cost Optimization — Strategy 6 : prompt caching API (`cache_control`, prix cache write/read, break-even, 4 breakpoints max) + - §Appendix Environment Variables — `CLAUDE_CODE_DISABLE_1M_CONTEXT` (v2.1.50+) et `CLAUDE_CODE_SIMPLE` (v2.1.50+) ajoutés à la table principale + + **P2 — Model deprecations + agents** + - §1.7 Pricing Model — Warning box : `claude-3-haiku-20240307` deprecated 19 fev 2026, retirement 20 avril 2026, migration vers `claude-haiku-4-5-20251001` + - §4.2 Frontmatter Fields — `background: true` (non-blocking, v2.1.49+) et `isolation: "worktree"` (spawn isolé, v2.1.50+) ajoutés au tableau + - §4.4 Best Practices — Nouvelle section "Background Agents" : comportement, gestion (ctrl+f, double ESC/ctrl+C), comparatif mode default vs background + - §4.4 Best Practices — Nouvelle section "`claude agents` CLI" : commande + exemple d'output annoté (v2.1.50+) + + **P3 — Worktree isolation native + cross-ref sécurité** + - §9.11 Git Worktrees — Nouvelle sous-section "Claude Code Native Worktree Features" : `--worktree`/`-w` flag, `isolation: "worktree"` déclaratif, hooks `WorktreeCreate`/`WorktreeRemove` avec exemple `settings.json` complet + - §7.4 Security Hooks — Callout cross-ref vers `security-hardening.md#claude-code-as-security-scanner-research-preview` + +- **docs/resource-evaluations/2026-02-22-veille-hebdo-anthropic-17-23-fev.md** — Fiche d'évaluation veille hebdo Anthropic 17-23 fev 2026 (score 3/5, intégration partielle) + +- **README.md + CLAUDE.md** — Mise à jour stat guide : `~19K lines` → `~20K lines` (20 440 lignes) + - **guide/diagrams/09-cost-and-optimization.md + guide/ultimate-guide.md §2.5** — Budget modifier for model selection decision flow - Le diagramme "Model Selection Decision Flow" assumait implicitement un budget illimité (Max/API) — angle mort signalé par la communauté - Ajout d'un **Budget modifier table** : Max/API → Opus plan + Sonnet impl ; Pro/Teams Standard → Sonnet plan + Haiku impl (tâches mécaniques) diff --git a/CLAUDE.md b/CLAUDE.md index ecda536..6ea04bd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,7 +10,7 @@ This repository is the **comprehensive documentation for Claude Code** (Anthropi ``` guide/ # Core documentation -├── ultimate-guide.md # Main guide (~19K lines, the reference) +├── ultimate-guide.md # Main guide (~20K lines, the reference) ├── cheatsheet.md # 1-page printable summary ├── architecture.md # How Claude Code works internally ├── methodologies.md # TDD, SDD, BDD workflows diff --git a/README.md b/README.md index f340937..8a2933f 100644 --- a/README.md +++ b/README.md @@ -158,7 +158,7 @@ graph LR ``` 📦 claude-code-ultimate-guide/ │ -├─ 📖 guide/ Core Documentation (~19K lines) +├─ 📖 guide/ Core Documentation (~20K lines) │ ├─ ultimate-guide.md Complete reference, 10 sections │ ├─ cheatsheet.md 1-page printable │ ├─ architecture.md How Claude Code works internally diff --git a/docs/resource-evaluations/2026-02-22-fp-dev-issue-tracker.md b/docs/resource-evaluations/2026-02-22-fp-dev-issue-tracker.md new file mode 100644 index 0000000..ec36cc3 --- /dev/null +++ b/docs/resource-evaluations/2026-02-22-fp-dev-issue-tracker.md @@ -0,0 +1,108 @@ +# Resource Evaluation: fp.dev — Agent-Native Issue Tracking + +**Evaluated**: 2026-02-22 +**Evaluator**: Claude Sonnet 4.6 + technical-writer agent challenge +**Target Guide**: Claude Code Ultimate Guide +**Source**: https://fp.dev/ + LinkedIn post (community) + +--- + +## Executive Summary + +**Resource**: fp.dev — "Agent-native issue tracking for ambitious Claude Code users" +**URL**: https://fp.dev/ + +**Initial Score**: 3/5 +**Challenged Score**: 2/5 +**Final Score**: **2/5 (Marginal — Watchlist)** + +**Decision**: **Ne pas intégrer activement. Ajouter dans Known Gaps + Watch List.** + +--- + +## 📄 Résumé du contenu + +- **fp.dev** est un outil de tracking d'issues local-first conçu spécifiquement pour Claude Code +- Issues stockées en `.md` dans `/.claude/` — git-committables (différentiateur réel vs Tasks API) +- Workflow via skills custom (`/fp-plan`, `/fp-implement`, `/fp-review`) + CLI (`fp tree`, `fp issue list`, `fp issue show`, `fp review`) +- Résout le "context rot" : permet de `/clear` la session sans perdre l'état projet +- App desktop Mac (Apple Silicon uniquement) + UI code review avec diff viewer intégré +- Zéro dépendance externe, zéro MCP server +- Installation : `curl -fsSL https://setup.fp.dev/install.sh | sh -s && fp setup claude && fp init` + +--- + +## 🎯 Score de pertinence (1-5) + +| Score | Signification | +|-------|---------------| +| 5 | Essentiel - Gap majeur dans le guide | +| 4 | Très pertinent - Amélioration significative | +| 3 | Pertinent - Complément utile | +| 2 | Marginal - Info secondaire | +| 1 | Hors scope - Non pertinent | + +**Score final : 2/5** + +**Justification** : Problème adressé réel mais déjà couvert partiellement par le guide (fresh-context-loop.sh, Tasks API native). Un seul différentiateur solide (issues .md git-committables). Adoption insuffisante, restriction Apple Silicon disqualifiante pour recommandation large. + +--- + +## ⚖️ Comparatif + +| Aspect | fp.dev | Guide actuel | +|--------|--------|-------------| +| Context rot / session clear | ✅ Issues .md persistées | ✅ `fresh-context-loop.sh` (Ralph Wiggum pattern) | +| Task management structuré | ✅ CLI + skills dédiés | ✅ Tasks API native | +| Issues git-committables | ✅ (.md files dans repo) | ❌ Manquant | +| Code review avec diff viewer | ✅ UI locale dédiée | ❌ Non couvert | +| Multi-plateforme | ❌ Desktop = Apple Silicon only | ✅ N/A | +| MCP intégration | ❌ Pas de MCP | ✅ Couvert dans le guide | +| Équipes / sync | ❌ Local only | ✅ Tasks API multi-agent | + +--- + +## 🔥 Challenge (technical-writer) + +Arguments pour descendre à 2/5 : + +1. **Redondance** : `/clear` + Tasks API couvre déjà le problème principal +2. **Restriction plateforme** : Apple Silicon only pour le desktop = dealbreaker Linux/Windows +3. **Signaux d'adoption manquants** : Pas de GitHub stars, pas de release cadence documentée → risque d'abandon +4. **Mauvaise catégorisation** : Ne va pas aux côtés de Gas Town/multiclaude (multi-agent orchestration) — fp.dev est du task tracking +5. **Un vrai différentiateur** : Issues `.md` git-committables → mais insuffisant seul pour 3/5 + +**Score ajusté** : 2/5 +**Risques de non-intégration** : Faibles. Le guide couvre déjà le problème. La valeur est dans documenter le GAP (markdown-based issue tracking) pas nécessairement fp.dev. + +--- + +## ✅ Fact-Check + +| Affirmation | Vérifiée | Source | +|-------------|----------|--------| +| Issues stockées en `.md` dans `/.claude/` | ✅ | fp.dev (WebFetch) + Perplexity | +| CLI : `fp tree`, `fp issue list`, `fp issue show`, `fp review` | ✅ | WebFetch direct | +| Installation : `fp setup claude` + `fp init` | ✅ | fp.dev + Perplexity | +| Local-first, no external services | ✅ | fp.dev | +| Mac desktop app = Apple Silicon requis | ✅ | fp.dev | +| Skills `/fp-plan`, `/fp-implement`, `/fp-review` | ✅ | Description + WebFetch | + +Zéro hallucination. Toutes les claims vérifiées. + +--- + +## 📍 Recommandations + +**Score < 3 → Watchlist, pas d'intégration directe.** + +Actions effectuées : +1. ✅ Ajout dans `docs/resource-evaluations/watch-list.md` +2. ✅ Ajout du gap "Agent-native issue tracking (markdown-based, git-committable)" dans `guide/third-party-tools.md` Known Gaps + +**Trigger de re-évaluation** : GitHub stars visibles + release cadence documentée + au moins un write-up praticien en production. + +--- + +**Évaluation complétée** : 2026-02-22 +**Prochaine révision** : Sur trigger (adoption signals) diff --git a/docs/resource-evaluations/2026-02-22-veille-hebdo-anthropic-17-23-fev.md b/docs/resource-evaluations/2026-02-22-veille-hebdo-anthropic-17-23-fev.md new file mode 100644 index 0000000..2cf7938 --- /dev/null +++ b/docs/resource-evaluations/2026-02-22-veille-hebdo-anthropic-17-23-fev.md @@ -0,0 +1,55 @@ +--- +title: "Veille hebdomadaire Anthropic (17-23 fev 2026)" +type: "weekly-watch" +date: "2026-02-22" +score: 3 +action: "partial-integration" +sources: + - "Texte copie (digest agregateur, pas d'URL)" +--- + +# Veille hebdomadaire Anthropic (17-23 fev 2026) + +## Resume + +Digest agregateur couvrant Sonnet 4.6, Claude Code Security, CC v2.1.49-v2.1.50, Automatic Prompt Caching API, model deprecations, et activite Twitter. + +## Score: 3/5 + +**Justification**: Digest de sources primaires (blog Anthropic, CHANGELOG GitHub, Twitter). 50% deja documente dans le guide. La valeur reelle = signal de 2-3 gaps : prompt caching API (zero couverture), model deprecations (zero couverture), env vars manquantes. Score 3 (baisse de 4 → 3 apres challenge) : c'est un trigger de recherche, pas une source citable — pas d'URL, claims API non verifiables directement. + +## Gaps identifies + +| Gap | Localisation | Priorite | +|-----|-------------|----------| +| Prompt caching API (`cache_control`) | guide/ultimate-guide.md (Cost Optimization) | **P1** | +| `CLAUDE_CODE_DISABLE_1M_CONTEXT` env var | guide/ultimate-guide.md (env vars table) | **P1** | +| `CLAUDE_CODE_SIMPLE` env var clarification | guide/ultimate-guide.md (env vars table) | **P1** | +| Model deprecations (Haiku 3 → 20 avril 2026) | guide/ultimate-guide.md ou architecture.md | P2 | +| `background: true` agent field | guide/ultimate-guide.md (agents section) | P2 | +| `claude agents` CLI command | guide/ultimate-guide.md (agents section) | P2 | +| Worktree hooks `WorktreeCreate`/`WorktreeRemove` | guide/ultimate-guide.md (worktree section) | P3 | + +## Fact-Check + +| Affirmation | Statut | Source | +|-------------|--------|--------| +| Sonnet 4.6 = default model | ✅ Verifie | ultimate-guide.md:1765 | +| CC v2.1.49/v2.1.50 dates 19-20 fev | ✅ Verifie | claude-code-releases.md:27-51 | +| Claude Code Security research preview | ✅ Verifie | security-hardening.md:780-832 | +| Haiku 3 deprecated 19 fev 2026, retirement 20 avril | ✅ Verifie | Perplexity → platform.claude.com/docs/model-deprecations | +| "Automatic" Prompt Caching (zero config) | ⚠️ Incorrecte | Anthropic utilise des breakpoints **explicites** (`cache_control`), pas automatiques. Perplexity confirme : "developer-controlled through explicit cache breakpoints, not automatic" | +| Sonnet 3.7 / Haiku 3.5 retires | ⚠️ Non verifie | Pas retrouve dans sources Perplexity. A verifier sur docs.anthropic.com/release-notes | +| Pricing prompt caching : 90% de reduction | ✅ Verifie | Cache reads = 0.1x base price (Perplexity + docs Anthropic) | + +## Actions P1 (effectuees) + +1. **Prompt caching** → Strategy 6 ajoutee dans Cost Optimization Strategies (ultimate-guide.md ~1912) +2. **Env vars** → `CLAUDE_CODE_DISABLE_1M_CONTEXT` et `CLAUDE_CODE_SIMPLE` ajoutes a la table principale (ultimate-guide.md ~19862) + +## Challenge (technical-writer) + +- **Score ajuste** : 3/5 (baisse de 4 → 3) +- **Raison** : Digest sans URL = source non citable. 50% deja couvert. La valeur = trigger de recherche primaire. +- **Risque principal** : Claim "automatic prompt caching" est incorrect — Anthropic requiert `cache_control` explicite. Ne pas integrer cette formulation. +- **Next steps** : Verifier Sonnet 3.7/Haiku 3.5 sur docs officiels avant integration P2. diff --git a/docs/resource-evaluations/watch-list.md b/docs/resource-evaluations/watch-list.md index 56da713..ba6baf0 100644 --- a/docs/resource-evaluations/watch-list.md +++ b/docs/resource-evaluations/watch-list.md @@ -16,6 +16,7 @@ Trigger reached → re-evaluation → Integrate (Graduated) / Drop (Dropped) | Resource | Type | Added | Why Watching | Re-eval Trigger | |----------|------|-------|--------------|-----------------| +| [fp.dev](https://fp.dev/) | Tool | 2026-02-22 | Agent-native issue tracking pour Claude Code. Un vrai différentiateur (issues .md git-committables) mais adoption insuffisante, Apple Silicon only, redondant avec Tasks API. Score 2/5. | GitHub stars visibles + release cadence + write-up praticien en prod | | [ICM](https://github.com/rtk-ai/icm) | MCP | 2026-02-12 | Pre-v1 (1 star, 11 commits) | First release + >20 stars | | [System Prompts](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools) | Tool | 2026-01-26 | Redundant with official sources. Re-evaluated 2026-02-13 (Opus 4.6 update): still 2/5. | Anthropic confirms CLI prompts not published | | [o16g — Outcome Engineering](https://o16g.com/) | Manifesto | 2026-02-13 | Emerging framework by Cory Ondrejka (CTO Onebrief, co-creator Second Life, ex-VP Google/Meta). 16 principles for shifting from "code writing" to "outcome engineering". Honeycomb endorsement. No Claude Code-specific content yet. Memetic potential (naming follows i18n/k8s pattern). | Term adopted in >3 independent AI engineering resources OR author publishes tool-specific implementation | diff --git a/guide/third-party-tools.md b/guide/third-party-tools.md index b4e276d..338fba9 100644 --- a/guide/third-party-tools.md +++ b/guide/third-party-tools.md @@ -382,6 +382,7 @@ As of February 2026, the community tooling ecosystem has notable gaps: | **Visual hooks editor** | No GUI for managing hooks in `settings.json` — requires JSON editing | | **Unified admin panel** | No single dashboard combining config, sessions, cost, and MCP management | | **Session replay** | ✅ **FILLED**: Entire CLI (launched Feb 2026) provides rewindable checkpoints with full context replay | +| **Agent-native issue tracking** | No established tool for markdown-based, git-committable issue tracking with Claude Code. [fp.dev](https://fp.dev/) is an early-stage solution (local-first, `/fp-plan` + `/fp-implement` skills, diff viewer) but lacks adoption signals and requires Apple Silicon for the desktop app. The Tasks API covers state persistence but issues aren't git-committable. | | **Per-MCP-server profiler** | No way to measure token cost attributable to each MCP server individually | | **Cross-platform config sync** | No tool syncs Claude Code config across machines (must manual copy `~/.claude/`) | diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md index cd8372b..2b407bf 100644 --- a/guide/ultimate-guide.md +++ b/guide/ultimate-guide.md @@ -1771,6 +1771,8 @@ Claude Code uses **Claude Sonnet 4.6** by default (as of Feb 2026): **Reality check**: A typical 1-hour session costs **$0.10 - $0.50** depending on usage patterns. +> **Model deprecations (Feb 2026)**: `claude-3-haiku-20240307` (Claude 3 Haiku) was deprecated on **February 19, 2026** with **retirement scheduled for April 20, 2026**. If your CLAUDE.md, agent definitions, or scripts hardcode this model ID, migrate to `claude-haiku-4-5-20251001` (Haiku 4.5) before April 2026. Source: [platform.claude.com/docs/model-deprecations](https://platform.claude.com/docs/model-deprecations) + #### 200K vs 1M Context: Performance, Cost & Use Cases The 1M context window (beta, API + usage tier 4 required) is a significant capability jump — but community feedback consistently frames it as a **niche premium tool**, not a default. @@ -1911,6 +1913,45 @@ claude --model opus "Design the entire authentication system" # Shared context, single response ``` +**Strategy 6: Use prompt caching for repeated context (API)** + +If you call the Anthropic API directly (e.g., for custom agents or pipelines), prompt caching cuts costs by up to 90% on repeated prefixes. + +```python +# Mark stable sections with cache_control +response = client.messages.create( + model="claude-sonnet-4-6-20250514", + max_tokens=1024, + system=[ + { + "type": "text", + "text": "", + "cache_control": {"type": "ephemeral"} # Cache this prefix + } + ], + messages=[{"role": "user", "content": "Fix the bug in auth.ts"}] +) +``` + +**Prompt caching economics**: + +| Operation | Cost multiplier | TTL | +|-----------|-----------------|-----| +| Cache write | 1.25x base price | 5 minutes (default) | +| Cache write (extended) | 2x base price | 1 hour | +| Cache read (hit) | 0.1x base price | — | +| Latency reduction | Up to 85% for long prompts | — | + +**Break-even**: 2 cache hits with 5-minute TTL. After that, pure savings. + +**Rules**: +- Max **4 cache breakpoints** per request +- Cache key = exact prefix match (single character change = cache miss) +- Place breakpoints after large stable sections: system prompt, tool definitions, codebase context +- For Claude Code itself: caching is handled automatically by the CLI — this applies to API-based workflows you build on top of Claude + +> Docs: [prompt caching](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching) + #### Tracking Costs **Real-time tracking**: @@ -5500,6 +5541,8 @@ disallowedTools: | `skills` | ❌ | Skills to inherit | | `disallowedTools` | ❌ | Tools to block | | `memory` | ❌ | Pre-populated memory context (v2.1.32+) | +| `background` | ❌ | Always run as background task — non-blocking (v2.1.49+) | +| `isolation` | ❌ | `"worktree"` — spawn agent in isolated git worktree (v2.1.50+) | **New in v2.1.32**: The `memory` field enables pre-populated agent context: @@ -5663,6 +5706,64 @@ Before deploying a custom agent, validate against these criteria: > **Automated audit**: Run `/audit-agents-skills` for a comprehensive quality audit across all agents, skills, and commands. Scores each file on 16 criteria with weighted grading (32 points for agents/skills, 20 for commands). See `examples/skills/audit-agents-skills/` for the full scoring methodology. +### Background Agents (v2.1.49+) + +The `background: true` field makes an agent always run non-blocking — the parent session continues immediately instead of waiting for the agent to finish. + +```yaml +--- +name: test-runner +description: Run the full test suite after every significant change +model: sonnet +tools: Bash +background: true # Non-blocking — parent continues without waiting +--- + +Run `npm test` and report results. Flag failures with file + line number. +``` + +**Vs. standard agents:** + +| Mode | Behavior | Use when | +|------|----------|----------| +| Default | Parent waits for agent output | Need result before continuing | +| `background: true` | Agent runs in parallel, parent continues | Fire-and-forget (tests, linting, notifications) | + +**Managing background agents:** + +```bash +# List running agents +ctrl+f # Opens agent manager overlay + +# Kill all background agents (double-press within 3s) +ctrl+c ctrl+c +# or +ESC ESC +``` + +### `claude agents` CLI (v2.1.50+) + +List all configured agents across global and project directories: + +```bash +claude agents +``` + +**Example output:** + +``` +Global agents (~/.claude/agents/): + ├── code-reviewer [sonnet] — Code quality reviews, security audits + ├── test-runner [sonnet] [background] — Run full test suite + └── security-audit [opus] — OWASP Top 10, auth, encryption + +Project agents (.claude/agents/): + ├── backend-arch [opus] — API design, database schemas + └── docs-writer [haiku] — Generate docs from code +``` + +Useful for debugging agent discovery issues or auditing which agents are available in a project. + ## 4.5 Agent Examples ### Example 1: Code Reviewer Agent @@ -8130,6 +8231,8 @@ Security hooks are critical for protecting your system. > **Advanced patterns**: For comprehensive security including Unicode injection detection, MCP config integrity verification, and CVE-specific mitigations, see [Security Hardening Guide](./security-hardening.md). +> **Claude Code Security (research preview)**: Anthropic offers a dedicated codebase vulnerability scanner that traces data flows across files, challenges findings internally before surfacing them (adversarial validation), and generates patch suggestions. Separate from the Security Auditor Agent above — waitlist access only. See [Security Hardening Guide → Claude Code as Security Scanner](./security-hardening.md#claude-code-as-security-scanner-research-preview). + ### Recommended Security Rules ```bash @@ -13824,6 +13927,78 @@ git worktree remove --force .worktrees/old-feature - [`examples/commands/git-worktree-remove.md`](../examples/commands/git-worktree-remove.md) — Remove - [`examples/commands/git-worktree-clean.md`](../examples/commands/git-worktree-clean.md) — Clean +### Claude Code Native Worktree Features (v2.1.49–v2.1.50) + +Claude Code has built-in worktree integration beyond the manual `git worktree` workflow above. + +#### Start Claude in an isolated worktree + +```bash +# --worktree / -w flag: creates a temporary worktree based on HEAD +claude --worktree +claude -w +``` + +The worktree is created automatically, Claude runs inside it, and it is cleaned up on exit (if no changes were made). + +#### Declarative isolation in agent definitions + +Set `isolation: "worktree"` in an agent's frontmatter to automatically spawn it in a fresh worktree every time (v2.1.50+): + +```yaml +--- +name: refactoring-agent +description: Large-scale refactors that must not pollute the main working tree +model: opus +isolation: "worktree" # Each invocation gets its own isolated checkout +--- + +Perform the requested refactoring. Commit your changes inside the worktree. +``` + +This replaces the earlier pattern of manually passing `isolation: "worktree"` to each Task tool call. + +#### Custom VCS setup with hook events (v2.1.50+) + +Two new hook events fire around agent worktree lifecycle: + +| Event | Fires | Use case | +|-------|-------|----------| +| `WorktreeCreate` | When an agent worktree is created | Set up DB branch, copy .env, install deps | +| `WorktreeRemove` | When an agent worktree is torn down | Clean up DB branch, delete temp credentials | + +```json +// .claude/settings.json +{ + "hooks": { + "WorktreeCreate": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "scripts/worktree-setup.sh $CLAUDE_WORKTREE_PATH" + } + ] + } + ], + "WorktreeRemove": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "scripts/worktree-teardown.sh $CLAUDE_WORKTREE_PATH" + } + ] + } + ] + } +} +``` + +Typical `worktree-setup.sh`: create a Neon/PlanetScale DB branch, copy `.env.local`, run `npm install`. + ### Database Branch Isolation with Worktrees **Modern pattern (2024+):** Combine git worktrees with database branches for true feature isolation. @@ -19860,6 +20035,8 @@ Set these in your shell profile (`~/.zshrc`, `~/.bashrc`, or Windows System Prop | `ANTHROPIC_SMALL_FAST_MODEL` | Fast model for simple tasks | `claude-haiku-4-20250514` | | `BASH_DEFAULT_TIMEOUT_MS` | Bash command timeout | `60000` | | `ANTHROPIC_AUTH_TOKEN` | Alternative auth token | Your auth token | +| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Disable 1M context window support (v2.1.50+) | `true` | +| `CLAUDE_CODE_SIMPLE` | Fully minimal mode: disables skills, agents, MCP, hooks, CLAUDE.md loading (v2.1.50+) | `true` | ### Finding Your Paths