Plan and Environment Setup

Good Claude Code work starts before the first prompt. The agent needs a clear plan boundary, a known working directory, and a verification target it can run without guessing.

Choose The Right Access Model

• Use interactive terminal sessions for product work, refactors, debugging, and long-running repo tasks.
• Use headless execution for repeatable tasks with narrow input and predictable output.
• Use remote or mobile controls only when the desktop session already has a clean workspace and branch.
• Keep plan, branch, and verification target visible in the first message.

Claude Code is available in several interfaces beyond the terminal CLI: on the web, as a desktop app, inside VS Code and JetBrains IDEs, in Slack, and in CI/CD through GitHub Actions and GitLab. Pick the interface that matches the task, but keep the same plan-and-verify discipline in each.

Installation Baseline

Prefer the official native installer for your platform. The native installer is the recommended path and automatically updates in the background to keep you on the latest version. Keep one owner for updates in team environments so prompts, hooks, and permission behavior change deliberately.

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

Other supported install methods are Homebrew (brew install --cask claude-code), WinGet (winget install Anthropic.ClaudeCode), the signed apt/dnf/apk Linux repositories, and the global npm package (npm install -g @anthropic-ai/claude-code, which requires Node.js 18 or later and installs the same native binary).

For npm-managed machines, install the stable channel explicitly when predictability matters:

npm install -g @anthropic-ai/claude-code@stable

System requirements: macOS 13.0+, Windows 10 1809+ / Windows Server 2019+, Ubuntu 20.04+, Debian 10+, or Alpine Linux 3.19+; 4 GB+ RAM; an x64 or ARM64 processor; and an internet connection.

After installing or updating, verify the basics:

claude --version
claude doctor
git status --short

The version check confirms what behavior you are debugging against. doctor catches common shell, authentication, and editor integration issues, and reports the result of the most recent background update attempt. git status --short makes accidental edits visible before the agent starts.

Update Policy

Native installs check for updates on startup and periodically while running, then apply them the next time Claude Code starts. You can control this through settings rather than ad-hoc upgrades:

• autoUpdatesChannel selects the release channel: "latest" (default, new features as soon as they ship) or "stable" (typically about one week behind, skipping releases with major regressions). Configure it via /config → Auto-update channel or in settings.json.
• minimumVersion pins a floor so an auto-update or claude update refuses to install anything older. In managed settings this enforces an organization-wide minimum.
• DISABLE_AUTOUPDATER=1 (in the env key of settings.json) stops the background check only; claude update and claude install still work. Set DISABLE_UPDATES instead to block all update paths, including manual ones.

For enterprise deployments, enforce a consistent channel and minimum version through managed settings. To apply an update immediately, run claude update.

Model Baseline Through Fable 5.1

As of the 2026-09-12 Claude Code v2.1.269 baseline, the current model surface includes Claude Fable 5.1, Claude Opus 5, and Claude Sonnet 5, with Claude Fable 5 still served as a legacy model. Fable 5.1 requires Claude Code v2.1.255 or later and became the default Fable model in v2.1.257; Opus 5 requires v2.1.219 or later. All three provide a native 1M context window:

Use Fable 5.1 for tasks larger than a single sitting: ambiguous root-cause investigations, outage debugging, architecture decisions, and long autonomous sessions where extra investigation and verification are worth the cost. The official guidance is to start most workloads on Opus 5 and move to Fable 5.1 when Opus 5 at higher effort still falls short. Neither Fable model is the default on any account type; choose Fable 5.1 with /model fable, claude --model fable, a model setting, or best where the organization has access, and Fable 5 with /model claude-fable-5. The availableModels prefix claude-fable-5 permits both. Use Opus 5 for complex planning and high-stakes refactors. Use Sonnet for everyday coding and documentation. Use Haiku for narrow, cheap, low-risk support work.

Recent v2.1.181–v2.1.220 releases tightened model validation: Haiku is restricted as a main conversation model while remaining valid for subagents, and deprecated or retired model choices now produce clearer warnings. Revalidate full model IDs in CI and customer reproduction docs when a new stable channel lands.

Fable 5.1 and Fable 5 have a 1M context window by default (also the maximum), support up to 128k output tokens, and are priced at $10 per million input tokens and$50 per million output tokens. Fable 5.1 cuts prompt-cache reads to $0.25 per million tokens (2.5the Fable 5 rate) with 5-minute cache writes at$12.50 and 1-hour cache writes at $20. Both are covered models with 30-day data retention and are not available under zero data retention unless Anthropic expressly authorizes it. Fable uses adaptive thinking on every request; MAX_THINKING_TOKENS=0, the session thinking toggle, and alwaysThinkingEnabled do not turn thinking off for Fable. Use effort levels to control depth instead. Fable 5.1's reliable knowledge cutoff is June 2026 and it will not be retired before 2027-09-01.

For custom harnesses on the Messages API, moving from claude-fable-5 to claude-fable-5-1 has three breaking changes: forced tool_choice (any/tool) returns 400 (use auto plus an explicit instruction, strict: true, or structured outputs); Fable 5.1 thinking blocks are dropped unbilled when an older model receives them; and editing system, tools, or an earlier message invalidates later thinking blocks, enforced for accounts created on or after 2026-08-31 (older accounts opt in via thinking.block_binding.prefix_mismatch_behavior). Per-message effort (mid-conversation-output-config-2026-07-01 beta), turn-scoped system messages (clear_at: "next_user_message", beta), thinking.display: "updates" (beta), and content provenance are additive. Claude Code, claude.ai, Managed Agents, and the Agent SDK keep the prefix intact, so interactive sessions are unaffected; start code migrations with /claude-api migrate this project to claude-fable-5-1.

To pin specific models per tier, set ANTHROPIC_DEFAULT_FABLE_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, or ANTHROPIC_DEFAULT_HAIKU_MODEL to a full model name. To force a single model regardless of alias, set ANTHROPIC_MODEL. To disable prompt caching only for Fable, set DISABLE_PROMPT_CACHING_FABLE=1.

Claude Code v2.1.236 adds ANTHROPIC_DEFAULT_MODEL as a lower-precedence default for new sessions. It is used only when --model, ANTHROPIC_MODEL, settings model, and organization defaults do not select a model. It does not override special values such as default, inherit, opusplan, or haiku, organization allowlists, or account availability; use it as a default, not a reproducibility pin.

On v2.1.242+, modelPicker is accepted only at user or managed scope; project and local values are ignored. The highest-precedence object replaces the entire lower-precedence lineup instead of merging with it. replaceBuiltInOptions: true hides the built-in rows except Default and the current-session row, while availableModels still filters the final list.

{
  "modelPicker": {
    "options": [
      { "model": "sonnet", "label": "Daily" },
      { "model": "opus", "description": "Complex planning and refactors" }
    ],
    "replaceBuiltInOptions": true
  },
  "promptCacheTtl": "1h",
  "subagentPromptCacheTtl": "5m"
}

Both cache settings accept only "5m" or "1h" and can appear in any settings file. The main setting covers interactive, -p, SDK, and inline-helper requests; the subagent setting covers subagents, workflows, background work, compaction, and title generation. The exact precedence is FORCE_PROMPT_CACHING_5M, then CLAUDE_CODE_PROMPT_CACHE_TTL (or CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL), then the settings key, and finally ENABLE_PROMPT_CACHING_1H. Check all four layers before assuming a file value won.

The v2.1.243 changelog also announces managed modelPricing for contracted rates and discount multipliers in /cost, the status line, and telemetry. As of this re-check, the current Settings reference does not publish its configuration schema. Treat the feature as release-tracked: use only an organization-provided managed policy and do not invent a local JSON shape. Cost displays remain estimates, not invoices.

Feedback drafting is controlled separately at user or managed scope with "feedbackDrafts": "notify" | "quiet" | "off"; project and local values are ignored. notify is the default and shows drafts and notifications, quiet keeps the drafts for /feedback without notifications, and off removes the SendFeedback tool. CLAUDE_CODE_SEND_FEEDBACK=0 disables it for one launched session.

Fable 5.1 and Fable 5 have safety classifiers for domains such as cybersecurity and biology. When a request is flagged, Claude Code reruns it on another model and shows a notice: biology flags go to Opus 5 and cybersecurity flags to Opus 4.8 (Opus 5 itself reruns cybersecurity flags on Opus 4.8 and refuses biology flags). Set switchModelsOnFlag: false to disable the automatic switch; on third-party providers, set ANTHROPIC_DEFAULT_OPUS_MODEL so fallback has a target. Run /model fable again to return. If fallback triggers before any unusual prompt, workspace context such as CLAUDE.md or git status may be enough to trip the classifier. Start with claude --safe-mode to debug whether customizations are responsible.

Fable 5 and Mythos 5 were suspended for all users on 2026-06-12 under US export controls (~19 days); Fable 5 was restored globally on 2026-07-01 with an improved safety classifier targeting the reported vulnerability-finding behavior, so the automatic fallback follows that classifier. For Pro/Max/Team/ select Enterprise, Fable 5 is included up to 50% of weekly usage limits through 2026-07-07, then via usage credits. The Fable 5.1 announcement did not change plan inclusion, so treat these rules as the Fable-family baseline until a plan-specific notice lands. Mythos 5 shared Fable 5's specs but omitted the safety classifiers; its successor Mythos 5.1 (claude-mythos-5-1) shares Fable 5.1's specs and pricing with a different safeguard level. Both are available only through Project Glasswing (approved customers vetted through the Cyber and Life Sciences Verification Programs, currently US organizations), so they cannot be selected via /model.

--safe-mode disables customizations such as CLAUDE.md, skills, MCP servers, plugins, and hooks. Git status and directory names are still included, so security- or biology-heavy repositories may still trigger fallback even in safe mode.

For availability failures, configure an explicit fallback chain:

{
  "fallbackModel": ["claude-opus-4-8", "claude-sonnet-4-6"]
}

/model now matters operationally because v2.1.153 made picker Enter and /model <name> save the model as the default for future sessions. Press s in the picker when the switch should apply only to the current session. Resumed sessions keep the model saved in the transcript unless that model has been retired.

/status
/model
claude --model fable
claude --model opus
claude --fallback-model opus,sonnet

For reproducible CI, benchmarks, and customer investigations, prefer full model names over moving aliases.

Repository Setup

Start each repository with three files or conventions:

• CLAUDE.md for durable project rules.
• A test command the agent can run without extra discovery.
• A branch or worktree naming convention for parallel work.

Example first prompt:

Work in this repository only.
Goal: add locale-aware home filtering for English content.
Before editing, inspect routing, source loading, and tests.
After editing, run typecheck and the focused E2E test.
Do not touch unrelated files.

Permission Policy

The best permission policy is boring and explicit. Allow read-only discovery broadly, but keep write operations, network calls, package installs, and destructive shell commands visible. If the project uses denied domains or allowlists, record the reason in team onboarding docs.

Claude Code uses named permission modes. Cycle through default → acceptEdits → plan with Shift+Tab during a session, with the current mode shown in the status bar. You can also set a preferred default mode in settings.json (valid values include default, acceptEdits, plan, and bypassPermissions). acceptEdits removes the prompt for plain file edits for the session; reserve bypassPermissions for sandboxed throwaway environments only.

Auto mode is more capable than earlier builds, including stronger detection for data exfiltration patterns, but it is still not a replacement for scoped network rules, denied domains, and explicit permission policy.

For sandboxed environments, include sandbox.credentials in the same managed settings bundle as sandbox.failIfUnavailable and network allow/deny rules. Use sandbox.network.strictAllowlist when requests must fail closed outside the allowlist. Since v2.1.216, sandbox.filesystem.disabled can turn off filesystem isolation while preserving network isolation for environments that provide their own filesystem boundary. Current v2.1.181–v2.1.269 builds also improve destructive-command approval inside the sandbox and Windows PowerShell sandbox behavior, so validate both Bash and PowerShell paths on native Windows runners.

The v2.1.246–247 window adds a startup warning for Bash allow rules whose wildcard appears before a subcommand, rejects control or invisible characters in marketplace names and output, and prevents an API key configured for a third-party gateway from being attached to Anthropic telemetry requests.

Setup Checklist

• The shell opens in the expected repository.
• Authentication is valid.
• The current branch is correct.
• CLAUDE.md exists and is short enough to obey.
• Tests and typecheck can run locally.
• The user knows which commands may be expensive or destructive.