Advanced Features
Comprehensive guide to Claude Code’s advanced capabilities including planning mode, extended thinking, auto mode, background tasks, permission modes, print mode (non-interactive), session management, interactive features, channels, voice dictation, remote control, web sessions, desktop app, task list, prompt suggestions, git worktrees, sandboxing, managed settings, and configuration.
Table of Contents
- Overview
- Planning Mode
- Extended Thinking
- Auto Mode
- Background Tasks
- Scheduled Tasks
- Permission Modes
- Headless Mode
- Session Management
- Interactive Features
- Voice Dictation
- Channels
- Chrome Integration
- Remote Control
- Web Sessions
- Desktop App
- Task List
- Prompt Suggestions
- Git Worktrees
- Sandboxing
- Managed Settings (Enterprise)
- Configuration and Settings
- Best Practices
- Related Concepts
- Deep Dives
Overview
Advanced features in Claude Code extend the core capabilities with planning, reasoning, automation, and control mechanisms. These features enable sophisticated workflows for complex development tasks, code review, automation, and multi-session management.
Key advanced features include:
- Planning Mode: Create detailed implementation plans before coding
- Extended Thinking: Deep reasoning for complex problems
- Auto Mode: Background safety classifier reviews each action before execution (Research Preview)
- Background Tasks: Run long operations without blocking the conversation
- Permission Modes: Control what Claude can do (
default,acceptEdits,plan,auto,dontAsk,bypassPermissions) - Print Mode: Run Claude Code non-interactively for automation and CI/CD (
claude -p) - Session Management: Manage multiple work sessions
- Interactive Features: Keyboard shortcuts, multi-line input, and command history
- Voice Dictation: Push-to-talk voice input with 20-language STT support
- Channels: MCP servers push messages into running sessions (Research Preview)
- Remote Control: Control Claude Code from Claude.ai or the Claude app
- Web Sessions: Run Claude Code in the browser at claude.ai/code
- Desktop App: Standalone app for visual diff review and multiple sessions
- Task List: Persistent task tracking across context compactions
- Prompt Suggestions: Smart command suggestions based on context
- Git Worktrees: Isolated worktree branches for parallel work
- Sandboxing: OS-level filesystem and network isolation
- Managed Settings: Enterprise deployment via plist, Registry, or managed files
- Configuration: Customize behavior with JSON configuration files
Planning Mode
Planning mode allows Claude to think through complex tasks before implementing them, creating a detailed plan that you can review and approve.
What is Planning Mode?
Planning mode is a two-phase approach:
- Planning Phase: Claude analyzes the task and creates a detailed implementation plan
- Implementation Phase: After approval, Claude executes the plan
When to Use Planning Mode
✅ Use planning mode for:
- Complex multi-file refactoring
- New feature implementations
- Architectural changes
- Database migrations
- Major API redesigns
❌ Don’t use planning mode for:
- Simple bug fixes
- Formatting changes
- Single-file edits
- Quick queries
Activating Planning Mode
Slash command:
/plan Implement user authentication systemCLI flag:
claude --permission-mode planSet as default:
{ "permissions": { "defaultMode": "plan" }}Keyboard shortcut:
Shift + Tab- Toggle permission modes (including plan)Alt + M- Toggle permission modes (Windows/Linux)
Benefits of Planning Mode
- Structured implementation approach: Detailed breakdown of implementation steps
- Review and approval: Approve or adjust the plan before execution
- Risk identification: Identify potential issues before implementation
- Clear phases: Organized implementation phases and milestones
Example: Feature Implementation
User: /plan Add a real-time notification system
Claude: I'll create a plan for implementing real-time notifications.
## Implementation Plan
### Phase 1: Infrastructure Setup1. Install WebSocket libraries (socket.io)2. Set up WebSocket server3. Configure connection management
### Phase 2: Backend Implementation4. Create notification service5. Implement notification queue6. Add database schema for notifications7. Create API endpoints
### Phase 3: Frontend Integration8. Set up WebSocket client9. Create notification UI components10. Implement notification state management11. Add notification permissions
### Phase 4: Testing & Deployment12. Write unit tests13. Write integration tests14. Update documentation15. Deploy to staging
Estimated time: 3-4 hoursFiles to modify: 12New files to create: 8
Ready to proceed? (yes/no/modify plan)
User: yes
Claude: [Begins implementation following the plan]Plan Modifications
User: Modify the plan - skip the queue for now, we'll add it later
Claude: Updated plan:[Shows modified plan with queue removed]
User: Looks good, proceed
Claude: [Implements modified plan]Planning Mode Configuration
Planning mode is activated via the CLI flag or slash command:
# Activate plan mode via CLIclaude --permission-mode plan
# Or use the /plan slash command inside the REPL/plan Implement user authentication systemModel alias for planning: Use opusplan as a model alias to use Opus for planning and Sonnet for execution:
claude --model opusplan "design and implement the new API"Edit plan externally: Press Ctrl+G to open the current plan in your external editor for detailed modifications.
Extended Thinking
Extended thinking allows Claude to spend more time reasoning about complex problems before providing a solution.
What is Extended Thinking?
Extended thinking is a deliberate, step-by-step reasoning process where Claude:
- Breaks down complex problems
- Considers multiple approaches
- Evaluates trade-offs
- Reasons through edge cases
Activating Extended Thinking
Keyboard shortcut:
Option + T(macOS) /Alt + T(Windows/Linux) - Toggle extended thinking
Automatic activation:
- Enabled by default for all models (Opus 4.6, Sonnet 4.6, Haiku 4.5)
- Opus 4.6: Adaptive reasoning with effort levels:
low(○),medium(◐),high(●),max(Opus 4.6 only) - Other models: Fixed budget up to 31,999 tokens
Configuration methods:
- Toggle:
Alt+T/Option+T, or via/config - View reasoning:
Ctrl+O(verbose mode) - Set effort:
/effortcommand or--effortflag
Custom budget:
export MAX_THINKING_TOKENS=1024Effort level (Opus 4.6 only):
export CLAUDE_CODE_EFFORT_LEVEL=high # low (○), medium (◐), high (●), or max (Opus 4.6 only)CLI flag:
claude --effort high "complex architectural review"Slash command:
/effort highNote: The keyword “ultrathink” in prompts activates deep reasoning mode. Effort levels
low,medium,high, andmax(Opus 4.6 only) control how much reasoning Claude performs.
Benefits of Extended Thinking
- Deep reasoning: Spend more time thinking about complex problems
- Better architectural decisions: Make informed choices with comprehensive evaluation
- Consideration of edge cases: Think through potential issues and scenarios
- Thorough analysis: Structured approach to complex problem-solving
Example: Architectural Decision
User: /think Should we use microservices or a monolith for our e-commerce platform?
Claude: Let me think through this architectural decision carefully...
<extended_thinking>## Context Analysis- Team size: 5 developers- Expected traffic: 10k daily users initially- Need to scale to 100k+ users- Limited DevOps resources- 6-month timeline to MVP
## Approach 1: MicroservicesPros:+ Independent scaling+ Technology flexibility+ Team independence+ Fault isolation
Cons:- Operational complexity- Network overhead- Distributed tracing needed- Requires DevOps expertise- Slower initial development
## Approach 2: MonolithPros:+ Simpler deployment+ Faster initial development+ Easier debugging+ Lower operational overhead+ Single codebase
Cons:- Scaling challenges later- All-or-nothing deployments- Technology lock-in- Potential for tight coupling
## Decision Factors1. Team size (5 devs) → Favors monolith2. DevOps resources (limited) → Favors monolith3. Timeline (6 months) → Favors monolith4. Future scale (100k users) → Achievable with monolith + caching5. Complexity budget → Limited
## RecommendationStart with a **modular monolith**:- Single deployment unit- Clear module boundaries- Clean interfaces between modules- Prepare for future extraction to microservices if needed
This gives you:✓ Fast initial development✓ Low operational complexity✓ Option to extract services later✓ Clear architecture
Migration path: When you reach 50k+ users or specific modules need independent scaling, extract those modules into microservices.</extended_thinking>
**Recommendation**: Implement a modular monolith with clean module boundaries.
This approach balances your current constraints (team size, timeline, DevOps resources) with future scalability needs. You can migrate specific modules to microservices later when there's a clear business need.Extended Thinking Configuration
Extended thinking is controlled via environment variables, keyboard shortcuts, and CLI flags:
# Set thinking token budgetexport MAX_THINKING_TOKENS=16000
# Set effort level (Opus 4.6 only): low (○), medium (◐), high (●), or max (Opus 4.6 only)export CLAUDE_CODE_EFFORT_LEVEL=highToggle during a session with Alt+T / Option+T, set effort with /effort, or configure via /config.
Auto Mode
Auto Mode is a Research Preview permission mode (March 2026) that uses a background safety classifier to review each action before execution. It allows Claude to work autonomously while blocking dangerous operations.
Requirements
- Plan: Team plan (Enterprise and API rolling out)
- Model: Claude Sonnet 4.6 or Opus 4.6
- Classifier: Runs on Claude Sonnet 4.6 (adds extra token cost)
Enabling Auto Mode
# Unlock auto mode with CLI flagclaude --enable-auto-mode
# Then cycle to it with Shift+Tab in the REPLOr set it as the default permission mode:
claude --permission-mode autoSetting via config:
{ "permissions": { "defaultMode": "auto" }}How the Classifier Works
The background classifier evaluates each action using the following decision order:
- Allow/deny rules — Explicit permission rules are checked first
- Read-only/edits auto-approved — File reads and edits pass automatically
- Classifier — The background classifier reviews the action
- Fallback — Falls back to prompting after 3 consecutive or 20 total blocks
Default Blocked Actions
Auto mode blocks the following by default:
| Blocked Action | Example |
|---|---|
| Pipe-to-shell installs | curl | bash |
| Sending sensitive data externally | API keys, credentials over network |
| Production deploys | Deploy commands targeting production |
| Mass deletion | rm -rf on large directories |
| IAM changes | Permission and role modifications |
| Force push to main | git push --force origin main |
Default Allowed Actions
| Allowed Action | Example |
|---|---|
| Local file operations | Read, write, edit project files |
| Declared dependency installs | npm install, pip install from manifest |
| Read-only HTTP | curl for fetching documentation |
| Pushing to current branch | git push origin feature-branch |
🔧 Under the Hood: 6-Layer Permission Pipeline
Auto mode’s classifier is just one layer. The full permission pipeline has 6 layers: safe tool allowlist, permission mode, shell rule matching, dangerous patterns, bash AST analysis, and denial tracking. 99% of calls are fast-pathed at layer 1. Deep dive → Permission Pipeline
Configuring Auto Mode
Print default rules as JSON:
claude auto-mode defaultsConfigure trusted infrastructure via the autoMode.environment managed setting for enterprise deployments. This allows administrators to define trusted CI/CD environments, deployment targets, and infrastructure patterns.
Fallback Behavior
When the classifier is uncertain, auto mode falls back to prompting the user:
- After 3 consecutive classifier blocks
- After 20 total classifier blocks in a session
This ensures the user always retains control when the classifier cannot confidently approve an action.
Seeding Auto-Mode-Equivalent Permissions (No Team Plan Required)
If you don’t have a Team plan or want a simpler approach without the background classifier, you can seed your ~/.claude/settings.json with a conservative baseline of safe permission rules. The script starts with read-only and local-inspection rules, then lets you opt into edits, tests, local git writes, package installs, and GitHub write actions only when you want them.
File: 09-advanced-features/setup-auto-mode-permissions.py
# Preview what would be added (no changes written)python3 09-advanced-features/setup-auto-mode-permissions.py --dry-run
# Apply the conservative baselinepython3 09-advanced-features/setup-auto-mode-permissions.py
# Add more capability only when you need itpython3 09-advanced-features/setup-auto-mode-permissions.py --include-edits --include-testspython3 09-advanced-features/setup-auto-mode-permissions.py --include-git-write --include-packagesThe script adds rules across these categories:
| Category | Examples |
|---|---|
| Core read-only tools | Read(*), Glob(*), Grep(*), Agent(*), WebSearch(*), WebFetch(*) |
| Local inspection | Bash(git status:*), Bash(git log:*), Bash(git diff:*), Bash(cat:*) |
| Optional edits | Edit(*), Write(*), NotebookEdit(*) |
| Optional test/build | Bash(pytest:*), Bash(python3 -m pytest:*), Bash(cargo test:*) |
| Optional git writes | Bash(git add:*), Bash(git commit:*), Bash(git stash:*) |
| Git (local write) | Bash(git add:*), Bash(git commit:*), Bash(git checkout:*) |
| Package managers | Bash(npm install:*), Bash(pip install:*), Bash(cargo build:*) |
| Build & test | Bash(make:*), Bash(pytest:*), Bash(go test:*) |
| Common shell | Bash(ls:*), Bash(cat:*), Bash(find:*), Bash(cp:*), Bash(mv:*) |
| GitHub CLI | Bash(gh pr view:*), Bash(gh pr create:*), Bash(gh issue list:*) |
Dangerous operations (rm -rf, sudo, force push, DROP TABLE, terraform destroy, etc.) are intentionally excluded. The script is idempotent — running it twice won’t duplicate rules.
Background Tasks
Background tasks allow long-running operations to execute without blocking your conversation.
🔧 Under the Hood: 7 Task Types + Context Defense
Claude Code supports 7 background task types including a “dream” task that consolidates memories between sessions. All tasks write output to disk with incremental reading via offset — crash-safe, size-unlimited, multi-reader. Context is protected by 5 escalating defense layers. Deep dive → Context & Memory
What Are Background Tasks?
Background tasks run asynchronously while you continue working:
- Long test suites
- Build processes
- Database migrations
- Deployment scripts
- Analysis tools
Basic Usage:
User: Run tests in background
Claude: Started task bg-1234
/task list # Show all tasks/task status bg-1234 # Check progress/task show bg-1234 # View output/task cancel bg-1234 # Cancel taskStarting Background Tasks
User: Run the full test suite in the background
Claude: Starting tests in background (task-id: bg-1234)You can continue working while tests run.
[You can continue the conversation]
User: Meanwhile, let's refactor the auth module
Claude: [Works on auth module while tests run in background]
[Later, when tests complete]
Claude: 📢 Background task bg-1234 completed:✅ 245 tests passed❌ 3 tests failedView results: /task show bg-1234Managing Background Tasks
List active tasks:
User: /task list
Active background tasks:1. [bg-1234] Running tests (50% complete, 2min remaining)2. [bg-1235] Building Docker image (25% complete, 8min remaining)3. [bg-1236] Deploying to staging (90% complete, 30sec remaining)Check task status:
User: /task status bg-1234
Task bg-1234: Running testsStatus: In progressProgress: 120/245 tests (49%)Started: 2025-11-08 10:30:15Estimated completion: 2025-11-08 10:34:22View task output:
User: /task show bg-1234
[Shows live output from the test run]Cancel task:
User: /task cancel bg-1234
Cancelled background task bg-1234Example: Parallel Development
User: Run the build in the background
Claude: Starting build... (task-id: bg-5001)
User: Also run the linter in background
Claude: Starting linter... (task-id: bg-5002)
User: While those run, let's implement the new API endpoint
Claude: [Implements API endpoint while build and linter run]
[10 minutes later]
Claude: 📢 Build completed successfully (bg-5001)📢 Linter found 12 issues (bg-5002)
User: Show me the linter issues
Claude: [Shows linter output from bg-5002]Configuration
{ "backgroundTasks": { "enabled": true, "maxConcurrentTasks": 5, "notifyOnCompletion": true, "autoCleanup": true, "logOutput": true }}Ultraplan (/ultraplan)
For complex tasks requiring deep analysis, /ultraplan delegates planning to a remote Opus 4.6 session that runs for up to 30 minutes.
How It Works
- Run
/ultraplan [task description]with your requirements - Claude Code packages your codebase context and sends it to a remote Opus 4.6 session
- The remote session plans extensively (polling every ~3 seconds, 5-failure timeout)
- When complete, you choose:
- Execute locally — bring the plan back and implement it in your current session
- Teleport — transfer your session to the remote environment for execution
When to Use
| Scenario | Use /ultraplan? | Why |
|---|---|---|
| Refactoring entire codebase architecture | Yes | Needs deep multi-file analysis |
| Multi-module redesign with dependencies | Yes | Complex dependency planning |
| Adding a simple feature | No | Overkill, slower than direct work |
| Quick bug fix | No | Faster to investigate directly |
Note:
/ultraplanis feature-gated and may not be available in all builds. It requires network access for the remote session.
Scheduled Tasks
Scheduled Tasks let you run prompts automatically on a recurring schedule or as one-time reminders. Tasks are session-scoped — they run while Claude Code is active and are cleared when the session ends. Available since v2.1.72+.
The /loop command
# Explicit interval/loop 5m check if the deployment finished
# Natural language/loop check build status every 30 minutesStandard 5-field cron expressions are also supported for precise scheduling.
One-time reminders
Set reminders that fire once at a specific time:
remind me at 3pm to push the release branchin 45 minutes, run the integration testsManaging scheduled tasks
| Tool | Description |
|---|---|
CronCreate | Create a new scheduled task |
CronList | List all active scheduled tasks |
CronDelete | Remove a scheduled task |
Limits and behavior:
- Up to 50 scheduled tasks per session
- Session-scoped — cleared when the session ends
- Recurring tasks auto-expire after 3 days
- Tasks only fire while Claude Code is running — no catch-up for missed fires
Behavior details
| Aspect | Detail |
|---|---|
| Recurring jitter | Up to 10% of the interval (max 15 minutes) |
| One-shot jitter | Up to 90 seconds on :00/:30 boundaries |
| Missed fires | No catch-up — skipped if Claude Code was not running |
| Persistence | Not persisted across restarts |
Cloud Scheduled Tasks
Use /schedule to create Cloud scheduled tasks that run on Anthropic infrastructure:
/schedule daily at 9am run the test suite and report failuresCloud scheduled tasks persist across restarts and do not require Claude Code to be running locally.
Disabling scheduled tasks
export CLAUDE_CODE_DISABLE_CRON=1Example: monitoring a deployment
/loop 5m check the deployment status of the staging environment. If the deploy succeeded, notify me and stop looping. If it failed, show the error logs.Tip: Scheduled tasks are session-scoped. For persistent automation that survives restarts, use CI/CD pipelines, GitHub Actions, or Desktop App scheduled tasks instead.
Permission Modes
Permission modes control what actions Claude can take without explicit approval.
Available Permission Modes
| Mode | Behavior |
|---|---|
default | Read files only; prompts for all other actions |
acceptEdits | Read and edit files; prompts for commands |
plan | Read files only (research mode, no edits) |
auto | All actions with background safety classifier checks (Research Preview) |
bypassPermissions | All actions, no permission checks (dangerous) |
dontAsk | Only pre-approved tools execute; all others denied |
Cycle through modes with Shift+Tab in the CLI. Set a default with the --permission-mode flag or the permissions.defaultMode setting.
Activation Methods
Keyboard shortcut:
Shift + Tab # Cycle through all 6 modesSlash command:
/plan # Enter plan modeCLI flag:
claude --permission-mode planclaude --permission-mode autoSetting:
{ "permissions": { "defaultMode": "auto" }}Permission Mode Examples
Default Mode
Claude asks for confirmation on significant actions:
User: Fix the bug in auth.ts
Claude: I need to modify src/auth.ts to fix the bug.The change will update the password validation logic.
Approve this change? (yes/no/show)Plan Mode
Review implementation plan before execution:
User: /plan Implement user authentication system
Claude: I'll create a plan for implementing authentication.
## Implementation Plan[Detailed plan with phases and steps]
Ready to proceed? (yes/no/modify)Accept Edits Mode
Automatically accept file modifications:
User: acceptEditsUser: Fix the bug in auth.ts
Claude: [Makes changes without asking]Use Cases
Code Review:
User: claude --permission-mode planUser: Review this PR and suggest improvements
Claude: [Reads code, provides feedback, but cannot modify]Pair Programming:
User: claude --permission-mode defaultUser: Let's implement the feature together
Claude: [Asks for approval before each change]Automated Tasks:
User: claude --permission-mode acceptEditsUser: Fix all linting issues in the codebase
Claude: [Auto-accepts file edits without asking]Headless Mode
Print mode (claude -p) allows Claude Code to run without interactive input, perfect for automation and CI/CD. This is the non-interactive mode, replacing the older --headless flag.
What is Print Mode?
Print mode enables:
- Automated script execution
- CI/CD integration
- Batch processing
- Scheduled tasks
Running in Print Mode (Non-Interactive)
# Run specific taskclaude -p "Run all tests"
# Process piped contentcat error.log | claude -p "Analyze these errors"
# CI/CD integration (GitHub Actions)- name: AI Code Review run: claude -p "Review PR"Additional Print Mode Usage Examples
# Run a specific task with output captureclaude -p "Run all tests and generate coverage report"
# With structured outputclaude -p --output-format json "Analyze code quality"
# With input from stdinecho "Analyze code quality" | claude -p "explain this"Example: CI/CD Integration
GitHub Actions:
name: AI Code Review
on: [pull_request]
jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4
- name: Install Claude Code run: npm install -g @anthropic-ai/claude-code
- name: Run Claude Code Review env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | claude -p --output-format json \ --max-turns 3 \ "Review this PR for: - Code quality issues - Security vulnerabilities - Performance concerns - Test coverage Output results as JSON" > review.json
- name: Post Review Comment uses: actions/github-script@v7 with: script: | const fs = require('fs'); const review = JSON.parse(fs.readFileSync('review.json', 'utf8')); github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: JSON.stringify(review, null, 2) });Print Mode Configuration
Print mode (claude -p) supports several flags for automation:
# Limit autonomous turnsclaude -p --max-turns 5 "refactor this module"
# Structured JSON outputclaude -p --output-format json "analyze this codebase"
# With schema validationclaude -p --json-schema '{"type":"object","properties":{"issues":{"type":"array"}}}' \ "find bugs in this code"
# Disable session persistenceclaude -p --no-session-persistence "one-off analysis"Session Management
Manage multiple Claude Code sessions effectively.
Session Management Commands
| Command | Description |
|---|---|
/resume | Resume a conversation by ID or name |
/rename | Name the current session |
/fork | Fork current session into a new branch |
claude -c | Continue most recent conversation |
claude -r "session" | Resume session by name or ID |
Resuming Sessions
Continue last conversation:
claude -cResume a named session:
claude -r "auth-refactor" "finish this PR"Rename the current session (inside the REPL):
/rename auth-refactorForking Sessions
Fork a session to try an alternative approach without losing the original:
/forkOr from the CLI:
claude --resume auth-refactor --fork-session "try OAuth instead"Session Persistence
Sessions are automatically saved and can be resumed:
# Continue last conversationclaude -c
# Resume specific session by name or IDclaude -r "auth-refactor"
# Resume and fork for experimentationclaude --resume auth-refactor --fork-session "alternative approach"Interactive Features
Keyboard Shortcuts
Claude Code supports keyboard shortcuts for efficiency. Here’s the complete reference from official docs:
| Shortcut | Description |
|---|---|
Ctrl+C | Cancel current input/generation |
Ctrl+D | Exit Claude Code |
Ctrl+G | Edit plan in external editor |
Ctrl+L | Clear terminal screen |
Ctrl+O | Toggle verbose output (view reasoning) |
Ctrl+R | Reverse search history |
Ctrl+T | Toggle task list view |
Ctrl+B | Background running tasks |
Esc+Esc | Rewind code/conversation |
Shift+Tab / Alt+M | Toggle permission modes |
Option+P / Alt+P | Switch model |
Option+T / Alt+T | Toggle extended thinking |
Line Editing (standard readline shortcuts):
| Shortcut | Action |
|---|---|
Ctrl + A | Move to line start |
Ctrl + E | Move to line end |
Ctrl + K | Cut to end of line |
Ctrl + U | Cut to start of line |
Ctrl + W | Delete word backward |
Ctrl + Y | Paste (yank) |
Tab | Autocomplete |
↑ / ↓ | Command history |
Customizing keybindings
Create custom keyboard shortcuts by running /keybindings, which opens ~/.claude/keybindings.json for editing (v2.1.18+).
Configuration format:
{ "$schema": "https://www.schemastore.org/claude-code-keybindings.json", "bindings": [ { "context": "Chat", "bindings": { "ctrl+e": "chat:externalEditor", "ctrl+u": null, "ctrl+k ctrl+s": "chat:stash" } }, { "context": "Confirmation", "bindings": { "ctrl+a": "confirmation:yes" } } ]}Set a binding to null to unbind a default shortcut.
Available contexts
Keybindings are scoped to specific UI contexts:
| Context | Key Actions |
|---|---|
| Chat | submit, cancel, cycleMode, modelPicker, thinkingToggle, undo, externalEditor, stash, imagePaste |
| Confirmation | yes, no, previous, next, nextField, cycleMode, toggleExplanation |
| Global | interrupt, exit, toggleTodos, toggleTranscript |
| Autocomplete | accept, dismiss, next, previous |
| HistorySearch | search, previous, next |
| Settings | Context-specific settings navigation |
| Tabs | Tab switching and management |
| Help | Help panel navigation |
There are 18 contexts total including Transcript, Task, ThemePicker, Attachments, Footer, MessageSelector, DiffDialog, ModelPicker, and Select.
Chord support
Keybindings support chord sequences (multi-key combinations):
"ctrl+k ctrl+s" → Two-key sequence: press ctrl+k, then ctrl+s"ctrl+shift+p" → Simultaneous modifier keysKeystroke syntax:
- Modifiers:
ctrl,alt(oropt),shift,meta(orcmd) - Uppercase implies Shift:
Kis equivalent toshift+k - Special keys:
escape,enter,return,tab,space,backspace,delete, arrow keys
Reserved and conflicting keys
| Key | Status | Notes |
|---|---|---|
Ctrl+C | Reserved | Cannot be rebound (interrupt) |
Ctrl+D | Reserved | Cannot be rebound (exit) |
Ctrl+B | Terminal conflict | tmux prefix key |
Ctrl+A | Terminal conflict | GNU Screen prefix key |
Ctrl+Z | Terminal conflict | Process suspend |
Tip: If a shortcut does not work, check for conflicts with your terminal emulator or multiplexer.
Tab Completion
Claude Code provides intelligent tab completion:
User: /rew<TAB>→ /rewind
User: /plu<TAB>→ /plugin
User: /plugin <TAB>→ /plugin install→ /plugin enable→ /plugin disableCommand History
Access previous commands:
User: <↑> # Previous commandUser: <↓> # Next commandUser: Ctrl+R # Search history
(reverse-i-search)`test': run all testsMulti-line Input
For complex queries, use multi-line mode:
User: \> Long complex prompt> spanning multiple lines> \endExample:
User: \> Implement a user authentication system> with the following requirements:> - JWT tokens> - Email verification> - Password reset> - 2FA support> \end
Claude: [Processes the multi-line request]Inline Editing
Edit commands before sending:
User: Deploy to prodcution<Backspace><Backspace>uction
[Edit in-place before sending]Vim Mode
Enable Vi/Vim keybindings for text editing:
Activation:
- Use
/vimcommand or/configto enable - Mode switching with
Escfor NORMAL,i/a/ofor INSERT
Navigation keys:
h/l- Move left/rightj/k- Move down/upw/b/e- Move by word0/$- Move to line start/endgg/G- Jump to start/end of text
Text objects:
iw/aw- Inner/around wordi"/a"- Inner/around quoted stringi(/a(- Inner/around parentheses
Bash Mode
Execute shell commands directly with ! prefix:
! npm test! git status! cat src/index.jsUse this for quick command execution without switching contexts.
Voice Dictation
Voice Dictation provides push-to-talk voice input for Claude Code, allowing you to speak your prompts instead of typing them.
Activating Voice Dictation
/voiceFeatures
| Feature | Description |
|---|---|
| Push-to-talk | Hold a key to record, release to send |
| 20 languages | Speech-to-text supports 20 languages |
| Custom keybinding | Configure the push-to-talk key via /keybindings |
| Account requirement | Requires a Claude.ai account for STT processing |
Configuration
Customize the push-to-talk keybinding in your keybindings file (/keybindings). Voice dictation uses your Claude.ai account for speech-to-text processing.
Channels
Channels (Research Preview) allow MCP servers to push messages into running Claude Code sessions, enabling real-time integrations with external services.
Subscribing to Channels
# Subscribe to channel plugins at startupclaude --channels discord,telegramSupported Integrations
| Integration | Description |
|---|---|
| Discord | Receive and respond to Discord messages in your session |
| Telegram | Receive and respond to Telegram messages in your session |
Configuration
Managed setting for enterprise deployments:
{ "allowedChannelPlugins": ["discord", "telegram"]}The allowedChannelPlugins managed setting controls which channel plugins are permitted across the organization.
How It Works
- MCP servers act as channel plugins that connect to external services
- Incoming messages are pushed into the active Claude Code session
- Claude can read and respond to messages within the session context
- Channel plugins must be approved via the
allowedChannelPluginsmanaged setting
Chrome Integration
Chrome Integration connects Claude Code to your Chrome or Microsoft Edge browser for live web automation and debugging. This is a beta feature available since v2.0.73+ (Edge support added in v1.0.36+).
Enabling Chrome Integration
At startup:
claude --chrome # Enable Chrome connectionclaude --no-chrome # Disable Chrome connectionWithin a session:
/chromeSelect “Enabled by default” to activate Chrome Integration for all future sessions. Claude Code shares your browser’s login state, so it can interact with authenticated web apps.
Capabilities
| Capability | Description |
|---|---|
| Live debugging | Read console logs, inspect DOM elements, debug JavaScript in real time |
| Design verification | Compare rendered pages against design mockups |
| Form validation | Test form submissions, input validation, and error handling |
| Web app testing | Interact with authenticated apps (Gmail, Google Docs, Notion, etc.) |
| Data extraction | Scrape and process content from web pages |
| Session recording | Record browser interactions as GIF files |
Site-level permissions
The Chrome extension manages per-site access. Grant or revoke access for specific sites at any time through the extension popup. Claude Code only interacts with sites you have explicitly allowed.
How it works
Claude Code controls the browser in a visible window — you can watch actions happen in real time. When the browser encounters a login page or CAPTCHA, Claude pauses and waits for you to handle it manually before continuing.
Known limitations
- Browser support: Chrome and Edge only — Brave, Arc, and other Chromium browsers are not supported
- WSL: Not available in Windows Subsystem for Linux
- Third-party providers: Not supported with Bedrock, Vertex, or Foundry API providers
- Service worker idle: The Chrome extension service worker may go idle during extended sessions
Tip: Chrome Integration is a beta feature. Browser support may expand in future releases.
Remote Control
Remote Control lets you continue a locally running Claude Code session from your phone, tablet, or any browser. Your local session keeps running on your machine — nothing moves to the cloud. Available on Pro, Max, Team, and Enterprise plans (v2.1.51+).
Starting Remote Control
From the CLI:
# Start with default session nameclaude remote-control
# Start with a custom nameclaude remote-control --name "Auth Refactor"From within a session:
/remote-control/remote-control "Auth Refactor"Available flags:
| Flag | Description |
|---|---|
--name "title" | Custom session title for easy identification |
--verbose | Show detailed connection logs |
--sandbox | Enable filesystem and network isolation |
--no-sandbox | Disable sandboxing (default) |
Connecting to a session
Three ways to connect from another device:
- Session URL — Printed to the terminal when the session starts; open in any browser
- QR code — Press
spacebarafter starting to display a scannable QR code - Find by name — Browse your sessions at claude.ai/code or in the Claude mobile app (iOS/Android)
Security
- No inbound ports opened on your machine
- Outbound HTTPS only over TLS
- Scoped credentials — multiple short-lived, narrowly scoped tokens
- Session isolation — each remote session is independent
Remote Control vs Claude Code on the web
| Aspect | Remote Control | Claude Code on Web |
|---|---|---|
| Execution | Runs on your machine | Runs on Anthropic cloud |
| Local tools | Full access to local MCP servers, files, and CLI | No local dependencies |
| Use case | Continue local work from another device | Start fresh from any browser |
Limitations
- One remote session per Claude Code instance
- Terminal must stay open on the host machine
- Session times out after ~10 minutes if the network is unreachable
Use cases
- Control Claude Code from a mobile device or tablet while away from your desk
- Use the richer claude.ai UI while maintaining local tool execution
- Quick code reviews on the go with your full local development environment
Web Sessions
Web Sessions allow you to run Claude Code directly in the browser at claude.ai/code, or create web sessions from the CLI.
Creating a Web Session
# Create a new web session from the CLIclaude --remote "implement the new API endpoints"This starts a Claude Code session on claude.ai that you can access from any browser.
Resuming Web Sessions Locally
If you started a session on the web and want to continue it locally:
# Resume a web session in the local terminalclaude --teleportOr from within an interactive REPL:
/teleportUse Cases
- Start work on one machine and continue on another
- Share a session URL with team members
- Use the web UI for visual diff review, then switch to terminal for execution
Desktop App
The Claude Code Desktop App provides a standalone application with visual diff review, parallel sessions, and integrated connectors. Available for macOS and Windows (Pro, Max, Team, and Enterprise plans).
Installation
Download from claude.ai for your platform:
- macOS: Universal build (Apple Silicon and Intel)
- Windows: x64 and ARM64 installers available
See the Desktop Quickstart for setup instructions.
Handing off from CLI
Transfer your current CLI session to the Desktop App:
/desktopCore features
| Feature | Description |
|---|---|
| Diff view | File-by-file visual review with inline comments; Claude reads comments and revises |
| App preview | Auto-starts dev servers with an embedded browser for live verification |
| PR monitoring | GitHub CLI integration with auto-fix CI failures and auto-merge when checks pass |
| Parallel sessions | Multiple sessions in the sidebar with automatic Git worktree isolation |
| Scheduled tasks | Recurring tasks (hourly, daily, weekdays, weekly) that run while the app is open |
| Rich rendering | Code, markdown, and diagram rendering with syntax highlighting |
App preview configuration
Configure dev server behavior in .claude/launch.json:
{ "command": "npm run dev", "port": 3000, "readyPattern": "ready on", "persistCookies": true}Connectors
Connect external services for richer context:
| Connector | Capability |
|---|---|
| GitHub | PR monitoring, issue tracking, code review |
| Slack | Notifications, channel context |
| Linear | Issue tracking, sprint management |
| Notion | Documentation, knowledge base access |
| Asana | Task management, project tracking |
| Calendar | Schedule awareness, meeting context |
Note: Connectors are not available for remote (cloud) sessions.
Remote and SSH sessions
- Remote sessions: Run on Anthropic cloud infrastructure; continue even when the app is closed. Accessible from claude.ai/code or the Claude mobile app
- SSH sessions: Connect to remote machines over SSH with full access to the remote filesystem and tools. Claude Code must be installed on the remote machine
Permission modes in Desktop
The Desktop App supports the same 4 permission modes as the CLI:
| Mode | Behavior |
|---|---|
| Ask permissions (default) | Review and approve every edit and command |
| Auto accept edits | File edits auto-approved; commands require manual approval |
| Plan mode | Review approach before any changes are made |
| Bypass permissions | Automatic execution (sandbox-only, admin-controlled) |
Enterprise features
- Admin console: Control Code tab access and permission settings for the organization
- MDM deployment: Deploy via MDM on macOS or MSIX on Windows
- SSO integration: Require single sign-on for organization members
- Managed settings: Centrally manage team configuration and model availability
Task List
The Task List feature provides persistent task tracking that survives context compactions (when the conversation history is trimmed to fit the context window).
Toggling the Task List
Press Ctrl+T to toggle the task list view on or off during a session.
Persistent Tasks
Tasks persist across context compactions, ensuring that long-running work items are not lost when the conversation context is trimmed. This is particularly useful for complex, multi-step implementations.
Named Task Directories
Use the CLAUDE_CODE_TASK_LIST_ID environment variable to create named task directories shared across sessions:
export CLAUDE_CODE_TASK_LIST_ID=my-project-sprint-3This allows multiple sessions to share the same task list, making it useful for team workflows or multi-session projects.
Prompt Suggestions
Prompt Suggestions display grayed-out example commands based on your git history and current conversation context.
How It Works
- Suggestions appear as grayed-out text below your input prompt
- Press
Tabto accept the suggestion - Press
Enterto accept and immediately submit - Suggestions are context-aware, drawing from git history and conversation state
Disabling Prompt Suggestions
export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=falseGit Worktrees
Git Worktrees allow you to start Claude Code in an isolated worktree, enabling parallel work on different branches without stashing or switching.
Starting in a Worktree
# Start Claude Code in an isolated worktreeclaude --worktree# orclaude -wWorktree Location
Worktrees are created at:
<repo>/.claude/worktrees/<name>Sparse Checkout for Monorepos
Use the worktree.sparsePaths setting to perform sparse-checkout in monorepos, reducing disk usage and clone time:
{ "worktree": { "sparsePaths": ["packages/my-package", "shared/"] }}Worktree Tools and Hooks
| Item | Description |
|---|---|
ExitWorktree | Tool to exit and clean up the current worktree |
WorktreeCreate | Hook event fired when a worktree is created |
WorktreeRemove | Hook event fired when a worktree is removed |
Auto-Cleanup
If no changes are made in the worktree, it is automatically cleaned up when the session ends.
Use Cases
- Work on a feature branch while keeping main branch untouched
- Run tests in isolation without affecting the working directory
- Try experimental changes in a disposable environment
- Sparse-checkout specific packages in monorepos for faster startup
Sandboxing
Sandboxing provides OS-level filesystem and network isolation for Bash commands executed by Claude Code. This is complementary to permission rules and provides an additional security layer.
Enabling Sandboxing
Slash command:
/sandboxCLI flags:
claude --sandbox # Enable sandboxingclaude --no-sandbox # Disable sandboxingConfiguration Settings
| Setting | Description |
|---|---|
sandbox.enabled | Enable or disable sandboxing |
sandbox.failIfUnavailable | Fail if sandboxing cannot be activated |
sandbox.filesystem.allowWrite | Paths allowed for write access |
sandbox.filesystem.allowRead | Paths allowed for read access |
sandbox.filesystem.denyRead | Paths denied for read access |
sandbox.enableWeakerNetworkIsolation | Enable weaker network isolation on macOS |
Example Configuration
{ "sandbox": { "enabled": true, "failIfUnavailable": true, "filesystem": { "allowWrite": ["/Users/me/project"], "allowRead": ["/Users/me/project", "/usr/local/lib"], "denyRead": ["/Users/me/.ssh", "/Users/me/.aws"] }, "enableWeakerNetworkIsolation": true }}How It Works
- Bash commands run in a sandboxed environment with restricted filesystem access
- Network access can be isolated to prevent unintended external connections
- Works alongside permission rules for defense in depth
- On macOS, use
sandbox.enableWeakerNetworkIsolationfor network restrictions (full network isolation is not available on macOS)
Use Cases
- Running untrusted or generated code safely
- Preventing accidental modifications to files outside the project
- Restricting network access during automated tasks
Managed Settings (Enterprise)
Managed Settings enable enterprise administrators to deploy Claude Code configuration across an organization using platform-native management tools.
Deployment Methods
| Platform | Method | Since |
|---|---|---|
| macOS | Managed plist files (MDM) | v2.1.51+ |
| Windows | Windows Registry | v2.1.51+ |
| Cross-platform | Managed configuration files | v2.1.51+ |
| Cross-platform | Managed drop-ins (managed-settings.d/ directory) | v2.1.83+ |
Managed Drop-ins
Since v2.1.83, administrators can deploy multiple managed settings files into a managed-settings.d/ directory. Files are merged in alphabetical order, allowing modular configuration across teams:
~/.claude/managed-settings.d/ 00-org-defaults.json 10-team-policies.json 20-project-overrides.jsonAvailable Managed Settings
| Setting | Description |
|---|---|
disableBypassPermissionsMode | Prevent users from enabling bypass permissions |
availableModels | Restrict which models users can select |
allowedChannelPlugins | Control which channel plugins are permitted |
autoMode.environment | Configure trusted infrastructure for auto mode |
| Custom policies | Organization-specific permission and tool policies |
Example: macOS Plist
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict> <key>disableBypassPermissionsMode</key> <true/> <key>availableModels</key> <array> <string>claude-sonnet-4-6</string> <string>claude-haiku-4-5</string> </array></dict></plist>Configuration and Settings
Configuration File Locations
- Global config:
~/.claude/config.json - Project config:
./.claude/config.json - User config:
~/.config/claude-code/settings.json
Complete Configuration Example
Core advanced features configuration:
{ "permissions": { "mode": "default" }, "hooks": { "PreToolUse:Edit": "eslint --fix ${file_path}", "PostToolUse:Write": "~/.claude/hooks/security-scan.sh" }, "mcp": { "enabled": true, "servers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] } } }}Extended configuration example:
{ "permissions": { "mode": "default", "allowedTools": ["Bash(git log:*)", "Read"], "disallowedTools": ["Bash(rm -rf:*)"] },
"hooks": { "PreToolUse": [{ "matcher": "Edit", "hooks": ["eslint --fix ${file_path}"] }], "PostToolUse": [{ "matcher": "Write", "hooks": ["~/.claude/hooks/security-scan.sh"] }], "Stop": [{ "hooks": ["~/.claude/hooks/notify.sh"] }] },
"mcp": { "enabled": true, "servers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } } } }}Environment Variables
Override config with environment variables:
# Model selectionexport ANTHROPIC_MODEL=claude-opus-4-6export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5
# API configurationexport ANTHROPIC_API_KEY=sk-ant-...
# Thinking configurationexport MAX_THINKING_TOKENS=16000export CLAUDE_CODE_EFFORT_LEVEL=high
# Feature togglesexport CLAUDE_CODE_DISABLE_AUTO_MEMORY=trueexport CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=trueexport CLAUDE_CODE_DISABLE_CRON=1export CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=trueexport CLAUDE_CODE_DISABLE_TERMINAL_TITLE=trueexport CLAUDE_CODE_DISABLE_1M_CONTEXT=trueexport CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=trueexport CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=falseexport CLAUDE_CODE_ENABLE_TASKS=trueexport CLAUDE_CODE_SIMPLE=true # Set by --bare flag
# MCP configurationexport MAX_MCP_OUTPUT_TOKENS=50000export ENABLE_TOOL_SEARCH=true
# Task managementexport CLAUDE_CODE_TASK_LIST_ID=my-project-tasks
# Agent teams (experimental)export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true
# Subagent and plugin configurationexport CLAUDE_CODE_SUBAGENT_MODEL=sonnetexport CLAUDE_CODE_PLUGIN_SEED_DIR=./my-pluginsexport CLAUDE_CODE_NEW_INIT=true
# Subprocess and streamingexport CLAUDE_CODE_SUBPROCESS_ENV_SCRUB="SECRET_KEY,DB_PASSWORD"export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80export CLAUDE_STREAM_IDLE_TIMEOUT_MS=30000export ANTHROPIC_CUSTOM_MODEL_OPTION=my-custom-modelexport SLASH_COMMAND_TOOL_CHAR_BUDGET=50000Configuration Management Commands
User: /config[Opens interactive configuration menu]The /config command provides an interactive menu to toggle settings such as:
- Extended thinking on/off
- Verbose output
- Permission mode
- Model selection
Per-Project Configuration
Create .claude/config.json in your project:
{ "hooks": { "PreToolUse": [{ "matcher": "Bash", "hooks": ["npm test && npm run lint"] }] }, "permissions": { "mode": "default" }, "mcp": { "servers": { "project-db": { "command": "mcp-postgres", "env": { "DATABASE_URL": "${PROJECT_DB_URL}" } } } }}Best Practices
Planning Mode
- ✅ Use for complex multi-step tasks
- ✅ Review plans before approving
- ✅ Modify plans when needed
- ❌ Don’t use for simple tasks
Extended Thinking
- ✅ Use for architectural decisions
- ✅ Use for complex problem-solving
- ✅ Review the thinking process
- ❌ Don’t use for simple queries
Background Tasks
- ✅ Use for long-running operations
- ✅ Monitor task progress
- ✅ Handle task failures gracefully
- ❌ Don’t start too many concurrent tasks
Permissions
- ✅ Use
planfor code review (read-only) - ✅ Use
defaultfor interactive development - ✅ Use
acceptEditsfor automation workflows - ✅ Use
autofor autonomous work with safety guardrails - ❌ Don’t use
bypassPermissionsunless absolutely necessary
Sessions
- ✅ Use separate sessions for different tasks
- ✅ Save important session states
- ✅ Clean up old sessions
- ❌ Don’t mix unrelated work in one session
Additional Resources
For more information about Claude Code and related features:
- Official Interactive Mode Documentation
- Official Headless Mode Documentation
- CLI Reference
- Checkpoints Guide - Session management and rewinding
- Slash Commands - Command reference
- Memory Guide - Persistent context
- Skills Guide - Autonomous capabilities
- Subagents Guide - Delegated task execution
- MCP Guide - External data access
- Hooks Guide - Event-driven automation
- Plugins Guide - Bundled extensions
- Official Scheduled Tasks Documentation
- Official Chrome Integration Documentation
- Official Remote Control Documentation
- Official Keybindings Documentation
- Official Desktop App Documentation
Deep Dives
The sections above cover each feature in overview. The following pages provide full deep-dive guides — installation, examples, gotchas, and patterns for each topic.
Commands
| Page | What It Covers |
|---|---|
| Voice Coding | Full setup guide — macOS, Windows, Linux, Wispr Flow, dictation workflow |
| Loop | Local recurring tasks, up to 3 days, examples + safe stopping |
| Schedule | Cloud-scheduled tasks, up to 1 week, Pro requirement |
| Batch | Fan-out to parallel agents, large migrations, merge strategies |
| Branch & Fork Session | Session forking — explore alternatives without losing context |
| btw | Side queries that don’t interrupt the agent’s context |
| Teleport & Remote Control | Session mobility across devices |
| Doctor | Diagnose installation, config, MCP, and auth issues |
| Bare & Add-Dir Flags | 10x startup speed for SDK use + multi-repo context |
Features
| Page | What It Covers |
|---|---|
| Extended Thinking | ultrathink keyword, effort flags, reasoning depth |
| Background Tasks | Long-running non-blocking work, notifications, /tasks |
| Session Management | Naming, listing, resuming, exporting sessions |
| Git Worktrees | Running dozens of Claude instances — setup, workflow, limits |
| Channels | External systems pushing messages into sessions (Research Preview) |
Production Concerns
| Page | What It Covers |
|---|---|
| Context Management | Avoiding the dumb zone, 50% compact rule, subtask sizing |
| Security Hardening | Sandbox, env scrubbing, deny rules, managed settings |
| Model Selection Strategy | Opus vs Sonnet vs Haiku + effort levels decision matrix |
| Skill Design Principles | Thariq’s framework for skills that work — full 9-point guide |
Creator Workflows: For workflow patterns based on how Boris Cherny (Claude Code’s creator) actually uses the tool, see the Creator Workflows section.