Claude Code

Claude Code Expert

Claude Code is Anthropic's agentic coding tool that lives in the terminal and helps turn ideas into code faster. It combines autonomous planning, execution, and validation with extensibility through skills, plugins, MCP servers, and hooks.

When to Use This Skill

Use when users need help with:

• Understanding Claude Code features and capabilities
• Installation, setup, and authentication
• Using slash commands for development workflows
• Creating or managing Agent Skills
• Configuring MCP servers for external tool integration
• Setting up hooks and plugins
• Troubleshooting Claude Code issues
• Enterprise deployment (SSO, sandboxing, monitoring)
• IDE integration (VS Code, JetBrains)
• CI/CD integration (GitHub Actions, GitLab)
• Advanced features (extended thinking, caching, checkpointing)
• Cost tracking and optimization

Activation examples:

• "How do I use Claude Code?"
• "What slash commands are available?"
• "How to set up MCP servers?"
• "Create a new skill for X"
• "Fix Claude Code authentication issues"
• "Deploy Claude Code in enterprise environment"

Core Architecture

Subagents: Specialized AI agents (planner, code-reviewer, tester, debugger, docs-manager, ui-ux-designer, database-admin, etc.)

Agent Skills: Modular capabilities with instructions, metadata, and resources that Claude uses automatically

Slash Commands: User-defined operations in .claude/commands/ that expand to prompts

Hooks: Shell commands executing in response to events (pre/post-tool, user-prompt-submit)

MCP Servers: Model Context Protocol integrations connecting external tools and services

Plugins: Packaged collections of commands, skills, hooks, and MCP servers

Quick Reference

Load these references when needed for detailed guidance:

Getting Started

• Installation & Setup: references/getting-started.md
• Prerequisites, installation methods, authentication, first run

Development Workflows

• Slash Commands: references/slash-commands.md
• Complete command catalog: /cook, /plan, /debug, /test, /fix:, /docs:, /git:, /design:, /content:*

• Agent Skills: references/agent-skills.md
• Creating skills, skill.json format, best practices, API usage

Integration & Extension

• MCP Integration: references/mcp-integration.md
• Configuration, common servers, remote servers

• Hooks & Plugins: references/hooks-and-plugins.md
• Hook types, configuration, environment variables, plugin structure, installation

Configuration & Settings

• Configuration: references/configuration.md
• Settings hierarchy, key settings, model configuration, output styles

Enterprise & Production

• Enterprise Features: references/enterprise-features.md
• IAM, SSO, RBAC, sandboxing, audit logging, deployment options, monitoring

• IDE Integration: references/ide-integration.md
• VS Code extension, JetBrains plugin setup and features

• CI/CD Integration: references/cicd-integration.md
• GitHub Actions, GitLab CI/CD workflow examples

Advanced Usage

• Advanced Features: references/advanced-features.md
• Extended thinking, prompt caching, checkpointing, memory management

• Troubleshooting: references/troubleshooting.md
• Common issues, authentication failures, MCP problems, performance, debug mode

• API Reference: references/api-reference.md
• Admin API, Messages API, Files API, Models API, Skills API

• Best Practices: references/best-practices.md
• Project organization, security, performance, team collaboration, cost management

Common Workflows

Feature Implementation

/cook implement user authentication with JWT
# Or plan first
/plan implement payment integration with Stripe

Bug Fixing

/fix:fast the login button is not working
/debug the API returns 500 errors intermittently
/fix:types  # Fix TypeScript errors

Code Review & Testing

claude "review my latest commit"
/test
/fix:test the user service tests are failing

Documentation

/docs:init      # Create initial documentation
/docs:update    # Update existing docs
/docs:summarize # Summarize changes

Git Operations

/git:cm                    # Stage and commit
/git:cp                    # Stage, commit, and push
/git:pr feature-branch main  # Create pull request

Design & Content

/design:fast create landing page for SaaS product
/content:good write product description for new feature

Instructions for Claude

When responding to Claude Code questions:

1. Identify the topic from the user's question 2. Load relevant references from the Quick Reference section above 3. Provide specific guidance using information from loaded references 4. Include examples when helpful

Loading references:

• Read reference files only when needed for the specific question
• Multiple references can be loaded for complex queries
• Use grep patterns if searching within references

For setup/installation questions: Load references/getting-started.md

For slash command questions: Load references/slash-commands.md

For skill creation: Load references/agent-skills.md

For MCP questions: Load references/mcp-integration.md

For hooks/plugins: Load references/hooks-and-plugins.md

For configuration: Load references/configuration.md

For enterprise deployment: Load references/enterprise-features.md

For IDE integration: Load references/ide-integration.md

For CI/CD: Load references/cicd-integration.md

For advanced features: Load references/advanced-features.md

For troubleshooting: Load references/troubleshooting.md

For API usage: Load references/api-reference.md

For best practices: Load references/best-practices.md

Documentation links:

• llms.txt: https://context7.com/websites/claude_en_claude-code/llms.txt?tokens=10000
• Search for specific topics: https://context7.com/websites/claude_en_claude-code/llms.txt?topic=<topic>&tokens=5000
• Eg. Search for "subagent": https://context7.com/websites/claude_en_claude-code/llms.txt?topic=subagent&tokens=5000
• Main docs: https://docs.claude.com/en/docs/claude-code/
• GitHub: https://github.com/anthropics/claude-code
• Support: support.claude.com

Provide accurate, actionable guidance based on the loaded references and official documentation.

Advanced Features

Extended thinking, prompt caching, checkpointing, and memory management in Claude Code.

Extended Thinking

Deep reasoning for complex problems.

Enable Extended Thinking

Global configuration:

claude config set thinking.enabled true
claude config set thinking.budget 15000

Project settings (.claude/settings.json):

{
  "thinking": {
    "enabled": true,
    "budget": 10000,
    "mode": "auto"
  }
}

Command-line flag:

claude --thinking "architect microservices system"

Thinking Modes

auto: Claude decides when to use extended thinking manual: User explicitly requests thinking disabled: No extended thinking

{
  "thinking": {
    "mode": "auto",
    "budget": 10000,
    "minComplexity": 0.7
  }
}

Budget Control

Set token budget for thinking:

{
  "thinking": {
    "budget": 10000,      // Max tokens for thinking
    "budgetPerRequest": 5000,  // Per-request limit
    "adaptive": true      // Adjust based on task complexity
  }
}

Best Use Cases

• Architecture design
• Complex algorithm development
• System refactoring
• Performance optimization
• Security analysis
• Bug investigation

Example

claude --thinking "Design a distributed caching system with:
- High availability
- Consistency guarantees
- Horizontal scalability
- Fault tolerance"

Prompt Caching

Reduce costs by caching repeated context.

Enable Caching

API usage:

const response = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  system: [
    {
      type: 'text',
      text: 'You are a coding assistant...',
      cache_control: { type: 'ephemeral' }
    }
  ],
  messages: [...]
});

CLI configuration:

{
  "caching": {
    "enabled": true,
    "ttl": 300,
    "maxSize": "100MB"
  }
}

Cache Strategy

What to cache:

• Large codebases
• Documentation
• API specifications
• System prompts
• Project context

What not to cache:

• User queries
• Dynamic content
• Temporary data
• Session-specific info

Cache Control

// Cache large context
{
  type: 'text',
  text: largeCodebase,
  cache_control: { type: 'ephemeral' }
}

// Update without invalidating cache
{
  type: 'text',
  text: newUserQuery
  // No cache_control = not cached
}

Cost Savings

With caching:

• First request: Full cost
• Subsequent requests: ~90% discount on cached tokens
• Cache TTL: 5 minutes

Example:

Without caching:
Request 1: 10,000 tokens @ $3/M = $0.03
Request 2: 10,000 tokens @ $3/M = $0.03
Total: $0.06

With caching (8,000 tokens cached):
Request 1: 10,000 tokens @ $3/M = $0.03
Request 2: 2,000 new + 8,000 cached @ $0.30/M = $0.0024
Total: $0.0324 (46% savings)

Checkpointing

Automatically track and rewind changes.

Enable Checkpointing

claude config set checkpointing.enabled true

Settings:

{
  "checkpointing": {
    "enabled": true,
    "autoSave": true,
    "interval": 300,
    "maxCheckpoints": 50
  }
}

View Checkpoints

# List checkpoints
claude checkpoint list

# View checkpoint details
claude checkpoint show checkpoint-123

Restore Checkpoint

# Restore to checkpoint
claude checkpoint restore checkpoint-123

# Restore to time
claude checkpoint restore --time "2025-11-06T10:00:00Z"

# Restore specific files
claude checkpoint restore checkpoint-123 --files src/main.js

Create Manual Checkpoint

# Create checkpoint with message
claude checkpoint create "before refactoring auth module"

# Create at important moments
claude checkpoint create "working state before experiment"

Checkpoint Strategies

Auto-save checkpoints:

• Before major changes
• After successful tests
• Every N minutes
• Before destructive operations

Manual checkpoints:

• Before risky refactors
• At working states
• Before experiments
• After milestones

Example Workflow

# Create checkpoint before risky change
claude checkpoint create "before performance optimization"

# Make changes
claude "optimize database queries for 10x performance"

# If something breaks
claude checkpoint restore "before performance optimization"

# Or continue with improvements
claude checkpoint create "performance optimization complete"

Memory Management

Control how Claude remembers context across sessions.

Memory Locations

global: Share memory across all projects project: Project-specific memory none: Disable memory

# Set memory location
claude config set memory.location project

# Enable memory
claude config set memory.enabled true

Configuration

{
  "memory": {
    "enabled": true,
    "location": "project",
    "ttl": 86400,
    "maxSize": "10MB",
    "autoSummarize": true
  }
}

Memory Operations

# View stored memories
claude memory list

# View specific memory
claude memory show memory-123

# Clear all memories
claude memory clear

# Clear old memories
claude memory clear --older-than 7d

# Clear project memories
claude memory clear --project

What Gets Remembered

Automatically:

• Project structure
• Coding patterns
• Preferences
• Common commands
• File locations

Explicitly stored:

• Important context
• Design decisions
• Architecture notes
• Team conventions

Memory Best Practices

Project memory:

• Good for project-specific context
• Shares across team members
• Persists in .claude/memory/
• Commit to version control (optional)

Global memory:

• Personal preferences
• General knowledge
• Common patterns
• Cross-project learnings

Disable memory when:

• Working with sensitive data
• One-off tasks
• Testing/experimentation
• Troubleshooting

Example

# Remember project architecture
claude "Remember: This project uses Clean Architecture with:
- Domain layer (core business logic)
- Application layer (use cases)
- Infrastructure layer (external dependencies)
- Presentation layer (API/UI)"

# Claude will recall this in future sessions
claude "Add a new user registration feature"
# Claude: "I'll implement this following the Clean Architecture..."

Context Windows

Manage large context effectively.

Maximum Context

Model context limits:

• Claude Sonnet: 200k tokens
• Claude Opus: 200k tokens
• Claude Haiku: 200k tokens

Context Management

{
  "context": {
    "maxTokens": 200000,
    "autoTruncate": true,
    "prioritize": ["recent", "relevant"],
    "summarizeLong": true
  }
}

Strategies

Summarization:

• Auto-summarize old context
• Keep summaries of large files
• Compress conversation history

Prioritization:

• Recent messages first
• Most relevant files
• Explicit user priorities

Chunking:

• Process large codebases in chunks
• Incremental analysis
• Parallel processing

See Also

• Pricing: https://docs.claude.com/about-claude/pricing
• Token counting: https://docs.claude.com/build-with-claude/token-counting
• Best practices: references/best-practices.md
• Configuration: references/configuration.md

Agent Skills

Create, manage, and share Skills to extend Claude's capabilities in Claude Code.

What Are Agent Skills?

Agent Skills are modular capabilities that extend Claude's functionality. Each Skill packages:

• Instructions and procedural knowledge
• Metadata (name, description)
• Optional resources (scripts, templates, references)

Skills are automatically discovered and used by Claude when relevant to the task using progressive disclosure principle.

Skill Structure

Basic Structure

.claude/skills/
└── my-skill/
    └── SKILL.md       # Uppercase filename, Metadata, instructions (required)

With Resources

.claude/skills/
└── my-skill/
    ├── SKILL.md       # Uppercase filename, Metadata, instructions (required)
    ├── scripts/       # Executable code
    ├── references/    # Documentation
    └── assets/        # Templates, images

Creating Skills

SKILL.md

Metadata and configuration:

Metadata's fields:

• name: Unique identifier (kebab-case)
• description: When Claude should activate this skill
• version: Semantic version
• author: Creator name or org

Main instructions for Claude:

---
name: my-skill
description: Brief description of when to use this skill
version: 1.0.0
---

# Skill Name

Description of what this skill does.

## When to Use This Skill

Specific scenarios when Claude should activate this skill.

## Instructions

Step-by-step instructions for Claude to follow.

## Examples

Concrete examples of skill usage.

Best Practices

Clear Activation Criteria

Define exactly when the skill should be used:

Good:

Use when creating React components with TypeScript and Tailwind CSS.

Bad:

Use for frontend development.

Concise Instructions

Focus on essential information, avoid duplication:

Good:

1. Create component file in src/components/
2. Use TypeScript interfaces for props
3. Apply Tailwind classes for styling

Bad:

First you need to think about creating a component,
then maybe you should consider...

Actionable Guidance

Provide clear steps Claude can follow:

Good:

Run `npm test` to validate implementation.

Bad:

You might want to test things.

Include Examples

Show concrete input/output examples:

## Examples

Input: "Create button component"
Output: Creates src/components/Button.tsx with props interface

Scope Limitation

Keep skills focused on specific domains:

Good:

• api-testing - Testing REST APIs
• db-migrations - Database schema changes

Bad:

• general-development - Everything

Resource Types

Scripts (scripts/)

Executable code for deterministic tasks:

scripts/
├── format-code.py
├── generate-types.js
└── run-tests.sh

When to use:

• Repeated code generation
• Deterministic transformations
• External tool integrations

References (references/)

Documentation loaded into context as needed:

references/
├── api-docs.md
├── schemas.md
└── workflows.md

When to use:

• API documentation
• Database schemas
• Domain knowledge
• Detailed workflows

Assets (assets/)

Files used in output:

assets/
├── templates/
│   └── component-template.tsx
├── icons/
└── configs/

When to use:

• Templates
• Boilerplate code
• Images, icons
• Configuration files

Using Skills via API

TypeScript Example

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY
});

const response = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 4096,
  skills: [
    {
      type: 'custom',
      custom: {
        name: 'document-creator',
        description: 'Creates professional documents',
        instructions: 'Follow corporate style guide...'
      }
    }
  ],
  messages: [{
    role: 'user',
    content: 'Create a project proposal'
  }]
});

Python Example

from anthropic import Anthropic

client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    skills=[
        {
            "type": "custom",
            "custom": {
                "name": "code-reviewer",
                "description": "Reviews code for quality and security",
                "instructions": "Check for common issues..."
            }
        }
    ],
    messages=[{
        "role": "user",
        "content": "Review this code"
    }]
)

Skill Discovery

Claude automatically discovers skills:

1. Global skills: ~/.claude/skills/ 2. Project skills: .claude/skills/ 3. Plugin skills: From installed plugins

Skills are activated when:

• Task matches skill description
• User explicitly invokes skill
• Context suggests skill is relevant

Managing Skills

List Skills

claude skills list

Test Skill

claude --skill my-skill "test task"

Share Skill

# Package skill
cd .claude/skills/my-skill
tar -czf my-skill.tar.gz .

# Or create plugin
# See references/hooks-and-plugins.md

Install Skill

# Manual installation
cd .claude/skills/
tar -xzf my-skill.tar.gz

Example Skills

API Testing Skill

SKILL.md:

---
name: api-testing
description: Test REST APIs with automated requests
version: 1.0.0
---
# API Testing

Test REST APIs with comprehensive validation.

## When to Use

Use when testing API endpoints, validating responses, or
creating API test suites.

## Instructions

1. Read API documentation from references/api-docs.md
2. Use scripts/test-api.py for making requests
3. Validate response status, headers, body
4. Generate test report

## Examples

Request: "Test the /users endpoint"
Actions:
- Read references/api-docs.md for endpoint spec
- Run scripts/test-api.py --endpoint /users
- Validate response matches schema
- Report results

Database Migration Skill

SKILL.md:

---
name: db-migrations
description: Create and manage database migrations
version: 1.0.0
---

# Database Migrations

Create safe, reversible database schema changes.

## When to Use

Use when modifying database schema, adding tables,
or changing column definitions.

## Instructions

1. Review current schema in references/schema.md
2. Create migration file in migrations/
3. Include both up and down migrations
4. Test migration on development database
5. Update references/schema.md

## Migration Template

See assets/migration-template.sql for standard format.

Progressive Disclosure

Keep SKILL.md concise (<100 lines) by:

1. Core instructions in SKILL.md 2. Detailed docs in references/ 3. Executable code in scripts/ 4. Templates in assets/

Example structure:

# My Skill

Brief overview.

## When to Use

Clear activation criteria.

## Instructions

High-level steps that reference:
- references/detailed-workflow.md
- scripts/automation.py
- assets/template.tsx

Troubleshooting

Skill Not Activating

• Check description specificity
• Ensure SKILL.md has clear activation criteria

Resource Not Found

• Verify file paths in SKILL.md
• Check directory structure
• Use relative paths from skill root

Conflicting Skills

• Make descriptions more specific
• Use unique names
• Scope skills narrowly

See Also

• Skill creation guide: https://docs.claude.com/claude-code/skills
• Best practices: https://docs.claude.com/agents-and-tools/agent-skills/best-practices
• API usage: references/api-reference.md
• Plugin system: references/hooks-and-plugins.md

API Reference

API endpoints and programmatic access to Claude Code functionality.

Admin API

Usage Reports

Get Claude Code Usage Report:

GET /v1/admin/claude-code/usage

Query parameters:

• start_date: Start date (YYYY-MM-DD)
• end_date: End date (YYYY-MM-DD)
• user_id: Filter by user
• workspace_id: Filter by workspace

Response:

{
  "usage": [
    {
      "date": "2025-11-06",
      "user_id": "user-123",
      "requests": 150,
      "tokens": 45000,
      "cost": 12.50
    }
  ]
}

Example:

curl https://api.anthropic.com/v1/admin/claude-code/usage \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d start_date=2025-11-01 \
  -d end_date=2025-11-06

Cost Reports

Get Cost Report:

GET /v1/admin/usage/cost

Query parameters:

• start_date: Start date
• end_date: End date
• group_by: user | project | model

Response:

{
  "costs": [
    {
      "group": "user-123",
      "input_tokens": 100000,
      "output_tokens": 50000,
      "cost": 25.00
    }
  ],
  "total": 250.00
}

User Management

List Users:

GET /v1/admin/users

Get User:

GET /v1/admin/users/{user_id}

Update User:

PATCH /v1/admin/users/{user_id}

Remove User:

DELETE /v1/admin/users/{user_id}

Messages API

Create Message

Endpoint:

POST /v1/messages

Request:

{
  "model": "claude-sonnet-4-5-20250929",
  "max_tokens": 4096,
  "messages": [
    {
      "role": "user",
      "content": "Explain this code"
    }
  ]
}

With Skills:

{
  "model": "claude-sonnet-4-5-20250929",
  "max_tokens": 4096,
  "skills": [
    {
      "type": "custom",
      "custom": {
        "name": "code-reviewer",
        "description": "Reviews code quality",
        "instructions": "Check for bugs, security issues..."
      }
    }
  ],
  "messages": [...]
}

Response:

{
  "id": "msg_123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This code implements..."
    }
  ],
  "usage": {
    "input_tokens": 100,
    "output_tokens": 200
  }
}

Stream Messages

Streaming response:

{
  "model": "claude-sonnet-4-5-20250929",
  "max_tokens": 4096,
  "stream": true,
  "messages": [...]
}

Server-sent events:

event: message_start
data: {"type":"message_start","message":{...}}

event: content_block_delta
data: {"type":"content_block_delta","delta":{"text":"Hello"}}

event: message_stop
data: {"type":"message_stop"}

Count Tokens

Endpoint:

POST /v1/messages/count_tokens

Request:

{
  "model": "claude-sonnet-4-5-20250929",
  "messages": [
    {
      "role": "user",
      "content": "Count these tokens"
    }
  ]
}

Response:

{
  "input_tokens": 15
}

Files API

Upload File

Endpoint:

POST /v1/files

Request (multipart/form-data):

curl https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -F file=@document.pdf \
  -F purpose=user_upload

Response:

{
  "id": "file-123",
  "object": "file",
  "bytes": 12345,
  "created_at": 1699564800,
  "filename": "document.pdf",
  "purpose": "user_upload"
}

List Files

Endpoint:

GET /v1/files

Response:

{
  "data": [
    {
      "id": "file-123",
      "filename": "document.pdf",
      "bytes": 12345
    }
  ]
}

Download File

Endpoint:

GET /v1/files/{file_id}/content

Delete File

Endpoint:

DELETE /v1/files/{file_id}

Models API

List Models

Endpoint:

GET /v1/models

Response:

{
  "data": [
    {
      "id": "claude-sonnet-4-5-20250929",
      "type": "model",
      "display_name": "Claude Sonnet 4.5"
    }
  ]
}

Get Model

Endpoint:

GET /v1/models/{model_id}

Response:

{
  "id": "claude-sonnet-4-5-20250929",
  "type": "model",
  "display_name": "Claude Sonnet 4.5",
  "created_at": 1699564800
}

Skills API

Create Skill

Endpoint:

POST /v1/skills

Request:

{
  "name": "my-skill",
  "description": "Skill description",
  "instructions": "Detailed instructions...",
  "version": "1.0.0"
}

List Skills

Endpoint:

GET /v1/skills

Response:

{
  "data": [
    {
      "id": "skill-123",
      "name": "my-skill",
      "description": "Skill description"
    }
  ]
}

Update Skill

Endpoint:

PATCH /v1/skills/{skill_id}

Request:

{
  "description": "Updated description",
  "instructions": "Updated instructions..."
}

Delete Skill

Endpoint:

DELETE /v1/skills/{skill_id}

Client SDKs

TypeScript/JavaScript

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY
});

const message = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Hello, Claude!' }
  ]
});

console.log(message.content);

Python

import anthropic

client = anthropic.Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY")
)

message = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)

print(message.content)

Error Handling

Error Response Format

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid API key"
  }
}

Error Types

invalid_request_error: Invalid request parameters authentication_error: Invalid API key permission_error: Insufficient permissions not_found_error: Resource not found rate_limit_error: Rate limit exceeded api_error: Internal API error overloaded_error: Server overloaded

Retry Logic

async function withRetry(fn: () => Promise<any>, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 529 && i < maxRetries - 1) {
        await new Promise(r => setTimeout(r, 1000 * (i + 1)));
        continue;
      }
      throw error;
    }
  }
}

Rate Limits

Headers

Response headers include rate limit info:

anthropic-ratelimit-requests-limit: 1000
anthropic-ratelimit-requests-remaining: 999
anthropic-ratelimit-requests-reset: 2025-11-06T12:00:00Z
anthropic-ratelimit-tokens-limit: 100000
anthropic-ratelimit-tokens-remaining: 99500
anthropic-ratelimit-tokens-reset: 2025-11-06T12:00:00Z

Best Practices

• Monitor rate limit headers
• Implement exponential backoff
• Batch requests when possible
• Use caching to reduce requests

Authentication

API Key

Include API key in requests:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

Workspace Keys

For organization workspaces:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $WORKSPACE_API_KEY" \
  -H "anthropic-version: 2023-06-01"

See Also

• API documentation: https://docs.anthropic.com/api
• Client SDKs: https://docs.anthropic.com/api/client-sdks
• Rate limits: https://docs.anthropic.com/api/rate-limits
• Error handling: https://docs.anthropic.com/api/errors

Best Practices

Guidelines for project organization, security, performance, collaboration, and cost management.

Project Organization

Directory Structure

Keep .claude/ directory in version control:

project/
├── .claude/
│   ├── settings.json       # Project settings
│   ├── commands/           # Custom slash commands
│   │   ├── test-all.md
│   │   └── deploy.md
│   ├── skills/            # Project-specific skills
│   │   └── api-testing/
│   ├── hooks.json         # Hooks configuration
│   ├── mcp.json           # MCP servers (no secrets!)
│   └── .env.example       # Environment template
├── .gitignore             # Ignore .claude/.env
└── README.md

Documentation

Document custom extensions:

README.md:

## Claude Code Setup

### Custom Commands
- `/test-all`: Run full test suite
- `/deploy`: Deploy to staging

### Skills
- `api-testing`: REST API testing utilities

### MCP Servers
- `postgres`: Database access
- `github`: Repository integration

### Environment Variables
Copy `.claude/.env.example` to `.claude/.env` and fill in:
- GITHUB_TOKEN
- DATABASE_URL

Team Sharing

What to commit:

• .claude/settings.json
• .claude/commands/
• .claude/skills/
• .claude/hooks.json
• .claude/mcp.json (without secrets)
• .claude/.env.example

What NOT to commit:

• .claude/.env (contains secrets)
• .claude/memory/ (optional)
• .claude/cache/
• API keys or tokens

.gitignore:

.claude/.env
.claude/memory/
.claude/cache/
.claude/logs/

Security

API Key Management

Never commit API keys:

# Use environment variables
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# Or .env file (gitignored)
echo 'ANTHROPIC_API_KEY=sk-ant-xxxxx' > .claude/.env

Rotate keys regularly:

# Generate new key
# Update in all environments
# Revoke old key

Use workspace keys:

# For team projects, use workspace API keys
# Easier to manage and rotate
# Better access control

Sandboxing

Enable sandboxing in production:

{
  "sandboxing": {
    "enabled": true,
    "allowedPaths": ["/workspace"],
    "networkAccess": "restricted",
    "allowedDomains": ["api.company.com"]
  }
}

Hook Security

Review hook scripts before execution:

# Check hooks.json
cat .claude/hooks.json | jq .

# Review scripts
cat .claude/scripts/hook.sh

# Validate inputs in hooks
#!/bin/bash
if [[ ! "$TOOL_ARGS" =~ ^[a-zA-Z0-9_-]+$ ]]; then
  echo "Invalid input"
  exit 1
fi

Plugin Security

Audit plugins before installation:

# Review plugin source
gh repo view username/plugin

# Check plugin.json
tar -xzf plugin.tar.gz
cat plugin.json

# Install from trusted sources only
claude plugin install gh:anthropics/official-plugin

Performance Optimization

Model Selection

Choose appropriate model for task:

Haiku - Fast, cost-effective:

claude --model haiku "fix typo in README"
claude --model haiku "format code"

Sonnet - Balanced (default):

claude "implement user authentication"
claude "review this PR"

Opus - Complex tasks:

claude --model opus "architect microservices system"
claude --model opus "optimize algorithm performance"

Prompt Caching

Cache repeated context:

// Cache large codebase
const response = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  system: [
    {
      type: 'text',
      text: largeCodebase,
      cache_control: { type: 'ephemeral' }
    }
  ],
  messages: [...]
});

Benefits:

• 90% cost reduction on cached tokens
• Faster responses
• Better for iterative development

Rate Limiting

Implement rate limiting in hooks:

#!/bin/bash
# .claude/scripts/rate-limit.sh

REQUESTS_FILE=".claude/requests.log"
MAX_REQUESTS=100
WINDOW=3600  # 1 hour

# Count recent requests
RECENT=$(find $REQUESTS_FILE -mmin -60 | wc -l)

if [ $RECENT -ge $MAX_REQUESTS ]; then
  echo "Rate limit exceeded"
  exit 1
fi

echo $(date) >> $REQUESTS_FILE

Token Management

Monitor token usage:

# Check usage
claude usage show

# Set limits
claude config set maxTokens 8192

# Track costs
claude analytics cost --group-by project

Team Collaboration

Standardize Commands

Create consistent slash commands:

# .claude/commands/test.md
Run test suite with coverage report.

Options:
- {{suite}}: Specific test suite (optional)

Usage:

/test
/test unit
/test integration

Share Skills

Create team skills via plugins:

# Create team plugin
cd .claude/plugins/team-plugin
cat > plugin.json <<EOF
{
  "name": "team-plugin",
  "skills": ["skills/*/"],
  "commands": ["commands/*.md"]
}
EOF

# Package and share
tar -czf team-plugin.tar.gz .

Consistent Settings

Use project settings for consistency:

.claude/settings.json:

{
  "model": "claude-sonnet-4-5-20250929",
  "maxTokens": 8192,
  "outputStyle": "technical-writer",
  "thinking": {
    "enabled": true,
    "budget": 10000
  }
}

Memory Settings

Use project memory for shared context:

{
  "memory": {
    "enabled": true,
    "location": "project"
  }
}

Benefits:

• Shared project knowledge
• Consistent behavior across team
• Reduced onboarding time

Cost Management

Budget Limits

Set budget limits in hooks:

#!/bin/bash
# .claude/scripts/budget-check.sh

MONTHLY_BUDGET=1000
CURRENT_SPEND=$(claude analytics cost --format json | jq '.total')

if (( $(echo "$CURRENT_SPEND > $MONTHLY_BUDGET" | bc -l) )); then
  echo "⚠️  Monthly budget exceeded: \$$CURRENT_SPEND / \$$MONTHLY_BUDGET"
  exit 1
fi

Usage Monitoring

Monitor via analytics API:

# Daily usage report
claude analytics usage --start $(date -d '1 day ago' +%Y-%m-%d)

# Cost by user
claude analytics cost --group-by user

# Export to CSV
claude analytics export --format csv > usage.csv

Cost Optimization

Use Haiku for simple tasks:

# Expensive (Sonnet)
claude "fix typo in README"

# Cheap (Haiku)
claude --model haiku "fix typo in README"

Enable caching:

{
  "caching": {
    "enabled": true,
    "ttl": 300
  }
}

Batch operations:

# Instead of multiple requests
claude "fix file1.js"
claude "fix file2.js"
claude "fix file3.js"

# Batch them
claude "fix all files: file1.js file2.js file3.js"

Track per-project costs:

# Tag projects
claude --project my-project "implement feature"

# View project costs
claude analytics cost --project my-project

Development Workflows

Feature Development

# 1. Plan feature
claude /plan "implement user authentication"

# 2. Create checkpoint
claude checkpoint create "before auth implementation"

# 3. Implement
claude /cook "implement user authentication"

# 4. Test
claude /test

# 5. Review
claude "review authentication implementation"

# 6. Commit
claude /git:cm

Bug Fixing

# 1. Debug
claude /debug "login button not working"

# 2. Fix
claude /fix:fast "fix login button issue"

# 3. Test
claude /test

# 4. Commit
claude /git:cm

Code Review

# Review PR
claude "review PR #123"

# Check security
claude "review for security vulnerabilities"

# Verify tests
claude "check test coverage"

See Also

• Security guide: https://docs.claude.com/claude-code/security
• Cost tracking: https://docs.claude.com/claude-code/costs
• Team setup: https://docs.claude.com/claude-code/overview
• API usage: references/api-reference.md

CI/CD Integration

Integrate Claude Code into development workflows with GitHub Actions and GitLab CI/CD.

GitHub Actions

Basic Workflow

.github/workflows/claude.yml:

name: Claude Code CI

on: [push, pull_request]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - uses: anthropic/claude-code-action@v1
        with:
          command: '/fix:types && /test'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Code Review Workflow

name: Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Review with Claude
        uses: anthropic/claude-code-action@v1
        with:
          command: |
            Review the changes in this PR:
            - Check for bugs and edge cases
            - Verify test coverage
            - Assess performance implications
            - Review security concerns
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Post Review Comment
        uses: actions/github-script@v6
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: process.env.CLAUDE_OUTPUT
            })

Test & Fix Workflow

name: Test and Fix

on: [push]

jobs:
  test-fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Run Tests
        id: test
        continue-on-error: true
        run: npm test

      - name: Fix Failures
        if: steps.test.outcome == 'failure'
        uses: anthropic/claude-code-action@v1
        with:
          command: '/fix:test check test output and fix failures'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Commit Fixes
        if: steps.test.outcome == 'failure'
        run: |
          git config user.name "Claude Bot"
          git config user.email "claude@anthropic.com"
          git add .
          git commit -m "fix: auto-fix test failures"
          git push

Documentation Update

name: Update Docs

on:
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Update Documentation
        uses: anthropic/claude-code-action@v1
        with:
          command: '/docs:update'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Commit Docs
        run: |
          git config user.name "Claude Bot"
          git config user.email "claude@anthropic.com"
          git add docs/
          git commit -m "docs: auto-update documentation" || echo "No changes"
          git push

GitLab CI/CD

Basic Pipeline

.gitlab-ci.yml:

stages:
  - review
  - test
  - deploy

claude-review:
  stage: review
  image: node:18
  script:
    - npm install -g @anthropic-ai/claude-code
    - claude login --api-key $ANTHROPIC_API_KEY
    - claude '/fix:types && /test'
  only:
    - merge_requests

Advanced Pipeline

variables:
  CLAUDE_MODEL: "claude-sonnet-4-5-20250929"

stages:
  - lint
  - test
  - review
  - deploy

before_script:
  - npm install -g @anthropic-ai/claude-code
  - claude login --api-key $ANTHROPIC_API_KEY

lint:
  stage: lint
  script:
    - claude '/fix:types'
  artifacts:
    paths:
      - src/
    expire_in: 1 hour

test:
  stage: test
  script:
    - npm test || claude '/fix:test analyze failures and fix'
  coverage: '/Coverage: \d+\.\d+%/'

review:
  stage: review
  script:
    - |
      claude "Review this merge request:
      - Check code quality
      - Verify tests
      - Review security
      - Assess performance" > review.md
  artifacts:
    reports:
      codequality: review.md
  only:
    - merge_requests

deploy:
  stage: deploy
  script:
    - claude '/deploy-check'
    - ./deploy.sh
  only:
    - main

Automated Fixes

fix-on-failure:
  stage: test
  script:
    - npm test
  retry:
    max: 2
    when:
      - script_failure
  after_script:
    - |
      if [ $CI_JOB_STATUS == 'failed' ]; then
        claude '/fix:test analyze CI logs and fix issues'
        git add .
        git commit -m "fix: auto-fix from CI"
        git push origin HEAD:$CI_COMMIT_REF_NAME
      fi

Common Patterns

PR Comment Bot

Post Claude reviews as PR comments:

# GitHub Actions
- name: Comment PR
  uses: actions/github-script@v6
  with:
    script: |
      const review = process.env.CLAUDE_REVIEW
      github.rest.pulls.createReview({
        owner: context.repo.owner,
        repo: context.repo.repo,
        pull_number: context.issue.number,
        body: review,
        event: 'COMMENT'
      })

Conditional Execution

Run Claude only on certain conditions:

# Run on large PRs only
- name: Review Large PRs
  if: ${{ github.event.pull_request.changed_files > 10 }}
  uses: anthropic/claude-code-action@v1
  with:
    command: '/review:codebase analyze changes'

Cost Control

Limit CI usage to control costs:

# Skip for draft PRs
- name: Claude Review
  if: ${{ !github.event.pull_request.draft }}
  uses: anthropic/claude-code-action@v1

# Run only on specific branches
- name: Claude Check
  if: startsWith(github.ref, 'refs/heads/release/')
  uses: anthropic/claude-code-action@v1

Security Best Practices

API Key Management

GitHub:

Settings → Secrets and variables → Actions
Add: ANTHROPIC_API_KEY

GitLab:

Settings → CI/CD → Variables
Add: ANTHROPIC_API_KEY (Protected, Masked)

Restricted Permissions

GitHub Actions:

permissions:
  contents: read
  pull-requests: write
  issues: write

GitLab CI:

variables:
  GIT_STRATEGY: clone
  GIT_DEPTH: 1

Secrets Scanning

Prevent API key exposure:

- name: Scan for Secrets
  run: |
    if git diff | grep -i "ANTHROPIC_API_KEY"; then
      echo "API key detected in diff!"
      exit 1
    fi

Monitoring & Debugging

Workflow Logs

GitHub Actions:

- name: Debug Info
  run: |
    echo "Workflow: ${{ github.workflow }}"
    echo "Event: ${{ github.event_name }}"
    echo "Ref: ${{ github.ref }}"

GitLab CI:

debug:
  script:
    - echo "Pipeline ID: $CI_PIPELINE_ID"
    - echo "Job ID: $CI_JOB_ID"
    - echo "Branch: $CI_COMMIT_BRANCH"

Artifacts

Save Claude outputs:

# GitHub
- name: Save Claude Output
  uses: actions/upload-artifact@v3
  with:
    name: claude-results
    path: claude-output.md

# GitLab
artifacts:
  paths:
    - claude-output.md
  expire_in: 1 week

Error Handling

- name: Claude Task
  continue-on-error: true
  id: claude
  uses: anthropic/claude-code-action@v1

- name: Handle Failure
  if: steps.claude.outcome == 'failure'
  run: |
    echo "Claude task failed, continuing anyway"

Performance Optimization

Caching

GitHub Actions:

- uses: actions/cache@v3
  with:
    path: ~/.claude/cache
    key: claude-cache-${{ hashFiles('package-lock.json') }}

GitLab CI:

cache:
  key: claude-cache
  paths:
    - .claude/cache

Parallel Execution

# GitHub - Matrix builds
strategy:
  matrix:
    task: [lint, test, review]
steps:
  - run: claude "/${{ matrix.task }}"

# GitLab - Parallel jobs
test:
  parallel: 3
  script:
    - claude "/test --shard $CI_NODE_INDEX/$CI_NODE_TOTAL"

See Also

• GitHub Actions docs: https://docs.github.com/actions
• GitLab CI/CD docs: https://docs.gitlab.com/ee/ci/
• Claude Code Actions: https://github.com/anthropics/claude-code-action
• Best practices: references/best-practices.md

Configuration and Settings

Configure Claude Code behavior with settings hierarchy, model selection, and output styles.

Settings Hierarchy

Settings are applied in order of precedence:

1. Command-line flags (highest priority) 2. Environment variables 3. Project settings (.claude/settings.json) 4. Global settings (~/.claude/settings.json)

Settings File Format

Global Settings

~/.claude/settings.json:

{
  "model": "claude-sonnet-4-5-20250929",
  "maxTokens": 8192,
  "temperature": 1.0,
  "thinking": {
    "enabled": true,
    "budget": 10000
  },
  "outputStyle": "default",
  "memory": {
    "enabled": true,
    "location": "global"
  }
}

Project Settings

.claude/settings.json:

{
  "model": "claude-sonnet-4-5-20250929",
  "maxTokens": 4096,
  "sandboxing": {
    "enabled": true,
    "allowedPaths": ["/workspace"]
  },
  "memory": {
    "enabled": true,
    "location": "project"
  }
}

Key Settings

Model Configuration

model: Claude model to use

• claude-sonnet-4-5-20250929 (default, latest Sonnet)
• claude-opus-4-20250514 (Opus for complex tasks)
• claude-haiku-4-20250408 (Haiku for speed)

Model aliases:

• sonnet: Latest Claude Sonnet
• opus: Latest Claude Opus
• haiku: Latest Claude Haiku
• opusplan: Opus with extended thinking for planning

{
  "model": "sonnet"
}

Token Settings

maxTokens: Maximum tokens in response

• Default: 8192
• Range: 1-200000

{
  "maxTokens": 16384
}

temperature: Randomness in responses

• Default: 1.0
• Range: 0.0-1.0
• Lower = more focused, higher = more creative

{
  "temperature": 0.7
}

Thinking Configuration

Extended thinking for complex reasoning:

{
  "thinking": {
    "enabled": true,
    "budget": 10000,
    "mode": "auto"
  }
}

Options:

• enabled: Enable extended thinking
• budget: Token budget for thinking (default: 10000)
• mode: auto | manual | disabled

Sandboxing

Filesystem and network isolation:

{
  "sandboxing": {
    "enabled": true,
    "allowedPaths": [
      "/workspace",
      "/home/user/projects"
    ],
    "networkAccess": "restricted",
    "allowedDomains": [
      "api.example.com",
      "*.trusted.com"
    ]
  }
}

Options:

• enabled: Enable sandboxing
• allowedPaths: Filesystem access paths
• networkAccess: full | restricted | none
• allowedDomains: Whitelisted domains

Memory Management

Control how Claude remembers context:

{
  "memory": {
    "enabled": true,
    "location": "project",
    "ttl": 86400
  }
}

location options:

• global: Share memory across all projects
• project: Project-specific memory
• none: Disable memory

ttl: Time to live in seconds (default: 86400 = 24 hours)

Output Styles

Customize Claude's behavior:

{
  "outputStyle": "technical-writer"
}

Built-in styles:

• default: Standard coding assistant
• technical-writer: Documentation focus
• code-reviewer: Review-focused
• minimal: Concise responses

Logging

Configure logging behavior:

{
  "logging": {
    "level": "info",
    "file": ".claude/logs/session.log",
    "console": true
  }
}

Levels: debug, info, warn, error

Model Configuration

Using Model Aliases

# Use Sonnet (default)
claude

# Use Opus for complex task
claude --model opus "architect a microservices system"

# Use Haiku for speed
claude --model haiku "fix typo in README"

# Use opusplan for planning
claude --model opusplan "plan authentication system"

In Settings File

{
  "model": "opus",
  "thinking": {
    "enabled": true,
    "budget": 20000
  }
}

Model Selection Guide

Sonnet (claude-sonnet-4-5-20250929):

• Balanced performance and cost
• Default choice for most tasks
• Good for general development

Opus (claude-opus-4-20250514):

• Highest capability
• Complex reasoning and planning
• Use for architecture, design, complex debugging

Haiku (claude-haiku-4-20250408):

• Fastest, most cost-effective
• Simple tasks (typos, formatting)
• High-volume operations

opusplan:

• Opus + extended thinking
• Deep planning and analysis
• Architecture decisions

Output Styles

Creating Custom Output Style

Create ~/.claude/output-styles/my-style.md:

You are a senior software architect focused on scalability.

Guidelines:
- Prioritize performance and scalability
- Consider distributed systems patterns
- Include monitoring and observability
- Think about failure modes
- Document trade-offs

Using Custom Output Style

claude --output-style my-style

Or in settings:

{
  "outputStyle": "my-style"
}

Example Output Styles

technical-writer.md:

You are a technical writer creating clear documentation.

Guidelines:
- Use simple, clear language
- Provide examples
- Structure with headings
- Include diagrams when helpful
- Focus on user understanding

code-reviewer.md:

You are a senior code reviewer.

Guidelines:
- Check for bugs and edge cases
- Review security vulnerabilities
- Assess performance implications
- Verify test coverage
- Suggest improvements

Environment Variables

API Configuration

export ANTHROPIC_API_KEY=sk-ant-xxxxx
export ANTHROPIC_BASE_URL=https://api.anthropic.com

Proxy Configuration

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1

Custom CA Certificates

export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.crt

Debug Mode

export CLAUDE_DEBUG=1
export CLAUDE_LOG_LEVEL=debug

Command-Line Flags

Common Flags

# Set model
claude --model opus

# Set max tokens
claude --max-tokens 16384

# Set temperature
claude --temperature 0.8

# Enable debug mode
claude --debug

# Use specific output style
claude --output-style technical-writer

# Disable memory
claude --no-memory

# Set project directory
claude --project /path/to/project

Configuration Commands

# View current settings
claude config list

# Set global setting
claude config set model opus

# Set project setting
claude config set --project maxTokens 4096

# Get specific setting
claude config get model

# Reset to defaults
claude config reset

Advanced Configuration

Custom Tools

Register custom tools:

{
  "tools": [
    {
      "name": "custom-tool",
      "description": "Custom tool",
      "command": "./scripts/custom-tool.sh",
      "parameters": {
        "arg1": "string"
      }
    }
  ]
}

Rate Limiting

Configure rate limits:

{
  "rateLimits": {
    "requestsPerMinute": 100,
    "tokensPerMinute": 100000,
    "retryStrategy": "exponential"
  }
}

Caching

Prompt caching configuration:

{
  "caching": {
    "enabled": true,
    "ttl": 3600,
    "maxSize": "100MB"
  }
}

Best Practices

Project Settings

• Keep project-specific in .claude/settings.json
• Commit to version control
• Document custom settings
• Share with team

Global Settings

• Personal preferences only
• Don't override project settings unnecessarily
• Use for API keys and auth

Security

• Never commit API keys
• Use environment variables for secrets
• Enable sandboxing in production
• Restrict network access

Performance

• Use appropriate model for task
• Set reasonable token limits
• Enable caching
• Configure rate limits

Troubleshooting

Settings Not Applied

# Check settings hierarchy
claude config list --all

# Verify settings file syntax
cat .claude/settings.json | jq .

# Reset to defaults
claude config reset

Environment Variables Not Recognized

# Verify export
echo $ANTHROPIC_API_KEY

# Check shell profile
cat ~/.bashrc | grep ANTHROPIC

# Reload shell
source ~/.bashrc

See Also

• Model selection: https://docs.claude.com/about-claude/models
• Output styles: references/best-practices.md
• Security: references/enterprise-features.md
• Troubleshooting: references/troubleshooting.md

Enterprise Features

Enterprise deployment, security, compliance, and monitoring for Claude Code.

Identity & Access Management

SSO Integration

Support for SAML 2.0 and OAuth 2.0:

{
  "auth": {
    "type": "saml",
    "provider": "okta",
    "entityId": "claude-code",
    "ssoUrl": "https://company.okta.com/app/saml",
    "certificate": "/path/to/cert.pem"
  }
}

Supported providers:

• Okta
• Azure AD
• Google Workspace
• OneLogin
• Auth0

Role-Based Access Control (RBAC)

Define user roles and permissions:

{
  "rbac": {
    "roles": {
      "developer": {
        "permissions": ["code:read", "code:write", "tools:use"]
      },
      "reviewer": {
        "permissions": ["code:read", "code:review"]
      },
      "admin": {
        "permissions": ["*"]
      }
    }
  }
}

User Management

Centralized user provisioning:

# Add user
claude admin user add user@company.com --role developer

# Remove user
claude admin user remove user@company.com

# List users
claude admin user list

# Update user role
claude admin user update user@company.com --role admin

Security & Compliance

Sandboxing

Filesystem and network isolation:

{
  "sandboxing": {
    "enabled": true,
    "mode": "strict",
    "filesystem": {
      "allowedPaths": ["/workspace"],
      "readOnlyPaths": ["/usr/lib", "/etc"],
      "deniedPaths": ["/etc/passwd", "/etc/shadow"]
    },
    "network": {
      "enabled": false,
      "allowedDomains": ["api.anthropic.com"]
    }
  }
}

Audit Logging

Comprehensive activity logs:

{
  "auditLog": {
    "enabled": true,
    "destination": "syslog",
    "syslogHost": "logs.company.com:514",
    "includeToolCalls": true,
    "includePrompts": false,
    "retention": "90d"
  }
}

Log format:

{
  "timestamp": "2025-11-06T10:30:00Z",
  "user": "user@company.com",
  "action": "tool_call",
  "tool": "bash",
  "args": {"command": "git status"},
  "result": "success"
}

Data Residency

Region-specific deployment:

{
  "region": "us-east-1",
  "dataResidency": {
    "enabled": true,
    "allowedRegions": ["us-east-1", "us-west-2"]
  }
}

Compliance Certifications

• SOC 2 Type II: Security controls
• HIPAA: Healthcare data protection
• GDPR: EU data protection
• ISO 27001: Information security

Deployment Options

Amazon Bedrock

Deploy via AWS Bedrock:

{
  "provider": "bedrock",
  "region": "us-east-1",
  "model": "anthropic.claude-sonnet-4-5",
  "credentials": {
    "accessKeyId": "${AWS_ACCESS_KEY_ID}",
    "secretAccessKey": "${AWS_SECRET_ACCESS_KEY}"
  }
}

Google Vertex AI

Deploy via GCP Vertex AI:

{
  "provider": "vertex",
  "project": "company-project",
  "location": "us-central1",
  "model": "claude-sonnet-4-5",
  "credentials": "/path/to/service-account.json"
}

Self-Hosted

On-premises deployment:

Docker:

docker run -d \
  -v /workspace:/workspace \
  -e ANTHROPIC_API_KEY=$API_KEY \
  anthropic/claude-code:latest

Kubernetes:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: claude-code
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: claude-code
        image: anthropic/claude-code:latest
        env:
        - name: ANTHROPIC_API_KEY
          valueFrom:
            secretKeyRef:
              name: claude-secrets
              key: api-key

LLM Gateway

Integration with LiteLLM:

{
  "gateway": {
    "enabled": true,
    "url": "http://litellm-proxy:4000",
    "apiKey": "${GATEWAY_API_KEY}"
  }
}

Monitoring & Analytics

OpenTelemetry

Built-in telemetry support:

{
  "telemetry": {
    "enabled": true,
    "exporter": "otlp",
    "endpoint": "http://otel-collector:4317",
    "metrics": true,
    "traces": true,
    "logs": true
  }
}

Usage Analytics

Track team productivity metrics:

# Get usage report
claude analytics usage --start 2025-11-01 --end 2025-11-06

# Get cost report
claude analytics cost --group-by user

# Export metrics
claude analytics export --format csv > metrics.csv

Metrics tracked:

• Requests per user/project
• Token usage
• Tool invocations
• Session duration
• Error rates
• Cost per user/project

Custom Dashboards

Build org-specific dashboards:

from claude_code import Analytics

analytics = Analytics(api_key=API_KEY)

# Get metrics
metrics = analytics.get_metrics(
    start="2025-11-01",
    end="2025-11-06",
    group_by="user"
)

# Create visualization
dashboard = analytics.create_dashboard(
    metrics=metrics,
    charts=["usage", "cost", "errors"]
)

Cost Management

Monitor and control API costs:

{
  "costControl": {
    "enabled": true,
    "budgets": {
      "monthly": 10000,
      "perUser": 500
    },
    "alerts": {
      "threshold": 0.8,
      "recipients": ["admin@company.com"]
    }
  }
}

Network Configuration

Proxy Support

HTTP/HTTPS proxy configuration:

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,company.internal

Custom CA

Trust custom certificate authorities:

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/company-ca.crt

Mutual TLS (mTLS)

Client certificate authentication:

{
  "mtls": {
    "enabled": true,
    "clientCert": "/path/to/client-cert.pem",
    "clientKey": "/path/to/client-key.pem",
    "caCert": "/path/to/ca-cert.pem"
  }
}

IP Allowlisting

Restrict access by IP:

{
  "ipAllowlist": {
    "enabled": true,
    "addresses": [
      "10.0.0.0/8",
      "192.168.1.0/24",
      "203.0.113.42"
    ]
  }
}

Data Governance

Data Retention

Configure data retention policies:

{
  "dataRetention": {
    "conversations": "30d",
    "logs": "90d",
    "metrics": "1y",
    "backups": "7d"
  }
}

Data Encryption

Encryption at rest and in transit:

{
  "encryption": {
    "atRest": {
      "enabled": true,
      "algorithm": "AES-256-GCM",
      "keyManagement": "aws-kms"
    },
    "inTransit": {
      "tlsVersion": "1.3",
      "cipherSuites": ["TLS_AES_256_GCM_SHA384"]
    }
  }
}

PII Protection

Detect and redact PII:

{
  "piiProtection": {
    "enabled": true,
    "detectPatterns": ["email", "ssn", "credit_card"],
    "action": "redact",
    "auditLog": true
  }
}

High Availability

Load Balancing

Distribute requests across instances:

# HAProxy configuration
frontend claude_front
  bind *:443 ssl crt /etc/ssl/certs/claude.pem
  default_backend claude_back

backend claude_back
  balance roundrobin
  server claude1 10.0.1.10:8080 check
  server claude2 10.0.1.11:8080 check
  server claude3 10.0.1.12:8080 check

Failover

Automatic failover configuration:

{
  "highAvailability": {
    "enabled": true,
    "primaryRegion": "us-east-1",
    "failoverRegions": ["us-west-2", "eu-west-1"],
    "healthCheck": {
      "interval": "30s",
      "timeout": "5s"
    }
  }
}

Backup & Recovery

Automated backup strategies:

# Configure backups
claude admin backup configure \
  --schedule "0 2 * * *" \
  --retention 30d \
  --destination s3://backups/claude-code

# Manual backup
claude admin backup create

# Restore from backup
claude admin backup restore backup-20251106

See Also

• Network configuration: https://docs.claude.com/claude-code/network-config
• Security best practices: references/best-practices.md
• Monitoring setup: https://docs.claude.com/claude-code/monitoring
• Compliance: https://docs.claude.com/claude-code/legal-and-compliance

Getting Started with Claude Code

Installation, authentication, and setup guide for Claude Code.

What is Claude Code?

Claude Code is Anthropic's agentic coding tool that lives in the terminal and helps turn ideas into code faster. Key features:

• Agentic Capabilities: Autonomous planning, execution, and validation
• Terminal Integration: Works directly in command line
• IDE Support: Extensions for VS Code and JetBrains IDEs
• Extensibility: Plugins, skills, slash commands, and MCP servers
• Enterprise Ready: SSO, sandboxing, monitoring, and compliance features

Prerequisites

System Requirements

• Operating Systems: macOS, Linux, or Windows (WSL2)
• Runtime: Node.js 18+ or Python 3.10+
• API Key: From Anthropic Console (console.anthropic.com)

Getting API Key

1. Go to console.anthropic.com 2. Sign in or create account 3. Navigate to API Keys section 4. Generate new API key 5. Save key securely (cannot be viewed again)

Installation

Install via npm (Recommended)

npm install -g @anthropic-ai/claude-code

Install via pip

pip install claude-code

Verify Installation

claude --version

Authentication

Method 1: Interactive Login

claude login
# Follow prompts to enter API key

Method 2: Environment Variable

# Add to ~/.bashrc or ~/.zshrc
export ANTHROPIC_API_KEY=your_api_key_here

# Or set for single session
export ANTHROPIC_API_KEY=your_api_key_here
claude

Method 3: Configuration File

Create ~/.claude/config.json:

{
  "apiKey": "your_api_key_here"
}

Verify Authentication

claude "hello"
# Should respond without authentication errors

First Run

Start Interactive Session

# In any directory
claude

# In specific project
cd /path/to/project
claude

Run with Specific Task

claude "implement user authentication"

Run with File Context

claude "explain this code" --file app.js

Basic Usage

Interactive Mode

$ claude
Claude Code> help me create a React component
# Claude will plan and execute

One-Shot Mode

claude "add error handling to main.py"

With Additional Context

claude "refactor this function" --file utils.js --context "make it async"

Understanding the Interface

Session Start

Claude Code v1.x.x
Working directory: /path/to/project
Model: claude-sonnet-4-5-20250929

Claude Code>

Tool Execution

Claude will show:

• Tool being used (Read, Write, Bash, etc.)
• Tool parameters
• Results or outputs
• Thinking/planning process (if enabled)

Session End

# Type Ctrl+C or Ctrl+D
# Or type 'exit' or 'quit'

Common First Commands

Explore Codebase

claude "explain the project structure"

Run Tests

claude "run the test suite"

Fix Issues

claude "fix all TypeScript errors"

Add Feature

claude "add input validation to the login form"

Directory Structure

Claude Code creates .claude/ in your project:

project/
├── .claude/
│   ├── settings.json      # Project-specific settings
│   ├── commands/          # Custom slash commands
│   ├── skills/            # Custom skills
│   ├── hooks.json         # Hook configurations
│   └── mcp.json           # MCP server configurations
└── ...

Next Steps

Learn Slash Commands

# See available commands
/help

# Try common workflows
/cook implement feature X
/fix:fast bug in Y
/test

Create Custom Skills

See references/agent-skills.md for creating project-specific skills.

Configure MCP Servers

See references/mcp-integration.md for connecting external tools.

Set Up Hooks

See references/hooks-and-plugins.md for automation.

Configure Settings

See references/configuration.md for customization options.

Quick Troubleshooting

Authentication Issues

# Re-login
claude logout
claude login

# Verify API key is set
echo $ANTHROPIC_API_KEY

Permission Errors

# Check file permissions
ls -la ~/.claude

# Fix ownership
sudo chown -R $USER ~/.claude

Installation Issues

# Clear npm cache
npm cache clean --force

# Reinstall
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

WSL2 Issues (Windows)

# Ensure WSL2 is updated
wsl --update

# Check Node.js version in WSL
node --version  # Should be 18+

Getting Help

• Documentation: https://docs.claude.com/claude-code
• GitHub Issues: https://github.com/anthropics/claude-code/issues
• Support: support.claude.com
• Community: discord.gg/anthropic

For detailed troubleshooting, see references/troubleshooting.md.

Hooks and Plugins

Customize and extend Claude Code behavior with hooks and plugins.

Hooks System

Hooks are shell commands that execute in response to events.

Hook Types

Pre-tool hooks: Execute before tool calls Post-tool hooks: Execute after tool calls User prompt submit hooks: Execute when user submits prompts

Configuration

Hooks are configured in .claude/hooks.json:

{
  "hooks": {
    "pre-tool": {
      "bash": "echo 'Running: $TOOL_ARGS'",
      "write": "./scripts/validate-write.sh"
    },
    "post-tool": {
      "write": "./scripts/format-code.sh",
      "edit": "prettier --write $FILE_PATH"
    },
    "user-prompt-submit": "./scripts/validate-request.sh"
  }
}

Environment Variables

Available in hook scripts:

All hooks:

• $TOOL_NAME: Name of the tool being called
• $TOOL_ARGS: JSON string of tool arguments

Post-tool only:

• $TOOL_RESULT: Tool execution result

User-prompt-submit only:

• $USER_PROMPT: User's prompt text

Hook Examples

Pre-tool: Security Validation

#!/bin/bash
# .claude/scripts/validate-bash.sh

# Block dangerous commands
if echo "$TOOL_ARGS" | grep -E "rm -rf /|format|mkfs"; then
  echo "❌ Dangerous command blocked"
  exit 1
fi

echo "✓ Command validated"

Configuration:

{
  "hooks": {
    "pre-tool": {
      "bash": "./.claude/scripts/validate-bash.sh"
    }
  }
}

Post-tool: Auto-format

#!/bin/bash
# .claude/scripts/format-code.sh

# Extract file path from tool args
FILE_PATH=$(echo "$TOOL_ARGS" | jq -r '.file_path')

# Format based on file type
case "$FILE_PATH" in
  *.js|*.ts|*.jsx|*.tsx)
    prettier --write "$FILE_PATH"
    ;;
  *.py)
    black "$FILE_PATH"
    ;;
  *.go)
    gofmt -w "$FILE_PATH"
    ;;
esac

Configuration:

{
  "hooks": {
    "post-tool": {
      "write": "./.claude/scripts/format-code.sh",
      "edit": "./.claude/scripts/format-code.sh"
    }
  }
}

User-prompt-submit: Cost Tracking

#!/bin/bash
# .claude/scripts/track-usage.sh

# Log prompt
echo "$(date): $USER_PROMPT" >> .claude/usage.log

# Estimate tokens (rough)
TOKEN_COUNT=$(echo "$USER_PROMPT" | wc -w)
echo "Estimated tokens: $TOKEN_COUNT"

Configuration:

{
  "hooks": {
    "user-prompt-submit": "./.claude/scripts/track-usage.sh"
  }
}

Hook Best Practices

Performance: Keep hooks fast (<100ms) Reliability: Handle errors gracefully Security: Validate all inputs Logging: Log important actions Testing: Test hooks thoroughly

Hook Errors

When a hook fails:

• Pre-tool hook failure blocks tool execution
• Post-tool hook failure is logged but doesn't block
• User can configure strict mode to block on all failures

Plugins System

Plugins are packaged collections of extensions.

Plugin Structure

my-plugin/
├── plugin.json          # Plugin metadata
├── commands/            # Slash commands
│   ├── my-command.md
│   └── another-command.md
├── skills/             # Agent skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/              # Hook scripts
│   ├── hooks.json
│   └── scripts/
├── mcp/                # MCP server configurations
│   └── mcp.json
└── README.md           # Documentation

plugin.json

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Plugin description",
  "author": "Your Name",
  "homepage": "https://github.com/user/plugin",
  "license": "MIT",
  "commands": ["commands/*.md"],
  "skills": ["skills/*/"],
  "hooks": "hooks/hooks.json",
  "mcpServers": "mcp/mcp.json",
  "dependencies": {
    "node": ">=18.0.0"
  }
}

Installing Plugins

From GitHub

claude plugin install gh:username/repo
claude plugin install gh:username/repo@v1.0.0

From npm

claude plugin install npm:package-name
claude plugin install npm:@scope/package-name

From Local Path

claude plugin install ./path/to/plugin
claude plugin install ~/plugins/my-plugin

From URL

claude plugin install https://example.com/plugin.zip

Managing Plugins

List Installed Plugins

claude plugin list

Update Plugin

claude plugin update my-plugin
claude plugin update --all

Uninstall Plugin

claude plugin uninstall my-plugin

Enable/Disable Plugin

claude plugin disable my-plugin
claude plugin enable my-plugin

Creating Plugins

Initialize Plugin

mkdir my-plugin
cd my-plugin

Create plugin.json

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My awesome plugin",
  "author": "Your Name",
  "commands": ["commands/*.md"],
  "skills": ["skills/*/"]
}

Add Components

# Add slash command
mkdir -p commands
cat > commands/my-command.md <<EOF
# My Command
Do something awesome with {{input}}.
EOF

# Add skill
mkdir -p skills/my-skill
cat > skills/my-skill/skill.json <<EOF
{
  "name": "my-skill",
  "description": "Does something",
  "version": "1.0.0"
}
EOF

Package Plugin

# Create archive
tar -czf my-plugin.tar.gz .

# Or zip
zip -r my-plugin.zip .

Publishing Plugins

To GitHub

git init
git add .
git commit -m "Initial commit"
git tag v1.0.0
git push origin main --tags

To npm

npm init
npm publish

Plugin Marketplaces

Organizations can create private plugin marketplaces.

Configure Marketplace

{
  "marketplaces": [
    {
      "name": "company-internal",
      "url": "https://plugins.company.com/catalog.json",
      "auth": {
        "type": "bearer",
        "token": "${COMPANY_PLUGIN_TOKEN}"
      }
    }
  ]
}

Marketplace Catalog Format

{
  "plugins": [
    {
      "name": "company-plugin",
      "version": "1.0.0",
      "description": "Internal plugin",
      "downloadUrl": "https://plugins.company.com/company-plugin-1.0.0.zip",
      "checksum": "sha256:abc123..."
    }
  ]
}

Install from Marketplace

claude plugin install company-internal:company-plugin

Example Plugin: Code Quality

Structure

code-quality-plugin/
├── plugin.json
├── commands/
│   ├── lint.md
│   └── format.md
├── skills/
│   └── code-review/
│       └── SKILL.md
└── hooks/
    ├── hooks.json
    └── scripts/
        └── auto-lint.sh

plugin.json

{
  "name": "code-quality",
  "version": "1.0.0",
  "description": "Code quality tools and automation",
  "commands": ["commands/*.md"],
  "skills": ["skills/*/"],
  "hooks": "hooks/hooks.json"
}

commands/lint.md

# Lint

Run linter on {{files}} and fix all issues automatically.

hooks/hooks.json

{
  "hooks": {
    "post-tool": {
      "write": "./scripts/auto-lint.sh"
    }
  }
}

Security Considerations

Hook Security

• Validate all inputs
• Use whitelists for allowed commands
• Implement timeouts
• Log all executions
• Review hook scripts regularly

Plugin Security

• Verify plugin sources
• Review code before installation
• Use signed packages when available
• Monitor plugin behavior
• Keep plugins updated

Best Practices

• Install plugins from trusted sources only
• Review plugin permissions
• Use plugin sandboxing when available
• Monitor resource usage
• Regular security audits

Troubleshooting

Hooks Not Running

• Check hooks.json syntax
• Verify script permissions (chmod +x)
• Check script paths
• Review logs in .claude/logs/

Plugin Installation Failures

• Verify internet connectivity
• Check plugin URL/path
• Review error messages
• Clear cache: claude plugin cache clear

Plugin Conflicts

• Check for conflicting commands
• Review plugin load order
• Disable conflicting plugins
• Update plugins to compatible versions

See Also

• Creating slash commands: references/slash-commands.md
• Agent skills: references/agent-skills.md
• Configuration: references/configuration.md
• Best practices: references/best-practices.md

IDE Integration

Use Claude Code with Visual Studio Code and JetBrains IDEs.

Visual Studio Code

Installation

1. Open VS Code 2. Go to Extensions (Ctrl+Shift+X) 3. Search for "Claude Code" 4. Click Install 5. Authenticate with API key

Features

Inline Chat

• Press Ctrl+I (Cmd+I on Mac)
• Ask questions about code
• Get suggestions in context
• Apply changes directly

Code Actions

• Right-click on code
• Select "Ask Claude"
• Get refactoring suggestions
• Fix bugs and issues

Diff View

• See proposed changes
• Accept/reject modifications
• Review before applying
• Staged diff comparison

Terminal Integration

• Built-in Claude terminal
• Run commands via Claude
• Execute tools directly
• View real-time output

Configuration

.vscode/settings.json:

{
  "claude.apiKey": "${ANTHROPIC_API_KEY}",
  "claude.model": "claude-sonnet-4-5-20250929",
  "claude.maxTokens": 8192,
  "claude.autoSave": true,
  "claude.inlineChat.enabled": true,
  "claude.terminalIntegration": true
}

Keyboard Shortcuts

Default shortcuts:

• Ctrl+I: Inline chat
• Ctrl+Shift+C: Open Claude panel
• Ctrl+Shift+Enter: Submit to Claude
• Escape: Close Claude chat

Custom shortcuts (.vscode/keybindings.json):

[
  {
    "key": "ctrl+alt+c",
    "command": "claude.openChat"
  },
  {
    "key": "ctrl+alt+r",
    "command": "claude.refactor"
  }
]

Workspace Integration

Project-specific Claude settings:

.vscode/claude.json:

{
  "skills": [".claude/skills/project-skill"],
  "commands": [".claude/commands"],
  "mcpServers": ".claude/mcp.json",
  "outputStyle": "technical-writer"
}

Common Workflows

Explain Code: 1. Select code 2. Right-click → "Ask Claude" 3. Type: "Explain this code"

Refactor: 1. Select function 2. Press Ctrl+I 3. Type: "Refactor for better performance"

Fix Bug: 1. Click on error 2. Press Ctrl+I 3. Type: "Fix this error"

Generate Tests: 1. Select function 2. Right-click → "Ask Claude" 3. Type: "Write tests for this"

JetBrains IDEs

Supported IDEs:

• IntelliJ IDEA
• PyCharm
• WebStorm
• PhpStorm
• GoLand
• RubyMine
• CLion
• Rider

Installation

1. Open Settings (Ctrl+Alt+S) 2. Go to Plugins 3. Search "Claude Code" 4. Click Install 5. Restart IDE 6. Authenticate with API key

Features

AI Assistant Panel

• Dedicated Claude panel
• Context-aware suggestions
• Multi-file awareness
• Project understanding

Inline Suggestions

• As-you-type completions
• Contextual code generation
• Smart refactoring hints
• Error fix suggestions

Code Reviews

• Automated code reviews
• Security vulnerability detection
• Best practice recommendations
• Performance optimization tips

Refactoring Support

• Smart rename
• Extract method
• Inline variable
• Move class

Configuration

Settings → Tools → Claude Code:

API Key: [Your API Key]
Model: claude-sonnet-4-5-20250929
Max Tokens: 8192
Auto-complete: Enabled
Code Review: Enabled

Project Settings (.idea/claude.xml):

<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
  <component name="ClaudeSettings">
    <option name="model" value="claude-sonnet-4-5-20250929" />
    <option name="skillsPath" value=".claude/skills" />
    <option name="autoReview" value="true" />
  </component>
</project>

Keyboard Shortcuts

Default shortcuts:

• Ctrl+Shift+A: Ask Claude
• Alt+Enter: Quick fixes with Claude
• Ctrl+Alt+L: Format with Claude suggestions

Custom shortcuts (Settings → Keymap → Claude Code):

Ask Claude: Ctrl+Shift+C
Refactor with Claude: Ctrl+Alt+R
Generate Tests: Ctrl+Alt+T
Code Review: Ctrl+Alt+V

Integration with IDE Features

Version Control:

• Review commit diffs with Claude
• Generate commit messages
• Suggest PR improvements
• Analyze merge conflicts

Debugger:

• Explain stack traces
• Suggest fixes for errors
• Debug complex issues
• Analyze variable states

Database Tools:

• Generate SQL queries
• Optimize database schema
• Write migration scripts
• Explain query plans

Common Workflows

Generate Boilerplate: 1. Right-click in editor 2. Select "Generate" → "Claude Code" 3. Choose template type

Review Changes: 1. Open Version Control panel 2. Right-click on changeset 3. Select "Review with Claude"

Debug Error: 1. Hit breakpoint 2. Right-click in debugger 3. Select "Ask Claude about this"

CLI Integration

Use Claude Code from IDE terminal:

# In VS Code terminal
claude "explain this project structure"

# In JetBrains terminal
claude "add error handling to current file"

Best Practices

VS Code

Workspace Organization:

• Use workspace settings for team consistency
• Share .vscode/claude.json in version control
• Document custom shortcuts
• Configure output styles per project

Performance:

• Limit inline suggestions in large files
• Disable auto-save for better control
• Use specific prompts
• Close unused editor tabs

JetBrains

Project Configuration:

• Enable Claude for specific file types only
• Configure inspection severity
• Set up custom code review templates
• Use project-specific skills

Performance:

• Adjust auto-complete delay
• Limit scope of code analysis
• Disable for binary files
• Configure memory settings

Troubleshooting

VS Code

Extension Not Loading:

# Check extension status
code --list-extensions | grep claude

# Reinstall
code --uninstall-extension anthropic.claude-code
code --install-extension anthropic.claude-code

Authentication Issues:

• Verify API key in settings
• Check environment variable
• Re-authenticate in extension
• Review proxy settings

JetBrains

Plugin Not Responding:

File → Invalidate Caches / Restart
Settings → Plugins → Claude Code → Reinstall

Performance Issues:

• Increase IDE memory (Help → Edit Custom VM Options)
• Disable unused features
• Clear caches
• Update plugin version

See Also

• VS Code extension: https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code
• JetBrains plugin: https://plugins.jetbrains.com/plugin/claude-code
• Configuration: references/configuration.md
• Troubleshooting: references/troubleshooting.md

MCP Integration

Model Context Protocol (MCP) integration for connecting Claude Code to external tools and services.

What is MCP?

Model Context Protocol enables Claude Code to:

• Connect to external tools and services
• Access resources (files, databases, APIs)
• Use custom tools
• Provide prompts and completions

Configuration

MCP servers are configured in .claude/mcp.json:

Basic Configuration

{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "VAR_NAME": "value"
      }
    }
  }
}

Example Configuration

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/db"
      }
    }
  }
}

Common MCP Servers

Filesystem Access

{
  "filesystem": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-filesystem",
      "/path/to/allowed/files"
    ]
  }
}

Capabilities:

• Read/write files
• List directories
• File search
• Path restrictions for security

GitHub Integration

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}

Capabilities:

• Repository access
• Issues and PRs
• Code search
• Workflow management

PostgreSQL Database

{
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": {
      "DATABASE_URL": "${DATABASE_URL}"
    }
  }
}

Capabilities:

• Query execution
• Schema inspection
• Transaction management
• Connection pooling

Brave Search

{
  "brave-search": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "BRAVE_API_KEY": "${BRAVE_API_KEY}"
    }
  }
}

Capabilities:

• Web search
• News search
• Local search
• Result filtering

Puppeteer (Browser Automation)

{
  "puppeteer": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
  }
}

Capabilities:

• Browser automation
• Screenshots
• PDF generation
• Web scraping

Remote MCP Servers

Connect to MCP servers over HTTP/SSE:

Basic Remote Server

{
  "mcpServers": {
    "remote-service": {
      "url": "https://api.example.com/mcp"
    }
  }
}

With Authentication

{
  "mcpServers": {
    "remote-service": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}",
        "X-Custom-Header": "value"
      }
    }
  }
}

With Proxy

{
  "mcpServers": {
    "remote-service": {
      "url": "https://api.example.com/mcp",
      "proxy": "http://proxy.company.com:8080"
    }
  }
}

Environment Variables

Use environment variables for sensitive data:

.env File

# .claude/.env
GITHUB_TOKEN=ghp_xxxxx
DATABASE_URL=postgresql://user:pass@localhost/db
BRAVE_API_KEY=BSAxxxxx
API_TOKEN=token_xxxxx

Reference in mcp.json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Testing MCP Servers

Inspector Tool

npx @modelcontextprotocol/inspector

Opens web UI for testing MCP servers:

• List available tools
• Test tool invocations
• View resources
• Debug connections

Manual Testing

# Test server command
npx -y @modelcontextprotocol/server-filesystem /tmp

# Check server output
echo '{"jsonrpc":"2.0","method":"initialize","params":{}}' | \
  npx -y @modelcontextprotocol/server-filesystem /tmp

Creating Custom MCP Servers

Python Server

from mcp.server import Server
from mcp.server.stdio import stdio_server

server = Server("my-server")

@server.tool()
async def my_tool(arg: str) -> str:
    """Tool description"""
    return f"Result: {arg}"

if __name__ == "__main__":
    stdio_server(server)

Configuration

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["path/to/server.py"]
    }
  }
}

Node.js Server

import { Server } from "@modelcontextprotocol/server-node";

const server = new Server("my-server");

server.tool({
  name: "my-tool",
  description: "Tool description",
  parameters: { arg: "string" }
}, async ({ arg }) => {
  return `Result: ${arg}`;
});

server.listen();

Security Considerations

Filesystem Access

• Restrict to specific directories
• Use read-only access when possible
• Validate file paths
• Monitor access logs

API Credentials

• Use environment variables
• Never commit credentials
• Rotate keys regularly
• Implement least-privilege access

Network Access

• Whitelist allowed domains
• Use HTTPS only
• Implement timeouts
• Rate limit requests

Remote Servers

• Validate server certificates
• Use authentication
• Implement request signing
• Monitor for anomalies

Troubleshooting

Server Not Starting

# Check server command
npx -y @modelcontextprotocol/server-filesystem /tmp

# Verify environment variables
echo $GITHUB_TOKEN

# Check logs
cat ~/.claude/logs/mcp-*.log

Connection Errors

# Test network connectivity
curl https://api.example.com/mcp

# Verify proxy settings
echo $HTTP_PROXY

# Check firewall rules

Permission Errors

# Verify file permissions
ls -la /path/to/allowed/files

# Check user permissions
whoami
groups

Tool Not Found

• Verify server is running
• Check server configuration
• Inspect server capabilities
• Review tool registration

Best Practices

Configuration Management

• Use environment variables for secrets
• Document server purposes
• Version control mcp.json (without secrets)
• Test configurations thoroughly

Performance

• Use local servers when possible
• Implement caching
• Set appropriate timeouts
• Monitor resource usage

Maintenance

• Update servers regularly
• Monitor server health
• Review access logs
• Clean up unused servers

See Also

• MCP specification: https://modelcontextprotocol.io
• Creating MCP servers: references/api-reference.md
• Security best practices: references/best-practices.md
• Troubleshooting: references/troubleshooting.md

Slash Commands Reference

Comprehensive catalog of Claude Code slash commands for development workflows.

What Are Slash Commands?

Slash commands are user-defined operations that:

• Start with / (e.g., /cook, /test)
• Expand to full prompts when executed
• Accept arguments
• Located in .claude/commands/
• Can be project-specific or global

Development Commands

/cook [task]

Implement features step by step.

/cook implement user authentication with JWT
/cook add payment integration with Stripe

When to use: Feature implementation with iterative development

/plan [task]

Research, analyze, and create implementation plans.

/plan implement OAuth2 authentication
/plan migrate from SQLite to PostgreSQL

When to use: Before starting complex implementations

/debug [issue]

Debug technical issues and provide solutions.

/debug the API returns 500 errors intermittently
/debug authentication flow not working

When to use: Investigating and diagnosing problems

/test

Run test suite.

/test

When to use: Validate implementations, check for regressions

/refactor [target]

Improve code quality.

/refactor the authentication module
/refactor for better performance

When to use: Code quality improvements

Fix Commands

/fix:fast [issue]

Quick fixes for small issues.

/fix:fast the login button is not working
/fix:fast typo in error message

When to use: Simple, straightforward fixes

/fix:hard [issue]

Complex issues requiring planning and subagents.

/fix:hard database connection pooling issues
/fix:hard race condition in payment processing

When to use: Complex bugs requiring deep investigation

/fix:types

Fix TypeScript type errors.

/fix:types

When to use: TypeScript compilation errors

/fix:test [issue]

Fix test failures.

/fix:test the user service tests are failing
/fix:test integration tests timing out

When to use: Test suite failures

/fix:ui [issue]

Fix UI issues.

/fix:ui button alignment on mobile
/fix:ui dark mode colors inconsistent

When to use: Visual or interaction issues

/fix:ci [url]

Analyze GitHub Actions logs and fix CI/CD issues.

/fix:ci https://github.com/owner/repo/actions/runs/123456

When to use: Build or deployment failures

/fix:logs [issue]

Analyze logs and fix issues.

/fix:logs server error logs showing memory leaks

When to use: Production issues with log evidence

Documentation Commands

/docs:init

Create initial documentation structure.

/docs:init

When to use: New projects needing documentation

/docs:update

Update existing documentation based on code changes.

/docs:update

When to use: After significant code changes

/docs:summarize

Summarize codebase and create overview.

/docs:summarize

When to use: Generate project summaries

Git Commands

/git:cm

Stage all files and create commit.

/git:cm

When to use: Commit changes with automatic message

/git:cp

Stage, commit, and push all code in current branch.

/git:cp

When to use: Commit and push in one command

/git:pr [branch] [from-branch]

Create pull request.

/git:pr feature-branch main
/git:pr bugfix-auth develop

When to use: Creating PRs with automatic descriptions

Planning Commands

/plan:two [task]

Create implementation plan with 2 alternative approaches.

/plan:two implement caching layer

When to use: Need to evaluate multiple approaches

/plan:ci [url]

Analyze GitHub Actions logs and create fix plan.

/plan:ci https://github.com/owner/repo/actions/runs/123456

When to use: CI/CD failure analysis

/plan:cro [issue]

Create conversion rate optimization plan.

/plan:cro landing page conversion improvement

When to use: Marketing/conversion optimization

Content Commands

/content:fast [request]

Quick copy writing.

/content:fast write product description for new feature

When to use: Fast content generation

/content:good [request]

High-quality, conversion-focused copy.

/content:good write landing page hero section

When to use: Marketing copy requiring polish

/content:enhance [issue]

Enhance existing content.

/content:enhance improve clarity of pricing page

When to use: Improving existing copy

/content:cro [issue]

Conversion rate optimization for content.

/content:cro optimize email campaign copy

When to use: Conversion-focused content improvements

Design Commands

/design:fast [task]

Quick design implementation.

/design:fast create dashboard layout

When to use: Rapid prototyping

/design:good [task]

High-quality, polished design.

/design:good create landing page for SaaS product

When to use: Production-ready designs

/design:3d [task]

Create 3D designs with Three.js.

/design:3d create interactive 3D product viewer

When to use: 3D visualization needs

/design:screenshot [path]

Create design based on screenshot.

/design:screenshot screenshot.png

When to use: Recreating designs from images

/design:video [path]

Create design based on video.

/design:video demo-video.mp4

When to use: Implementing designs from video demos

Deployment Commands

/deploy

Deploy using deployment tool.

/deploy

When to use: Production deployments

/deploy-check

Check deployment readiness.

/deploy-check

When to use: Pre-deployment validation

Integration Commands

/integrate:polar [tasks]

Implement payment integration with Polar.sh.

/integrate:polar add subscription payments

When to use: Polar payment integration

/integrate:sepay [tasks]

Implement payment integration with SePay.vn.

/integrate:sepay add Vietnamese payment gateway

When to use: SePay payment integration

Other Commands

/brainstorm [question]

Brainstorm features and ideas.

/brainstorm how to improve user onboarding

When to use: Ideation and exploration

/ask [question]

Answer technical and architectural questions.

/ask what's the best way to handle websocket connections

When to use: Technical guidance

/scout [prompt] [scale]

Scout directories to respond to requests.

/scout find authentication code

When to use: Code exploration

/watzup

Review recent changes and wrap up work.

/watzup

When to use: End of session summary

/bootstrap [requirements]

Bootstrap new project step by step.

/bootstrap create React app with TypeScript and Tailwind

When to use: New project setup

/bootstrap:auto [requirements]

Bootstrap new project automatically.

/bootstrap:auto create Next.js app

When to use: Automated project setup

/journal

Write journal entries for development log.

/journal

When to use: Development documentation

/review:codebase [prompt]

Scan and analyze codebase.

/review:codebase analyze architecture patterns

When to use: Codebase analysis

/skill:create [prompt]

Create new agent skill.

/skill:create create skill for API testing

When to use: Extending Claude with custom skills

Creating Custom Slash Commands

Command File Structure

.claude/commands/
└── my-command.md

Example Command File

# File: .claude/commands/my-command.md

Create comprehensive test suite for {{feature}}.

Include:
- Unit tests
- Integration tests
- Edge cases
- Mocking examples

Usage

/my-command authentication
# Expands to: "Create comprehensive test suite for authentication..."

Best Practices

Clear prompts: Write specific, actionable prompts Use variables: {{variable}} for dynamic content Document usage: Add comments explaining the command Test thoroughly: Verify commands work as expected

Command Arguments

Single Argument

/cook implement user auth
# Argument: "implement user auth"

Multiple Arguments

/git:pr feature-branch main
# Arguments: "feature-branch", "main"

Optional Arguments

Some commands work with or without arguments:

/test              # Run all tests
/test user.test.js # Run specific test

See Also

• Creating custom commands: references/hooks-and-plugins.md
• Command automation: references/configuration.md
• Best practices: references/best-practices.md

Troubleshooting

Common issues, debugging, and solutions for Claude Code.

Authentication Issues

API Key Not Recognized

Symptoms:

• "Invalid API key" errors
• Authentication failures
• 401 Unauthorized responses

Solutions:

# Verify API key is set
echo $ANTHROPIC_API_KEY

# Re-login
claude logout
claude login

# Check API key format (should start with sk-ant-)
echo $ANTHROPIC_API_KEY | grep "^sk-ant-"

# Test API key directly
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-5-20250929","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

Environment Variable Issues

# Add to shell profile
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxxx' >> ~/.bashrc
source ~/.bashrc

# Or use .env file
echo 'ANTHROPIC_API_KEY=sk-ant-xxxxx' > .claude/.env

# Verify it's loaded
claude config get apiKey

Installation Problems

npm Installation Failures

# Clear npm cache
npm cache clean --force

# Remove and reinstall
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

# Use specific version
npm install -g @anthropic-ai/claude-code@1.0.0

# Check installation
which claude
claude --version

Permission Errors

# Fix permissions on Unix/Mac
sudo chown -R $USER ~/.claude
chmod -R 755 ~/.claude

# Or install without sudo (using nvm)
nvm install 18
npm install -g @anthropic-ai/claude-code

Python Installation Issues

# Upgrade pip
pip install --upgrade pip

# Install in virtual environment
python -m venv claude-env
source claude-env/bin/activate
pip install claude-code

# Install with --user flag
pip install --user claude-code

Connection & Network Issues

Proxy Configuration

# Set proxy environment variables
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1

# Configure in settings
claude config set proxy http://proxy.company.com:8080

# Test connection
curl -x $HTTP_PROXY https://api.anthropic.com

SSL/TLS Errors

# Trust custom CA certificate
export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.crt

# Disable SSL verification (not recommended for production)
export NODE_TLS_REJECT_UNAUTHORIZED=0

# Update ca-certificates
sudo update-ca-certificates  # Debian/Ubuntu
sudo update-ca-trust         # RHEL/CentOS

Firewall Issues

# Check connectivity to Anthropic API
ping api.anthropic.com
telnet api.anthropic.com 443

# Test HTTPS connection
curl -v https://api.anthropic.com

# Check firewall rules
sudo iptables -L  # Linux
netsh advfirewall show allprofiles  # Windows

MCP Server Problems

Server Not Starting

# Test MCP server command manually
npx -y @modelcontextprotocol/server-filesystem /tmp

# Check server logs
cat ~/.claude/logs/mcp-*.log

# Verify environment variables
echo $GITHUB_TOKEN  # For GitHub MCP

# Test with MCP Inspector
npx @modelcontextprotocol/inspector

Connection Timeouts

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-example"],
      "timeout": 30000,
      "retries": 3
    }
  }
}

Permission Denied

# Check file permissions
ls -la /path/to/mcp/server

# Make executable
chmod +x /path/to/mcp/server

# Check directory access
ls -ld /path/to/allowed/directory

Performance Issues

Slow Responses

Check network latency:

ping api.anthropic.com

Use faster model:

claude --model haiku "simple task"

Reduce context:

{
  "maxTokens": 4096,
  "context": {
    "autoTruncate": true
  }
}

Enable caching:

{
  "caching": {
    "enabled": true
  }
}

High Memory Usage

# Clear cache
rm -rf ~/.claude/cache/*

# Limit context window
claude config set maxTokens 8192

# Disable memory
claude config set memory.enabled false

# Close unused sessions
claude session list
claude session close session-123

Rate Limiting

# Check rate limits
claude usage show

# Wait and retry
sleep 60
claude "retry task"

# Implement exponential backoff in scripts

Tool Execution Errors

Bash Command Failures

Check sandboxing settings:

{
  "sandboxing": {
    "enabled": true,
    "allowedPaths": ["/workspace", "/tmp"]
  }
}

Verify command permissions:

# Make script executable
chmod +x script.sh

# Check PATH
echo $PATH
which command-name

File Access Denied

# Check file permissions
ls -la file.txt

# Change ownership
sudo chown $USER file.txt

# Grant read/write permissions
chmod 644 file.txt

Write Tool Failures

# Check disk space
df -h

# Verify directory exists
mkdir -p /path/to/directory

# Check write permissions
touch /path/to/directory/test.txt
rm /path/to/directory/test.txt

Hook Errors

Hooks Not Running

# Verify hooks.json syntax
cat .claude/hooks.json | jq .

# Check hook script permissions
chmod +x .claude/scripts/hook.sh

# Test hook script manually
.claude/scripts/hook.sh

# Check logs
cat ~/.claude/logs/hooks.log

Hook Script Errors

# Add error handling to hooks
#!/bin/bash
set -e  # Exit on error
set -u  # Exit on undefined variable

# Debug hook execution
#!/bin/bash
set -x  # Print commands
echo "Hook running: $TOOL_NAME"

Debug Mode

Enable Debugging

# Set debug environment variable
export CLAUDE_DEBUG=1
export CLAUDE_LOG_LEVEL=debug

# Run with debug flag
claude --debug "task"

# View debug logs
tail -f ~/.claude/logs/debug.log

Verbose Output

# Enable verbose mode
claude --verbose "task"

# Show all tool calls
claude --show-tools "task"

# Display thinking process
claude --show-thinking "task"

Common Error Messages

"Model not found"

# Use correct model name
claude --model claude-sonnet-4-5-20250929

# Update claude-code
npm update -g @anthropic-ai/claude-code

"Rate limit exceeded"

# Wait and retry
sleep 60

# Check usage
claude usage show

# Implement rate limiting in code

"Context length exceeded"

# Reduce context
claude config set maxTokens 100000

# Summarize long content
claude "summarize this codebase"

# Process in chunks
claude "analyze first half of files"

"Timeout waiting for response"

# Increase timeout
claude config set timeout 300

# Check network connection
ping api.anthropic.com

# Retry with smaller request

Getting Help

Collect Diagnostic Info

# System info
claude --version
node --version
npm --version

# Configuration
claude config list --all

# Recent logs
tail -n 100 ~/.claude/logs/session.log

# Environment
env | grep CLAUDE
env | grep ANTHROPIC

Report Issues

1. Check existing issues: https://github.com/anthropics/claude-code/issues 2. Gather diagnostic info 3. Create minimal reproduction 4. Submit issue with:

• Claude Code version
• Operating system
• Error messages
• Steps to reproduce

Support Channels

• Documentation: https://docs.claude.com/claude-code
• GitHub Issues: https://github.com/anthropics/claude-code/issues
• Support Portal: support.claude.com
• Community Discord: discord.gg/anthropic

See Also

• Installation guide: references/getting-started.md
• Configuration: references/configuration.md
• MCP setup: references/mcp-integration.md
• Best practices: references/best-practices.md