Claude Code

Claude Code is an agentic CLI. You speak in natural language; it reads files, runs commands, edits code, and ships work. Everything else is configuration around that loop.

The agentic loop runs in three blended phases — gather context, take action, verify results — and uses built-in tools (Read, Edit, Write, Bash, Grep, Glob, WebFetch, Task) to touch your project. Each tool call feeds the next decision. You extend this loop by adding knowledge, connections, or constraints — without ever changing the loop itself.

Four supported installers. The native script is the only one that auto-updates in the background; Homebrew and winget need manual upgrades. The npm path still works but is deprecated — if you're new, don't start there.

# Official install script
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew
brew install --cask claude-code
brew upgrade claude-code   # manual upgrade

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

# winget
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode  # manual

# Start in the current project
cd your-project && claude

# Version / update / health
claude --version
claude update
claude doctor

# Force reinstall if update misbehaves
claude install --force

# Auth
claude   # prompts /login on first run

Every flag is also available via config file or an env var. The CLI is the canonical source — the full CLI reference lists everything including less-used diagnostic flags.

Memorize Esc, Esc Esc, Shift+Tab, Ctrl+B, and Alt/Option+P before anything else. Full list in the interactive mode reference.

Type / to open the menu; continue typing to filter. Unknown commands suggest the closest match. Full catalog in the commands reference.

Daily drivers

Project & code

Extensions & integrations

Session & environment

Toggle with Shift+Tab. The current mode shows under the prompt. Permission rules layer on top — see the IAM & permissions docs.

Rule evaluation order

Permission rules evaluate deny → ask → allow. First match wins. Use Tool alone or Tool(specifier) — for example, Bash(git push:*) or Read(./.env*). MCP server rules use the server name: mcp__github (whole server) or an exact tool like mcp__github__get_issue. Wildcards on tool names don't exist.

Claude Code resolves aliases per-provider. On the Anthropic API, opus → Opus 4.7 and sonnet → Sonnet 4.6. On Bedrock / Vertex / Foundry, opus → Opus 4.6 and sonnet → Sonnet 4.5 (newer models available by explicit name or pinning env var). Always pin versions in production.

Current model aliases

Switching model

# Launch with a specific model
claude --model claude-sonnet-4-6
claude --model claude-opus-4-7

# Mid-session
/model sonnet
/model opus
/model opusplan

# While typing a prompt
Alt+P  # or Option+P on macOS

Effort levels

Loaded automatically at session start. One per project root, plus a user-global file at ~/.claude/CLAUDE.md. Edit inline via /memory. The first 200 lines or 25 KB — whichever comes first — are loaded into every session's context.

Example skeleton

# BrandName — project management SaaS
  
Stack: Next.js 15 · TypeScript · Drizzle + Postgres · Tailwind.
Package manager: pnpm. Node 20.

## Commands
- Dev: pnpm dev
- Test: pnpm test  (Vitest, watch by default)
- Lint: pnpm lint --fix

## Conventions
- Commit style: Conventional Commits.
- Server components by default; mark client with "use client".
- Never edit db/migrations/** — generate via pnpm db:generate.

## Refs
@docs/architecture.md
@docs/api-contract.md

Skills and commands have converged. .claude/commands/ still works; .claude/skills/ is the recommended home — it supports auto-invocation, supporting files, subagent execution, and the Agent Skills open standard.

Authoring a custom command

// .claude/commands/commit.md
---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
argument-hint: [message]
description: Create a conventional commit
model: claude-haiku-4-5
---

## Context
- Status: !`git status`
- Diff: !`git diff HEAD`
- Branch: !`git branch --show-current`
- Recent: !`git log --oneline -10`

## Task
Create a single Conventional Commits commit.
Message hint from user: $ARGUMENTS

Authoring a skill

// .claude/skills/api-conventions/SKILL.md
---
name: api-conventions
description: API design rules for this codebase. Use when writing
  or reviewing any route under app/api or services/*.
allowed-tools: Read, Grep, Glob
---

# API conventions

- REST nouns; no verbs in paths.
- Validate inputs with Zod at the route boundary.
- Errors: return { error: { code, message } }, HTTP code matches.
- Server components fetch via typed client in lib/api/.

Subagents run in an isolated context window with a custom system prompt and a whitelisted toolset. Use them when a task would pollute the main conversation, or when you want a proactive expert that jumps in automatically. They return a summary, not a full transcript — zero main-context cost.

// .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Proactively reviews code for quality, security,
  maintainability. MUST BE USED immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior reviewer. When invoked:
1. Run git diff to see recent changes.
2. Check for: readability, naming, duplication, error handling,
   exposed secrets, input validation, test coverage, performance.
3. Output feedback by priority: Critical · Warnings · Suggestions.
4. For each, provide a concrete fix.

Hooks fall into three cadences: once per session (SessionStart, SessionEnd), once per turn (UserPromptSubmit, Stop, StopFailure), every tool call (PreToolUse, PostToolUse). They can be shell commands, HTTP endpoints, or prompts. See the full event schema reference.

Format & wiring

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\"" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command",
            "command": "echo \"$(date): $CONVERSATION_SUMMARY\" >> ~/.claude/activity.log" }
        ]
      }
    ]
  }
}

Model Context Protocol servers expose tools, resources, and prompts. HTTP transport is preferred over stdio — it's cross-client compatible and easier to manage. See the MCP setup guide.

Management

Tool Search — why 2.1.x MCP scales

When MCP tool descriptions would consume more than 10 % of context, Claude Code loads them dynamically instead of preloading. Set ENABLE_TOOL_SEARCH=true to force it on. Expect ~85 % token reduction on heavy setups and better tool-selection accuracy on Opus.

Popular connectors — quick reference

MCP-exposed prompts appear as /mcp__<server>__<prompt>. Example: /mcp__github__list_prs.

Enterprise policy

// /etc/claude-code/managed-mcp.json (excerpt)
{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "sentry" }
  ],
  "deniedMcpServers": [
    { "serverName": "filesystem" }
  ]
}

Denylist takes absolute precedence over allowlist.

A plugin is a self-contained directory — the unit of sharing for Claude Code extensions. Install scopes: user (personal), project (checked into git, shared with team), local (project-local, gitignored).

Plugin directory shape

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # manifest (required)
├── skills/                # auto-invokable capabilities
├── commands/              # flat .md slash commands
├── agents/                # subagents
├── hooks/                 # hook configs
├── monitors/              # background monitors
├── .mcp.json              # MCP servers
├── .lsp.json              # LSP servers
└── scripts/

Background tasks

Git worktrees

Run parallel sessions on the same repo without git stash dances. Each worktree keeps its own Claude session with full context. Great for "feature branch + urgent hotfix + model comparison" scenarios.

# Parallel feature + hotfix
git worktree add ../app-auth -b feature/auth main
git worktree add ../app-hotfix -b hotfix/crit main

cd ../app-auth   && claude        # terminal 1
cd ../app-hotfix && claude        # terminal 2

# Claude-native shortcut
claude -w feature/auth
claude --worktree hotfix/crit

The status line JSON input includes workspace.git_worktree, set whenever cwd is inside a linked worktree — handy for custom statuslines. Subagents with isolation: worktree run in a fresh worktree automatically.

Headless mode (-p/--print) is the backbone of every Claude-in-CI story: PR reviews, security audits, nightly dependency reports, log triage. The Agent SDK gives you the same capabilities from TypeScript or Python, with fine-grained control over permissions, hooks, and approvals.

Print mode essentials

# One-shot
claude -p "summarize the last 10 commits"

# Structured output with metadata (cost, session_id)
claude -p --output-format json "audit this file" > result.json

# Streaming messages for real-time UIs
claude -p --output-format stream-json "long task"

# Pipe in
gh pr diff 123 | claude -p \
  --append-system-prompt "You are a security reviewer" \
  --output-format json \
  --allowedTools "Read,Grep" > audit.json

# Multi-turn via session id
sid=$(claude -p "start analysis" --output-format json | jq -r .session_id)
claude --resume "$sid" -p "now check test coverage"
claude --resume "$sid" -p "summarize findings"

Caching for CI

--exclude-dynamic-system-prompt-sections trims out per-user sections from print mode so cross-user prompt caching actually hits. Worth using on any shared CI job where many runs share a static system prompt.

Agent SDK

// TypeScript — @anthropic-ai/claude-agent-sdk
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const msg of query({
  prompt: "/code-review",
  options: { maxTurns: 3 }
})) {
  // msg has type + payload
  console.log(msg);
}

Settings layer from enterprise → project → project-local → user. Full schema in the settings reference. Permission rule syntax is in the IAM reference.

Commands

Safe-default permission template

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(pnpm *)",
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(git add *)",
      "Bash(git commit *)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(npm install *)",
      "Bash(pnpm add *)"
    ],
    "deny": [
      "Read(./.env*)",
      "Read(./secrets/**)",
      "Read(./**/credentials*)",
      "Read(./**/*.key)",
      "Read(./**/*.pem)",
      "Bash(rm -rf:*)",
      "Bash(curl:*)",
      "Bash(wget:*)"
    ]
  }
}

Git-ignore essentials

# Keep personal settings out of git
.claude/settings.local.json

# Keep policy-managed hooks + plugin locks IN git
# so the team gets the same behavior

Any env var can also be set under env in settings.json to apply it to every session. Full list in the environment variables reference.

Starting points, not scripture. Mix and match for your stack. For richer patterns, see common workflows and best practices.

1. New-project bootstrap

cd your-project
claude
> /init
> # review the generated CLAUDE.md, trim aggressively
> /memory   # add commands, conventions, "do not touch" zones
> /permissions   # lock down .env and secrets

2. Plan → execute with opusplan

claude --model opusplan
> Shift+Tab Shift+Tab   # enter plan mode
> Plan a migration from REST to GraphQL for the user service.
> # exit plan → Claude switches to Sonnet for execution

3. Safe parallel work

git worktree add ../app-hotfix -b hotfix/login-500 main
cd ../app-hotfix && claude "fix the 500 on /api/login"
# main project keeps running in the other terminal, full context

4. Automated PR review in CI

# .github/workflows/review.yml (excerpt)
- run: |
    gh pr diff ${{ github.event.number }} | \
      claude -p \
        --append-system-prompt "Senior reviewer. Focus on security, regressions." \
        --output-format json \
        --allowedTools "Read,Grep" \
        --exclude-dynamic-system-prompt-sections \
      > review.json

5. Auto-format on write

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write \"$FILE_PATH\" 2>/dev/null || true"
      }]
    }]
  }
}

6. Cost discipline

• Start on Sonnet; /model opus only when it's stuck.
• /compact at ~80 % context — cheaper than letting it auto-compact under pressure.
• /clear between unrelated tasks. Don't pay to carry old context.
• Frequent custom commands: pin model: claude-haiku-4-5 in frontmatter.
• /effort low for mechanical work; save high for hard reasoning.
• /btw for side questions — answers in a dismissible overlay, never enter history.

• Checkpoints ≠ git. /rewind restores tracked edits only. Changes made by rm, mv, cp, or external editors are not recoverable. Commit often.
• Permission wildcards don't exist for tool names. mcp__github__* matches nothing. Use the server name alone or list tools explicitly.
• Switching model mid-conversation is expensive. Full history re-reads without cache. Claude warns you — read the warning.
• .local suffix is convention, not magic. .claude/settings.local.json is not auto-ignored. You still need a .gitignore entry.
• Homebrew / winget don't auto-update. Only the native installer does. Run brew upgrade claude-code or winget upgrade Anthropic.ClaudeCode manually.
• MCP tool descriptions can swallow context. Enable ENABLE_TOOL_SEARCH=true on heavy setups — 85 % token reduction in Anthropic's benchmarks.
• Hooks run with your credentials. Always audit plugin hook scripts before enabling. PreToolUse hooks cannot override permissions.deny — deny wins.
• Skills that should never auto-fire need disable-model-invocation: true. Otherwise Claude may invoke them at surprising moments.
• Pin models in production. Aliases shift when new models ship. Set ANTHROPIC_DEFAULT_*_MODEL to versioned IDs so your agents are reproducible.
• Enterprise MCP denylist wins. If a server is in both allowedMcpServers and deniedMcpServers, denied wins — regardless of order.
• Subagent worktree isolation. Subagents running in isolated worktrees need Read/Edit access to files inside their own worktree.
• Environment variables don't persist across Bash calls. An export in one command won't be available in the next. Use CLAUDE_ENV_FILE or a SessionStart hook to populate env dynamically.
• cd carries over between Bash calls by default (but not across subagent sessions). Disable with CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 if it causes confusion.
• OS CA store is trusted by default. Use CLAUDE_CODE_CERT_STORE=bundled only if you need to skip OS certificate trust (some enterprise TLS setups).