Choose your environment to get started. Most surfaces require a Claude subscription or Anthropic Console account. The Terminal CLI and VS Code also support third-party providers.

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

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

brew install --cask claude-code

cd your-project
claude

What you can do

Here are some of the ways you can use Claude Code:

claude "write tests for the auth module, run them, and fix any failures"

claude "commit my changes with a descriptive message"

# Analyze recent log output
tail -200 app.log | claude -p "Slack me if you see any anomalies"

# Automate translations in CI
claude -p "translate new strings into French and raise a PR for review"

# Bulk operations across files
git diff main --name-only | claude -p "review these changed files for security issues"

Use Claude Code everywhere

Each surface connects to the same underlying Claude Code engine, so your CLAUDE.md files, settings, and MCP servers work across all of them.

Beyond the Terminal, VS Code, JetBrains, Desktop, and Web environments above, Claude Code integrates with CI/CD, chat, and browser workflows:

Next steps

Once you've installed Claude Code, these guides help you go deeper.

• Quickstart: walk through your first real task, from exploring a codebase to committing a fix
• Store instructions and memories: give Claude persistent instructions with CLAUDE.md files and auto memory
• Common workflows and best practices: patterns for getting the most out of Claude Code
• Settings: customize Claude Code for your workflow
• Troubleshooting: solutions for common issues
• code.claude.com: demos, pricing, and product details

This quickstart guide will have you using AI-powered coding assistance in a few minutes. By the end, you'll understand how to use Claude Code for common development tasks.

Before you begin

Make sure you have:

• A terminal or command prompt open
  • If you've never used the terminal before, check out the terminal guide
• A code project to work with
• A Claude subscription (Pro, Max, Team, or Enterprise), Claude Console account, or access through a supported cloud provider

Step 1: Install Claude Code

To install Claude Code, use one of the following methods:

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

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

brew install --cask claude-code

Step 2: Log in to your account

Claude Code requires an account to use. When you start an interactive session with the claude command, you'll need to log in:

claude
# You'll be prompted to log in on first use

/login
# Follow the prompts to log in with your account

You can log in using any of these account types:

• Claude Pro, Max, Team, or Enterprise (recommended)
• Claude Console (API access with pre-paid credits). On first login, a "Claude Code" workspace is automatically created in the Console for centralized cost tracking.
• Amazon Bedrock, Google Vertex AI, or Microsoft Foundry (enterprise cloud providers)

Once logged in, your credentials are stored and you won't need to log in again. To switch accounts later, use the /login command.

Step 3: Start your first session

Open your terminal in any project directory and start Claude Code:

cd /path/to/your/project
claude

You'll see the Claude Code welcome screen with your session information, recent conversations, and latest updates. Type /help for available commands or /resume to continue a previous conversation.

Step 4: Ask your first question

Let's start with understanding your codebase. Try one of these commands:

what does this project do?

Claude will analyze your files and provide a summary. You can also ask more specific questions:

what technologies does this project use?

where is the main entry point?

explain the folder structure

You can also ask Claude about its own capabilities:

what can Claude Code do?

how do I create custom skills in Claude Code?

can Claude Code work with Docker?

Step 5: Make your first code change

Now let's make Claude Code do some actual coding. Try a simple task:

add a hello world function to the main file

Claude Code will:

1. Find the appropriate file
2. Show you the proposed changes
3. Ask for your approval
4. Make the edit

Step 6: Use Git with Claude Code

Claude Code makes Git operations conversational:

what files have I changed?

commit my changes with a descriptive message

You can also prompt for more complex Git operations:

create a new branch called feature/quickstart

show me the last 5 commits

help me resolve merge conflicts

Step 7: Fix a bug or add a feature

Claude is proficient at debugging and feature implementation.

Describe what you want in natural language:

add input validation to the user registration form

Or fix existing issues:

there's a bug where users can submit empty forms - fix it

Claude Code will:

• Locate the relevant code
• Understand the context
• Implement a solution
• Run tests if available

Step 8: Test out other common workflows

There are a number of ways to work with Claude:

Refactor code

refactor the authentication module to use async/await instead of callbacks

Write tests

write unit tests for the calculator functions

Update documentation

update the README with installation instructions

Code review

review my changes and suggest improvements

Essential commands

Here are the most important commands for daily use:

See the CLI reference for a complete list of commands.

Pro tips for beginners

For more, see best practices and common workflows.

1. create a new database table for user profiles
2. create an API endpoint to get and update user profiles
3. build a webpage that allows users to see and edit their information

analyze the database schema

build a dashboard showing products that are most frequently returned by our UK customers

What's next?

Now that you've learned the basics, explore more advanced features:

Getting help

• In Claude Code: Type /help or ask "how do I..."
• Documentation: You're here! Browse other guides
• Community: Join our Discord for tips and support

This page is generated from the CHANGELOG.md on GitHub.

Run claude --version to check your installed version.

Claude Code is an agentic assistant that runs in your terminal. While it excels at coding, it can help with anything you can do from the command line: writing docs, running builds, searching files, researching topics, and more.

This guide covers the core architecture, built-in capabilities, and tips for working effectively. For step-by-step walkthroughs, see Common workflows. For extensibility features like skills, MCP, and hooks, see Extend Claude Code.

The agentic loop

When you give Claude a task, it works through three phases: gather context, take action, and verify results. These phases blend together. Claude uses tools throughout, whether searching files to understand your code, editing to make changes, or running tests to check its work.

The loop adapts to what you ask. A question about your codebase might only need context gathering. A bug fix cycles through all three phases repeatedly. A refactor might involve extensive verification. Claude decides what each step requires based on what it learned from the previous step, chaining dozens of actions together and course-correcting along the way.

You're part of this loop too. You can interrupt at any point to steer Claude in a different direction, provide additional context, or ask it to try a different approach. Claude works autonomously but stays responsive to your input.

The agentic loop is powered by two components: models that reason and tools that act. Claude Code serves as the agentic harness around Claude: it provides the tools, context management, and execution environment that turn a language model into a capable coding agent.

Models

Claude Code uses Claude models to understand your code and reason about tasks. Claude can read code in any language, understand how components connect, and figure out what needs to change to accomplish your goal. For complex tasks, it breaks work into steps, executes them, and adjusts based on what it learns.

Multiple models are available with different tradeoffs. Sonnet handles most coding tasks well. Opus provides stronger reasoning for complex architectural decisions. Switch with /model during a session or start with claude --model <name>.

When this guide says "Claude chooses" or "Claude decides," it's the model doing the reasoning.

Tools

Tools are what make Claude Code agentic. Without tools, Claude can only respond with text. With tools, Claude can act: read your code, edit files, run commands, search the web, and interact with external services. Each tool use returns information that feeds back into the loop, informing Claude's next decision.

The built-in tools generally fall into five categories, each representing a different kind of agency.

These are the primary capabilities. Claude also has tools for spawning subagents, asking you questions, and other orchestration tasks. See Tools available to Claude for the complete list.

Claude chooses which tools to use based on your prompt and what it learns along the way. When you say "fix the failing tests," Claude might:

1. Run the test suite to see what's failing
2. Read the error output
3. Search for the relevant source files
4. Read those files to understand the code
5. Edit the files to fix the issue
6. Run the tests again to verify

Each tool use gives Claude new information that informs the next step. This is the agentic loop in action.

Extending the base capabilities: The built-in tools are the foundation. You can extend what Claude knows with skills, connect to external services with MCP, automate workflows with hooks, and offload tasks to subagents. These extensions form a layer on top of the core agentic loop. See Extend Claude Code for guidance on choosing the right extension for your needs.

What Claude can access

This guide focuses on the terminal. Claude Code also runs in VS Code, JetBrains IDEs, and other environments.

When you run claude in a directory, Claude Code gains access to:

• Your project. Files in your directory and subdirectories, plus files elsewhere with your permission.
• Your terminal. Any command you could run: build tools, git, package managers, system utilities, scripts. If you can do it from the command line, Claude can too.
• Your git state. Current branch, uncommitted changes, and recent commit history.
• Your CLAUDE.md. A markdown file where you store project-specific instructions, conventions, and context that Claude should know every session.
• Auto memory. Learnings Claude saves automatically as you work, like project patterns and your preferences. The first 200 lines or 25KB of MEMORY.md, whichever comes first, load at the start of each session.
• Extensions you configure. MCP servers for external services, skills for workflows, subagents for delegated work, and Claude in Chrome for browser interaction.

Because Claude sees your whole project, it can work across it. When you ask Claude to "fix the authentication bug," it searches for relevant files, reads multiple files to understand context, makes coordinated edits across them, runs tests to verify the fix, and commits the changes if you ask. This is different from inline code assistants that only see the current file.

Environments and interfaces

The agentic loop, tools, and capabilities described above are the same everywhere you use Claude Code. What changes is where the code executes and how you interact with it.

Execution environments

Claude Code runs in three environments, each with different tradeoffs for where your code executes.

Interfaces

You can access Claude Code through the terminal, IDE extensions, claude.ai/code, Remote Control, Slack, and CI/CD pipelines. The interface determines how you see and interact with Claude, but the underlying agentic loop is identical. See Use Claude Code everywhere for the full list.

Work with sessions

Claude Code saves your conversation locally as you work. Each message, tool use, and result is written to a plaintext JSONL file under ~/.claude/projects/, which enables rewinding, resuming, and forking sessions. Before Claude makes code changes, it also snapshots the affected files so you can revert if needed. For paths, retention, and how to clear this data, see application data in ~/.claude.

Sessions are independent. Each new session starts with a fresh context window, without the conversation history from previous sessions. Claude can persist learnings across sessions using auto memory, and you can add your own persistent instructions in CLAUDE.md.

Work across branches

Each Claude Code conversation is a session tied to your current directory. When you resume, you only see sessions from that directory.

Claude sees your current branch's files. When you switch branches, Claude sees the new branch's files, but your conversation history stays the same. Claude remembers what you discussed even after switching.

Since sessions are tied to directories, you can run parallel Claude sessions by using git worktrees, which create separate directories for individual branches.

Resume or fork sessions

When you resume a session with claude --continue or claude --resume, you pick up where you left off using the same session ID. New messages append to the existing conversation. Your full conversation history is restored, but session-scoped permissions are not. You'll need to re-approve those.

To branch off and try a different approach without affecting the original session, use the --fork-session flag:

claude --continue --fork-session

This creates a new session ID while preserving the conversation history up to that point. The original session remains unchanged. Like resume, forked sessions don't inherit session-scoped permissions.

Same session in multiple terminals: If you resume the same session in multiple terminals, both terminals write to the same session file. Messages from both get interleaved, like two people writing in the same notebook. Nothing corrupts, but the conversation becomes jumbled. Each terminal only sees its own messages during the session, but if you resume that session later, you'll see everything interleaved. For parallel work from the same starting point, use --fork-session to give each terminal its own clean session.

The context window

Claude's context window holds your conversation history, file contents, command outputs, CLAUDE.md, auto memory, loaded skills, and system instructions. As you work, context fills up. Claude compacts automatically, but instructions from early in the conversation can get lost. Put persistent rules in CLAUDE.md, and run /context to see what's using space.

For an interactive walkthrough of what loads and when, see Explore the context window.

When context fills up

Claude Code manages context automatically as you approach the limit. It clears older tool outputs first, then summarizes the conversation if needed. Your requests and key code snippets are preserved; detailed instructions from early in the conversation may be lost. Put persistent rules in CLAUDE.md rather than relying on conversation history.

To control what's preserved during compaction, add a "Compact Instructions" section to CLAUDE.md or run /compact with a focus (like /compact focus on the API changes).

If a single file or tool output is so large that context refills immediately after each summary, Claude Code stops auto-compacting after a few attempts and shows an error instead of looping. See Auto-compaction stops with a thrashing error for recovery steps.

Run /context to see what's using space. MCP tool definitions are deferred by default and loaded on demand via tool search, so only tool names consume context until Claude uses a specific tool. Run /mcp to check per-server costs.

Manage context with skills and subagents

Beyond compaction, you can use other features to control what loads into context.

Skills load on demand. Claude sees skill descriptions at session start, but the full content only loads when a skill is used. For skills you invoke manually, set disable-model-invocation: true to keep descriptions out of context until you need them.

Subagents get their own fresh context, completely separate from your main conversation. Their work doesn't bloat your context. When done, they return a summary. This isolation is why subagents help with long sessions.

See context costs for what each feature costs, and reduce token usage for tips on managing context.

Stay safe with checkpoints and permissions

Claude has two safety mechanisms: checkpoints let you undo file changes, and permissions control what Claude can do without asking.

Undo changes with checkpoints

Every file edit is reversible. Before Claude edits any file, it snapshots the current contents. If something goes wrong, press Esc twice to rewind to a previous state, or ask Claude to undo.

Checkpoints are local to your session, separate from git. They only cover file changes. Actions that affect remote systems (databases, APIs, deployments) can't be checkpointed, which is why Claude asks before running commands with external side effects.

Control what Claude can do

Press Shift+Tab to cycle through permission modes:

• Default: Claude asks before file edits and shell commands
• Auto-accept edits: Claude edits files and runs common filesystem commands like mkdir and mv without asking, still asks for other commands
• Plan mode: Claude uses read-only tools only, creating a plan you can approve before execution
• Auto mode: Claude evaluates all actions with background safety checks. Currently a research preview

You can also allow specific commands in .claude/settings.json so Claude doesn't ask each time. This is useful for trusted commands like npm test or git status. Settings can be scoped from organization-wide policies down to personal preferences. See Permissions for details.

Work effectively with Claude Code

These tips help you get better results from Claude Code.

Ask Claude Code for help

Claude Code can teach you how to use it. Ask questions like "how do I set up hooks?" or "what's the best way to structure my CLAUDE.md?" and Claude will explain.

Built-in commands also guide you through setup:

• /init walks you through creating a CLAUDE.md for your project
• /agents helps you configure custom subagents
• /doctor diagnoses common issues with your installation

It's a conversation

Claude Code is conversational. You don't need perfect prompts. Start with what you want, then refine:

Fix the login bug

[Claude investigates, tries something]

That's not quite right. The issue is in the session handling.

[Claude adjusts approach]

When the first attempt isn't right, you don't start over. You iterate.

Interrupt and steer

You can interrupt Claude at any point. If it's going down the wrong path, just type your correction and press Enter. Claude will stop what it's doing and adjust its approach based on your input. You don't have to wait for it to finish or start over.

Be specific upfront

The more precise your initial prompt, the fewer corrections you'll need. Reference specific files, mention constraints, and point to example patterns.

The checkout flow is broken for users with expired cards.
Check src/payments/ for the issue, especially token refresh.
Write a failing test first, then fix it.

Vague prompts work, but you'll spend more time steering. Specific prompts like the one above often succeed on the first attempt.

Give Claude something to verify against

Claude performs better when it can check its own work. Include test cases, paste screenshots of expected UI, or define the output you want.

Implement validateEmail. Test cases: 'user@example.com' → true,
'invalid' → false, 'user@.com' → false. Run the tests after.

For visual work, paste a screenshot of the design and ask Claude to compare its implementation against it.

Explore before implementing

For complex problems, separate research from coding. Use plan mode (Shift+Tab twice) to analyze the codebase first:

Read src/auth/ and understand how we handle sessions.
Then create a plan for adding OAuth support.

Review the plan, refine it through conversation, then let Claude implement. This two-phase approach produces better results than jumping straight to code.

Delegate, don't dictate

Think of delegating to a capable colleague. Give context and direction, then trust Claude to figure out the details:

The checkout flow is broken for users with expired cards.
The relevant code is in src/payments/. Can you investigate and fix it?

You don't need to specify which files to read or what commands to run. Claude figures that out.

What's next

Claude Code combines a model that reasons about your code with built-in tools for file operations, search, execution, and web access. The built-in tools cover most coding tasks. This guide covers the extension layer: features you add to customize what Claude knows, connect it to external services, and automate workflows.

New to Claude Code? Start with CLAUDE.md for project conventions, then add other extensions as specific triggers come up.

Overview

Extensions plug into different parts of the agentic loop:

• CLAUDE.md adds persistent context Claude sees every session
• Skills add reusable knowledge and invocable workflows
• MCP connects Claude to external services and tools
• Subagents run their own loops in isolated context, returning summaries
• Agent teams coordinate multiple independent sessions with shared tasks and peer-to-peer messaging
• Hooks run outside the loop entirely as deterministic scripts
• Plugins and marketplaces package and distribute these features

Skills are the most flexible extension. A skill is a markdown file containing knowledge, workflows, or instructions. You can invoke skills with a command like /deploy, or Claude can load them automatically when relevant. Skills can run in your current conversation or in an isolated context via subagents.

Match features to your goal

Features range from always-on context that Claude sees every session, to on-demand capabilities you or Claude can invoke, to background automation that runs on specific events. The table below shows what's available and when each one makes sense.

Plugins are the packaging layer. A plugin bundles skills, hooks, subagents, and MCP servers into a single installable unit. Plugin skills are namespaced (like /my-plugin:review) so multiple plugins can coexist. Use plugins when you want to reuse the same setup across multiple repositories or distribute to others via a marketplace.

Build your setup over time

You don't need to configure everything up front. Each feature has a recognizable trigger, and most teams add them in roughly this order:

The same triggers tell you when to update what you already have. A repeated mistake or a recurring review comment is a CLAUDE.md edit, not a one-off correction in chat. A workflow you keep tweaking by hand is a skill that needs another revision.

Compare similar features

Some features can seem similar. Here's how to tell them apart.

Understand how features layer

Features can be defined at multiple levels: user-wide, per-project, via plugins, or through managed policies. You can also nest CLAUDE.md files in subdirectories or place skills in specific packages of a monorepo. When the same feature exists at multiple levels, here's how they layer:

• CLAUDE.md files are additive: all levels contribute content to Claude's context simultaneously. Files from your working directory and above load at launch; subdirectories load as you work in them. When instructions conflict, Claude uses judgment to reconcile them, with more specific instructions typically taking precedence. See how CLAUDE.md files load.
• Skills and subagents override by name: when the same name exists at multiple levels, one definition wins based on priority (managed > user > project for skills; managed > CLI flag > project > user > plugin for subagents). Plugin skills are namespaced to avoid conflicts. See skill discovery and subagent scope.
• MCP servers override by name: local > project > user. See MCP scope.
• Hooks merge: all registered hooks fire for their matching events regardless of source. See hooks.

Combine features

Each extension solves a different problem: CLAUDE.md handles always-on context, skills handle on-demand knowledge and workflows, MCP handles external connections, subagents handle isolation, and hooks handle automation. Real setups combine them based on your workflow.

For example, you might use CLAUDE.md for project conventions, a skill for your deployment workflow, MCP to connect to your database, and a hook to run linting after every edit. Each feature handles what it's best at.

Understand context costs

Every feature you add consumes some of Claude's context. Too much can fill up your context window, but it can also add noise that makes Claude less effective; skills may not trigger correctly, or Claude may lose track of your conventions. Understanding these trade-offs helps you build an effective setup. For an interactive view of how these features combine in a running session, see Explore the context window.

Context cost by feature

Each feature has a different loading strategy and context cost:

*By default, skill descriptions load at session start so Claude can decide when to use them. Set disable-model-invocation: true in a skill's frontmatter to hide it from Claude entirely until you invoke it manually. This reduces context cost to zero for skills you only trigger yourself.

Understand how features load

Each feature loads at different points in your session. The tabs below explain when each one loads and what goes into context.

Learn more

Each feature has its own guide with setup instructions, examples, and configuration options.

Each Claude Code session begins with a fresh context window. Two mechanisms carry knowledge across sessions:

• CLAUDE.md files: instructions you write to give Claude persistent context
• Auto memory: notes Claude writes itself based on your corrections and preferences

This page covers how to:

• Write and organize CLAUDE.md files
• Scope rules to specific file types with .claude/rules/
• Configure auto memory so Claude takes notes automatically
• Troubleshoot when instructions aren't being followed

CLAUDE.md vs auto memory

Claude Code has two complementary memory systems. Both are loaded at the start of every conversation. Claude treats them as context, not enforced configuration. The more specific and concise your instructions, the more consistently Claude follows them.

Use CLAUDE.md files when you want to guide Claude's behavior. Auto memory lets Claude learn from your corrections without manual effort.

Subagents can also maintain their own auto memory. See subagent configuration for details.

CLAUDE.md files

CLAUDE.md files are markdown files that give Claude persistent instructions for a project, your personal workflow, or your entire organization. You write these files in plain text; Claude reads them at the start of every session.

When to add to CLAUDE.md

Treat CLAUDE.md as the place you write down what you'd otherwise re-explain. Add to it when:

• Claude makes the same mistake a second time
• A code review catches something Claude should have known about this codebase
• You type the same correction or clarification into chat that you typed last session
• A new teammate would need the same context to be productive

Keep it to facts Claude should hold in every session: build commands, conventions, project layout, "always do X" rules. If an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule instead. The extension overview covers when to use each mechanism.

Choose where to put CLAUDE.md files

CLAUDE.md files can live in several locations, each with a different scope. More specific locations take precedence over broader ones.

CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the working directory are loaded in full at launch. Files in subdirectories load on demand when Claude reads files in those directories. See How CLAUDE.md files load for the full resolution order.

For large projects, you can break instructions into topic-specific files using project rules. Rules let you scope instructions to specific file types or subdirectories.

Set up a project CLAUDE.md

A project CLAUDE.md can be stored in either ./CLAUDE.md or ./.claude/CLAUDE.md. Create this file and add instructions that apply to anyone working on the project: build and test commands, coding standards, architectural decisions, naming conventions, and common workflows. These instructions are shared with your team through version control, so focus on project-level standards rather than personal preferences.

Write effective instructions

CLAUDE.md files are loaded into the context window at the start of every session, consuming tokens alongside your conversation. The context window visualization shows where CLAUDE.md loads relative to the rest of the startup context. Because they're context rather than enforced configuration, how you write instructions affects how reliably Claude follows them. Specific, concise, well-structured instructions work best.

Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence. If your instructions are growing large, split them using imports or .claude/rules/ files.

Structure: use markdown headers and bullets to group related instructions. Claude scans structure the same way readers do: organized sections are easier to follow than dense paragraphs.

Specificity: write instructions that are concrete enough to verify. For example:

• "Use 2-space indentation" instead of "Format code properly"
• "Run npm test before committing" instead of "Test your changes"
• "API handlers live in src/api/handlers/" instead of "Keep files organized"

Consistency: if two rules contradict each other, Claude may pick one arbitrarily. Review your CLAUDE.md files, nested CLAUDE.md files in subdirectories, and .claude/rules/ periodically to remove outdated or conflicting instructions. In monorepos, use claudeMdExcludes to skip CLAUDE.md files from other teams that aren't relevant to your work.

Import additional files

CLAUDE.md files can import additional files using @path/to/import syntax. Imported files are expanded and loaded into context at launch alongside the CLAUDE.md that references them.

Both relative and absolute paths are allowed. Relative paths resolve relative to the file containing the import, not the working directory. Imported files can recursively import other files, with a maximum depth of five hops.

To pull in a README, package.json, and a workflow guide, reference them with @ syntax anywhere in your CLAUDE.md:

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

For private per-project preferences that shouldn't be checked into version control, create a CLAUDE.local.md at the project root. It loads alongside CLAUDE.md and is treated the same way. Add CLAUDE.local.md to your .gitignore so it isn't committed; running /init and choosing the personal option does this for you.

If you work across multiple git worktrees of the same repository, a gitignored CLAUDE.local.md only exists in the worktree where you created it. To share personal instructions across worktrees, import a file from your home directory instead:

# Individual Preferences
- @~/.claude/my-project-instructions.md

For a more structured approach to organizing instructions, see .claude/rules/.

AGENTS.md

Claude Code reads CLAUDE.md, not AGENTS.md. If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them. You can also add Claude-specific instructions below the import. Claude loads the imported file at session start, then appends the rest:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

How CLAUDE.md files load

Claude Code reads CLAUDE.md files by walking up the directory tree from your current working directory, checking each directory along the way for CLAUDE.md and CLAUDE.local.md files. This means if you run Claude Code in foo/bar/, it loads instructions from foo/bar/CLAUDE.md, foo/CLAUDE.md, and any CLAUDE.local.md files alongside them.

All discovered files are concatenated into context rather than overriding each other. Within each directory, CLAUDE.local.md is appended after CLAUDE.md, so when instructions conflict, your personal notes are the last thing Claude reads at that level.

Claude also discovers CLAUDE.md and CLAUDE.local.md files in subdirectories under your current working directory. Instead of loading them at launch, they are included when Claude reads files in those subdirectories.

If you work in a large monorepo where other teams' CLAUDE.md files get picked up, use claudeMdExcludes to skip them.

Block-level HTML comments (<!-- maintainer notes -->) in CLAUDE.md files are stripped before the content is injected into Claude's context. Use them to leave notes for human maintainers without spending context tokens on them. Comments inside code blocks are preserved. When you open a CLAUDE.md file directly with the Read tool, comments remain visible.

Load from additional directories

The --add-dir flag gives Claude access to additional directories outside your main working directory. By default, CLAUDE.md files from these directories are not loaded.

To also load memory files from additional directories, set the CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD environment variable:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

This loads CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md, and CLAUDE.local.md from the additional directory. CLAUDE.local.md is skipped if you exclude local from --setting-sources.

Organize rules with .claude/rules/

For larger projects, you can organize instructions into multiple files using the .claude/rules/ directory. This keeps instructions modular and easier for teams to maintain. Rules can also be scoped to specific file paths, so they only load into context when Claude works with matching files, reducing noise and saving context space.

Set up rules

Place markdown files in your project's .claude/rules/ directory. Each file should cover one topic, with a descriptive filename like testing.md or api-design.md. All .md files are discovered recursively, so you can organize rules into subdirectories like frontend/ or backend/:

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

Rules without paths frontmatter are loaded at launch with the same priority as .claude/CLAUDE.md.

Path-specific rules

Rules can be scoped to specific files using YAML frontmatter with the paths field. These conditional rules only apply when Claude is working with files matching the specified patterns.

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

Rules without a paths field are loaded unconditionally and apply to all files. Path-scoped rules trigger when Claude reads files matching the pattern, not on every tool use.

Use glob patterns in the paths field to match files by extension, directory, or any combination:

You can specify multiple patterns and use brace expansion to match multiple extensions in one pattern:

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

Share rules across projects with symlinks

The .claude/rules/ directory supports symlinks, so you can maintain a shared set of rules and link them into multiple projects. Symlinks are resolved and loaded normally, and circular symlinks are detected and handled gracefully.

This example links both a shared directory and an individual file:

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

User-level rules

Personal rules in ~/.claude/rules/ apply to every project on your machine. Use them for preferences that aren't project-specific:

~/.claude/rules/
├── preferences.md    # Your personal coding preferences
└── workflows.md      # Your preferred workflows

User-level rules are loaded before project rules, giving project rules higher priority.

Manage CLAUDE.md for large teams

For organizations deploying Claude Code across teams, you can centralize instructions and control which CLAUDE.md files are loaded.

Deploy organization-wide CLAUDE.md

Organizations can deploy a centrally managed CLAUDE.md that applies to all users on a machine. This file cannot be excluded by individual settings.

A managed CLAUDE.md and managed settings serve different purposes. Use settings for technical enforcement and CLAUDE.md for behavioral guidance:

Settings rules are enforced by the client regardless of what Claude decides to do. CLAUDE.md instructions shape Claude's behavior but are not a hard enforcement layer.

Exclude specific CLAUDE.md files

In large monorepos, ancestor CLAUDE.md files may contain instructions that aren't relevant to your work. The claudeMdExcludes setting lets you skip specific files by path or glob pattern.

This example excludes a top-level CLAUDE.md and a rules directory from a parent folder. Add it to .claude/settings.local.json so the exclusion stays local to your machine:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

Patterns are matched against absolute file paths using glob syntax. You can configure claudeMdExcludes at any settings layer: user, project, local, or managed policy. Arrays merge across layers.

Managed policy CLAUDE.md files cannot be excluded. This ensures organization-wide instructions always apply regardless of individual settings.

Auto memory

Auto memory lets Claude accumulate knowledge across sessions without you writing anything. Claude saves notes for itself as it works: build commands, debugging insights, architecture notes, code style preferences, and workflow habits. Claude doesn't save something every session. It decides what's worth remembering based on whether the information would be useful in a future conversation.

Enable or disable auto memory

Auto memory is on by default. To toggle it, open /memory in a session and use the auto memory toggle, or set autoMemoryEnabled in your project settings:

{
  "autoMemoryEnabled": false
}

To disable auto memory via environment variable, set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Storage location

Each project gets its own memory directory at ~/.claude/projects/<project>/memory/. The <project> path is derived from the git repository, so all worktrees and subdirectories within the same repo share one auto memory directory. Outside a git repo, the project root is used instead.

To store auto memory in a different location, set autoMemoryDirectory in your user or local settings:

{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

This setting is accepted from policy, local, and user settings. It is not accepted from project settings (.claude/settings.json) to prevent a shared project from redirecting auto memory writes to sensitive locations.

The directory contains a MEMORY.md entrypoint and optional topic files:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Concise index, loaded into every session
├── debugging.md       # Detailed notes on debugging patterns
├── api-conventions.md # API design decisions
└── ...                # Any other topic files Claude creates

MEMORY.md acts as an index of the memory directory. Claude reads and writes files in this directory throughout your session, using MEMORY.md to keep track of what's stored where.

Auto memory is machine-local. All worktrees and subdirectories within the same git repository share one auto memory directory. Files are not shared across machines or cloud environments.

How it works

The first 200 lines of MEMORY.md, or the first 25KB, whichever comes first, are loaded at the start of every conversation. Content beyond that threshold is not loaded at session start. Claude keeps MEMORY.md concise by moving detailed notes into separate topic files.

This limit applies only to MEMORY.md. CLAUDE.md files are loaded in full regardless of length, though shorter files produce better adherence.

Topic files like debugging.md or patterns.md are not loaded at startup. Claude reads them on demand using its standard file tools when it needs the information.

Claude reads and writes memory files during your session. When you see "Writing memory" or "Recalled memory" in the Claude Code interface, Claude is actively updating or reading from ~/.claude/projects/<project>/memory/.

Audit and edit your memory

Auto memory files are plain markdown you can edit or delete at any time. Run /memory to browse and open memory files from within a session.

View and edit with /memory

The /memory command lists all CLAUDE.md, CLAUDE.local.md, and rules files loaded in your current session, lets you toggle auto memory on or off, and provides a link to open the auto memory folder. Select any file to open it in your editor.

When you ask Claude to remember something, like "always use pnpm, not npm" or "remember that the API tests require a local Redis instance," Claude saves it to auto memory. To add instructions to CLAUDE.md instead, ask Claude directly, like "add this to CLAUDE.md," or edit the file yourself via /memory.

Troubleshoot memory issues

These are the most common issues with CLAUDE.md and auto memory, along with steps to debug them.

Claude isn't following my CLAUDE.md

CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance, especially for vague or conflicting instructions.

To debug:

• Run /memory to verify your CLAUDE.md and CLAUDE.local.md files are being loaded. If a file isn't listed, Claude can't see it.
• Check that the relevant CLAUDE.md is in a location that gets loaded for your session (see Choose where to put CLAUDE.md files).
• Make instructions more specific. "Use 2-space indentation" works better than "format code nicely."
• Look for conflicting instructions across CLAUDE.md files. If two files give different guidance for the same behavior, Claude may pick one arbitrarily.

For instructions you want at the system prompt level, use --append-system-prompt. This must be passed every invocation, so it's better suited to scripts and automation than interactive use.

I don't know what auto memory saved

Run /memory and select the auto memory folder to browse what Claude has saved. Everything is plain markdown you can read, edit, or delete.

My CLAUDE.md is too large

Files over 200 lines consume more context and may reduce adherence. Move detailed content into separate files referenced with @path imports (see Import additional files), or split your instructions across .claude/rules/ files.

Instructions seem lost after /compact

Project-root CLAUDE.md survives compaction: after /compact, Claude re-reads it from disk and re-injects it into the session. Nested CLAUDE.md files in subdirectories are not re-injected automatically; they reload the next time Claude reads a file in that subdirectory.

If an instruction disappeared after compaction, it was either given only in conversation or lives in a nested CLAUDE.md that hasn't reloaded yet. Add conversation-only instructions to CLAUDE.md to make them persist. See What survives compaction for the full breakdown.

See Write effective instructions for guidance on size, structure, and specificity.

Related resources

• Skills: package repeatable workflows that load on demand
• Settings: configure Claude Code behavior with settings files
• Subagent memory: let subagents maintain their own auto memory

When Claude wants to edit a file, run a shell command, or make a network request, it pauses and asks you to approve the action. Permission modes control how often that pause happens. The mode you pick shapes the flow of a session: default mode has you review each action as it comes, while looser modes let Claude work in longer uninterrupted stretches and report back when done. Pick more oversight for sensitive work, or fewer interruptions when you trust the direction.

Available modes

Each mode makes a different tradeoff between convenience and oversight. The table below shows what Claude can do without a permission prompt in each mode.

Regardless of mode, writes to protected paths are never auto-approved, guarding repository state and Claude's own configuration against accidental corruption.

Modes set the baseline. Layer permission rules on top to pre-approve or block specific tools in any mode except bypassPermissions, which skips the permission layer entirely.

Switch permission modes

You can switch modes mid-session, at startup, or as a persistent default. The mode is set through these controls, not by asking Claude in chat. Select your interface below to see how to change it.

claude --permission-mode plan

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

claude remote-control --permission-mode acceptEdits

Auto-approve file edits with acceptEdits mode

acceptEdits mode lets Claude create and edit files in your working directory without prompting. The status bar shows ⏵⏵ accept edits on while this mode is active.

In addition to file edits, acceptEdits mode auto-approves common filesystem Bash commands: mkdir, touch, rm, rmdir, mv, cp, and sed. These commands are also auto-approved when prefixed with safe environment variables such as LANG=C or NO_COLOR=1, or process wrappers such as timeout, nice, or nohup. Like file edits, auto-approval applies only to paths inside your working directory or additionalDirectories. Paths outside that scope, writes to protected paths, and all other Bash commands still prompt.

Use acceptEdits when you want to review changes in your editor or via git diff after the fact rather than approving each edit inline. Press Shift+Tab once from default mode to enter it, or start with it directly:

claude --permission-mode acceptEdits

Analyze before you edit with plan mode

Plan mode tells Claude to research and propose changes without making them. Claude reads files, runs shell commands to explore, and writes a plan, but does not edit your source. Permission prompts still apply the same as default mode.

Enter plan mode by pressing Shift+Tab or prefixing a single prompt with /plan. You can also start in plan mode from the CLI:

claude --permission-mode plan

Press Shift+Tab again to leave plan mode without approving a plan.

When the plan is ready, Claude presents it and asks how to proceed. From that prompt you can:

• Approve and start in auto mode
• Approve and accept edits
• Approve and review each edit manually
• Keep planning with feedback
• Refine with Ultraplan for browser-based review

Each approve option also offers to clear the planning context first.

Eliminate prompts with auto mode

Auto mode lets Claude execute without permission prompts. A separate classifier model reviews actions before they run, blocking anything that escalates beyond your request, targets unrecognized infrastructure, or appears driven by hostile content Claude read.

Auto mode is available only when your account meets all of these requirements:

• Plan: Team, Enterprise, or API. Not available on Pro or Max.
• Admin: on Team and Enterprise, an admin must enable it in Claude Code admin settings before users can turn it on. Admins can also lock it off by setting permissions.disableAutoMode to "disable" in managed settings.
• Model: Claude Sonnet 4.6 or Opus 4.6. Not available on Haiku or claude-3 models.
• Provider: Anthropic API only. Not available on Bedrock, Vertex, or Foundry.

If Claude Code reports auto mode as unavailable, one of these requirements is unmet; this is not a transient outage.

Once enabled, start with the flag and auto joins the Shift+Tab cycle:

claude --enable-auto-mode

What the classifier blocks by default

The classifier trusts your working directory and your repo's configured remotes. Everything else is treated as external until you configure trusted infrastructure.

Blocked by default:

• Downloading and executing code, like curl | bash
• Sending sensitive data to external endpoints
• Production deploys and migrations
• Mass deletion on cloud storage
• Granting IAM or repo permissions
• Modifying shared infrastructure
• Irreversibly destroying files that existed before the session
• Force push, or pushing directly to main

Allowed by default:

• Local file operations in your working directory
• Installing dependencies declared in your lock files or manifests
• Reading .env and sending credentials to their matching API
• Read-only HTTP requests
• Pushing to the branch you started on or one Claude created
• Sandbox network access requests

Run claude auto-mode defaults to see the full rule lists. If routine actions get blocked, an administrator can add trusted repos, buckets, and services via the autoMode.environment setting: see Configure the auto mode classifier.

When auto mode falls back

Each denied action shows a notification and appears in /permissions under the Recently denied tab, where you can press r to retry it with a manual approval.

If the classifier blocks an action 3 times in a row or 20 times total, auto mode pauses and Claude Code resumes prompting. Approving the prompted action resumes auto mode. These thresholds are not configurable. Any allowed action resets the consecutive counter, while the total counter persists for the session and resets only when its own limit triggers a fallback.

In non-interactive mode with the -p flag, repeated blocks abort the session since there is no user to prompt.

Repeated blocks usually mean the classifier is missing context about your infrastructure. Use /feedback to report false positives, or have an administrator configure trusted infrastructure.

Allow only pre-approved tools with dontAsk mode

dontAsk mode auto-denies every tool that is not explicitly allowed. Only actions matching your permissions.allow rules can execute; explicit ask rules are also denied rather than prompting. This makes the mode fully non-interactive for CI pipelines or restricted environments where you pre-define exactly what Claude may do.

Set it at startup with the flag:

claude --permission-mode dontAsk

Skip all checks with bypassPermissions mode

bypassPermissions mode disables permission prompts and safety checks so tool calls execute immediately. Writes to protected paths are the only actions that still prompt. Only use this mode in isolated environments like containers, VMs, or devcontainers without internet access, where Claude Code cannot damage your host system.

You cannot enter bypassPermissions from a session that was started without one of the enabling flags; restart with one to enable it:

claude --permission-mode bypassPermissions

The --dangerously-skip-permissions flag is equivalent.

Protected paths

Writes to a small set of paths are never auto-approved, in every mode. This prevents accidental corruption of repository state and Claude's own configuration. In default, acceptEdits, plan, and bypassPermissions these writes prompt; in auto they route to the classifier; in dontAsk they are denied.

Protected directories:

• .git
• .vscode
• .idea
• .husky
• .claude, except for .claude/commands, .claude/agents, .claude/skills, and .claude/worktrees where Claude routinely creates content

Protected files:

• .gitconfig, .gitmodules
• .bashrc, .bash_profile, .zshrc, .zprofile, .profile
• .ripgreprc
• .mcp.json, .claude.json

See also

• Permissions: allow, ask, and deny rules; auto mode classifier configuration; managed policies
• Hooks: custom permission logic via PreToolUse and PermissionRequest hooks
• Ultraplan: run plan mode in a Claude Code on the web session with browser-based review
• Security: safeguards and best practices
• Sandboxing: filesystem and network isolation for Bash commands
• Non-interactive mode: run Claude Code with the -p flag

This page covers practical workflows for everyday development: exploring unfamiliar code, debugging, refactoring, writing tests, creating PRs, and managing sessions. Each section includes example prompts you can adapt to your own projects. For higher-level patterns and tips, see Best practices.

Understand new codebases

Get a quick codebase overview

Suppose you've just joined a new project and need to understand its structure quickly.

cd /path/to/project 

claude 

give me an overview of this codebase

explain the main architecture patterns used here

what are the key data models?

how is authentication handled?

Find relevant code

Suppose you need to locate code related to a specific feature or functionality.

find the files that handle user authentication

how do these authentication files work together?

trace the login process from front-end to database

Fix bugs efficiently

Suppose you've encountered an error message and need to find and fix its source.

I'm seeing an error when I run npm test

suggest a few ways to fix the @ts-ignore in user.ts

update user.ts to add the null check you suggested

Refactor code

Suppose you need to update old code to use modern patterns and practices.

find deprecated API usage in our codebase

suggest how to refactor utils.js to use modern JavaScript features

refactor utils.js to use ES2024 features while maintaining the same behavior

run tests for the refactored code

Use specialized subagents

Suppose you want to use specialized AI subagents to handle specific tasks more effectively.

/agents

review my recent code changes for security issues

run all tests and fix any failures

use the code-reviewer subagent to check the auth module

have the debugger subagent investigate why users can't log in

/agents

Use Plan Mode for safe code analysis

Plan Mode instructs Claude to create a plan by analyzing the codebase with read-only operations, perfect for exploring codebases, planning complex changes, or reviewing code safely. In Plan Mode, Claude uses AskUserQuestion to gather requirements and clarify your goals before proposing a plan.

When to use Plan Mode

• Multi-step implementation: When your feature requires making edits to many files
• Code exploration: When you want to research the codebase thoroughly before changing anything
• Interactive development: When you want to iterate on the direction with Claude

How to use Plan Mode

Turn on Plan Mode during a session

You can switch into Plan Mode during a session using Shift+Tab to cycle through permission modes.

If you are in Normal Mode, Shift+Tab first switches into Auto-Accept Mode, indicated by ⏵⏵ accept edits on at the bottom of the terminal. A subsequent Shift+Tab will switch into Plan Mode, indicated by ⏸ plan mode on.

Start a new session in Plan Mode

To start a new session in Plan Mode, use the --permission-mode plan flag:

claude --permission-mode plan

Run "headless" queries in Plan Mode

You can also run a query in Plan Mode directly with -p (that is, in "headless mode"):

claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"

Example: Planning a complex refactor

claude --permission-mode plan

I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.

Claude analyzes the current implementation and create a comprehensive plan. Refine with follow-ups:

What about backward compatibility?

How should we handle database migration?

When you accept a plan, Claude automatically names the session from the plan content. The name appears on the prompt bar and in the session picker. If you've already set a name with --name or /rename, accepting a plan won't overwrite it.

Configure Plan Mode as default

// .claude/settings.json
{
  "permissions": {
    "defaultMode": "plan"
  }
}

See settings documentation for more configuration options.

Work with tests

Suppose you need to add tests for uncovered code.

find functions in NotificationsService.swift that are not covered by tests

add tests for the notification service

add test cases for edge conditions in the notification service

run the new tests and fix any failures

Claude can generate tests that follow your project's existing patterns and conventions. When asking for tests, be specific about what behavior you want to verify. Claude examines your existing test files to match the style, frameworks, and assertion patterns already in use.

For comprehensive coverage, ask Claude to identify edge cases you might have missed. Claude can analyze your code paths and suggest tests for error conditions, boundary values, and unexpected inputs that are easy to overlook.

Create pull requests

You can create pull requests by asking Claude directly ("create a pr for my changes"), or guide Claude through it step-by-step:

summarize the changes I've made to the authentication module

create a pr

enhance the PR description with more context about the security improvements

When you create a PR using gh pr create, the session is automatically linked to that PR. You can resume it later with claude --from-pr <number>.

Handle documentation

Suppose you need to add or update documentation for your code.

find functions without proper JSDoc comments in the auth module

add JSDoc comments to the undocumented functions in auth.js

improve the generated documentation with more context and examples

check if the documentation follows our project standards

Work with images

Suppose you need to work with images in your codebase, and you want Claude's help analyzing image content.

What does this image show?

Describe the UI elements in this screenshot

Are there any problematic elements in this diagram?

Here's a screenshot of the error. What's causing it?

This is our current database schema. How should we modify it for the new feature?

Generate CSS to match this design mockup

What HTML structure would recreate this component?

Reference files and directories

Use @ to quickly include files or directories without waiting for Claude to read them.

Explain the logic in @src/utils/auth.js

What's the structure of @src/components?

Show me the data from @github:repos/owner/repo/issues

Use extended thinking (thinking mode)

Extended thinking is enabled by default, giving Claude space to reason through complex problems step-by-step before responding. This reasoning is visible in verbose mode, which you can toggle on with Ctrl+O.

Additionally, Opus 4.6 and Sonnet 4.6 support adaptive reasoning: instead of a fixed thinking token budget, the model dynamically allocates thinking based on your effort level setting. Extended thinking and adaptive reasoning work together to give you control over how deeply Claude reasons before responding.

Extended thinking is particularly valuable for complex architectural decisions, challenging bugs, multi-step implementation planning, and evaluating tradeoffs between different approaches.

Configure thinking mode

Thinking is enabled by default, but you can adjust or disable it.

To view Claude's thinking process, press Ctrl+O to toggle verbose mode and see the internal reasoning displayed as gray italic text.

How extended thinking works

Extended thinking controls how much internal reasoning Claude performs before responding. More thinking provides more space to explore solutions, analyze edge cases, and self-correct mistakes.

With Opus 4.6 and Sonnet 4.6, thinking uses adaptive reasoning: the model dynamically allocates thinking tokens based on the effort level you select. This is the recommended way to tune the tradeoff between speed and reasoning depth.

With older models, thinking uses a fixed token budget drawn from your output allocation. The budget varies by model; see MAX_THINKING_TOKENS for per-model ceilings. You can limit the budget with that environment variable, or disable thinking entirely via /config or the Option+T/Alt+T toggle.

On Opus 4.6 and Sonnet 4.6, adaptive reasoning controls thinking depth, so MAX_THINKING_TOKENS only applies when set to 0 to disable thinking, or when CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 reverts these models to the fixed budget. See environment variables.

Resume previous conversations

When starting Claude Code, you can resume a previous session:

• claude --continue continues the most recent conversation in the current directory
• claude --resume opens a conversation picker or resumes by name
• claude --from-pr 123 resumes sessions linked to a specific pull request

From inside an active session, use /resume to switch to a different conversation.

Sessions are stored per project directory. The /resume picker shows interactive sessions from the same git repository, including worktrees. When you select a session from another worktree of the same repository, Claude Code resumes it directly without requiring you to switch directories first. Sessions created by claude -p or SDK invocations do not appear in the picker, but you can still resume one by passing its session ID or custom name to claude --resume <session-id-or-name>. Custom names set with --name or /rename are accepted in addition to session IDs.