Claude Interfaces — four ways to use Claude

💬

Claude Chat

claude.ai — the conversational interface

Who: Everyone — general consumers, knowledge workers
Where: Browser & mobile app
What: Chat, artifacts, file uploads, web search, deep research, memory, Projects
Agentic: Partial — Claude in Chrome, Deep Research are agentic; core chat is turn-based
Extensions: Connectors (Gmail, Calendar, etc.) in Settings
Coding: Artifacts, code blocks — not a full dev environment

Consumer Browser Mobile

🖥️

Claude Cowork

Desktop app — automate files & workflows

Who: Non-developers who want automation without code
Where: Native desktop application
What: File management, task automation, workflow orchestration
Agentic: Yes — takes multi-step actions on your filesystem & apps
Extensions: MCP servers for connecting local & cloud tools
Coding: Not a coding tool — focuses on tasks & files

Non-dev Desktop Agentic

⌨️

Claude Code

CLI tool — agentic software development

Who: Developers, engineers
Where: Terminal / command line
What: Write, edit, run, debug code; manage repos; run tests
Agentic: Fully — reads files, runs shell commands, edits code autonomously
Extensions: MCP servers, skills, plugins, hooks, subagents
Coding: Core purpose — entire dev workflow in the terminal

Developer CLI Agentic

🔧

Claude API

Anthropic SDK — build your own apps

Who: Developers building AI-powered applications
Where: Any language/platform via HTTP or SDK
What: Messages, tool use, vision, streaming, batches
Agentic: Build-your-own — agentic loops via tool use + Agent SDK
Extensions: MCP client support, custom tool definitions
Coding: Not a coding tool — it's the building block for them

Platform SDK REST

All four share

MCP protocol support

Support for context injection

File input/output

Also in the Claude family — embedded agents

🌐 Claude in Chrome

Browser agent — navigates, reads, and acts on web pages. Powers computer use in Claude Chat.

📊 Claude in Excel / PowerPoint

Office agents — Claude embedded directly in Microsoft 365 apps for spreadsheet & slide tasks.

IDE integrations — Claude Code inside your editor

💻 VS Code Extension

Claude Code embedded as a VS Code panel. Full CLI capabilities (edit, run, debug) with IDE context — sees open files, diagnostics, terminal output. Install from the VS Code marketplace or run code --install-extension anthropic.claude-code.

🧩 JetBrains Plugin

Claude Code as a tool window in IntelliJ, WebStorm, PyCharm, and other JetBrains IDEs. Same agentic capabilities as the CLI — reads project files, runs commands, edits code — integrated into your IDE workflow.

⚙️ How they relate to the CLI

IDE extensions are frontends for the same Claude Code engine. They share settings, permissions, CLAUDE.md, plugins, MCP servers, and memory. Your ~/.claude/ config applies everywhere.

Layered architecture — from user to model

User

You — developer, worker, consumer

↓

Interface

Claude Chat (web/mobile)

Claude Cowork (desktop)

Claude Code (CLI)

Claude API (SDK/REST)

↓

Extensions

Connectors

Skills

Plugins

Hooks

CLAUDE.md

Scheduled Tasks

Subagents

Artifacts

↓

Protocol

MCP (Model Context Protocol)

Tools · Resources · Prompts

↓

Model

Claude Opus

Claude Sonnet

Claude Haiku

Each layer can be used independently — MCP servers work without Skills, Connectors work without Hooks, etc.

Extension mechanisms — how you add capabilities to Claude

🔌

MCP Servers

Protocol Layer · Technical

Model Context Protocol — an open standard for exposing tools, data sources, and actions to Claude. The underlying plumbing that powers everything else.

Layer:Protocol / infrastructure

Who sets up:Developers, IT, operators

Used in:Claude Code (native), Claude Cowork (native), Claude API, powers Connectors in Chat

Examples:Gmail MCP, Asana MCP, custom DB MCP

Scope:Any tool, any data source, any action

Open?:Yes — open spec, anyone can build

🔗

Connectors

User-facing · Claude.ai only

MCP servers with a friendly face. Connectors are the claude.ai Settings UI for enabling pre-built MCP integrations. Same protocol, consumer packaging.

Layer:UI / user-facing

Who sets up:End users in claude.ai Settings

Used in:Claude Chat only (claude.ai)

Examples:Gmail, Google Calendar, Google Drive, Slack

Scope:Curated integrations from Anthropic partners

Under hood:MCP servers — same protocol

📋

Skills

Operator-injected · Instruction sets

Reusable prompt + tool bundles defined in SKILL.md files. Operators package domain expertise (e.g., "QGenda scheduling") so Claude knows how to use specific tools in context.

Layer:Instruction / prompt layer

Who sets up:Developers, operators, power users

Used in:Claude Code (slash commands), can be bundled as plugins

Examples:QGenda skill, deploy skill, code-review skill

Scope:Domain-specific workflows combining instructions + MCP tools

Format:SKILL.md — markdown with examples & tool references

Bundled:/batch /claude-api /debug /loop /simplify

⚡

Hooks

Event-driven · Shell commands

Shell commands that fire on Claude Code events — before/after tool calls, on prompt submit, etc. Enables guardrails, logging, and automated side-effects.

Layer:Automation / event hooks

Who sets up:Developers in settings.json

Used in:Claude Code only

Examples:Lint on save, notify on commit, block dangerous commands

Scope:React to tool events within a Claude Code session

Triggers:PreToolUse, PostToolUse, PromptSubmit, Stop

📦

Plugins

Distribution · Packaging

Distributable bundles that package Skills + MCP servers + hooks + agents + configuration together. Discoverable via marketplaces — the delivery truck for skills & tools.

Layer:Packaging / distribution

Who sets up:Plugin authors (developers)

Used in:Claude Code only

Contains:Skills, agents, MCP/LSP servers, hooks, settings

Manifest:.claude-plugin/plugin.json

Install:/plugin install <name>@<marketplace>

Discovery:Official marketplace + custom marketplaces

✨

Artifacts

Output · Rendered content

Rich rendered outputs in the Claude Chat side panel — code, documents, diagrams, interactive React components. A way Claude produces content, not a way to extend it.

Layer:Output / rendering

Who creates:Claude generates them automatically

Used in:Claude Chat only (claude.ai)

Types:Code, Markdown, HTML, SVG, Mermaid, React

Scope:Rendered preview — not a full dev environment

Note:Output mechanism, not an extension point

📄

CLAUDE.md

Instructions · Project context

Persistent project instructions loaded automatically when Claude Code enters a directory. The repo-level equivalent of a system prompt — conventions, architecture notes, do/don't rules.

Layer:Instruction / context

Who sets up:Developers, per repo or directory

Used in:Claude Code (auto-loaded), informally in Chat Projects

Scopes:Repo root, subdirectories, ~/.claude/CLAUDE.md (global)

vs Skills:CLAUDE.md = project context; Skills = reusable domain expertise

vs System:CLAUDE.md is checked into git; system prompts are set via API

⏰

Scheduled Tasks

Scheduled · Recurring agents

Cron-scheduled Claude Code agents that run on a timer — automated PR reviews, status checks, recurring maintenance. Three flavors: Cloud, Desktop, and /loop.

Layer:Automation / scheduling

Who sets up:Developers via CLI or slash command

Used in:Claude Code only

Examples:Nightly PR triage, scheduled code reviews, deploy checks

Runs:Cloud (Anthropic infra), Desktop (local machine), or /loop (session-scoped)

Setup:/schedule (cloud), Desktop app, or /loop in session

🤖

Subagents

Parallel · Child agents

Child Claude instances spawned by the main agent for parallel work — research, exploration, independent tasks. Protects the main context window from overflow.

Layer:Execution / orchestration

Who triggers:Claude itself (via Agent tool)

Used in:Claude Code (native), Claude API (via Agent SDK)

Types:Explore (research), general (task execution)

Scope:Isolated context — results returned to parent

Use case:Parallel file searches, independent subtasks, deep dives

How they relate: MCP Servers are the protocol layer — they expose tools. Connectors are MCP servers packaged for end-users in claude.ai. Skills bundle instructions + tool references into reusable prompts. Hooks run shell commands in response to Claude Code events. Plugins package skills + MCP servers for distribution. Artifacts are rendered outputs in Chat — not an extension point. CLAUDE.md gives persistent project instructions, checked into git. Scheduled Tasks run agents on a cron (cloud, desktop, or /loop). Subagents are child Claude instances for parallel work.

Plugin Marketplace & Discovery

Plugins are distributed through marketplaces — registries that catalog available plugins with metadata and installation info. There's an official Anthropic marketplace (claude-plugins-official) plus support for custom marketplaces hosted on GitHub, GitLab, or any Git host.

Install a plugin

/plugin — open the interactive plugin manager (Discover tab)
/plugin install <name>@<marketplace> — install directly
/plugin install github@claude-plugins-official — from official
Scopes: user (default), project (.claude/settings.json), local
/reload-plugins — reload all plugins without restarting

Add a marketplace

/plugin marketplace add owner/repo — GitHub repo
/plugin marketplace add https://gitlab.com/... — any Git URL
/plugin marketplace add ./local-path — local directory
/plugin marketplace list — list configured marketplaces
/plugin marketplace update <name> — refresh listings

See the Plugins tab for complete details on plugin structure, creating marketplaces, plugin.json schema, source types, and team configuration.

Plugins & Marketplaces — build, distribute, and discover Claude Code extensions

What is a Plugin?

A plugin is a self-contained directory that bundles reusable components for Claude Code: skills, agents, MCP servers, hooks, LSP servers, and settings. Plugins are versioned, shareable, and installable from marketplaces.

Think of plugins as npm packages for Claude Code — they let you share and reuse Claude functionality across projects and teams.

Plugin directory structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # ← manifest (ONLY file in here)
├── skills/                   # ← at root level, NOT inside .claude-plugin/
│   ├── code-review/
│   │   └── SKILL.md
│   └── deployment/
│       ├── SKILL.md
│       └── scripts/
├── agents/
│   ├── security-reviewer.md
│   └── performance-tester.md
├── hooks/
│   └── hooks.json
├── .mcp.json                 # MCP server config
├── .lsp.json                 # LSP server config
├── settings.json             # Default settings when plugin enabled
└── README.md

plugin.json manifest

{
  "name": "my-plugin",              // required — unique id, kebab-case
  "version": "1.0.0",              // semantic versioning
  "description": "What it does",    // shown in plugin manager
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "repository": "https://github.com/you/my-plugin",
  "license": "MIT",
  "keywords": ["review", "quality"],
  "skills": "./skills/",            // custom paths (defaults to skills/)
  "agents": "./agents/",            // custom paths (defaults to agents/)
  "hooks": "./hooks/hooks.json",
  "mcpServers": "./.mcp.json",
  "lspServers": "./.lsp.json",
  "userConfig": {              // prompted at enable time
    "api_token": {
      "description": "API auth token",
      "sensitive": true
    }
  }
}

Environment variables: Use ${CLAUDE_PLUGIN_ROOT} for the plugin install path and ${CLAUDE_PLUGIN_DATA} for persistent data that survives updates (~/.claude/plugins/data/{id}/).

What is a Marketplace?

A marketplace is a registry — a catalog of plugins with metadata and source locations. It's how users discover and install plugins. Marketplaces can be hosted on GitHub, GitLab, any Git host, or locally. They are NOT where plugins run — just where they're cataloged.

Official marketplace

claude-plugins-official — auto-available when Claude Code starts. Browsable at claude.com/plugins.

Includes: code intelligence (LSP for TypeScript, Python, Rust, Go, etc.), integrations (GitHub, Jira, Linear, Notion, Slack, Sentry, Vercel), and dev workflows.

Custom marketplaces

Anyone can create a marketplace — for a team, company, or community. Just a Git repo with a .claude-plugin/marketplace.json file.

Users add it with /plugin marketplace add owner/repo and can then install any plugin from it.

Creating a Marketplace

A marketplace is a repository containing a .claude-plugin/marketplace.json that catalogs available plugins.

Create the marketplace structure

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json      # ← registry file
└── plugins/
    ├── code-review/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   └── skills/
    │       └── review/
    │           └── SKILL.md
    └── deploy-tools/
        ├── .claude-plugin/
        │   └── plugin.json
        ├── skills/...
        └── .mcp.json

Write marketplace.json

{
  "name": "company-tools",               // marketplace id, kebab-case
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "metadata": {
    "description": "Internal dev tools",
    "pluginRoot": "./plugins"              // base dir for relative source paths
  },
  "plugins": [
    {
      "name": "code-review",
      "source": "./plugins/code-review",  // relative to repo root
      "description": "Code review skills",
      "version": "1.0.0"
    },
    {
      "name": "deploy-tools",
      "source": {                       // external repo source
        "source": "github",
        "repo": "your-org/deploy-tools"
      },
      "description": "Deployment automation",
      "version": "2.1.0"
    }
  ]
}

Push to a Git host and share

# Push to GitHub/GitLab/etc.
git push origin main

# Users add your marketplace:
/plugin marketplace add your-org/company-tools

# Then install plugins from it:
/plugin install code-review@company-tools

Validate before publishing

# Validate marketplace.json, plugin.json, skills, agents, hooks
/plugin validate .

Checks syntax of all manifests, skill/agent frontmatter, and hook configs.

Adding a Plugin to a Marketplace

To add a new plugin, append an entry to the plugins array in marketplace.json.

Plugin source types

Source	Format	Notes
Relative path	`"source": "./plugins/my-plugin"`	Within same repo (monorepo). Only works when marketplace added via Git.
GitHub	`{"source": "github", "repo": "owner/repo"}`	Optionally pin with `"ref": "v2.0.0"` and/or `"sha": "abc..."`
Git URL	`{"source": "url", "url": "https://gitlab.com/..."}`	Any Git host. Supports `"ref"` and `"sha"` pinning.
Git subdirectory	`{"source": "git-subdir", "url": "...", "path": "tools/plugin"}`	Sparse clone from monorepo — minimal bandwidth.
npm	`{"source": "npm", "package": "@acme/plugin"}`	Supports `"version"` and custom `"registry"` URL.

After updating marketplace.json, push to your repo. Users run /plugin marketplace update <name> to see new plugins.

Installing & Managing Plugins

Discovery & install

# Interactive plugin manager
/plugin

# Install from official marketplace
/plugin install github@claude-plugins-official

# Install from custom marketplace
/plugin install my-plugin@company-tools

# Install to project scope (shared via git)
/plugin install fmt@tools --scope project

# Reload plugins without restart
/reload-plugins

Manage & update

# Enable/disable without uninstalling
/plugin enable my-plugin@market
/plugin disable my-plugin@market

# Uninstall (--keep-data preserves data)
/plugin uninstall my-plugin@market

# Update to latest version
/plugin update my-plugin@market

# Marketplace management
/plugin marketplace add owner/repo
/plugin marketplace remove name
/plugin marketplace list

Installation scopes

Scope	File	Use case
user	`~/.claude/settings.json`	Personal, across all projects (default)
project	`.claude/settings.json`	Team-shared via version control
local	`.claude/settings.local.json`	Project-specific, gitignored
managed	Managed settings	Admin-controlled, read-only

Team Configuration

Pre-configure marketplaces and plugins for your team via .claude/settings.json (checked into git):

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deploy-tools@company-tools": true
  }
}

When teammates clone the repo, they'll automatically have access to the marketplace and its enabled plugins.

Admin lockdown (managed settings)

Restrict which marketplaces users can add with strictKnownMarketplaces:

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/approved-plugins" },
    { "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
  ]
}

Omit = no restrictions. Empty array [] = complete lockdown. List = allowlist only.

Quick Start: Create a Plugin in 5 Steps

Create the plugin directory and manifest

mkdir -p my-plugin/.claude-plugin

// my-plugin/.claude-plugin/plugin.json
{
  "name": "my-plugin",
  "description": "A greeting plugin",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

Add a skill

mkdir -p my-plugin/skills/hello

// my-plugin/skills/hello/SKILL.md
---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

Test locally

claude --plugin-dir ./my-plugin

Try your skill

/my-plugin:hello         # namespace is plugin-name:skill-name
/my-plugin:hello Alice   # pass arguments with $ARGUMENTS in SKILL.md

Distribute via a marketplace (or submit to official)

Add to a custom marketplace (see above), or submit to the official Anthropic marketplace at claude.ai/settings/plugins/submit.

SKILL.md frontmatter fields

Field	Type	Purpose
name	string	Display name, becomes `/slash-command` (kebab-case, max 64 chars)
description	string	When to use skill (max 250 chars in listing)
argument-hint	string	Hint for autocomplete (e.g., `[issue-number]`)
disable-model-invocation	boolean	Prevent Claude from auto-loading (manual `/name` only)
user-invocable	boolean	`false` hides from `/` menu (Claude-only background knowledge)
allowed-tools	array	Tools Claude can use without permission when skill active
model	string	Override model while skill active
effort	string	Effort level: low, medium, high, max
context	string	`fork` to run in forked subagent
agent	string	Which subagent type when `context: fork`
hooks	object	Hooks scoped to skill lifecycle
paths	array	Glob patterns limiting when skill activates
shell	string	`bash` (default) or `powershell`

String substitutions: $ARGUMENTS (all args), $ARGUMENTS[N] or $N (by index), ${CLAUDE_SESSION_ID}, ${CLAUDE_SKILL_DIR} (skill directory path).

Security: Plugins can execute arbitrary code with user permissions — only install from trusted sources. Review plugin source before installing. Admins can restrict allowed marketplaces via strictKnownMarketplaces in managed settings. The official Anthropic marketplace (claude-plugins-official) is auto-updated; third-party marketplaces require manual opt-in for auto-updates.

Permissions — control what Claude Code can access and do

Claude Code uses a tiered permission system to balance power and safety. Rules follow a strict evaluation order: deny → ask → allow. The first matching rule wins, so deny rules always take precedence. Manage permissions with /permissions or in settings.json.

Tool approval tiers

Tool type	Example	Approval needed?	"Don't ask again" behavior
Read-only	File reads, Grep, Glob	No	N/A
Bash commands	Shell execution	Yes	Permanently per project + command
File modification	Edit, Write	Yes	Until session end

Permission modes

Mode	Behavior	Use case
default	Prompts for permission on first use of each tool	Normal interactive development
acceptEdits	Auto-accepts file edit permissions for the session	Trusted editing with Bash prompts
plan	Claude can analyze but not modify files or execute commands	Read-only exploration and planning
auto	Auto-approves with background safety classifier checks	High autonomy with guardrails — requires org admin enablement
dontAsk	Auto-denies tools unless pre-approved via rules	Strict whitelist-only operation
bypassPermissions	Skips prompts (still protects .git, .claude, .vscode, .idea)	Containers/VMs only — dangerous on bare metal

Auto mode config: Set autoMode in user/local/managed settings (NOT project) with fields: environment (prose description), allow (allowed actions), soft_deny (soft-denied actions).
CLI tools: claude auto-mode defaults · claude auto-mode config · claude auto-mode critique
bypassPermissions detail: Protects .git, .claude, .vscode, .idea — but does not protect .claude/commands, .claude/agents, .claude/skills.

Permission rule syntax — Tool(specifier)

Rule	Matches
Bash	All Bash commands (same as `Bash(*)`)
Bash(npm run build)	Exact command `npm run build`
Bash(npm run *)	Commands starting with `npm run`
Bash(* --version)	Commands ending with `--version`
Bash(git * main)	e.g. `git checkout main`, `git merge main`
Read	All file reads
Read(./.env)	Reading `.env` in current directory
Read(~/.zshrc)	Reading home directory's `.zshrc`
Edit	All file edits/writes
Edit(/src/*/.ts)	Edits in `<project>/src/` (recursive)
Edit(//tmp/scratch.txt)	Absolute path `/tmp/scratch.txt`
WebFetch(domain:example.com)	Fetch requests to example.com
mcp__puppeteer	All tools from the `puppeteer` MCP server
mcp__puppeteer__navigate	Specific tool from an MCP server
Agent(Explore)	The Explore subagent

Read & Edit path patterns

Follow the gitignore specification:

//path — absolute from filesystem root
~/path — relative to home directory
/path — relative to project root
path or ./path — relative to current directory

* matches files in a single directory. ** matches recursively across directories.

Read/Edit deny rules only apply to Claude's built-in file tools, not to Bash subprocesses. A Read(./.env) deny rule blocks the Read tool but does not prevent cat .env in Bash. For OS-level enforcement, enable the sandbox.

Bash wildcard note: The space before * matters. Bash(ls *) matches ls -la but not lsof. Bash(ls*) without a space matches both. Claude is aware of shell operators — Bash(safe-cmd *) won't permit safe-cmd && other-cmd.

Example settings.json configuration

// Allow npm/git, deny git push
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(* --version)",
      "Bash(* --help *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Read(./.env)"
    ]
  }
}

// Disable specific agents
{
  "permissions": {
    "deny": [
      "Agent(Explore)"
    ]
  }
}

// Set default permission mode
{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Permission precedence (highest → lowest)

Managed settings

Cannot be overridden by any other level, including CLI flags. Org-wide enforcement

Command-line flags

--allowedTools, --disallowedTools — temporary session overrides

.claude/settings.local.json

Local project settings — your personal project overrides, gitignored

.claude/settings.json

Shared project settings — checked into git, shared with team

~/.claude/settings.json

User settings — your personal global defaults

Deny wins across levels: If a tool is denied at any level, no other level can allow it. A managed deny cannot be overridden by --allowedTools. A project deny overrides a user allow.

Extending permissions — hooks & managed settings

PreToolUse hooks

Deny the call (exit code 2) — blocks before permission rules are evaluated
Allow the call — skips the prompt, but deny rules still apply
Force a prompt — override auto-allow for specific cases

Use hooks for dynamic rules that can't be expressed as static patterns.

Managed settings (enterprise)

Org-wide policies that cannot be overridden by users or projects:

allowManagedPermissionRulesOnly — only managed rules apply
allowManagedHooksOnly — only managed hooks load
allowManagedMcpServersOnly — only managed MCP servers
disableBypassPermissionsMode — prevent unsafe modes
disableAutoMode — prevent auto mode

Delivered via MDM, managed settings files, or server-managed settings.

Permissions + Sandboxing = defense-in-depth: Permissions control which tools Claude can use — applies to all tools. Sandboxing enforces OS-level restrictions on Bash subprocesses — filesystem and network. Permission deny rules block Claude from attempting access. Sandbox restrictions block processes from reaching resources even if prompt injection bypasses Claude's decision-making.

Claude model family — choosing the right model

All Claude products are powered by the same model family. Choose based on your task's complexity, speed requirements, and cost sensitivity. Switch models anytime with /model in a session or --model on the CLI.

🧠

Claude Opus

Most capable — complex reasoning & analysis

Best for: Hard problems, multi-step reasoning, large-scale refactors, architecture decisions
Context: 200K tokens (1M extended)
Speed: Slower — prioritizes depth over speed
Cost: Highest — use for tasks that justify it
Model ID: claude-opus-4-6

Most capable 1M context

⚡

Claude Sonnet

Best balance — fast, smart, affordable

Best for: Everyday coding, code review, feature implementation, most development tasks
Context: 200K tokens
Speed: Fast — good throughput for interactive use
Cost: Moderate — best cost/performance ratio
Model ID: claude-sonnet-4-6

Recommended 200K context

🚀

Claude Haiku

Fastest & cheapest — quick tasks

Best for: Simple questions, quick lookups, high-volume tasks, CI pipelines, cost-sensitive automation
Context: 200K tokens
Speed: Fastest — lowest latency
Cost: Lowest — ideal for bulk operations
Model ID: claude-haiku-4-5-20251001

Fastest 200K context

When to use which

Scenario	Opus	Sonnet	Haiku
Complex multi-file refactors	Best choice	Good for smaller refactors	Too complex
Everyday feature development	Overkill / slow	Best choice	May miss nuance
Bug diagnosis & debugging	Best for hard bugs	Good for most bugs	Simple bugs only
Code review & PR feedback	Most thorough	Best balance	Surface-level
Quick questions & lookups	Wasteful	Fine	Best choice
CI/CD automation	Too slow / costly	Good for complex CI	Best choice
Architecture decisions	Best choice	Adequate	Insufficient
High-volume batch tasks	Cost prohibitive	Moderate cost	Best choice
Long-context analysis (100K+)	Best (1M available)	Handles 200K well	Shorter attention

How to select & switch models

Method	Command	Scope
CLI flag	`claude --model opus`	This session only
Mid-session	`/model`	Rest of current session
Fast mode	`/fast`	Toggle faster output (same model)
Persistent default	`settings.json → "model": "sonnet"`	All future sessions
API	`model: "claude-sonnet-4-6"`	Per request

Model aliases

Alias	Resolves to	Notes
default	Clears override	Reverts to recommended model for your plan
best	Most capable available	Currently Opus 4.6
sonnet	Latest Sonnet (4.6)	Default for most plans
opus	Latest Opus (4.6)	Default on Max/Team Premium
haiku	Haiku 4.5	Fast and cheap
sonnet[1m]	Sonnet with 1M context	Extended context window
opus[1m]	Opus with 1M context	Extended context window
opusplan	Opus for planning, Sonnet for execution	Cost-optimized hybrid

Effort levels

Level	Behavior	Set via
low	Minimal reasoning	`--effort low`, `/effort low`, `effortLevel` setting
medium	Default, recommended	(default)
high	Deeper reasoning	`--effort high`, `/effort high`
max	Maximum depth	Opus 4.6 only
auto	Adaptive per task complexity	`--effort auto`

Extended context (1M tokens)

Plan	Opus 1M	Sonnet 1M
Max / Team / Enterprise	Included	Extra usage
Pro	Extra usage	Extra usage
API (pay-as-you-go)	Full access	Full access

Disable: CLAUDE_CODE_DISABLE_1M_CONTEXT=1. Use aliases like opus[1m] or append [1m] to any model name.

Model environment variables

Env var	Purpose
ANTHROPIC_MODEL	Set default model (lower priority than `--model`)
ANTHROPIC_DEFAULT_OPUS_MODEL	Pin the `opus` alias to a specific model ID
ANTHROPIC_DEFAULT_SONNET_MODEL	Pin the `sonnet` alias
ANTHROPIC_DEFAULT_HAIKU_MODEL	Pin the `haiku` alias
CLAUDE_CODE_SUBAGENT_MODEL	Override model used by subagents

Pricing context (API)

Model	Input (per 1M tokens)	Output (per 1M tokens)	Relative cost
Opus 4.6	$15	$75	💰💰💰 Most expensive
Sonnet 4.6	$3	$15	💰💰 Moderate
Haiku 4.5	$0.80	$4	💰 Cheapest

Pricing shown is for the API. Claude Code subscription plans (Max, Pro) have their own pricing with included usage. Use /cost to track per-session spend. Use /usage for account-level billing.

Tips: Start with Sonnet for most work — it covers 90% of development tasks well. Switch to Opus when you hit a wall: complex bugs, architecture, or large refactors. Use Haiku for scripts, CI pipelines, and high-volume automation where speed and cost matter more than depth. The /fast toggle gives faster output on the same model — try it before downgrading models.

Automation — hooks, channels, and scheduled tasks in Claude Code

Hooks

Hooks are user-defined shell commands that execute at specific points in Claude Code's lifecycle. They provide deterministic control — ensuring certain actions always happen rather than relying on the LLM to choose to run them. Use hooks to enforce project rules, auto-format code, block dangerous commands, send notifications, and integrate with external tools.

Configure hooks in settings.json (user, project, or local scope), in plugin hooks/hooks.json, or in skill/agent frontmatter. Browse configured hooks with /hooks.

Hook types

command

Run a shell command. Communicates via stdin (JSON), stdout, stderr, and exit codes.

Exit 0 = proceed. Exit 2 = block (stderr sent to Claude). Other = proceed, stderr logged.

http

POST event data to an HTTP endpoint. Response body uses same JSON format as command hooks. Headers support env var interpolation.

prompt

Single-turn LLM evaluation (Haiku by default). Returns {"ok": true/false, "reason": "..."}. Good when judgment is needed, not just rules.

agent

Multi-turn subagent with tool access. Can read files, search code, run tests before deciding. Same ok/reason format. 60s default timeout.

Common hook config fields

Field	Type	Purpose
`if`	string	Permission rule syntax filter — only run hook when condition matches
`statusMessage`	string	Custom spinner/status text shown while hook runs
`once`	boolean	Run only once per session (skills only)
`shell`	string	Override shell: `bash` (default) or `powershell`

Hook Events

Events fire at specific lifecycle points. All matching hooks run in parallel. Use matchers to filter by tool name, session start type, notification type, etc.

Event	When it fires	Matcher filters
SessionStart	Session begins or resumes	`startup` `resume` `clear` `compact`
SessionEnd	Session terminates	`clear` `resume` `logout` `prompt_input_exit`
UserPromptSubmit	You submit a prompt, before Claude processes it	No matcher
PreToolUse	Before a tool call executes (can block it)	Tool name: `Bash` `Edit\|Write` `mcp__.*`
PostToolUse	After a tool call succeeds	Tool name
PostToolUseFailure	After a tool call fails	Tool name
PermissionRequest	When a permission dialog appears	Tool name
PermissionDenied	When a permission is denied by user or rule	Tool name
Notification	Claude sends a notification	`permission_prompt` `idle_prompt` `auth_success`
Stop	Claude finishes responding	No matcher
StopFailure	Turn ends due to API error	`rate_limit` `authentication_failed` `server_error`
SubagentStart/Stop	When a subagent spawns or finishes	Agent type: `Bash` `Explore` `Plan`
ConfigChange	Config file changes during session	`user_settings` `project_settings` `skills`
CwdChanged	Working directory changes	No matcher
FileChanged	Watched file changes on disk	Filename: `.envrc` `.env`
InstructionsLoaded	CLAUDE.md or rules file loaded	`session_start` `nested_traversal` `path_glob_match`
PreCompact/PostCompact	Before/after context compaction	`manual` `auto`
TaskCreated/Completed	Task lifecycle events	No matcher
WorktreeCreate/Remove	Worktree lifecycle events	No matcher
Elicitation	MCP server requests user input	MCP server name
ElicitationResult	User responds to an MCP elicitation	MCP server name
TeammateIdle	Agent team teammate about to go idle	No matcher

Common Hook Recipes

Desktop notification

Get notified when Claude needs input.

// ~/.claude/settings.json
{
  "hooks": {
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "osascript -e 'display notification \"Claude needs attention\" with title \"Claude Code\"'"
      }]
    }]
  }
}

Auto-format on edit

Run Prettier after every file edit.

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
      }]
    }]
  }
}

Block protected files

Prevent edits to .env, lock files, .git/.

// PreToolUse hook with matcher "Edit|Write"
// Script checks file_path against patterns
// Exit 2 to block + stderr reason

FILE_PATH=$(jq -r '.tool_input.file_path')
if [[ "$FILE_PATH" == *".env"* ]]; then
  echo "Blocked: protected file" >&2
  exit 2
fi

Re-inject context after compaction

Restore critical info when context is compressed.

// .claude/settings.json
{
  "hooks": {
    "SessionStart": [{
      "matcher": "compact",
      "hooks": [{
        "type": "command",
        "command": "echo 'Reminder: use Bun, not npm. Run bun test before commits.'"
      }]
    }]
  }
}

Auto-approve specific permissions

Skip permission dialog for trusted tool calls.

// PermissionRequest hook
{
  "matcher": "ExitPlanMode",
  "hooks": [{
    "type": "command",
    "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
  }]
}

Verify with agent hook

Spawn a subagent to check tests pass before stopping.

// Stop hook — agent type
{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "agent",
        "prompt": "Verify all unit tests pass. Run the test suite and check results.",
        "timeout": 120
      }]
    }]
  }
}

Hook configuration scope

Location	Scope	Shareable
~/.claude/settings.json	All your projects	No (local to machine)
.claude/settings.json	Single project	Yes (commit to repo)
.claude/settings.local.json	Single project	No (gitignored)
Managed policy settings	Organization-wide	Yes (admin-controlled)
Plugin hooks/hooks.json	When plugin is enabled	Yes (bundled with plugin)
Skill/agent frontmatter	While skill/agent is active	Yes (defined in component)

Channels

Channels push events into a running Claude Code session from external platforms — chat messages, CI alerts, webhooks — so Claude can react while you're away from the terminal. Channels are two-way: Claude reads the event and replies back through the same channel.

Research preview — requires Claude Code v2.1.80+, claude.ai login. Team/Enterprise orgs must enable channelsEnabled in managed settings.

Supported channels

Create a bot via BotFather, install plugin, configure token, pair your account.

/plugin install telegram@claude-plugins-official
/telegram:configure <token>
claude --channels plugin:telegram@claude-plugins-official
/telegram:access pair <code>
/telegram:access policy allowlist

Discord

Create app in Developer Portal, enable Message Content Intent, invite bot, install plugin.

/plugin install discord@claude-plugins-official
/discord:configure <token>
claude --channels plugin:discord@claude-plugins-official
/discord:access pair <code>
/discord:access policy allowlist

iMessage

macOS only. Reads Messages DB directly, replies via AppleScript. No bot token needed.

/plugin install imessage@claude-plugins-official
claude --channels plugin:imessage@claude-plugins-official
# Text yourself to test (bypasses access control)
/imessage:access allow +15551234567

Security: Every channel maintains a sender allowlist — only paired/approved IDs can push messages. Use --channels to opt in per session. Being in .mcp.json alone is not enough to push messages. Anyone on the allowlist can also approve/deny permission prompts via permission relay.

Channels vs. other remote features

Feature	What it does	Good for
Channels	Push external events into running session	Chat bridges, CI webhooks, monitoring alerts
Web sessions	Fresh cloud sandbox cloned from GitHub	Self-contained async work you check on later
Claude in Slack	Spawns web session from @Claude mention	Starting tasks from team conversation
Remote Control	Drive local session from claude.ai/mobile	Steering in-progress session from your phone
Standard MCP	Claude queries on demand, nothing pushed	On-demand read/query access to a system

Scheduled Tasks

Run prompts automatically on an interval within a session. Use /loop for quick polling, natural language for one-time reminders, or the underlying CronCreate/CronList/CronDelete tools directly. Tasks are session-scoped — they stop when you exit Claude Code.

Three scheduling options

Option	Runs on	Persistent	Local files	Min interval
Cloud	Anthropic cloud	Yes	No (fresh clone)	1 hour
Desktop	Your machine	Yes	Yes	1 minute
/loop	Your machine	No (session-scoped)	Yes	1 minute

/loop examples

Recurring poll

# Check deploy status every 5 minutes
/loop 5m check if the deployment finished

# Re-run a skill on interval
/loop 20m /review-pr 1234

# Default interval is 10 minutes
/loop check the build

One-time reminders

# Natural language — no /loop needed
remind me at 3pm to push the release branch

# Relative time
in 45 minutes, check whether integration tests passed

Interval syntax

Units: s (seconds, rounded up to 1m), m (minutes), h (hours), d (days). Leading: /loop 30m check build. Trailing: /loop check build every 2h. No interval defaults to 10m.

Managing tasks

# Natural language
what scheduled tasks do I have?
cancel the deploy check job

# Underlying tools
CronCreate  — schedule task (5-field cron, prompt, recur flag)
CronList    — list all tasks with IDs, schedules, prompts
CronDelete  — cancel by 8-char ID

Cron expression reference

Expression	Meaning
/5 * * *	Every 5 minutes
0 * * * *	Every hour on the hour
0 9 * * *	Every day at 9am local
0 9 * * 1-5	Weekdays at 9am local
30 14 15 3 *	March 15 at 2:30pm local

Limits: Max 50 tasks per session. Recurring tasks auto-expire after 7 days. Fires between turns (waits if Claude is busy). All times in local timezone. Disable with CLAUDE_CODE_DISABLE_CRON=1.

How they relate: Hooks fire deterministically at lifecycle events — format, block, notify, validate. Channels push external events (chat, CI, webhooks) into your session — react while you're away. Scheduled tasks poll on a timer — check deploys, babysit PRs, set reminders. For durable cron that survives restarts, use Cloud or Desktop scheduled tasks.

Feature & extension comparison across all four interfaces

Feature	Claude Chat	Claude Cowork	Claude Code	Claude API
Platform & Capabilities
Platform	Browser, mobile	Desktop app	Terminal / CLI	Any (HTTP/SDK)
Primary audience	Everyone	Non-developers	Developers	App builders
Agentic mode	Partial (Deep Research, Chrome)	Yes — multi-step actions	Yes — full autonomy	Yes — tool use loops, Agent SDK
File system access	No — uploads only	Yes — local files	Yes — full access	N/A — server-side
Shell execution	No	No	Yes	N/A — you build it
Code editing	Artifacts only	Not a coding tool	Yes — read/write/run	N/A — you build it
Web search	Yes	Yes	Yes	Via tool use
Memory	Yes	Yes	Yes (file-based)	No (you manage state)
Projects	Yes	No	Yes (CLAUDE.md)	No (use system prompts)
Extensions & Extensibility
MCP Servers	Via Connectors	Native	Native	MCP client
Connectors	Yes (Settings UI)	No	No (use MCP directly)	N/A
Skills	No	No	Yes (SKILL.md + slash cmds)	No (use system prompts)
Plugins	No	No	Yes (marketplaces)	N/A
Hooks	No	No	Yes (settings.json)	N/A
CLAUDE.md	No	No	Yes (auto-loaded per dir)	No (use system prompts)
Scheduled Tasks	No	No	Yes (/schedule)	N/A — you build it
Subagents	No	No	Yes (Agent tool)	Via Agent SDK
Artifacts	Yes (side panel)	No	No (writes files)	N/A
System prompts	No (fixed by Anthropic)	No	No (use CLAUDE.md)	Yes — full control

Claude Code — CLI commands & flags

Starting & launching

Command	Description
claude	Start an interactive REPL session in the current directory
claude "prompt"	Start a session with an initial prompt
claude --model sonnet	Override the model for this session (opus, sonnet, haiku, or full ID)
claude --add-dir ../other	Add additional directories to the session context
claude --verbose	Show detailed logging including tool calls
claude --name "my-task"	Set a display name for the session (shown in `/resume`)
claude --effort high	Set effort level (low, medium, high, max, auto)
claude --bare	Minimal mode — skip hooks, skills, plugins, MCP, auto memory, CLAUDE.md

Session management — rewind, restore, continue

Command	Description
claude -c	Continue the most recent conversation (restores full context)
claude -r "session-id"	Resume a specific conversation by its session ID
claude -r	Open interactive session picker — browse and resume recent sessions
/undo	Undo the last tool action (file edit, command, etc.) — rewinds one step
/retry	Retry the last Claude response with the same input (re-rolls)
/clear	Clear conversation history — fresh start in the same session
/compact	Compress context — summarize the conversation to free up token space
/compact "focus"	Compact with a focus hint — tells the summarizer what to preserve

Worktrees — parallel git branches

Command	Description
/worktree	Create a new git worktree and spawn a subagent to work in it in parallel
git worktree add ../path branch	Manual worktree creation — Claude can then operate in the new worktree

How worktrees work: Git worktrees let you check out multiple branches simultaneously in separate directories. Claude Code can spawn a subagent in a worktree to work on a separate branch while you continue on the current one. Each worktree is fully isolated — separate working directory, index, and HEAD. Useful for parallel PRs, experiments, or reviewing one branch while developing another.

Slash commands (inside a session)

Command	Description
/help	Show available slash commands and help
/init	Generate a CLAUDE.md for the current project by analyzing the codebase
/status	Show session status — model, mode, context usage, active tools
/doctor	Diagnose configuration issues — checks settings, MCP servers, permissions
/login	Authenticate with your Anthropic account
/logout	Sign out of the current session
/commit	Generate a commit message and commit staged changes
/pr	Generate a PR description and create a pull request
/config	Open or modify Claude Code configuration (alias: `/settings`)
/memory	View or edit persistent memory, toggle auto-memory
/sandbox	Open sandbox menu — choose mode, view status, install dependencies
/schedule	Create or manage Cloud scheduled tasks
/vim	Toggle vim keybindings
! command	Run a shell command directly (output lands in conversation)

Context & usage

Command	Description
/usage	Show API usage and billing summary for your account
/cost	Show token usage (input/output) and estimated cost for current session
/model	Switch model mid-conversation — affects all subsequent responses
/fast	Toggle fast mode — same model with faster output, lower latency
claude --effort high	Set effort level for the session (low, medium, high, max)

Plugin & extension management

Command	Description
/plugin	Open interactive plugin manager (Discover, Installed, Marketplaces tabs)
claude plugin install <name>@<market>	Install a plugin from a marketplace (--scope user\|project\|local)
claude plugin uninstall <name>	Uninstall a plugin
claude plugin enable / disable	Enable or disable a plugin without uninstalling
claude plugin update <name>@<market>	Update a plugin to latest version
claude plugin list	List installed plugins
claude plugin marketplace add <source>	Add a marketplace (owner/repo, Git URL, or local path)
claude plugin marketplace remove <name>	Remove a marketplace
claude plugin marketplace list	List configured marketplaces
claude plugin marketplace update <name>	Update marketplace(s) from their source
claude plugin validate <path>	Validate a plugin or marketplace at the given path
claude --plugin-dir ./path	Load a local plugin directory for development/testing
claude mcp add <name> <cmd>	Register an MCP server (stdio transport)
claude mcp remove <name>	Remove an MCP server
claude mcp list	List configured MCP servers
claude agents	List configured agents (built-in and plugin agents)
claude auth login	Sign in to your Anthropic account
claude auth status	Show authentication status
claude doctor	Check health of auto-updater and configuration

Sandboxing & permissions

Command	Description
--allowedTools "Tool1,Tool2"	Whitelist specific tools — Claude can only use these
--disallowedTools "Bash"	Blacklist specific tools — Claude cannot use these
--permission-mode plan	Plan mode — Claude describes actions but asks before executing them
/permissions	View and manage permission rules interactively
--dangerously-skip-permissions	Skip all permission prompts — runs everything without asking. Use only in sandboxed/CI environments

Permission modes: Default — prompts on risky tools · Permissive — auto-approves most tools · Strict — prompts on everything. Persistent allow/deny rules go in settings.json (matched by tool name + glob patterns). For full isolation, run claude inside a Docker container for filesystem + network sandboxing.

Remote & headless control

Command	Description
claude -p "prompt"	Non-interactive (headless) — run, print result, exit. Ideal for CI/CD and scripts
cat file \| claude -p "..."	Pipe content as context — combine with shell pipelines for automation
claude -p --output-format json	JSON output mode — structured results for programmatic consumption
claude -p --output-format stream-json	Streaming JSON — newline-delimited events for real-time processing

Integration patterns: Use claude -p over SSH for remote control on headless machines. Add claude -p as a step in GitHub Actions or other CI/CD pipelines. Combine with --output-format json for machine-readable results in automated workflows.

CLI flags — session & environment

Flag	Description
--agent <name>	Use a specific agent for this session
--agents <json>	Define custom subagents dynamically via JSON
--channels <list>	MCP servers whose channel notifications to listen for
--chrome	Enable Chrome browser integration
--no-chrome	Disable Chrome for this session
--fork-session	When resuming, create new session ID instead of reusing original
--from-pr <PR>	Resume sessions linked to a GitHub PR
--ide	Auto-connect to IDE if exactly one available
--init	Run initialization hooks then start interactive
--remote	Create new web session on claude.ai
--remote-control, --rc	Start with Remote Control enabled
--session-id <uuid>	Use specific session UUID
--teleport	Resume a web session in local terminal
--teammate-mode <mode>	Agent team display: auto, in-process, tmux
--tmux	Create tmux session for worktree
--worktree, -w	Start in isolated git worktree

CLI flags — output, limits & config

Flag	Description
--fallback-model <model>	Auto-fallback model when default is overloaded (print mode)
--json-schema <schema>	Get validated JSON output matching schema (print mode)
--max-budget-usd <n>	Max dollar spend before stopping (print mode)
--max-turns <n>	Limit number of agentic turns (print mode)
--tools <list>	Restrict which built-in tools Claude can use
--mcp-config <path>	Load MCP servers from JSON files or strings
--strict-mcp-config	Only use MCP servers from --mcp-config
--settings <path>	Load additional settings from file or JSON string
--system-prompt <text>	Replace entire default system prompt
--append-system-prompt <text>	Append to default system prompt
--system-prompt-file <path>	Replace system prompt from file
--append-system-prompt-file <path>	Append file contents to system prompt

Context, navigation & display

Command	Description
/add-dir <path>	Add working directory for file access during session
/context	Visualize current context usage as colored grid
/copy [N]	Copy last (or Nth) assistant response to clipboard
/diff	Interactive diff viewer — uncommitted changes + per-turn diffs
/export [file]	Export conversation as plain text
/color [color]	Set prompt bar color (red, blue, green, yellow, purple, orange, pink, cyan)
/theme	Change color theme (light, dark, daltonized, ANSI)
/statusline	Configure status bar (context, cost, git status)

Session management (additional)

Command	Description
/branch [name]	Fork conversation at this point (alias: `/fork`)
/rename [name]	Rename current session (auto-generates if no name given)
/rewind	Rewind conversation/code to previous checkpoint (alias: `/checkpoint`)
/plan [desc]	Enter plan mode directly from prompt
/effort [level]	Set effort level: low, medium, high, max, auto
/btw <question>	Ask side question without adding to conversation history

Integrations

Command	Description
/chrome	Configure Chrome browser integration
/desktop	Continue session in Desktop app (alias: `/app`)
/ide	Manage IDE integrations and show status
/mobile	Show QR code for Claude mobile app (aliases: `/ios`, `/android`)
/remote-control	Enable Remote Control from claude.ai/mobile (alias: `/rc`)
/remote-env	Configure default remote environment for web sessions
/install-github-app	Set up Claude GitHub Actions for a repo
/install-slack-app	Install Claude Slack app (opens browser)

Development tools

Command	Description
/pr-comments [PR]	Fetch and display GitHub PR comments (requires `gh` CLI)
/security-review	Analyze pending changes for security vulnerabilities
/tasks	List and manage background tasks (alias: `/bashes`)
/voice	Toggle push-to-talk voice dictation

Info & diagnostics

Command	Description
/insights	Generate report analyzing Claude Code sessions
/stats	Visualize daily usage, session history, streaks
/release-notes	View full changelog
/extra-usage	Configure extra usage for when rate limits hit
/privacy-settings	View/update privacy settings (Pro/Max only)
/passes	Share free week of Claude Code (if eligible)
/upgrade	Open plan upgrade page

Plugin & skill inspection

Command	Description
/hooks	View hook configurations for tool events
/skills	List available skills
/agents	Manage agent configurations
/reload-plugins	Reload active plugins without restart
/keybindings	Open keybindings configuration file
/terminal-setup	Configure terminal keybindings for Shift+Enter

Keyboard shortcuts — input & navigation

Key	Action
Enter	Submit prompt
Shift+Enter	New line (iTerm2, WezTerm, Ghostty, Kitty)
\ + Enter	New line (works in all terminals)
Esc	Cancel current generation / interrupt
Ctrl+C	Cancel or exit session
Ctrl+D	Exit Claude Code (EOF signal)
Up / Down	Navigate prompt history
Tab	Autocomplete slash commands and file paths
@	File path mention — triggers autocomplete
!	Bash mode — run shell command directly
/	Command or skill invocation

Keyboard shortcuts — session & mode

Key	Action
Shift+Tab / Alt+M	Cycle permission modes (default → acceptEdits → plan → auto → bypass)
Option+P / Alt+P	Switch model
Option+T / Alt+T	Toggle extended thinking
Option+O / Alt+O	Toggle fast mode
Esc Esc	Rewind or summarize
Hold Space	Push-to-talk voice dictation (requires `/voice` enabled)

Keyboard shortcuts — tools & editor

Key	Action
Ctrl+B	Background running task (press twice for tmux)
Ctrl+T	Toggle task list
Ctrl+X Ctrl+K	Kill all background agents (press twice within 3s)
Ctrl+O	Toggle verbose output
Ctrl+R	Reverse search command history
Ctrl+G / Ctrl+X Ctrl+E	Open prompt in default text editor
Ctrl+L	Clear terminal screen (keeps conversation)
Ctrl+V / Cmd+V	Paste image from clipboard
Ctrl+K	Delete to end of line
Ctrl+U	Delete to start of line
Ctrl+Y	Paste deleted text

Tips: Use claude -p for scripting & CI pipelines — it reads stdin and exits cleanly. Combine --allowedTools with -p for sandboxed automation. Slash commands with /skill-name invoke user-defined skills from installed plugins. Edit settings.json or use /config to set defaults like model, theme, and permissions. Use /undo to rewind file edits — it reverses the last tool action, not the whole conversation. /compact is your best friend in long sessions — compress early and often to stay under the context limit.

Memory system — persistent knowledge across conversations

Claude Code has a file-based memory system that persists information across conversations. Memory is stored as Markdown files with YAML frontmatter, organized by topic, and indexed by a MEMORY.md file. Unlike Claude Chat's built-in memory (stored server-side), Claude Code memory lives on your filesystem — you own it, can edit it, and can check it into git.

Four memory types

User

Who you are · How you work

Information about your role, preferences, expertise, and goals. Helps Claude tailor responses — a senior engineer gets different explanations than a student.

When saved: When Claude learns about your role, skills, or preferences.

"User is a data scientist, deep Python expertise, new to this repo's Go backend — frame Go explanations in terms of Python analogues."

Feedback

What to do · What not to do

Guidance you've given about how Claude should approach work — corrections ("don't do X") and confirmations ("yes, keep doing that"). Prevents repeating mistakes.

When saved: When you correct Claude's approach or confirm an unusual choice worked well.

"Don't mock the database in integration tests. Why: prior incident where mock/prod divergence masked a broken migration."

Project

What's happening · Why it matters

Information about ongoing work, goals, decisions, and deadlines that isn't derivable from code or git history. Provides broader context behind requests.

When saved: When Claude learns who is doing what, why, or by when. Relative dates are converted to absolute.

"Merge freeze begins 2026-03-05 for mobile release cut. Auth middleware rewrite is driven by legal/compliance, not tech debt."

Reference

Where to look · External pointers

Pointers to information in external systems — where bugs are tracked, which dashboard to check, where docs live. Helps Claude know where to look.

When saved: When you mention resources in external systems and their purpose.

"Pipeline bugs tracked in Linear project 'INGEST'. Oncall latency dashboard at grafana.internal/d/api-latency."

Storage format — each memory is a markdown file with frontmatter

--- (YAML frontmatter) name: user_role description: User is a senior backend engineer type: user --- (memory content below) Senior backend engineer with 10 years of Go experience. New to the React frontend in this repo. Frame frontend explanations in terms of backend analogues.

MEMORY.md — the index

MEMORY.md is an index file containing only links to memory files with brief descriptions. It is not a memory itself.

It's always loaded into conversation context (first 200 lines), so keep it concise. Memory content goes in individual files, not in the index.

Storage location

Two storage levels:
Project: ~/.claude/projects/<path>/memory/ (path uses dashes for slashes, e.g. -Users-lance-Maker-myproject)
User-level: ~/.claude/memory/ (auto-memory, v2.1.59+)

Disable: autoMemoryEnabled: false or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Custom path: autoMemoryDirectory setting.

CLAUDE.md features — imports and rules

@import syntax

Use @path/to/file inside CLAUDE.md to import another file's content.
Supports relative and absolute paths. Max 5 hops deep (prevents circular imports).
Example: @docs/coding-standards.md

.claude/rules/ directory

Organize instructions into multiple files under .claude/rules/.
Path-specific rules use YAML frontmatter with a paths field and glob patterns:
paths: ["**/*.ts", "src/components/*.tsx"]
Rules without paths load at session start. Rules with paths load when matching files enter context.
User-level: ~/.claude/rules/ applies to all projects.

Working with memory

Natural language

"Remember that we use pnpm, not npm"
→ Claude saves as the best-fit memory type
"Forget that I prefer tabs over spaces"
→ Claude finds and removes the entry
"What do you remember about me?"
→ Claude reads MEMORY.md index + relevant files
"Ignore memory for this question"
→ Claude answers as if no memory exists

Automatic behaviors

Auto-save — Claude saves memories without being asked when it learns your role, preferences, corrections, or project context
Auto-recall — MEMORY.md is loaded into context at conversation start; individual files read when relevant
Staleness checks — Claude verifies memories against current state before acting on them

Manual access

/memory — view or edit memory interactively in session
Edit files directly — memory is plain Markdown, edit or delete anytime
Commit to git — check project memory into the repo for team-shared context

What memory is good for

✓ Your role, expertise, and how you like to collaborate
✓ Corrections and confirmed approaches (feedback)
✓ Ongoing initiatives, deadlines, who owns what
✓ Pointers to external resources (dashboards, Linear projects)
✓ Non-obvious decisions and their rationale

What NOT to save in memory

✗ Code patterns or architecture — derivable from reading the code
✗ Git history or who-changed-what — use git log / git blame
✗ Debugging solutions — the fix is in the code + commit message
✗ Anything already in CLAUDE.md files
✗ Ephemeral task details or current conversation state

Memory vs. other persistence: Memory persists across conversations — use it for knowledge that stays relevant over time. Tasks track progress within a single conversation — use for current work breakdown. Plans align on approach before implementation — use for non-trivial task planning. CLAUDE.md holds project instructions — more stable and structured than memory. Memory can go stale — Claude verifies memories against current state before acting on them.

Sandboxing — OS-level isolation for safer agent execution

Claude Code features native sandboxing that uses OS-level primitives to enforce filesystem and network isolation on Bash commands. Instead of prompting for every command, sandboxing defines clear boundaries where Claude can work freely with reduced risk — reducing approval fatigue while maintaining security.

How it works — two layers of isolation

Filesystem isolation

Default writes: Read/write access to the current working directory and subdirectories
Default reads: Read access to the entire computer, except certain denied directories
Blocked: Cannot modify files outside the working directory without explicit permission
Configurable: Define custom allowed/denied paths via sandbox.filesystem settings
OS-enforced: Seatbelt (macOS) or bubblewrap (Linux) — applies to all subprocesses including kubectl, terraform, npm

Network isolation

Domain restrictions: Only approved domains can be accessed
User confirmation: New domain requests trigger permission prompts
Proxy-based: Network runs through a proxy server outside the sandbox
Custom proxy: Organizations can implement custom rules on outgoing traffic
Comprehensive: Restrictions apply to all scripts, programs, and subprocesses

Both layers required: Without network isolation, a compromised agent could exfiltrate sensitive files (SSH keys, etc.). Without filesystem isolation, it could backdoor system resources to gain network access. Always configure both together.

Platform support & prerequisites

Platform	Enforcement	Prerequisites
macOS	Seatbelt (built-in)	Works out of the box — no extra packages needed
Linux	bubblewrap	`sudo apt-get install bubblewrap socat` (Debian/Ubuntu) or `sudo dnf install bubblewrap socat` (Fedora)
WSL2	bubblewrap	Same as Linux — requires WSL2 (WSL1 not supported)
Windows	—	Native Windows support planned; use WSL2 for now

Getting started — enable & choose a mode

Command	Description
/sandbox	Open sandbox menu — choose mode, see status, install dependencies

Auto-allow mode

Sandboxed Bash commands run automatically without permission prompts. Commands needing non-allowed hosts fall back to the regular permission flow. Your explicit ask/deny rules are always respected.

Regular permissions mode

All Bash commands go through the standard permission flow, even when sandboxed. More control, but more approval prompts. The sandbox still enforces the same OS-level restrictions.

Auto-allow works independently of your permission mode. Even if you're not in "accept edits" mode, sandboxed Bash commands will run automatically when auto-allow is enabled — including commands that modify files within sandbox boundaries.

// settings.json — enable sandbox
{
  "sandbox": {
    "enabled": true
  }
}

// Grant write access to paths outside cwd
{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

Filesystem configuration — paths & prefixes

Setting	Purpose
sandbox.filesystem.allowWrite	Grant subprocess write access to paths outside the working directory
sandbox.filesystem.denyWrite	Block subprocess write access to specific paths
sandbox.filesystem.denyRead	Block subprocess read access to specific paths
sandbox.filesystem.allowRead	Re-allow reading within a denyRead region (takes precedence)
sandbox.failIfUnavailable	Hard fail if sandbox cannot be set up (instead of falling back to unsandboxed)

Path prefix	Meaning	Example
/	Absolute path from filesystem root	/tmp/build
~/	Relative to home directory	~/.kube → $HOME/.kube
./ or bare	Relative to project root (project settings) or ~/.claude (user settings)	./output

Merging behavior: When allowWrite, denyWrite, denyRead, or allowRead are defined in multiple settings scopes, the arrays are merged — paths from every scope are combined, not replaced. Users and projects can extend the list without overriding higher-priority scopes.

// Block reading ~/ but re-allow the project
{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

Network configuration & advanced options

Setting	Purpose
sandbox.network.allowedDomains	Domains Bash commands can reach
sandbox.network.httpProxyPort	Custom HTTP proxy port for traffic inspection
sandbox.network.socksProxyPort	Custom SOCKS proxy port
allowManagedDomainsOnly	Block non-allowed domains automatically (no prompt)
allowUnsandboxedCommands	Set to `false` to disable the escape hatch — all commands must be sandboxed
excludedCommands	Commands that run outside the sandbox (e.g., `docker`)
allowUnixSockets	Allow access to specific Unix sockets (use with caution)

// Custom proxy for traffic inspection
{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

Escape hatch

When a command fails due to sandbox restrictions, Claude may retry it with dangerouslyDisableSandbox — these commands go through the normal permission flow requiring user approval.

Disable with "allowUnsandboxedCommands": false to force all commands to be sandboxed or explicitly listed in excludedCommands.

Compatibility notes

watchman is incompatible — use jest --no-watchman
docker is incompatible — add to excludedCommands
CLI tools may request host access on first run — granting persists for future use

Security benefits & what it protects against

Protection against

Prompt injection: Cannot modify ~/.bashrc, /bin/, or exfiltrate data to attacker servers
Malicious dependencies: NPM packages or other deps with harmful code are constrained
Compromised scripts: Build scripts with security vulnerabilities are isolated
Social engineering: Limits damage from tricked execution of dangerous commands
Data exfiltration: Cannot contact domains not explicitly allowed

Security limitations

Network filtering: Operates at domain level — does not inspect traffic content
Domain fronting: Broad domains like github.com may allow data exfiltration
Unix sockets: allowUnixSockets for docker.sock effectively grants host access
Overly broad writes: Allowing writes to $PATH dirs or shell configs enables privilege escalation
Weak nested mode: enableWeakerNestedSandbox (for Docker-in-Docker) considerably weakens security

Sandboxing vs. permissions — complementary layers

Aspect	Sandboxing	Permissions
Scope	Bash commands + all child processes	All tools (Bash, Read, Edit, WebFetch, MCP)
Enforcement	OS-level (Seatbelt / bubblewrap)	Application-level (Claude Code runtime)
What it controls	Filesystem paths + network domains	Which tools can run + on which targets
When evaluated	At execution time by the OS	Before any tool runs
Built-in file tools	Not covered (Read, Edit, Write bypass sandbox)	Covered — use Read/Edit deny rules

Best practices: Start restrictive, expand as needed. Monitor violation attempts to understand Claude's needs. Use environment-specific configs (dev vs. prod). Combine sandboxing with permission rules for defense-in-depth. Open source: The sandbox runtime is available as npx @anthropic-ai/sandbox-runtime <command> — use it to sandbox any program, including MCP servers.

Docker Sandboxes — microVM isolation for coding agents

Docker Sandboxes run Claude Code in isolated microVM sandboxes — each gets its own Docker daemon, filesystem, and network. The agent can build containers, install packages, and modify files without touching your host. No Docker Desktop required. Separate from Claude Code's built-in Seatbelt/bubblewrap sandboxing above.

Platform	Requirements
macOS	Apple silicon
Windows	x86_64, Windows 11+, Hyper-V enabled

Install & login
macOS	`brew install docker/tap/sbx && sbx login`
Windows	`winget install -h Docker.sbx && sbx login`

Network policy	Behavior
Open	All network traffic allowed
Balanced	Default deny, common dev sites allowed
Locked Down	All traffic blocked unless explicitly allowed

Command	Description
sbx run claude	Launch Claude Code in a sandbox (from project dir)
sbx run claude ~/my-project	Launch with explicit project path
sbx run claude --name my-sandbox -- "prompt"	Named sandbox with initial prompt
sbx run claude -- --continue	Resume last session (flags after `--` pass to Claude)
sbx ls	List running sandboxes (name, status, uptime)
sbx policy allow <domain>	Allow outbound access to a domain
sbx secret set -g anthropic	Store Anthropic API key for sandbox use

Auth method	Details
API key	`sbx secret set -g anthropic` or export `ANTHROPIC_API_KEY`
OAuth (subscription)	Interactive browser login — proxy handles flow, creds not stored in sandbox

Key differences from built-in sandboxing: Docker Sandboxes use microVM isolation (stronger than Seatbelt/bubblewrap) — each sandbox gets a full VM, not just process-level restrictions. Claude Code runs with --dangerously-skip-permissions by default inside the sandbox since the VM is the security boundary. Project files are mounted into the sandbox; ~/.claude host config is not accessible. Custom environments can be built on the docker/sandbox-templates:claude-code base image.

File locations — where Claude Code stores everything

~/.claude/ — user-global config

~/.claude.json — auth tokens, session state, account info (auto-managed by CLI)

~/.claude/

CLAUDE.md — global instructions (loaded in every session)

settings.json — user settings (permissions, MCP servers, hooks)

settings.local.json — local overrides (not synced, gitignored)

keybindings.json — custom keyboard shortcuts

rules/ — user-level instruction rules (apply to all projects)

memory/ — user-level auto-memory files (v2.1.59+)

channels/ — channel configuration (Telegram, Discord, iMessage)

plugins/ — installed plugin storage

projects/ — per-project user data (path with dashes, e.g. -Users-lance-Maker-myproject)

<project-path>/

CLAUDE.md — user-specific project instructions (not checked in)

memory/ — project-scoped memory files

MEMORY.md — memory index (loaded into context)

*.md — individual memory entries with YAML frontmatter

project/ — repo-level config (checked into git)

your-repo/

CLAUDE.md — project instructions (auto-loaded at repo root)

.mcp.json — project-scoped MCP servers (shared with team, committed to git)

.worktreeinclude — gitignored files to copy into new worktrees

.claude/ — project Claude config directory

settings.json — project settings (shared with team)

settings.local.json — local project overrides (gitignored)

rules/ — topic-scoped instructions, optionally path-gated via paths: frontmatter

skills/ — skill definitions (SKILL.md files), invoked as /skill-name

agents/ — custom agent definitions

agent-memory/ — auto-generated subagent memory (<agent>/MEMORY.md)

hooks/ — event-driven hook scripts

output-styles/ — project-scoped output style definitions

commands/ — deprecated — single-file prompts (use skills/ instead)

subdir/

CLAUDE.md — subdirectory instructions (loaded when cd'd into)

.claude-plugin/ — plugin manifest (if this repo is a plugin)

plugin.json — plugin metadata, skills, MCP server definitions

Configuration precedence — settings loading order (lowest → highest)

System defaults

Built-in Anthropic defaults — base permissions, default model, standard tool set

~/.claude/settings.json

User-global settings — your personal MCP servers, permission rules, hooks. Applies to all projects

~/.claude/settings.local.json

User-local overrides — machine-specific settings not synced across devices

.claude/settings.json

Project settings — shared with the team via git. Project-specific permissions, MCP servers, hooks

.claude/settings.local.json

Project-local overrides — your personal project tweaks, gitignored

Command-line flags

Highest precedence — --model, --allowedTools, etc. override everything

CLAUDE.md loading order — instructions are concatenated top to bottom

~/.claude/CLAUDE.md

Global instructions — loaded in every session, every project. Your personal conventions and preferences

repo-root/CLAUDE.md

Project instructions — checked into git, shared with team. Architecture notes, conventions, rules

subdir/CLAUDE.md

Subdirectory instructions — loaded when Claude operates in that directory. Module-specific rules

~/.claude/projects/<hash>/CLAUDE.md

User-specific project instructions — your personal notes for this project, not checked into git

Key rules: settings.json files are merged — later files override earlier ones on a per-key basis, not wholesale replacement. CLAUDE.md files are concatenated — all applicable files are loaded together, not overridden. *.local.json files should be gitignored — they hold machine-specific overrides (API keys, local paths, personal prefs). Permissions in project settings.json are shown to the user for approval on first use — teams can't silently grant permissions. The projects/ directory under ~/.claude/ is keyed by a hash of the absolute project path — not the project name.