---

name: claude-code description: Claude Code CLI and integration for AI-powered coding assistance in terminal, IDE, and CI/CD workflows. Use when working with Claude Code features including: (1) Installation and setup, (2) Interactive sessions and queries, (3) MCP (Model Context Protocol) server configuration, (4) CLI commands and flags, (5) IDE integrations, (6) Common workflows (coding, debugging, git operations, automation), (7) Custom agents and subagents, (8) Project-based configuration and settings, or (9) Enterprise/team deployment scenarios.

Claude Code

Claude Code is Anthropic's AI-powered coding assistant that works directly in your development environment. Use this skill when you need help with Claude Code setup, configuration, or advanced workflows.

🌐 Documentation / 文档

This repository contains comprehensive documentation for Claude Code. Choose your language:

中文文档 (Chinese):

• README-zh.md - 完整的中文使用指南
• 适用于：需要中文文档或习惯中文术语的用户

English Documentation:

• README-en.md - Complete English guide -适用于：English-speaking users and developers

Additional References:

• See references/ directory for detailed guides on MCP integration, CLI commands, best practices, and more.

---

Quick Start / 快速开始

Native Install (Recommended):

# 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

Package Managers:

# Homebrew (macOS)
brew install --cask claude-code

# WinGet (Windows)
winget install Anthropic.ClaudeCode

First Session

cd your-project
claude

You'll be prompted to log in on first use with one of:

• Claude subscription (Pro, Max, Teams, Enterprise)
• Claude Console account
• Cloud provider (Amazon Bedrock, Google Vertex AI, Microsoft Foundry)

Core Concepts

Session Types

Claude Code supports multiple interaction modes:

Interactive Mode:

claude
# Start REPL, type natural language commands
# Use /help for available commands

One-shot Query:

claude "query"
# Execute and exit, no persistence

Print Mode (SDK):

claude -p "query"
# Output structured response, useful for scripts

Resume Session:

claude -r session-name
# Continue previous conversation

MCP (Model Context Protocol)

MCP enables Claude Code to connect to external tools, databases, and APIs.

Adding MCP Servers:

# HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# SSE server
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Local stdio server
claude mcp add --transport stdio airtable -- npx -y airtable-mcp-server

Scopes:

• --scope local: Project-specific, stored in project .mcp.json
• --scope project: Shared via .mcp.json in project root
• --scope user: Cross-project, stored in ~/.claude.json

Managing MCP:

claude mcp list           # List all servers
claude mcp get github      # Get server details
claude mcp remove github    # Remove a server
/mcp                      # Check status in Claude Code

CLI Reference

Essential Commands

| Command | Description | Example | |----------|-------------|----------| | claude | Start interactive REPL | claude | | claude "query" | One-shot query | claude "explain this function" | | claude -p "query" | Print mode (SDK) | claude -p "list files" | | claude -c | Continue last conversation | claude -c | | claude -r <session> | Resume specific session | claude -r auth-refactor | | claude commit | Git commit | claude commit | | claude update | Update to latest | claude update |

Important Flags

| Flag | Description | Example | |-------|-------------|----------| | --model | Set model (sonnet/opus/haiku) | claude --model sonnet | | --agents | Define custom subagents | claude --agents '{...}' | | --tools | Restrict available tools | claude --tools "Read,Edit" | | --mcp-config | Load MCP from JSON | claude --mcp-config ./mcp.json | | --chrome | Enable browser integration | claude --chrome | | --system-prompt | Replace system prompt | claude --system-prompt "You are a Python expert" | | --append-system-prompt | Append to system prompt | claude --append-system-prompt "Always use TypeScript" | | --verbose | Enable debug logging | claude --verbose |

Common Workflows

Coding Tasks

# Add a feature
claude "Add input validation to the user registration form"

# Refactor code
claude "refactor authentication module to use async/await"

# Fix a bug
claude "There's a bug where users can submit empty forms - fix it"

# Write tests
claude "Write unit tests for the calculator functions"

Git Operations

# Check changes
claude "What files have I changed?"

# Create commit
claude "Commit my changes with a descriptive message"

# Create branch
claude "Create a new branch called feature/authentication"

# Resolve conflicts
claude "Help me resolve merge conflicts"

Debugging

# Explain error
claude "Explain this error: TypeError: Cannot read property 'x' of undefined"

# Analyze logs
tail -f app.log | claude -p "Analyze this log stream and alert me to any errors"

# Code review
claude "Review my changes and suggest improvements"

Custom Agents

Define subagents for specialized tasks:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

Advanced Features

Permission Control

Claude Code supports granular permission control for tools:

# Allow specific tools without prompts
claude --allowedTools 'Bash(git log *)' 'Bash(git diff *)' 'Read' "query"

# Restrict tools
claude --disallowedTools 'Bash' 'Edit' "query"

# Plan mode (no execution)
claude --permission-mode plan "Show me the plan for this feature"

System Prompt Customization

Four modes for different needs:

Replace entire prompt:

claude --system-prompt "You are a Python expert who only writes type-annotated code"

Load from file:

claude -p --system-prompt-file ./prompts/code-review.txt "Review this PR"

Append to default:

claude --append-system-prompt "Always use TypeScript and include JSDoc comments"

Enterprise Features

Managed MCP Configuration:

Deploy /Library/Application Support/ClaudeCode/managed-mcp.json (macOS) for centralized control:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server"
    }
  }
}

Allowlist/Denylist:

{
  "allowedMcpServers": [
    {"serverName": "github"},
    {"serverCommand": ["npx", "-y", "approved-package"]},
    {"serverUrl": "https://*.internal.corp/*"}
  ],
  "deniedMcpServers": [
    {"serverName": "dangerous-server"},
    {"serverUrl": "https://*.untrusted.com/*"}
  ]
}

Integration Points

IDE Integrations

• VS Code: Inline diffs, @-mentions, plan review
• JetBrains: PyCharm, IntelliJ, WebStorm with IDE diff viewing
• GitHub Actions: Automate code review, issue triage
• GitLab CI/CD: Event-driven automation for MRs
• Slack: @mention to route tasks

Cloud/CI/CD

# GitHub Actions
- name: Run Claude Code Review
  run: |
    claude -p "Review this PR and suggest improvements" --from-pr ${{ github.event.number }}

# Automation
tail -f app.log | claude -p "If you see any anomalies, Slack me"

Configuration Files

Project .mcp.json:

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "env": {
        "API_KEY": "${API_KEY:-default-key}"
      }
    }
  }
}

Settings ~/.claude.json:

{
  "model": "sonnet",
  "permissionMode": "default",
  "chromeIntegration": true
}

Troubleshooting

Common Issues

Session not saving:

# Check permissions
ls -la ~/.claude/

# Reset configuration
claude /clear

MCP server not connecting:

# Check server status
claude mcp get <server-name>

# Test connection
claude mcp test <server-name>

# View logs
claude --debug

Debug Mode

Enable debug output with category filtering:

# Enable all debug
claude --debug

# Filter specific categories
claude --debug "api,mcp"

# Exclude specific categories
claude --debug "!statsig,!file"

Environment Variables

| Variable | Description | Example | |-----------|-------------|----------| | API_KEY | Claude API key | export API_KEY=sk-xxx | | MAX_MCP_OUTPUT_TOKENS | Max tokens from MCP tools | export MAX_MCP_OUTPUT_TOKENS=50000 | | ENABLE_TOOL_SEARCH | Enable MCP tool search | export ENABLE_TOOL_SEARCH=true |

Reference Documentation

• MCP Integration: See MCP Reference for detailed MCP server setup and management
• CLI Commands: See CLI Reference for complete command reference
• Best Practices: See Best Practices for coding workflows and patterns
• Settings: See Settings Reference for all configuration options