# Quick Install (macOS, Linux, WSL)
curl -fsSL https://claude.ai/install.sh | bash

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

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

# Alternative: Homebrew (macOS/Linux)
brew install --cask claude-code

# Alternative: WinGet (Windows)
winget install Anthropic.ClaudeCode

# Alternative: NPM (⚠️ Deprecated - use native install instead)
npm install -g @anthropic-ai/claude-code

claude --version  # Verify installation

# Starting Claude Code
claude                    # Start interactive session
claude -p "task"          # Print mode (non-interactive)
claude --continue         # Continue last session
claude --resume <id>      # Resume specific session

# Session Management
/help                     # Show available commands
/exit                     # End session
/compact                  # Reduce context size
/compact [instructions]  # Compact conversation with optional focus instructions

# Background Tasks
/bashes                   # List background processes
/kill <id>               # Stop background process

# Discovery
/commands                 # List skills and commands
/hooks                   # Show configured hooks
/skills                  # List available Skills (NEW)
/plugin                  # Manage plugins

# Output Control
claude -p, --print "task"          # Print mode: non-interactive, prints result and exits
claude --output-format json         # Output format: text, json, or stream-json
claude --input-format text          # Input format: text or stream-json
claude --verbose                    # Enable verbose logging (full turn-by-turn output)

# Session Management
claude --continue                   # Continue from last session
claude --resume <session-id>        # Resume specific session by ID or name
claude --from-pr <pr>               # Resume session linked to GitHub PR number or URL [NEW]
claude --fork-session               # Create new session ID instead of reusing original
claude --session-id <uuid>          # Use specific session ID (must be valid UUID)

# Remote Sessions (claude.ai subscribers)
claude --remote "task"              # Create web session on claude.ai
claude --teleport                   # Resume web session in local terminal

# Debugging & Logging
claude --debug                      # Enable debug mode (with optional category filtering)
claude --debug "api,mcp"            # Debug specific categories
claude --debug "!statsig,!file"     # Exclude categories with !

# Model & Agent Configuration
claude --model <name>               # Specify model (sonnet, opus, haiku, or full name)
claude --fallback-model <name>      # Fallback model when default overloaded (print mode)
claude --agent <name>               # Specify custom agent (overrides settings)
claude --agents '<json>'            # Define custom subagents dynamically via JSON

# System Prompt Customization
claude --system-prompt "prompt"     # Replace entire default system prompt
claude --system-prompt-file <path>  # Replace with file contents (print mode only)
claude --append-system-prompt "..."  # Append to default system prompt
claude --append-system-prompt-file <path>  # Append file contents (print mode only)

# Tool & Permission Management
claude --tools "Bash,Read,Edit"     # Restrict built-in tools (use "" to disable all)
claude --allowedTools "Bash(git:*)" # Tools that execute without prompting
claude --disallowedTools "Edit"     # Tools removed from context
claude --permission-mode plan       # Begin in specified permission mode
claude --dangerously-skip-permissions  # Skip all permission prompts ⚠️
claude --allow-dangerously-skip-permissions  # Enable bypass option without activating [NEW]
claude --permission-prompt-tool <mcp-tool>  # MCP tool for permission prompts (non-interactive) [NEW]

# Budget & Execution Limits (print mode)
claude --max-budget-usd 5.00        # Maximum dollar amount for API calls
claude --max-turns 3                # Limit number of agentic turns
claude --json-schema '<schema>'     # Get validated JSON output matching schema (print mode) [NEW]

# Directory & Configuration
claude --add-dir ../apps ../lib     # Add additional working directories
claude --plugin-dir ./my-plugins    # Load plugins from directories
claude --settings ./settings.json   # Path to settings JSON file
claude --setting-sources user,project  # Comma-separated list of setting sources [NEW]
claude --mcp-config ./mcp.json      # Load MCP servers from JSON file
claude --strict-mcp-config          # Only use MCP servers from --mcp-config

# IDE & Browser Integration
claude --ide                        # Auto-connect to IDE on startup
claude --chrome                     # Enable Chrome browser integration
claude --no-chrome                  # Disable Chrome browser integration

# Agent Teams [NEW]
claude --teammate-mode in-process   # Teammates display in main terminal
claude --teammate-mode tmux         # Each teammate in own pane (requires tmux/iTerm2)
claude --teammate-mode auto         # Auto-detect (default)

# Setup & Maintenance
claude --init                       # Run Setup hooks and start interactive mode
claude --init-only                  # Run Setup hooks and exit (no interactive session)
claude --maintenance                # Run Setup hooks with maintenance trigger and exit

# Other Options
claude --disable-slash-commands     # Disable all skills and slash commands
claude --no-session-persistence     # Disable session persistence (print mode)
claude --betas interleaved-thinking # Beta headers for API requests
claude --include-partial-messages   # Include partial streaming events (with stream-json) [NEW]

# One-off task with JSON output
claude --print "analyze this code" --output-format json

# Debug MCP and API issues
claude --debug "api,mcp"

# Resume session with specific model
claude --resume auth-refactor --model opus

# Non-interactive with budget limit (CI/CD)
claude -p --max-budget-usd 5.00 --output-format json "run tests"

# Custom subagents for specialized work
claude --agents '{"reviewer":{"description":"Code reviewer","prompt":"Review for bugs"}}'

# Remote session for claude.ai subscribers
claude --remote "fix the login bug"

# You describe what you want
$ claude
> "Add user authentication to the API"

# Claude Code:
1. Analyzes your codebase structure
2. Plans the implementation
3. Requests permission for file edits (first time)
4. Writes code directly to your files
5. Can run tests and verify changes
6. Creates git commits if requested

# Permission Modes
"ask"    # Prompt for each use (default for new operations)
"allow"  # Permit without asking
"deny"   # Block completely

# Permission Priority [NEW v2.1.27]
# Content-level rules override tool-level rules
# Example: allow: ["Bash"], ask: ["Bash(rm *)"]
#   -> Bash is generally allowed, but "rm *" commands require confirmation

# Tools Requiring Permission
- Bash (command execution)
- Write/Edit/NotebookEdit (file modifications)
- WebFetch/WebSearch (network access)
- Skill (skills and custom commands)

# Tools Not Requiring Permission (Safe Operations)
- Read/NotebookRead (reading files)
- Grep/Glob (searching)
- TodoWrite (task tracking)
- Task (sub-agents)

{
  "permissions": {
    "defaultMode": "ask",
    "allow": {
      "Bash": ["git status", "git diff", "git log", "npm test", "npm run*"],
      "Read": {},
      "Edit": {}
    },
    "deny": {
      "Write": ["*.env", ".env.*", ".git/*"],
      "Edit": ["*.env", ".env.*"]
    },
    "additionalDirectories": [
      "/path/to/other/project"
    ]
  }
}

# Examples
Read file_path="/src/app.ts"
Read file_path="/docs/screenshot.png"  # Can read images!
Read file_path="/docs/guide.pdf"       # Can read PDFs!
Read file_path="/docs/guide.pdf" pages="1-5"  # Read specific PDF pages [NEW v2.1.30]

Write file_path="/src/newFile.ts"
      content="export const config = {...}"

Edit file_path="/src/app.ts"
     old_string="const port = 3000"
     new_string="const port = process.env.PORT || 3000"

# 1. Read file to see exact content
Read file_path="/src/app.ts"

# 2. Edit with exact string match
Edit file_path="/src/app.ts"
     old_string="function login() {
  return 'TODO';
}"
     new_string="function login() {
  return authenticateUser();
}"

Bash command="npm test"
Bash command="git status"
Bash command="find . -name '*.test.ts'"

# Check status
Bash command="git status"

# View changes
Bash command="git diff"

# Create commit
Bash command='git add . && git commit -m "feat: add authentication"'

# View history
Bash command="git log --oneline -10"

# Find functions
Grep pattern="function.*auth" path="src/" output_mode="content"

# Find TODOs with context
Grep pattern="TODO" output_mode="content" -C=3

# Count occurrences
Grep pattern="import.*from" output_mode="count"

# Case insensitive
Grep pattern="error" -i=true output_mode="files_with_matches"

# Find test files
Glob pattern="**/*.test.ts"

# Find specific extensions
Glob pattern="src/**/*.{ts,tsx}"

# Find config files
Glob pattern="**/config.{json,yaml,yml}"

TodoWrite todos=[
  {
    "content": "Add authentication endpoint",
    "status": "in_progress",
    "activeForm": "Adding authentication endpoint"
  },
  {
    "content": "Write integration tests",
    "status": "pending",
    "activeForm": "Writing integration tests"
  },
  {
    "content": "Update API documentation",
    "status": "pending",
    "activeForm": "Updating API documentation"
  }
]

# Explore codebase
Task subagent_type="Explore"
     prompt="Find all API endpoints and their authentication requirements"

# General purpose agent for complex tasks
Task subagent_type="general-purpose"
     prompt="Research best practices for rate limiting APIs and implement a solution"

WebFetch url="https://docs.example.com/api"
         prompt="Extract all endpoint documentation"

WebSearch query="React 19 new features 2024"

LSP operation="goToDefinition"
    filePath="src/utils/auth.ts"
    line=42
    character=15

# Find where a function is defined
> "Go to the definition of getUserById"

# Find all usages of a function
> "Find all references to the authenticate function"

# Get documentation for a symbol
> "What does the validateToken function do?"

# Explore code structure
> "List all symbols in the auth.ts file"

/compact                   # Reduce context by removing old information
/compact "keep auth work"  # Compact with focus instructions (keeps specified context)

# Add another directory to current session
/add-dir /path/to/other/project

# Work across multiple projects
> "Update the User type in backend and propagate to frontend"
# Claude can now access both directories

{
  "permissions": {
    "additionalDirectories": [
      "/path/to/frontend",
      "/path/to/backend",
      "/path/to/shared-libs"
    ]
  }
}

# Configure status line
/statusline

# Options typically include:
# - Current model
# - Token usage
# - Session duration
# - Active tools
# - Background processes

# 1. Navigate to your project
cd /path/to/your/project

# 2. Start Claude Code
claude

# 3. Ask Claude to understand your project
> "Read the codebase and explain the project structure"

# Claude will:
- Look for README, package.json, or similar entry points
- Read relevant files (asks permission first time)
- Analyze the code structure
- Provide a summary

# 4. Request an analysis
> "Review the authentication system for security issues"

# Claude will:
- Find authentication-related files
- Analyze the implementation
- Identify potential vulnerabilities
- Suggest improvements

# 5. Make changes
> "Add rate limiting to the login endpoint"

# Claude will:
- Plan the implementation
- Show you what changes will be made
- Request permission to edit files
- Implement the changes
- Can run tests to verify

# 6. Create a commit
> "Create a git commit for these changes"

# Claude will:
- Run git status to see changes
- Review git diff
- Create a descriptive commit message
- Commit the changes

# Ask Claude to help create it
> "Create a CLAUDE.md file documenting this project's structure, commands, and conventions"

# Or create manually with:
- Languages and frameworks used
- Important commands (dev, test, build, lint)
- Project structure overview
- Coding conventions
- Known gotchas or issues

{
  "permissions": {
    "defaultMode": "ask",
    "allow": {
      "Bash": [
        "npm test",
        "npm run*",
        "git status",
        "git diff",
        "git log*"
      ],
      "Read": {},
      "Grep": {},
      "Glob": {}
    },
    "deny": {
      "Write": ["*.env", ".env.*"],
      "Edit": ["*.env", ".env.*", ".git/*"]
    }
  }
}

> "Run the tests"
# Should execute without permission prompt (if configured)

> "What commands are available?"
# Claude will read package.json and list scripts

> "What's in CLAUDE.md?"
# Claude will read and summarize your project context

# Toggle with keyboard shortcut
Alt+T (or Option+T on macOS)  # Toggle thinking on/off

# Or use natural language
> "think about this problem"
> "think harder about the architecture"
> "ultrathink about this security issue"

# Tab key (sticky toggle)
Press Tab to toggle thinking mode on/off for subsequent prompts

# Toggle with built-in command
/fast          # Toggle on/off

# Or set in settings
"fastMode": true   # In user settings file

# Enter plan mode
/plan

# Or Claude may suggest plan mode for complex tasks
> "Implement a complete authentication system"
# Claude: "This is a complex task. Would you like me to create a plan first?"

Ctrl+B  # Background current command or agent (unified shortcut)

# Start command in background
> "Run the dev server in background"
> "Start tests in watch mode in background"

# Or prefix with &
> "& npm run dev"

# View background tasks
/tasks
/bashes

# Kill a background task
/kill <task-id>

# Launch agent in background
> "Have an Explore agent analyze the codebase architecture in background"

# Agents run asynchronously and notify you when complete
# You receive wake-up messages when background agents finish

---
name: my-agent
memory: project  # Options: user, project, local
---

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

# Claude suggests contextual prompts
> _  # Cursor blinking
# Suggestion appears: "Review the changes we made"

# Tab to edit the suggestion
Tab → Edit the suggestion text

# Enter to submit immediately
Enter → Submit the suggestion as-is

# Toggle in /config
/config
# Search for "prompt suggestions"
# Toggle enable/disable

{
  // Response language
  "language": "en",  // Claude's response language

  // Git integration
  "attribution": true,  // Add model name to commit bylines
  "respectGitignore": true,  // Respect .gitignore in searches

  // UI preferences
  "showTurnDuration": true,  // Show turn duration messages
  "fileSuggestion": "custom-cmd",  // Custom @ file search command
  "spinnerVerbs": ["analyzing", "thinking", "processing"],  // Custom spinner verbs
  "prefersReducedMotion": false,  // Reduce UI animations for accessibility [NEW v2.1.30]

  // Session behavior
  "companyAnnouncements": true,  // Show startup announcements

  // Plan mode
  "plansDirectory": ".claude/plans"  // Custom directory for plan files
}

# In skill files, use ${CLAUDE_SESSION_ID} for session-specific operations
Session ID: ${CLAUDE_SESSION_ID}

# New: .claude/rules/ directory for project-specific rules
.claude/rules/
├── coding-style.md      # Coding conventions
├── testing.md           # Testing requirements
└── security.md          # Security guidelines

{
  "permissions": {
    "allow": {
      "Bash": ["npm *", "git *"],  // Wildcard patterns
      "mcp__myserver__*": {}       // MCP tool wildcards
    }
  }
}

# Claude auto-activates a skill based on your request
You: "Review this code for security issues"
Claude: [Loads security-reviewer skill automatically]

# Or you invoke a skill directly
You: /security-reviewer src/auth.ts
Claude: [Loads and executes the security-reviewer skill]

my-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template for Claude to fill in (optional)
├── examples/
│   └── sample.md      # Example output (optional)
└── scripts/
    └── validate.sh    # Script Claude can execute (optional)

## Additional resources
- For complete API details, see [reference.md](https://github.com/Cranot/claude-code-guide/blob/HEAD/reference.md)
- For usage examples, see [examples.md](https://github.com/Cranot/claude-code-guide/blob/HEAD/examples.md)

# Personal skill (available in all projects)
mkdir -p ~/.claude/skills/explain-code

# Project skill (shared with team via git)
mkdir -p .claude/skills/explain-code

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

Keep explanations conversational. For complex concepts, use multiple analogies.

# Let Claude invoke it automatically
> "How does this code work?"

# Or invoke it directly
> /explain-code src/auth/login.ts

# User-only skill (Claude won't auto-trigger)
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

# Model-only skill (hidden from / menu)
---
name: legacy-system-context
description: Background knowledge about the legacy system
user-invocable: false
---

# Allow only specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skills
Skill(deploy *)

# Disable all skills
Skill    # Add to deny rules

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit

/fix-issue 123
# Claude receives: "Fix GitHub issue 123 following our coding standards..."

---
name: compare-files
description: Compare two files

_…[view the full README on GitHub](https://github.com/Cranot/claude-code-guide)._