User Guide

Relevant source files

• CHANGELOG.md
• LICENSE.md
• README.md
• demo.gif

This page provides comprehensive documentation for end users on how to install, configure, and effectively use Claude Code. It covers the essential concepts, workflows, and capabilities needed to get started with the system.

For detailed information on specific topics:

• Installation procedures and initial setup: see Installation & Setup
• Configuration files and settings hierarchy: see Configuration Management
• Complete command reference and interactive commands: see CLI Commands & Interaction Modes
• Session lifecycle and management: see Session Management
• Feedback and issue reporting: see Providing Feedback & Reporting Issues

For information about extending Claude Code with plugins, hooks, and skills, see Plugin System, Hook System, and Skill System.

What is Claude Code?

Claude Code is an agentic coding tool that operates in your terminal, providing an interactive AI assistant for software development tasks. The system processes natural language commands, executes tools with permission controls, and maintains conversation context across sessions.

Key capabilities:

• Execute bash commands, read/write/edit files, search codebases
• Manage sessions with resume, fork, and branching capabilities
• Extend functionality through plugins, skills, and MCP servers
• Configure permissions and sandbox environments for security
• Spawn subagents for parallel or isolated task execution

Sources: README.md1-73 CHANGELOG.md1-50

Core System Architecture

System Flow:

1. User invokes claude command in terminal
2. REPL accepts natural language input or slash commands
3. Agent processes messages and determines tool usage
4. Permission Classifier evaluates tool requests against rules
5. Tools execute with appropriate isolation (sandbox/worktree)
6. Context Manager tracks token usage and triggers compaction
7. Session Storage persists conversation state

Sources: README.md1-73 CHANGELOG.md1-100

Installation Methods

Claude Code supports multiple installation methods. The recommended approach varies by platform:

Platform	Recommended Method	Command
macOS/Linux	Install script	curl -fsSL https://claude.ai/install.sh | bash
macOS/Linux	Homebrew	brew install --cask claude-code
Windows	Install script	irm https://claude.ai/install.ps1 | iex
Windows	WinGet	winget install Anthropic.ClaudeCode
All platforms	npm (deprecated)	npm install -g @anthropic-ai/claude-code

After installation, navigate to your project directory and run:

The system will prompt for authentication on first launch. See Installation & Setup for detailed instructions, troubleshooting, and alternative installation methods.

Sources: README.md14-46 CHANGELOG.md390-391

Basic Workflow

Typical interaction pattern:

1. Start Claude Code in project directory: claude
2. Provide natural language task descriptions
3. Review and approve permission requests
4. Iterate with follow-up questions or commands
5. Use slash commands for system operations (/model, /compact, etc.)
6. Exit with Ctrl+C (session auto-saves for resume)

Sources: README.md1-73 CHANGELOG.md32-100

Command Types

Claude Code supports three types of commands:

Natural Language Prompts

Standard conversational input processed by the AI agent. Examples:

• "Read the authentication module and explain how tokens are validated"
• "Create a new feature for user preferences"
• "Fix the bug in the payment processing logic"

Slash Commands

Built-in system commands that execute immediately. Common commands:

Command	Purpose
/help	Display available commands
/model	Select AI model
/compact	Trigger context compaction
/clear	Clear conversation history
/resume	Resume previous session
/config	Open settings editor
/sandbox	Configure bash sandbox

Full reference: CLI Commands & Interaction Modes

Skills

User-defined or plugin-provided commands with custom behavior. Skills are defined in SKILL.md files and support parameters, hooks, and custom tools.

Sources: CHANGELOG.md501-502 CHANGELOG.md543-548

Session Management

Session lifecycle:

• Sessions automatically save on exit (Ctrl+C)
• Resume with claude --resume (shows session picker)
• Resume specific session: claude --resume <session-id>
• Fork creates a branch from current conversation state
• Rename sessions: /rename [name]
• Link to PRs: --from-pr flag or automatic detection

Session storage location: ~/.claude/sessions/

Each session includes:

• Message transcript
• Tool execution results
• Context state
• Custom title (if renamed)
• Associated PR link (if applicable)

Sources: CHANGELOG.md55-56 CHANGELOG.md279-285 CHANGELOG.md329-344

Permission System

Permission rules control tool execution based on patterns:

• allow: Execute without prompting
• ask: Prompt user for approval (default)
• deny: Block execution

Rule syntax examples:

Wildcard patterns: Rules support * at any position (e.g., Bash(npm *), Bash(* install))

Scope hierarchy: Rules can be defined at enterprise, user, project, or local scope.

See Configuration Management for detailed rule configuration.

Sources: CHANGELOG.md562-563 CHANGELOG.md80-81 CHANGELOG.md449-450

Tool System Overview

Built-in tools:

• Bash: Execute shell commands (with optional sandbox)
• FileRead: Read file contents with token limits
• FileWrite: Create or overwrite files
• FileEdit: Apply targeted edits to existing files
• Task: Spawn subagents for parallel/isolated execution
• WebSearch: Search the web for information
• ToolSearch: Search within tool documentation
• MCP Tools: Dynamically loaded from MCP servers

Sandbox mode: When enabled, Bash tool executes in an isolated environment with:

• Network access restrictions (allowlist-based)
• Command exclusions (e.g., docker, git can escape sandbox)
• Automatic permission grants for sandboxed commands

See Sandbox Environment and Tool System & Permissions for details.

Sources: CHANGELOG.md198-199 CHANGELOG.md240-247

Configuration Hierarchy

Settings locations:

1. Enterprise/Managed: System-wide controls (cannot be overridden)
   • macOS/Linux: /etc/claude/managed-settings.json
   • Windows: C:\Program Files\ClaudeCode\managed-settings.json
2. User: ~/.claude/settings.json
3. Project: .claude/settings.json (in project root)
4. Local: settings.local.json (gitignored, machine-specific)

Key settings categories:

• Permission rules (permissionRules)
• Sandbox configuration (sandbox)
• Plugin enablement (enabledPlugins)
• Model preferences (defaultModel)
• Hook controls (disableAllHooks)
• Language preference (language)

Access settings: Use /config command for interactive editing.

See Configuration Management for comprehensive settings documentation.

Sources: CHANGELOG.md543-548 CHANGELOG.md536-537

Plugin and Skill System

Plugin categories:

• Development: Tools for building features (e.g., plugin-dev, feature-dev)
• Productivity: Git workflows, code review (e.g., commit-commands, code-review)
• Learning: Educational output styles (e.g., explanatory-output-style)
• Security: Security guidance and warnings

Skills are markdown files (SKILL.md) defining custom commands:

• Support frontmatter with metadata (name, description, permissions)
• Can include hooks (PreToolUse, PostToolUse)
• Hot-reload enabled (changes apply immediately)
• Discovered from ~/.claude/skills/ and .claude/skills/

Agents are specialized AI assistants defined in .claude/agents/*.md:

• Custom system prompts
• Model preferences
• Tool restrictions
• Memory scopes

See Plugin System, Skill System, and Official Plugins for detailed documentation.

Sources: CHANGELOG.md542-548 CHANGELOG.md226-227 CHANGELOG.md424-425

Context Management

Context window management:

• Tracks token usage in status bar
• Warns at high utilization (~65%+)
• Auto-compacts at ~98% capacity
• Manual compaction: /compact command

Compaction process:

• Sends conversation history to API for summarization
• Preserves recent messages
• Maintains task continuity
• Retains session metadata (title, PR link)

Token limits:

• Vary by model (e.g., Sonnet 4.6: 1M tokens)
• Reserved for output (max_tokens configuration)
• Tool descriptions counted against budget
• MCP tool search helps manage large tool sets

See Context Window & Compaction for implementation details.

Sources: CHANGELOG.md16-17 CHANGELOG.md329-344 CHANGELOG.md400-401

Background Tasks and Subagents

Background execution:

• Press Ctrl+B to background any running command
• Tasks complete asynchronously
• Notifications show results
• View with /tasks command
• Kill all: Ctrl+F (two-press confirmation)

Subagents:

• Spawned via Task tool
• Isolated context (separate conversation)
• Support worktree isolation (--worktree flag)
• Can specify custom agents (--agent parameter)
• Memory scopes: user, project, local

Agent teams (experimental):

• Multi-agent collaboration
• Teammate spawning in tmux sessions
• Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

See Agent System & Subagents for multi-agent orchestration patterns.

Sources: CHANGELOG.md5-12 CHANGELOG.md222-224 CHANGELOG.md496-497

Keyboard Shortcuts

Shortcut	Action	Context
Ctrl+C / ESC	Cancel or exit	Main input
Ctrl+B	Background current task	Active execution
Ctrl+F	Kill background agents	Background tasks running
Ctrl+G	Open external editor	Input field
Ctrl+R	Search command history	Input field
Ctrl+S	Stash current prompt	Input field
Shift+Enter	Insert newline	Input field
Shift+Down	Navigate teammates	Agent teams
Tab	Accept autocomplete	Input field
Up/Down	Command history	Input field

Customization: Configure custom keybindings with /keybindings command.

See CLI Commands & Interaction Modes for complete command reference.

Sources: CHANGELOG.md372-373 CHANGELOG.md50-52 CHANGELOG.md442-443

Model Selection

Models can be selected via /model command or --model flag:

Available models (varies by plan):

• Claude Sonnet 4.6 (default, 1M context)
• Claude Opus 4.6 (reasoning-focused)
• Claude Haiku (fast operations)

Fast mode: Available for Opus 4.6 with /fast command (requires extra-usage plan)

Provider support:

• Anthropic API (default)
• AWS Bedrock
• Google Vertex AI
• Custom providers

Model-specific features:

• Extended thinking (Opus)
• Adaptive thinking
• Effort levels (low/medium/high)

Sources: CHANGELOG.md16-17 CHANGELOG.md194-195 CHANGELOG.md110-111

Data Collection and Privacy

When using Claude Code, the system collects:

• Usage data (code acceptance/rejection)
• Conversation data
• User feedback via /bug command

Privacy safeguards:

• Limited retention periods for sensitive information
• Restricted access to user session data
• Clear policies against model training usage
• Configurable telemetry settings

For complete details, see:

• Commercial Terms of Service
• Privacy Policy
• Data usage policies

Help improve Claude: Configurable via settings or during session.

Sources: README.md62-72 CHANGELOG.md484-485

Troubleshooting and Diagnostics

Diagnostic command: /doctor

• Checks installation method
• Verifies authentication
• Lists auto-update channel
• Shows available versions
• Detects unreachable permission rules

Common issues:

• Authentication failures: Use claude auth login
• Update issues: Check auto-update channel in /config
• Permission errors: Review rules with /doctor
• Context overflow: Use /compact or check token usage
• MCP connection failures: Cached auth failures (automatic retry)

Debug logging: Enable verbose mode in settings or use --verbose flag.

Community support: Join Claude Developers Discord

Sources: CHANGELOG.md466-467 CHANGELOG.md155-157 README.md56-58

Next Steps

After completing basic setup, explore these topics:

1. Configure permissions: Review Configuration Management to customize tool permissions and sandbox settings
2. Install plugins: Browse marketplace with /plugins to extend functionality
3. Create custom skills: Learn Skill System to define project-specific commands
4. Optimize context: Understand Context Window & Compaction for long sessions
5. Leverage hooks: Use Hook System for workflow automation

For comprehensive command documentation, see CLI Commands & Interaction Modes.

Sources: README.md1-73