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 After Fable 5

As of the June 9, 2026 Claude Code v2.1.170 release, the current Claude Code model baseline includes Claude Fable 5:

Use Fable 5 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. Fable 5 is not the default model on any account type; choose it with /model fable, a model setting, or best where the organization has access. Use Opus 4.8 for complex planning and high-stakes refactors when Fable is unavailable or too expensive. Use Sonnet for everyday coding and documentation. Use Haiku for narrow, cheap, low-risk support work.

Recent v2.1.181~v2.1.190 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 has a 1M context window by default, supports up to 128k output tokens, and is priced at $10 per million input tokens and$50 per million output tokens. It is a covered model with 30-day data retention and is not available under zero data retention. Fable 5 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.

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.

Fable 5 has safety classifiers for domains such as cybersecurity and biology. When a request is flagged, Claude Code reruns the request on the default Opus model and shows a notice; 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.

--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 the newer sandbox.credentials policy in the same managed settings bundle as sandbox.failIfUnavailable and network allow/deny rules. Current v2.1.181~v2.1.190 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.

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.