Working With Claude Code

Working with Claude Code

Overview

This skill provides complete, authoritative documentation for Claude Code directly from docs.claude.com. Instead of guessing about configuration paths, API structures, or feature capabilities, read the official docs stored in this skill's references directory.

When to Use

Use this skill when:

• Creating or configuring Claude Code plugins
• Setting up MCP servers
• Working with hooks (pre-commit, session-start, etc.)
• Writing or testing skills
• Configuring Claude Code settings
• Troubleshooting Claude Code issues
• Understanding CLI commands
• Setting up integrations (VS Code, JetBrains, etc.)
• Configuring networking, security, or enterprise features

Quick Reference

Documentation Organization

All documentation is stored as individual markdown files in references/. Use the Read tool to access specific documentation:

references/
├── overview.md              # Claude Code introduction
├── quickstart.md           # Getting started guide
├── setup.md                # Installation and setup
├── plugins.md              # Plugin development
├── plugins-reference.md    # Plugin API reference
├── plugin-marketplaces.md  # Plugin marketplaces
├── skills.md               # Skill creation
├── mcp.md                  # MCP server integration
├── hooks.md                # Hooks overview
├── hooks-guide.md          # Hooks implementation guide
├── slash-commands.md       # Slash command reference
├── sub-agents.md           # Subagent usage
├── settings.md             # Configuration reference
├── cli-reference.md        # CLI command reference
├── common-workflows.md     # Common usage patterns
├── interactive-mode.md     # Interactive mode guide
├── headless.md             # Headless mode guide
├── output-styles.md        # Output customization
├── statusline.md           # Status line configuration
├── memory.md               # Memory and context management
├── checkpointing.md        # Checkpointing feature
├── analytics.md            # Usage analytics
├── costs.md                # Cost tracking
├── monitoring-usage.md     # Usage monitoring
├── data-usage.md           # Data usage policies
├── security.md             # Security features
├── iam.md                  # IAM integration
├── network-config.md       # Network configuration
├── terminal-config.md      # Terminal configuration
├── model-config.md         # Model configuration
├── llm-gateway.md          # LLM gateway setup
├── amazon-bedrock.md       # AWS Bedrock integration
├── google-vertex-ai.md     # Google Vertex AI integration
├── vs-code.md              # VS Code integration
├── jetbrains.md            # JetBrains integration
├── devcontainer.md         # Dev container support
├── github-actions.md       # GitHub Actions integration
├── gitlab-ci-cd.md         # GitLab CI/CD integration
├── third-party-integrations.md  # Other integrations
├── legal-and-compliance.md # Legal information
├── troubleshooting.md      # Troubleshooting guide
└── migration-guide.md      # Migration guide

Workflow

For Specific Questions

1. Identify the relevant documentation file from the list above 2. Use Read tool to load: @references/filename.md 3. Find the answer in the official documentation 4. Apply the solution

Example:

User: "How do I create a Claude Code plugin?"
→ Read @references/plugins.md
→ Follow the official plugin creation steps

For Broad Topics

When exploring a topic, start with the overview document, then drill into specific files:

• Extending Claude Code: Start with plugins.md, skills.md, or mcp.md
• Configuration: Start with settings.md or setup.md
• Integrations: Check relevant integration file (vs-code.md, github-actions.md, etc.)
• Troubleshooting: Start with troubleshooting.md

For Uncertain Topics

Use Grep tool to search across all documentation:

pattern: "search term"
path: ~/.claude/skills/working-with-claude-code/references/

Updating Documentation

The skill includes scripts/update_docs.js to fetch the latest documentation from docs.claude.com.

Run when:

• Documentation seems outdated
• New Claude Code features are released
• Official docs have been updated

node ~/.claude/skills/working-with-claude-code/scripts/update_docs.js

The script: 1. Fetches llms.txt from docs.claude.com 2. Extracts all Claude Code documentation URLs 3. Downloads each page to references/ 4. Reports success/failures

Common Patterns

Plugin Development

Read plugins.md for overview, then plugins-reference.md for API details.

MCP Server Setup

Read mcp.md for configuration format and examples.

Hook Configuration

Read hooks.md for overview, then hooks-guide.md for implementation details.

Skill Creation

Read skills.md for the complete skill authoring guide.

What This Skill Does NOT Do

• This skill provides documentation access, not procedural guidance
• For workflows on how to build plugins/skills, use the extending-claude-code skill (when available)
• This skill is a reference library, not a tutorial

Red Flags

If you find yourself:

• Guessing about configuration file locations → Read settings.md
• Speculating about API structures → Read relevant reference doc
• Unsure about hook names → Read hooks.md
• Making assumptions about features → Search the docs first

Always consult the official documentation before guessing.

Claude Code on Amazon Bedrock

Learn about configuring Claude Code through Amazon Bedrock, including setup, IAM configuration, and troubleshooting.

Prerequisites

Before configuring Claude Code with Bedrock, ensure you have:

• An AWS account with Bedrock access enabled
• Access to desired Claude models (e.g., Claude Sonnet 4.5) in Bedrock
• AWS CLI installed and configured (optional - only needed if you don't have another mechanism for getting credentials)
• Appropriate IAM permissions

Setup

1. Enable model access

First, ensure you have access to the required Claude models in your AWS account:

1. Navigate to the Amazon Bedrock console 2. Go to Model access in the left navigation 3. Request access to desired Claude models (e.g., Claude Sonnet 4.5) 4. Wait for approval (usually instant for most regions)

2. Configure AWS credentials

Claude Code uses the default AWS SDK credential chain. Set up your credentials using one of these methods:

Option A: AWS CLI configuration

```bash theme={null} aws configure

**Option B: Environment variables (access key)**

export AWS_ACCESS_KEY_ID=your-access-key-id export AWS_SECRET_ACCESS_KEY=your-secret-access-key export AWS_SESSION_TOKEN=your-session-token

**Option C: Environment variables (SSO profile)**

aws sso login --profile=<your-profile-name>

export AWS_PROFILE=your-profile-name

**Option D: Bedrock API keys**

export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

Bedrock API keys provide a simpler authentication method without needing full AWS credentials. [Learn more about Bedrock API keys](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/).

#### Advanced credential configuration

Claude Code supports automatic credential refresh for AWS SSO and corporate identity providers. Add these settings to your Claude Code settings file (see [Settings](/en/docs/claude-code/settings) for file locations).

When Claude Code detects that your AWS credentials are expired (either locally based on their timestamp or when Bedrock returns a credential error), it will automatically run your configured `awsAuthRefresh` and/or `awsCredentialExport` commands to obtain new credentials before retrying the request.

##### Example configuration

{ "awsAuthRefresh": "aws sso login --profile myprofile", "env": { "AWS_PROFILE": "myprofile" } }

##### Configuration settings explained

**`awsAuthRefresh`**: Use this for commands that modify the `.aws` directory (e.g., updating credentials, SSO cache, or config files). Output is shown to the user (but user input is not supported), making it suitable for browser-based authentication flows where the CLI displays a code to enter in the browser.

**`awsCredentialExport`**: Only use this if you cannot modify `.aws` and must directly return credentials. Output is captured silently (not shown to the user). The command must output JSON in this format:

{ "Credentials": { "AccessKeyId": "value", "SecretAccessKey": "value", "SessionToken": "value" } }

### 3. Configure Claude Code

Set the following environment variables to enable Bedrock:

Enable Bedrock integration

export CLAUDE_CODE_USE_BEDROCK=1 export AWS_REGION=us-east-1 # or your preferred region

Optional: Override the region for the small/fast model (Haiku)

export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2

When enabling Bedrock for Claude Code, keep the following in mind:

* `AWS_REGION` is a required environment variable. Claude Code does not read from the `.aws` config file for this setting.
* When using Bedrock, the `/login` and `/logout` commands are disabled since authentication is handled through AWS credentials.
* You can use settings files for environment variables like `AWS_PROFILE` that you don't want to leak to other processes. See [Settings](/en/docs/claude-code/settings) for more information.

### 4. Model configuration

Claude Code uses these default models for Bedrock:

| Model type       | Default value                                      |
| :--------------- | :------------------------------------------------- |
| Primary model    | `global.anthropic.claude-sonnet-4-5-20250929-v1:0` |
| Small/fast model | `us.anthropic.claude-haiku-4-5-20251001-v1:0`      |

<Note>
  For Bedrock users, Claude Code will not automatically upgrade from Haiku 3.5 to Haiku 4.5. To manually switch to a newer Haiku model, set the `ANTHROPIC_DEFAULT_HAIKU_MODEL` environment variable to the full model name (e.g., `us.anthropic.claude-haiku-4-5-20251001-v1:0`).
</Note>

To customize models, use one of these methods:

Using inference profile ID

export ANTHROPIC_MODEL='global.anthropic.claude-sonnet-4-5-20250929-v1:0' export ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

Using application inference profile ARN

export ANTHROPIC_MODEL='arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-model-id'

Optional: Disable prompt caching if needed

export DISABLE_PROMPT_CACHING=1

<Note>
  [Prompt caching](/en/docs/build-with-claude/prompt-caching) may not be available in all regions
</Note>

### 5. Output token configuration

When using Claude Code with Amazon Bedrock, we recommend the following token settings:

Recommended output token settings for Bedrock

export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096 export MAX_THINKING_TOKENS=1024

**Why these values:**

* **`CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096`**: Bedrock's burndown throttling logic sets a minimum of 4096 tokens as the max\_token penalty. Setting this lower won't reduce costs but may cut off long tool uses, causing the Claude Code agent loop to fail persistently. Claude Code typically uses less than 4096 output tokens without extended thinking, but may need this headroom for tasks involving significant file creation or Write tool usage.

* **`MAX_THINKING_TOKENS=1024`**: This provides space for extended thinking without cutting off tool use responses, while still maintaining focused reasoning chains. This balance helps prevent trajectory changes that aren't always helpful for coding tasks specifically.

## IAM configuration

Create an IAM policy with the required permissions for Claude Code:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream", "bedrock:ListInferenceProfiles" ], "Resource": [ "arn:aws:bedrock:::inference-profile/", "arn:aws:bedrock:::application-inference-profile/" ] } ] }

For more restrictive permissions, you can limit the Resource to specific inference profile ARNs.

For details, see [Bedrock IAM documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/security-iam.html).

<Note>
  We recommend creating a dedicated AWS account for Claude Code to simplify cost tracking and access control.
</Note>

## Troubleshooting

If you encounter region issues:

* Check model availability: `aws bedrock list-inference-profiles --region your-region`
* Switch to a supported region: `export AWS_REGION=us-east-1`
* Consider using inference profiles for cross-region access

If you receive an error "on-demand throughput isn’t supported":

* Specify the model as an [inference profile](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html) ID

Claude Code uses the Bedrock [Invoke API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html) and does not support the Converse API.

## Additional resources

* [Bedrock documentation](https://docs.aws.amazon.com/bedrock/)
* [Bedrock pricing](https://aws.amazon.com/bedrock/pricing/)
* [Bedrock inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html)
* [Claude Code on Amazon Bedrock: Quick Setup Guide](https://community.aws/content/2tXkZKrZzlrlu0KfH8gST5Dkppq/claude-code-on-amazon-bedrock-quick-setup-guide)- [Claude Code Monitoring Implementation (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)

Analytics

View detailed usage insights and productivity metrics for your organization's Claude Code deployment.

Claude Code provides an analytics dashboard that helps organizations understand developer usage patterns, track productivity metrics, and optimize their Claude Code adoption.

<Note> Analytics are currently available only for organizations using Claude Code with the Claude API through the Claude Console. </Note>

Access analytics

Navigate to the analytics dashboard at console.anthropic.com/claude-code.

Required roles

• Primary Owner
• Owner
• Billing
• Admin
• Developer

<Note> Users with User, Claude Code User or Membership Admin roles cannot access analytics. </Note>

Available metrics

Lines of code accepted

Total lines of code written by Claude Code that users have accepted in their sessions.

• Excludes rejected code suggestions
• Doesn't track subsequent deletions

Suggestion accept rate

Percentage of times users accept code editing tool usage, including:

• Edit
• Write
• NotebookEdit

Activity

users: Number of active users in a given day (number on left Y-axis)

sessions: Number of active sessions in a given day (number on right Y-axis)

Spend

users: Number of active users in a given day (number on left Y-axis)

spend: Total dollars spent in a given day (number on right Y-axis)

Team insights

Members: All users who have authenticated to Claude Code

• API key users are displayed by API key identifier
• OAuth users are displayed by email address

Spend this month: Per-user total spend for the current month.

Lines this month: Per-user total of accepted code lines for the current month.

Using analytics effectively

Monitor adoption

Track team member status to identify:

• Active users who can share best practices
• Overall adoption trends across your organization

Measure productivity

Tool acceptance rates and code metrics help you:

• Understand developer satisfaction with Claude Code suggestions
• Track code generation effectiveness
• Identify opportunities for training or process improvements

Related resources

• Monitoring usage with OpenTelemetry for custom metrics and alerting
• Identity and access management for role configuration

Checkpointing

Automatically track and rewind Claude's edits to quickly recover from unwanted changes.

Claude Code automatically tracks Claude's file edits as you work, allowing you to quickly undo changes and rewind to previous states if anything gets off track.

How checkpoints work

As you work with Claude, checkpointing automatically captures the state of your code before each edit. This safety net lets you pursue ambitious, wide-scale tasks knowing you can always return to a prior code state.

Automatic tracking

Claude Code tracks all changes made by its file editing tools:

• Every user prompt creates a new checkpoint
• Checkpoints persist across sessions, so you can access them in resumed conversations
• Automatically cleaned up along with sessions after 30 days (configurable)

Rewinding changes

Press Esc twice (Esc + Esc) or use the /rewind command to open up the rewind menu. You can choose to restore:

• Conversation only: Rewind to a user message while keeping code changes
• Code only: Revert file changes while keeping the conversation
• Both code and conversation: Restore both to a prior point in the session

Common use cases

Checkpoints are particularly useful when:

• Exploring alternatives: Try different implementation approaches without losing your starting point
• Recovering from mistakes: Quickly undo changes that introduced bugs or broke functionality
• Iterating on features: Experiment with variations knowing you can revert to working states

Limitations

Bash command changes not tracked

Checkpointing does not track files modified by bash commands. For example, if Claude Code runs:

```bash theme={null} rm file.txt mv old.txt new.txt cp source.txt dest.txt

These file modifications cannot be undone through rewind. Only direct file edits made through Claude's file editing tools are tracked.

### External changes not tracked

Checkpointing only tracks files that have been edited within the current session. Manual changes you make to files outside of Claude Code and edits from other concurrent sessions are normally not captured, unless they happen to modify the same files as the current session.

### Not a replacement for version control

Checkpoints are designed for quick, session-level recovery. For permanent version history and collaboration:

* Continue using version control (ex. Git) for commits, branches, and long-term history
* Checkpoints complement but don't replace proper version control
* Think of checkpoints as "local undo" and Git as "permanent history"

## See also

* [Interactive mode](/en/docs/claude-code/interactive-mode) - Keyboard shortcuts and session controls
* [Slash commands](/en/docs/claude-code/slash-commands) - Accessing checkpoints using `/rewind`
* [CLI reference](/en/docs/claude-code/cli-reference) - Command-line options

CLI reference

Complete reference for Claude Code command-line interface, including commands and flags.

CLI commands

CLI flags

Customize Claude Code's behavior with these command-line flags:

<Tip> The --output-format json flag is particularly useful for scripting and automation, allowing you to parse Claude's responses programmatically. </Tip>

Agents flag format

The --agents flag accepts a JSON object that defines one or more custom subagents. Each subagent requires a unique name (as the key) and a definition object with the following fields:

Example:

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

For more details on creating and using subagents, see the [subagents documentation](/en/docs/claude-code/sub-agents).

For detailed information about print mode (`-p`) including output formats,
streaming, verbose logging, and programmatic usage, see the
[SDK documentation](/en/docs/claude-code/sdk).

## See also

* [Interactive mode](/en/docs/claude-code/interactive-mode) - Shortcuts, input modes, and interactive features
* [Slash commands](/en/docs/claude-code/slash-commands) - Interactive session commands
* [Quickstart guide](/en/docs/claude-code/quickstart) - Getting started with Claude Code
* [Common workflows](/en/docs/claude-code/common-workflows) - Advanced workflows and patterns
* [Settings](/en/docs/claude-code/settings) - Configuration options
* [SDK documentation](/en/docs/claude-code/sdk) - Programmatic usage and integrations

Common workflows

Learn about common workflows with Claude Code.

Each task in this document includes clear instructions, example commands, and best practices to help you get the most from Claude Code.

Understand new codebases

Get a quick codebase overview

Suppose you've just joined a new project and need to understand its structure quickly.

<Steps> <Step title="Navigate to the project root directory"> ```bash theme={null} cd /path/to/project

  </Step>

  <Step title="Start Claude Code">

claude

  </Step>

  <Step title="Ask for a high-level overview">

give me an overview of this codebase

  </Step>

  <Step title="Dive deeper into specific components">

explain the main architecture patterns used here

what are the key data models?

how is authentication handled?

  </Step>
</Steps>

<Tip>
  Tips:

  * Start with broad questions, then narrow down to specific areas
  * Ask about coding conventions and patterns used in the project
  * Request a glossary of project-specific terms
</Tip>

### Find relevant code

Suppose you need to locate code related to a specific feature or functionality.

<Steps>
  <Step title="Ask Claude to find relevant files">

find the files that handle user authentication

  </Step>

  <Step title="Get context on how components interact">

how do these authentication files work together?

  </Step>

  <Step title="Understand the execution flow">

trace the login process from front-end to database

  </Step>
</Steps>

<Tip>
  Tips:

  * Be specific about what you're looking for
  * Use domain language from the project
</Tip>

***

## Fix bugs efficiently

Suppose you've encountered an error message and need to find and fix its source.

<Steps>
  <Step title="Share the error with Claude">

I'm seeing an error when I run npm test

  </Step>

  <Step title="Ask for fix recommendations">

suggest a few ways to fix the @ts-ignore in user.ts

  </Step>

  <Step title="Apply the fix">

update user.ts to add the null check you suggested

  </Step>
</Steps>

<Tip>
  Tips:

  * Tell Claude the command to reproduce the issue and get a stack trace
  * Mention any steps to reproduce the error
  * Let Claude know if the error is intermittent or consistent
</Tip>

***

## Refactor code

Suppose you need to update old code to use modern patterns and practices.

<Steps>
  <Step title="Identify legacy code for refactoring">

find deprecated API usage in our codebase

  </Step>

  <Step title="Get refactoring recommendations">

suggest how to refactor utils.js to use modern JavaScript features

  </Step>

  <Step title="Apply the changes safely">

refactor utils.js to use ES2024 features while maintaining the same behavior

  </Step>

  <Step title="Verify the refactoring">

run tests for the refactored code

  </Step>
</Steps>

<Tip>
  Tips:

  * Ask Claude to explain the benefits of the modern approach
  * Request that changes maintain backward compatibility when needed
  * Do refactoring in small, testable increments
</Tip>

***

## Use specialized subagents

Suppose you want to use specialized AI subagents to handle specific tasks more effectively.

<Steps>
  <Step title="View available subagents">

/agents

    This shows all available subagents and lets you create new ones.
  </Step>

  <Step title="Use subagents automatically">
    Claude Code will automatically delegate appropriate tasks to specialized subagents:

review my recent code changes for security issues

run all tests and fix any failures

  </Step>

  <Step title="Explicitly request specific subagents">

use the code-reviewer subagent to check the auth module

have the debugger subagent investigate why users can't log in

  </Step>

  <Step title="Create custom subagents for your workflow">

/agents

    Then select "Create New subagent" and follow the prompts to define:

    * Subagent type (e.g., `api-designer`, `performance-optimizer`)
    * When to use it
    * Which tools it can access
    * Its specialized system prompt
  </Step>
</Steps>

<Tip>
  Tips:

  * Create project-specific subagents in `.claude/agents/` for team sharing
  * Use descriptive `description` fields to enable automatic delegation
  * Limit tool access to what each subagent actually needs
  * Check the [subagents documentation](/en/docs/claude-code/sub-agents) for detailed examples
</Tip>

***

## Use Plan Mode for safe code analysis

Plan Mode instructs Claude to create a plan by analyzing the codebase with read-only operations, perfect for exploring codebases, planning complex changes, or reviewing code safely.

### When to use Plan Mode

* **Multi-step implementation**: When your feature requires making edits to many files
* **Code exploration**: When you want to research the codebase thoroughly before changing anything
* **Interactive development**: When you want to iterate on the direction with Claude

### How to use Plan Mode

**Turn on Plan Mode during a session**

You can switch into Plan Mode during a session using **Shift+Tab** to cycle through permission modes.

If you are in Normal Mode, **Shift+Tab** will first switch into Auto-Accept Mode, indicated by `⏵⏵ accept edits on` at the bottom of the terminal. A subsequent **Shift+Tab** will switch into Plan Mode, indicated by `⏸ plan mode on`.

**Start a new session in Plan Mode**

To start a new session in Plan Mode, use the `--permission-mode plan` flag:

claude --permission-mode plan

**Run "headless" queries in Plan Mode**

You can also run a query in Plan Mode directly with `-p` (i.e., in ["headless mode"](/en/docs/claude-code/sdk/sdk-headless)):

claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"

### Example: Planning a complex refactor

claude --permission-mode plan

I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.

Claude will analyze the current implementation and create a comprehensive plan. Refine with follow-ups:

What about backward compatibility?

How should we handle database migration?

### Configure Plan Mode as default

// .claude/settings.json { "permissions": { "defaultMode": "plan" } }

See [settings documentation](/en/docs/claude-code/settings#available-settings) for more configuration options.

***

## Work with tests

Suppose you need to add tests for uncovered code.

<Steps>
  <Step title="Identify untested code">

find functions in NotificationsService.swift that are not covered by tests

  </Step>

  <Step title="Generate test scaffolding">

add tests for the notification service

  </Step>

  <Step title="Add meaningful test cases">

add test cases for edge conditions in the notification service

  </Step>

  <Step title="Run and verify tests">

run the new tests and fix any failures

  </Step>
</Steps>

<Tip>
  Tips:

  * Ask for tests that cover edge cases and error conditions
  * Request both unit and integration tests when appropriate
  * Have Claude explain the testing strategy
</Tip>

***

## Create pull requests

Suppose you need to create a well-documented pull request for your changes.

<Steps>
  <Step title="Summarize your changes">

summarize the changes I've made to the authentication module

  </Step>

  <Step title="Generate a PR with Claude">

create a pr

  </Step>

  <Step title="Review and refine">

enhance the PR description with more context about the security improvements

  </Step>

  <Step title="Add testing details">

add information about how these changes were tested

  </Step>
</Steps>

<Tip>
  Tips:

  * Ask Claude directly to make a PR for you
  * Review Claude's generated PR before submitting
  * Ask Claude to highlight potential risks or considerations
</Tip>

## Handle documentation

Suppose you need to add or update documentation for your code.

<Steps>
  <Step title="Identify undocumented code">

find functions without proper JSDoc comments in the auth module

  </Step>

  <Step title="Generate documentation">

add JSDoc comments to the undocumented functions in auth.js

  </Step>

  <Step title="Review and enhance">

improve the generated documentation with more context and examples

  </Step>

  <Step title="Verify documentation">

check if the documentation follows our project standards

  </Step>
</Steps>

<Tip>
  Tips:

  * Specify the documentation style you want (JSDoc, docstrings, etc.)
  * Ask for examples in the documentation
  * Request documentation for public APIs, interfaces, and complex logic
</Tip>

***

## Work with images

Suppose you need to work with images in your codebase, and you want Claude's help analyzing image content.

<Steps>
  <Step title="Add an image to the conversation">
    You can use any of these methods:

    1. Drag and drop an image into the Claude Code window
    2. Copy an image and paste it into the CLI with ctrl+v (Do not use cmd+v)
    3. Provide an image path to Claude. E.g., "Analyze this image: /path/to/your/image.png"
  </Step>

  <Step title="Ask Claude to analyze the image">

What does this image show?

Describe the UI elements in this screenshot

Are there any problematic elements in this diagram?

  </Step>

  <Step title="Use images for context">

Here's a screenshot of the error. What's causing it?

This is our current database schema. How should we modify it for the new feature?

  </Step>

  <Step title="Get code suggestions from visual content">

Generate CSS to match this design mockup

What HTML structure would recreate this component?

  </Step>
</Steps>

<Tip>
  Tips:

  * Use images when text descriptions would be unclear or cumbersome
  * Include screenshots of errors, UI designs, or diagrams for better context
  * You can work with multiple images in a conversation
  * Image analysis works with diagrams, screenshots, mockups, and more
</Tip>

***

## Reference files and directories

Use @ to quickly include files or directories without waiting for Claude to read them.

<Steps>
  <Step title="Reference a single file">

Explain the logic in @src/utils/auth.js

    This includes the full content of the file in the conversation.
  </Step>

  <Step title="Reference a directory">

What's the structure of @src/components?

    This provides a directory listing with file information.
  </Step>

  <Step title="Reference MCP resources">

Show me the data from @github:repos/owner/repo/issues

    This fetches data from connected MCP servers using the format @server:resource. See [MCP resources](/en/docs/claude-code/mcp#use-mcp-resources) for details.
  </Step>
</Steps>

<Tip>
  Tips:

  * File paths can be relative or absolute
  * @ file references add CLAUDE.md in the file's directory and parent directories to context
  * Directory references show file listings, not contents
  * You can reference multiple files in a single message (e.g., "@file1.js and @file2.js")
</Tip>

***

## Use extended thinking

Suppose you're working on complex architectural decisions, challenging bugs, or planning multi-step implementations that require deep reasoning.

<Note>
  [Extended thinking](/en/docs/build-with-claude/extended-thinking) is disabled by default in Claude Code. You can enable it on-demand by using `Tab` to toggle Thinking on, or by using prompts like "think" or "think hard". You can also enable it permanently by setting the [`MAX_THINKING_TOKENS` environment variable](/en/docs/claude-code/settings#environment-variables) in your settings.
</Note>

<Steps>
  <Step title="Provide context and ask Claude to think">

I need to implement a new authentication system using OAuth2 for our API. Think deeply about the best approach for implementing this in our codebase.

    Claude will gather relevant information from your codebase and
    use extended thinking, which will be visible in the interface.
  </Step>

  <Step title="Refine the thinking with follow-up prompts">

think about potential security vulnerabilities in this approach

think hard about edge cases we should handle

  </Step>
</Steps>

<Tip>
  Tips to get the most value out of extended thinking:

  [Extended thinking](/en/docs/build-with-claude/extended-thinking) is most valuable for complex tasks such as:

  * Planning complex architectural changes
  * Debugging intricate issues
  * Creating implementation plans for new features
  * Understanding complex codebases
  * Evaluating tradeoffs between different approaches

  Use `Tab` to toggle Thinking on and off during a session.

  The way you prompt for thinking results in varying levels of thinking depth:

  * "think" triggers basic extended thinking
  * intensifying phrases such as "keep hard", "think more", "think a lot", or "think longer" triggers deeper thinking

  For more extended thinking prompting tips, see [Extended thinking tips](/en/docs/build-with-claude/prompt-engineering/extended-thinking-tips).
</Tip>

<Note>
  Claude will display its thinking process as italic gray text above the
  response.
</Note>

***

## Resume previous conversations

Suppose you've been working on a task with Claude Code and need to continue where you left off in a later session.

Claude Code provides two options for resuming previous conversations:

* `--continue` to automatically continue the most recent conversation
* `--resume` to display a conversation picker

<Steps>
  <Step title="Continue the most recent conversation">

claude --continue

    This immediately resumes your most recent conversation without any prompts.
  </Step>

  <Step title="Continue in non-interactive mode">

claude --continue --print "Continue with my task"

    Use `--print` with `--continue` to resume the most recent conversation in non-interactive mode, perfect for scripts or automation.
  </Step>

  <Step title="Show conversation picker">

claude --resume

    This displays an interactive conversation selector with a clean list view showing:

    * Session summary (or initial prompt)
    * Metadata: time elapsed, message count, and git branch

    Use arrow keys to navigate and press Enter to select a conversation. Press Esc to exit.
  </Step>
</Steps>

<Tip>
  Tips:

  * Conversation history is stored locally on your machine
  * Use `--continue` for quick access to your most recent conversation
  * Use `--resume` when you need to select a specific past conversation
  * When resuming, you'll see the entire conversation history before continuing
  * The resumed conversation starts with the same model and configuration as the original

  How it works:

  1. **Conversation Storage**: All conversations are automatically saved locally with their full message history
  2. **Message Deserialization**: When resuming, the entire message history is restored to maintain context
  3. **Tool State**: Tool usage and results from the previous conversation are preserved
  4. **Context Restoration**: The conversation resumes with all previous context intact

  Examples:

Continue most recent conversation

claude --continue

Continue most recent conversation with a specific prompt

claude --continue --print "Show me our progress"

Show conversation picker

claude --resume

Continue most recent conversation in non-interactive mode

claude --continue --print "Run the tests again"

</Tip>

***

## Run parallel Claude Code sessions with Git worktrees

Suppose you need to work on multiple tasks simultaneously with complete code isolation between Claude Code instances.

<Steps>
  <Step title="Understand Git worktrees">
    Git worktrees allow you to check out multiple branches from the same
    repository into separate directories. Each worktree has its own working
    directory with isolated files, while sharing the same Git history. Learn
    more in the [official Git worktree
    documentation](https://git-scm.com/docs/git-worktree).
  </Step>

  <Step title="Create a new worktree">

Create a new worktree with a new branch

git worktree add ../project-feature-a -b feature-a

Or create a worktree with an existing branch

git worktree add ../project-bugfix bugfix-123

    This creates a new directory with a separate working copy of your repository.
  </Step>

  <Step title="Run Claude Code in each worktree">

Navigate to your worktree

cd ../project-feature-a

Run Claude Code in this isolated environment

claude

  </Step>

  <Step title="Run Claude in another worktree">

cd ../project-bugfix claude

  </Step>

  <Step title="Manage your worktrees">

List all worktrees

git worktree list

Remove a worktree when done

git worktree remove ../project-feature-a

  </Step>
</Steps>

<Tip>
  Tips:

  * Each worktree has its own independent file state, making it perfect for parallel Claude Code sessions
  * Changes made in one worktree won't affect others, preventing Claude instances from interfering with each other
  * All worktrees share the same Git history and remote connections
  * For long-running tasks, you can have Claude working in one worktree while you continue development in another
  * Use descriptive directory names to easily identify which task each worktree is for
  * Remember to initialize your development environment in each new worktree according to your project's setup. Depending on your stack, this might include:
    * JavaScript projects: Running dependency installation (`npm install`, `yarn`)
    * Python projects: Setting up virtual environments or installing with package managers
    * Other languages: Following your project's standard setup process
</Tip>

***

## Use Claude as a unix-style utility

### Add Claude to your verification process

Suppose you want to use Claude Code as a linter or code reviewer.

**Add Claude to your build script:**

// package.json { ... "scripts": { ... "lint:claude": "claude -p 'you are a linter. please look at the changes vs. main and report any issues related to typos. report the filename and line number on one line, and a description of the issue on the second line. do not return any other text.'" } }

<Tip>
  Tips:

  * Use Claude for automated code review in your CI/CD pipeline
  * Customize the prompt to check for specific issues relevant to your project
  * Consider creating multiple scripts for different types of verification
</Tip>

### Pipe in, pipe out

Suppose you want to pipe data into Claude, and get back data in a structured format.

**Pipe data through Claude:**

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

<Tip>
  Tips:

  * Use pipes to integrate Claude into existing shell scripts
  * Combine with other Unix tools for powerful workflows
  * Consider using --output-format for structured output
</Tip>

### Control output format

Suppose you need Claude's output in a specific format, especially when integrating Claude Code into scripts or other tools.

<Steps>
  <Step title="Use text format (default)">

cat data.txt | claude -p 'summarize this data' --output-format text > summary.txt

    This outputs just Claude's plain text response (default behavior).
  </Step>

  <Step title="Use JSON format">

cat code.py | claude -p 'analyze this code for bugs' --output-format json > analysis.json

    This outputs a JSON array of messages with metadata including cost and duration.
  </Step>

  <Step title="Use streaming JSON format">

cat log.txt | claude -p 'parse this log file for errors' --output-format stream-json

    This outputs a series of JSON objects in real-time as Claude processes the request. Each message is a valid JSON object, but the entire output is not valid JSON if concatenated.
  </Step>
</Steps>

<Tip>
  Tips:

  * Use `--output-format text` for simple integrations where you just need Claude's response
  * Use `--output-format json` when you need the full conversation log
  * Use `--output-format stream-json` for real-time output of each conversation turn
</Tip>

***

## Create custom slash commands

Claude Code supports custom slash commands that you can create to quickly execute specific prompts or tasks.

For more details, see the [Slash commands](/en/docs/claude-code/slash-commands) reference page.

### Create project-specific commands

Suppose you want to create reusable slash commands for your project that all team members can use.

<Steps>
  <Step title="Create a commands directory in your project">

mkdir -p .claude/commands

  </Step>

  <Step title="Create a Markdown file for each command">

echo "Analyze the performance of this code and suggest three specific optimizations:" > .claude/commands/optimize.md

  </Step>

  <Step title="Use your custom command in Claude Code">

/optimize

  </Step>
</Steps>

<Tip>
  Tips:

  * Command names are derived from the filename (e.g., `optimize.md` becomes `/optimize`)
  * You can organize commands in subdirectories (e.g., `.claude/commands/frontend/component.md` creates `/component` with "(project:frontend)" shown in the description)
  * Project commands are available to everyone who clones the repository
  * The Markdown file content becomes the prompt sent to Claude when the command is invoked
</Tip>

### Add command arguments with \$ARGUMENTS

Suppose you want to create flexible slash commands that can accept additional input from users.

<Steps>
  <Step title="Create a command file with the $ARGUMENTS placeholder">

echo 'Find and fix issue #$ARGUMENTS. Follow these steps: 1. Understand the issue described in the ticket 2. Locate the relevant code in our codebase 3. Implement a solution that addresses the root cause 4. Add appropriate tests 5. Prepare a concise PR description' > .claude/commands/fix-issue.md

  </Step>

  <Step title="Use the command with an issue number">
    In your Claude session, use the command with arguments.

/fix-issue 123

    This will replace \$ARGUMENTS with "123" in the prompt.
  </Step>
</Steps>

<Tip>
  Tips:

  * The \$ARGUMENTS placeholder is replaced with any text that follows the command
  * You can position \$ARGUMENTS anywhere in your command template
  * Other useful applications: generating test cases for specific functions, creating documentation for components, reviewing code in particular files, or translating content to specified languages
</Tip>

### Create personal slash commands

Suppose you want to create personal slash commands that work across all your projects.

<Steps>
  <Step title="Create a commands directory in your home folder">

mkdir -p ~/.claude/commands

  </Step>

  <Step title="Create a Markdown file for each command">

echo "Review this code for security vulnerabilities, focusing on:" > ~/.claude/commands/security-review.md

  </Step>

  <Step title="Use your personal custom command">

/security-review

  </Step>
</Steps>

<Tip>
  Tips:

  * Personal commands show "(user)" in their description when listed with `/help`
  * Personal commands are only available to you and not shared with your team
  * Personal commands work across all your projects
  * You can use these for consistent workflows across different codebases
</Tip>

***

## Ask Claude about its capabilities

Claude has built-in access to its documentation and can answer questions about its own features and limitations.

### Example questions

can Claude Code create pull requests?

how does Claude Code handle permissions?

what slash commands are available?

how do I use MCP with Claude Code?

how do I configure Claude Code for Amazon Bedrock?

what are the limitations of Claude Code?

<Note>
  Claude provides documentation-based answers to these questions. For executable examples and hands-on demonstrations, refer to the specific workflow sections above.
</Note>

<Tip>
  Tips:

  * Claude always has access to the latest Claude Code documentation, regardless of the version you're using
  * Ask specific questions to get detailed answers
  * Claude can explain complex features like MCP integration, enterprise configurations, and advanced workflows
</Tip>

***

## Next steps

<Card title="Claude Code reference implementation" icon="code" href="https://github.com/anthropics/claude-code/tree/main/.devcontainer">
  Clone our development container reference implementation.
</Card>

Manage costs effectively

Learn how to track and optimize token usage and costs when using Claude Code.

Claude Code consumes tokens for each interaction. The average cost is \$6 per developer per day, with daily costs remaining below \$12 for 90% of users.

For team usage, Claude Code charges by API token consumption. On average, Claude Code costs \~\$100-200/developer per month with Sonnet 4.5 though there is large variance depending on how many instances users are running and whether they're using it in automation.

Track your costs

Using the /cost command

<Note> The /cost command is not intended for Claude Max and Pro subscribers. </Note>

The /cost command provides detailed token usage statistics for your current session:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    0 lines added, 0 lines removed

Additional tracking options

Check historical usage in the Claude Console (requires Admin or Billing role) and set workspace spend limits for the Claude Code workspace (requires Admin role).

<Note> When you first authenticate Claude Code with your Claude Console account, a workspace called "Claude Code" is automatically created for you. This workspace provides centralized cost tracking and management for all Claude Code usage in your organization. You cannot create API keys for this workspace - it is exclusively for Claude Code authentication and usage. </Note>

Managing costs for teams

When using Claude API, you can limit the total Claude Code workspace spend. To configure, follow these instructions. Admins can view cost and usage reporting by following these instructions.

On Bedrock and Vertex, Claude Code does not send metrics from your cloud. In order to get cost metrics, several large enterprises reported using LiteLLM, which is an open-source tool that helps companies track spend by key. This project is unaffiliated with Anthropic and we have not audited its security.

Rate limit recommendations

When setting up Claude Code for teams, consider these Token Per Minute (TPM) and Request Per Minute (RPM) per-user recommendations based on your organization size:

For example, if you have 200 users, you might request 20k TPM for each user, or 4 million total TPM (200\*20,000 = 4 million).

The TPM per user decreases as team size grows because we expect fewer users to use Claude Code concurrently in larger organizations. These rate limits apply at the organization level, not per individual user, which means individual users can temporarily consume more than their calculated share when others aren't actively using the service.

<Note> If you anticipate scenarios with unusually high concurrent usage (such as live training sessions with large groups), you may need higher TPM allocations per user. </Note>

Reduce token usage

• Compact conversations:

• Claude uses auto-compact by default when context exceeds 95% capacity
• Toggle auto-compact: Run /config and navigate to "Auto-compact enabled"
• Use /compact manually when context gets large
• Add custom instructions: /compact Focus on code samples and API usage
• Customize compaction by adding to CLAUDE.md:

```markdown theme={null}

Summary instructions

When you are using compact, please focus on test output and code changes

* **Write specific queries:** Avoid vague requests that trigger unnecessary scanning

* **Break down complex tasks:** Split large tasks into focused interactions

* **Clear history between tasks:** Use `/clear` to reset context

Costs can vary significantly based on:

* Size of codebase being analyzed
* Complexity of queries
* Number of files being searched or modified
* Length of conversation history
* Frequency of compacting conversations

## Background token usage

Claude Code uses tokens for some background functionality even when idle:

* **Conversation summarization**: Background jobs that summarize previous conversations for the `claude --resume` feature
* **Command processing**: Some commands like `/cost` may generate requests to check status

These background processes consume a small amount of tokens (typically under \$0.04 per session) even without active interaction.

## Tracking version changes and updates

### Current version information

To check your current Claude Code version and installation details:

claude doctor

This command shows your version, installation type, and system information.

### Understanding changes in Claude Code behavior

Claude Code regularly receives updates that may change how features work, including cost reporting:

* **Version tracking**: Use `claude doctor` to see your current version
* **Behavior changes**: Features like `/cost` may display information differently across versions
* **Documentation access**: Claude always has access to the latest documentation, which can help explain current feature behavior

### When cost reporting changes

If you notice changes in how costs are displayed (such as the `/cost` command showing different information):

1. **Verify your version**: Run `claude doctor` to confirm your current version
2. **Consult documentation**: Ask Claude directly about current feature behavior, as it has access to up-to-date documentation
3. **Contact support**: For specific billing questions, contact Anthropic support through your Console account

<Note>
  For team deployments, we recommend starting with a small pilot group to
  establish usage patterns before wider rollout.
</Note>

Data usage

Learn about Anthropic's data usage policies for Claude

Data policies

Data training policy

Consumer users (Free, Pro, and Max plans): Starting August 28, 2025, we're giving you the choice to allow your data to be used to improve future Claude models.

We will train new models using data from Free, Pro, and Max accounts when this setting is on (including when you use Claude Code from these accounts).

• If you're a current user, you can select your preference now and your selection will immediately go into effect.

This setting will only apply to new or resumed chats and coding sessions on Claude. Previous chats with no additional activity will not be used for model training.

• You have until October 8, 2025 to make your selection.

If you're a new user, you can pick your setting for model training during the signup process. You can change your selection at any time in your Privacy Settings.

Commercial users: (Team and Enterprise plans, API, 3rd-party platforms, and Claude Gov) maintain existing policies: Anthropic does not train generative models using code or prompts sent to Claude Code under commercial terms, unless the customer has chosen to provide their data to us for model improvement (e.g. Developer Partner Program).

Development Partner Program

If you explicitly opt in to methods to provide us with materials to train on, such as via the Development Partner Program, we may use those materials provided to train our models. An organization admin can expressly opt-in to the Development Partner Program for their organization. Note that this program is available only for Anthropic first-party API, and not for Bedrock or Vertex users.

Feedback using the /bug command

If you choose to send us feedback about Claude Code using the /bug command, we may use your feedback to improve our products and services. Transcripts shared via /bug are retained for 5 years.

Data retention

Anthropic retains Claude Code data based on your account type and preferences.

Consumer users (Free, Pro, and Max plans):

• Users who allow data use for model improvement: 5-year retention period to support model development and safety improvements
• Users who don't allow data use for model improvement: 30-day retention period
• Privacy settings can be changed at any time at claude.ai/settings/data-privacy-controls.

Commercial users (Team, Enterprise, and API):

• Standard: 30-day retention period
• Zero data retention: Available with appropriately configured API keys - Claude Code will not retain chat transcripts on servers
• Local caching: Claude Code clients may store sessions locally for up to 30 days to enable session resumption (configurable)

Learn more about data retention practices in our Privacy Center.

For full details, please review our Commercial Terms of Service (for Team, Enterprise, and API users) or Consumer Terms (for Free, Pro, and Max users) and Privacy Policy.

Data flow and dependencies

<img src="https://mintcdn.com/anthropic-claude-docs/LF5WV0SNF6oudpT5/images/claude-code-data-flow.png?fit=max&auto=format&n=LF5WV0SNF6oudpT5&q=85&s=4b30069d702719e7bfb974eaaafab21c" alt="Claude Code data flow diagram" data-og-width="1597" width="1597" data-og-height="1285" height="1285" data-path="images/claude-code-data-flow.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/LF5WV0SNF6oudpT5/images/claude-code-data-flow.png?w=280&fit=max&auto=format&n=LF5WV0SNF6oudpT5&q=85&s=067676caa12f89051cb193e6b3f7d0a0 280w, https://mintcdn.com/anthropic-claude-docs/LF5WV0SNF6oudpT5/images/claude-code-data-flow.png?w=560&fit=max&auto=format&n=LF5WV0SNF6oudpT5&q=85&s=5506197deff927f54f2fb5a349f358a8 560w, https://mintcdn.com/anthropic-claude-docs/LF5WV0SNF6oudpT5/images/claude-code-data-flow.png?w=840&fit=max&auto=format&n=LF5WV0SNF6oudpT5&q=85&s=bb4febe7974dde5b76b88744f89ab472 840w, https://mintcdn.com/anthropic-claude-docs/LF5WV0SNF6oudpT5/images/claude-code-data-flow.png?w=1100&fit=max&auto=format&n=LF5WV0SNF6oudpT5&q=85&s=b51af3074f87b33ccc342aaad655dcbf 1100w, https://mintcdn.com/anthropic-claude-docs/LF5WV0SNF6oudpT5/images/claude-code-data-flow.png?w=1650&fit=max&auto=format&n=LF5WV0SNF6oudpT5&q=85&s=8fd96f1dde615877d4e4bbe1874af12d 1650w, https://mintcdn.com/anthropic-claude-docs/LF5WV0SNF6oudpT5/images/claude-code-data-flow.png?w=2500&fit=max&auto=format&n=LF5WV0SNF6oudpT5&q=85&s=056deded541ec30e9b67a67d620f6aaf 2500w" />

Claude Code is installed from NPM. Claude Code runs locally. In order to interact with the LLM, Claude Code sends data over the network. This data includes all user prompts and model outputs. The data is encrypted in transit via TLS and is not encrypted at rest. Claude Code is compatible with most popular VPNs and LLM proxies.

Claude Code is built on Anthropic's APIs. For details regarding our API's security controls, including our API logging procedures, please refer to compliance artifacts offered in the Anthropic Trust Center.

Telemetry services

Claude Code connects from users' machines to the Statsig service to log operational metrics such as latency, reliability, and usage patterns. This logging does not include any code or file paths. Data is encrypted in transit using TLS and at rest using 256-bit AES encryption. Read more in the Statsig security documentation. To opt out of Statsig telemetry, set the DISABLE_TELEMETRY environment variable.

Claude Code connects from users' machines to Sentry for operational error logging. The data is encrypted in transit using TLS and at rest using 256-bit AES encryption. Read more in the Sentry security documentation. To opt out of error logging, set the DISABLE_ERROR_REPORTING environment variable.

When users run the /bug command, a copy of their full conversation history including code is sent to Anthropic. The data is encrypted in transit and at rest. Optionally, a Github issue is created in our public repository. To opt out of bug reporting, set the DISABLE_BUG_COMMAND environment variable.

Default behaviors by API provider

By default, we disable all non-essential traffic (including error reporting, telemetry, and bug reporting functionality) when using Bedrock or Vertex. You can also opt out of all of these at once by setting the CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC environment variable. Here are the full default behaviors:

All environment variables can be checked into settings.json (read more).

Development containers

Learn about the Claude Code development container for teams that need consistent, secure environments.

The reference devcontainer setup and associated Dockerfile offer a preconfigured development container that you can use as is, or customize for your needs. This devcontainer works with the Visual Studio Code Dev Containers extension and similar tools.

The container's enhanced security measures (isolation and firewall rules) allow you to run claude --dangerously-skip-permissions to bypass permission prompts for unattended operation.

<Warning> While the devcontainer provides substantial protections, no system is completely immune to all attacks. When executed with --dangerously-skip-permissions, devcontainers do not prevent a malicious project from exfiltrating anything accessible in the devcontainer including Claude Code credentials. We recommend only using devcontainers when developing with trusted repositories. Always maintain good security practices and monitor Claude's activities. </Warning>

Key features

• Production-ready Node.js: Built on Node.js 20 with essential development dependencies
• Security by design: Custom firewall restricting network access to only necessary services
• Developer-friendly tools: Includes git, ZSH with productivity enhancements, fzf, and more
• Seamless VS Code integration: Pre-configured extensions and optimized settings
• Session persistence: Preserves command history and configurations between container restarts
• Works everywhere: Compatible with macOS, Windows, and Linux development environments

Getting started in 4 steps

1. Install VS Code and the Remote - Containers extension 2. Clone the Claude Code reference implementation repository 3. Open the repository in VS Code 4. When prompted, click "Reopen in Container" (or use Command Palette: Cmd+Shift+P → "Remote-Containers: Reopen in Container")

Configuration breakdown

The devcontainer setup consists of three primary components:

• **devcontainer.json**: Controls container settings, extensions, and volume mounts
• **Dockerfile**: Defines the container image and installed tools
• **init-firewall.sh**: Establishes network security rules

Security features

The container implements a multi-layered security approach with its firewall configuration:

• Precise access control: Restricts outbound connections to whitelisted domains only (npm registry, GitHub, Claude API, etc.)
• Allowed outbound connections: The firewall permits outbound DNS and SSH connections
• Default-deny policy: Blocks all other external network access
• Startup verification: Validates firewall rules when the container initializes
• Isolation: Creates a secure development environment separated from your main system

Customization options

The devcontainer configuration is designed to be adaptable to your needs:

• Add or remove VS Code extensions based on your workflow
• Modify resource allocations for different hardware environments
• Adjust network access permissions
• Customize shell configurations and developer tooling

Example use cases

Secure client work

Use devcontainers to isolate different client projects, ensuring code and credentials never mix between environments.

Team onboarding

New team members can get a fully configured development environment in minutes, with all necessary tools and settings pre-installed.

Consistent CI/CD environments

Mirror your devcontainer configuration in CI/CD pipelines to ensure development and production environments match.

Related resources

• VS Code devcontainers documentation
• Claude Code security best practices
• Enterprise network configuration

Claude Code GitHub Actions

Learn about integrating Claude Code into your development workflow with Claude Code GitHub Actions

Claude Code GitHub Actions brings AI-powered automation to your GitHub workflow. With a simple @claude mention in any PR or issue, Claude can analyze your code, create pull requests, implement features, and fix bugs - all while following your project's standards.

<Note> Claude Code GitHub Actions is built on top of the Claude Code SDK, which enables programmatic integration of Claude Code into your applications. You can use the SDK to build custom automation workflows beyond GitHub Actions. </Note>

Why use Claude Code GitHub Actions?

• Instant PR creation: Describe what you need, and Claude creates a complete PR with all necessary changes
• Automated code implementation: Turn issues into working code with a single command
• Follows your standards: Claude respects your CLAUDE.md guidelines and existing code patterns
• Simple setup: Get started in minutes with our installer and API key
• Secure by default: Your code stays on Github's runners

What can Claude do?

Claude Code provides a powerful GitHub Action that transforms how you work with code:

Claude Code Action

This GitHub Action allows you to run Claude Code within your GitHub Actions workflows. You can use this to build any custom workflow on top of Claude Code.

View repository →

Setup

Quick setup

The easiest way to set up this action is through Claude Code in the terminal. Just open claude and run /install-github-app.

This command will guide you through setting up the GitHub app and required secrets.

<Note>

• You must be a repository admin to install the GitHub app and add secrets
• The GitHub app will request read & write permissions for Contents, Issues, and Pull requests
• This quickstart method is only available for direct Claude API users. If

you're using AWS Bedrock or Google Vertex AI, please see the Using with AWS Bedrock & Google Vertex AI section. </Note>

Manual setup

If the /install-github-app command fails or you prefer manual setup, please follow these manual setup instructions:

1. Install the Claude GitHub app to your repository: https://github.com/apps/claude

The Claude GitHub app requires the following repository permissions:

• Contents: Read & write (to modify repository files)
• Issues: Read & write (to respond to issues)
• Pull requests: Read & write (to create PRs and push changes)

For more details on security and permissions, see the security documentation. 2. Add ANTHROPIC\_API\_KEY to your repository secrets (Learn how to use secrets in GitHub Actions) 3. Copy the workflow file from examples/claude.yml into your repository's .github/workflows/

<Tip> After completing either the quickstart or manual setup, test the action by tagging @claude in an issue or PR comment! </Tip>

Upgrading from Beta

<Warning> Claude Code GitHub Actions v1.0 introduces breaking changes that require updating your workflow files in order to upgrade to v1.0 from the beta version. </Warning>

If you're currently using the beta version of Claude Code GitHub Actions, we recommend that you update your workflows to use the GA version. The new version simplifies configuration while adding powerful new features like automatic mode detection.

Essential changes

All beta users must make these changes to their workflow files in order to upgrade:

1. Update the action version: Change @beta to @v1 2. Remove mode configuration: Delete mode: "tag" or mode: "agent" (now auto-detected) 3. Update prompt inputs: Replace direct_prompt with prompt 4. Move CLI options: Convert max_turns, model, custom_instructions, etc. to claude_args

Breaking Changes Reference

Before and After Example

Beta version:

```yaml theme={null}

• uses: anthropics/claude-code-action@beta

with: mode: "tag" direct_prompt: "Review this PR for security issues" anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} custom_instructions: "Follow our coding standards" max_turns: "10" model: "claude-3-5-sonnet-20241022"

**GA version (v1.0):**

• uses: anthropics/claude-code-action@v1

with: prompt: "Review this PR for security issues" anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} claude_args: | --system-prompt "Follow our coding standards" --max-turns 10 --model claude-sonnet-4-5-20250929

<Tip>
  The action now automatically detects whether to run in interactive mode (responds to `@claude` mentions) or automation mode (runs immediately with a prompt) based on your configuration.
</Tip>

## Example use cases

Claude Code GitHub Actions can help you with a variety of tasks. The [examples directory](https://github.com/anthropics/claude-code-action/tree/main/examples) contains ready-to-use workflows for different scenarios.

### Basic workflow

name: Claude Code on: issue_comment: types: [created] pull_request_review_comment: types: [created] jobs: claude: runs-on: ubuntu-latest steps:

• uses: anthropics/claude-code-action@v1

with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Responds to @claude mentions in comments

### Using slash commands

name: Code Review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest steps:

• uses: anthropics/claude-code-action@v1

with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: "/review" claude_args: "--max-turns 5"

### Custom automation with prompts

name: Daily Report on: schedule:

• cron: "0 9 *"

jobs: report: runs-on: ubuntu-latest steps:

• uses: anthropics/claude-code-action@v1

with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: "Generate a summary of yesterday's commits and open issues" claude_args: "--model claude-opus-4-1-20250805"

### Common use cases

In issue or PR comments:

@claude implement this feature based on the issue description @claude how should I implement user authentication for this endpoint? @claude fix the TypeError in the user dashboard component

Claude will automatically analyze the context and respond appropriately.

## Best practices

### CLAUDE.md configuration

Create a `CLAUDE.md` file in your repository root to define code style guidelines, review criteria, project-specific rules, and preferred patterns. This file guides Claude's understanding of your project standards.

### Security considerations

<Warning>Never commit API keys directly to your repository!</Warning>

For comprehensive security guidance including permissions, authentication, and best practices, see the [Claude Code Action security documentation](https://github.com/anthropics/claude-code-action/blob/main/docs/security.md).

Always use GitHub Secrets for API keys:

* Add your API key as a repository secret named `ANTHROPIC_API_KEY`
* Reference it in workflows: `anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}`
* Limit action permissions to only what's necessary
* Review Claude's suggestions before merging

Always use GitHub Secrets (e.g., `${{ secrets.ANTHROPIC_API_KEY }}`) rather than hardcoding API keys directly in your workflow files.

### Optimizing performance

Use issue templates to provide context, keep your `CLAUDE.md` concise and focused, and configure appropriate timeouts for your workflows.

### CI costs

When using Claude Code GitHub Actions, be aware of the associated costs:

**GitHub Actions costs:**

* Claude Code runs on GitHub-hosted runners, which consume your GitHub Actions minutes
* See [GitHub's billing documentation](https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions) for detailed pricing and minute limits

**API costs:**

* Each Claude interaction consumes API tokens based on the length of prompts and responses
* Token usage varies by task complexity and codebase size
* See [Claude's pricing page](https://claude.com/platform/api) for current token rates

**Cost optimization tips:**

* Use specific `@claude` commands to reduce unnecessary API calls
* Configure appropriate `--max-turns` in `claude_args` to prevent excessive iterations
* Set workflow-level timeouts to avoid runaway jobs
* Consider using GitHub's concurrency controls to limit parallel runs

## Configuration examples

The Claude Code Action v1 simplifies configuration with unified parameters:

• uses: anthropics/claude-code-action@v1

with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: "Your instructions here" # Optional claude_args: "--max-turns 5" # Optional CLI arguments

Key features:

* **Unified prompt interface** - Use `prompt` for all instructions
* **Slash commands** - Pre-built prompts like `/review` or `/fix`
* **CLI passthrough** - Any Claude Code CLI argument via `claude_args`
* **Flexible triggers** - Works with any GitHub event

Visit the [examples directory](https://github.com/anthropics/claude-code-action/tree/main/examples) for complete workflow files.

<Tip>
  When responding to issue or PR comments, Claude automatically responds to @claude mentions. For other events, use the `prompt` parameter to provide instructions.
</Tip>

## Using with AWS Bedrock & Google Vertex AI

For enterprise environments, you can use Claude Code GitHub Actions with your own cloud infrastructure. This approach gives you control over data residency and billing while maintaining the same functionality.

### Prerequisites

Before setting up Claude Code GitHub Actions with cloud providers, you need:

#### For Google Cloud Vertex AI:

1. A Google Cloud Project with Vertex AI enabled
2. Workload Identity Federation configured for GitHub Actions
3. A service account with the required permissions
4. A GitHub App (recommended) or use the default GITHUB\_TOKEN

#### For AWS Bedrock:

1. An AWS account with Amazon Bedrock enabled
2. GitHub OIDC Identity Provider configured in AWS
3. An IAM role with Bedrock permissions
4. A GitHub App (recommended) or use the default GITHUB\_TOKEN

<Steps>
  <Step title="Create a custom GitHub App (Recommended for 3P Providers)">
    For best control and security when using 3P providers like Vertex AI or Bedrock, we recommend creating your own GitHub App:

    1. Go to [https://github.com/settings/apps/new](https://github.com/settings/apps/new)
    2. Fill in the basic information:
       * **GitHub App name**: Choose a unique name (e.g., "YourOrg Claude Assistant")
       * **Homepage URL**: Your organization's website or the repository URL
    3. Configure the app settings:
       * **Webhooks**: Uncheck "Active" (not needed for this integration)
    4. Set the required permissions:
       * **Repository permissions**:
         * Contents: Read & Write
         * Issues: Read & Write
         * Pull requests: Read & Write
    5. Click "Create GitHub App"
    6. After creation, click "Generate a private key" and save the downloaded `.pem` file
    7. Note your App ID from the app settings page
    8. Install the app to your repository:
       * From your app's settings page, click "Install App" in the left sidebar
       * Select your account or organization
       * Choose "Only select repositories" and select the specific repository
       * Click "Install"
    9. Add the private key as a secret to your repository:
       * Go to your repository's Settings → Secrets and variables → Actions
       * Create a new secret named `APP_PRIVATE_KEY` with the contents of the `.pem` file
    10. Add the App ID as a secret:

    * Create a new secret named `APP_ID` with your GitHub App's ID

    <Note>
      This app will be used with the [actions/create-github-app-token](https://github.com/actions/create-github-app-token) action to generate authentication tokens in your workflows.
    </Note>

    **Alternative for Claude API or if you don't want to setup your own Github app**: Use the official Anthropic app:

    1. Install from: [https://github.com/apps/claude](https://github.com/apps/claude)
    2. No additional configuration needed for authentication
  </Step>

  <Step title="Configure cloud provider authentication">
    Choose your cloud provider and set up secure authentication:

    <AccordionGroup>
      <Accordion title="AWS Bedrock">
        **Configure AWS to allow GitHub Actions to authenticate securely without storing credentials.**

        > **Security Note**: Use repository-specific configurations and grant only the minimum required permissions.

        **Required Setup**:

        1. **Enable Amazon Bedrock**:
           * Request access to Claude models in Amazon Bedrock
           * For cross-region models, request access in all required regions

        2. **Set up GitHub OIDC Identity Provider**:
           * Provider URL: `https://token.actions.githubusercontent.com`
           * Audience: `sts.amazonaws.com`

        3. **Create IAM Role for GitHub Actions**:
           * Trusted entity type: Web identity
           * Identity provider: `token.actions.githubusercontent.com`
           * Permissions: `AmazonBedrockFullAccess` policy
           * Configure trust policy for your specific repository

        **Required Values**:

        After setup, you'll need:

        * **AWS\_ROLE\_TO\_ASSUME**: The ARN of the IAM role you created

        <Tip>
          OIDC is more secure than using static AWS access keys because credentials are temporary and automatically rotated.
        </Tip>

        See [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) for detailed OIDC setup instructions.
      </Accordion>

      <Accordion title="Google Vertex AI">
        **Configure Google Cloud to allow GitHub Actions to authenticate securely without storing credentials.**

        > **Security Note**: Use repository-specific configurations and grant only the minimum required permissions.

        **Required Setup**:

        1. **Enable APIs** in your Google Cloud project:
           * IAM Credentials API
           * Security Token Service (STS) API
           * Vertex AI API

        2. **Create Workload Identity Federation resources**:
           * Create a Workload Identity Pool
           * Add a GitHub OIDC provider with:
             * Issuer: `https://token.actions.githubusercontent.com`
             * Attribute mappings for repository and owner
             * **Security recommendation**: Use repository-specific attribute conditions

        3. **Create a Service Account**:
           * Grant only `Vertex AI User` role
           * **Security recommendation**: Create a dedicated service account per repository

        4. **Configure IAM bindings**:
           * Allow the Workload Identity Pool to impersonate the service account
           * **Security recommendation**: Use repository-specific principal sets

        **Required Values**:

        After setup, you'll need:

        * **GCP\_WORKLOAD\_IDENTITY\_PROVIDER**: The full provider resource name
        * **GCP\_SERVICE\_ACCOUNT**: The service account email address

        <Tip>
          Workload Identity Federation eliminates the need for downloadable service account keys, improving security.
        </Tip>

        For detailed setup instructions, consult the [Google Cloud Workload Identity Federation documentation](https://cloud.google.com/iam/docs/workload-identity-federation).
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Add Required Secrets">
    Add the following secrets to your repository (Settings → Secrets and variables → Actions):

    #### For Claude API (Direct):

    1. **For API Authentication**:
       * `ANTHROPIC_API_KEY`: Your Claude API key from [console.anthropic.com](https://console.anthropic.com)

    2. **For GitHub App (if using your own app)**:
       * `APP_ID`: Your GitHub App's ID
       * `APP_PRIVATE_KEY`: The private key (.pem) content

    #### For Google Cloud Vertex AI

    1. **For GCP Authentication**:
       * `GCP_WORKLOAD_IDENTITY_PROVIDER`
       * `GCP_SERVICE_ACCOUNT`

    2. **For GitHub App (if using your own app)**:
       * `APP_ID`: Your GitHub App's ID
       * `APP_PRIVATE_KEY`: The private key (.pem) content

    #### For AWS Bedrock

    1. **For AWS Authentication**:
       * `AWS_ROLE_TO_ASSUME`

    2. **For GitHub App (if using your own app)**:
       * `APP_ID`: Your GitHub App's ID
       * `APP_PRIVATE_KEY`: The private key (.pem) content
  </Step>

  <Step title="Create workflow files">
    Create GitHub Actions workflow files that integrate with your cloud provider. The examples below show complete configurations for both AWS Bedrock and Google Vertex AI:

    <AccordionGroup>
      <Accordion title="AWS Bedrock workflow">
        **Prerequisites:**

        * AWS Bedrock access enabled with Claude model permissions
        * GitHub configured as an OIDC identity provider in AWS
        * IAM role with Bedrock permissions that trusts GitHub Actions

        **Required GitHub secrets:**

        | Secret Name          | Description                                       |
        | -------------------- | ------------------------------------------------- |
        | `AWS_ROLE_TO_ASSUME` | ARN of the IAM role for Bedrock access            |
        | `APP_ID`             | Your GitHub App ID (from app settings)            |
        | `APP_PRIVATE_KEY`    | The private key you generated for your GitHub App |

name: Claude PR Action

permissions: contents: write pull-requests: write issues: write id-token: write

on: issue_comment: types: [created] pull_request_review_comment: types: [created] issues: types: [opened, assigned]

jobs: claude-pr: if: | (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) || (github.event_name == 'issues' && contains(github.event.issue.body, '@claude')) runs-on: ubuntu-latest env: AWS_REGION: us-west-2 steps:

• name: Checkout repository

uses: actions/checkout@v4

• name: Generate GitHub App token

id: app-token uses: actions/create-github-app-token@v2 with: app-id: ${{ secrets.APP_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }}

• name: Configure AWS Credentials (OIDC)

uses: aws-actions/configure-aws-credentials@v4 with: role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }} aws-region: us-west-2

• uses: anthropics/claude-code-action@v1

with: github_token: ${{ steps.app-token.outputs.token }} use_bedrock: "true" claude_args: '--model us.anthropic.claude-sonnet-4-5-20250929-v1:0 --max-turns 10'

        <Tip>
          The model ID format for Bedrock includes the region prefix (e.g., `us.anthropic.claude...`) and version suffix.
        </Tip>
      </Accordion>

      <Accordion title="Google Vertex AI workflow">
        **Prerequisites:**

        * Vertex AI API enabled in your GCP project
        * Workload Identity Federation configured for GitHub
        * Service account with Vertex AI permissions

        **Required GitHub secrets:**

        | Secret Name                      | Description                                       |
        | -------------------------------- | ------------------------------------------------- |
        | `GCP_WORKLOAD_IDENTITY_PROVIDER` | Workload identity provider resource name          |
        | `GCP_SERVICE_ACCOUNT`            | Service account email with Vertex AI access       |
        | `APP_ID`                         | Your GitHub App ID (from app settings)            |
        | `APP_PRIVATE_KEY`                | The private key you generated for your GitHub App |

name: Claude PR Action

permissions: contents: write pull-requests: write issues: write id-token: write

on: issue_comment: types: [created] pull_request_review_comment: types: [created] issues: types: [opened, assigned]

jobs: claude-pr: if: | (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) || (github.event_name == 'issues' && contains(github.event.issue.body, '@claude')) runs-on: ubuntu-latest steps:

• name: Checkout repository

uses: actions/checkout@v4

• name: Generate GitHub App token

id: app-token uses: actions/create-github-app-token@v2 with: app-id: ${{ secrets.APP_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }}

• name: Authenticate to Google Cloud

id: auth uses: google-github-actions/auth@v2 with: workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }} service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}

• uses: anthropics/claude-code-action@v1

with: github_token: ${{ steps.app-token.outputs.token }} trigger_phrase: "@claude" use_vertex: "true" claude_args: '--model claude-sonnet-4@20250514 --max-turns 10' env: ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }} CLOUD_ML_REGION: us-east5 VERTEX_REGION_CLAUDE_3_7_SONNET: us-east5

        <Tip>
          The project ID is automatically retrieved from the Google Cloud authentication step, so you don't need to hardcode it.
        </Tip>
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

## Troubleshooting

### Claude not responding to @claude commands

Verify the GitHub App is installed correctly, check that workflows are enabled, ensure API key is set in repository secrets, and confirm the comment contains `@claude` (not `/claude`).

### CI not running on Claude's commits

Ensure you're using the GitHub App or custom app (not Actions user), check workflow triggers include the necessary events, and verify app permissions include CI triggers.

### Authentication errors

Confirm API key is valid and has sufficient permissions. For Bedrock/Vertex, check credentials configuration and ensure secrets are named correctly in workflows.

## Advanced configuration

### Action parameters

The Claude Code Action v1 uses a simplified configuration:

| Parameter           | Description                                     | Required |
| ------------------- | ----------------------------------------------- | -------- |
| `prompt`            | Instructions for Claude (text or slash command) | No\*     |
| `claude_args`       | CLI arguments passed to Claude Code             | No       |
| `anthropic_api_key` | Claude API key                                  | Yes\*\*  |
| `github_token`      | GitHub token for API access                     | No       |
| `trigger_phrase`    | Custom trigger phrase (default: "@claude")      | No       |
| `use_bedrock`       | Use AWS Bedrock instead of Claude API           | No       |
| `use_vertex`        | Use Google Vertex AI instead of Claude API      | No       |

\*Prompt is optional - when omitted for issue/PR comments, Claude responds to trigger phrase\
\*\*Required for direct Claude API, not for Bedrock/Vertex

#### Using claude\_args

The `claude_args` parameter accepts any Claude Code CLI arguments:

claude_args: "--max-turns 5 --model claude-sonnet-4-5-20250929 --mcp-config /path/to/config.json"

Common arguments:

* `--max-turns`: Maximum conversation turns (default: 10)
* `--model`: Model to use (e.g., `claude-sonnet-4-5-20250929`)
* `--mcp-config`: Path to MCP configuration
* `--allowed-tools`: Comma-separated list of allowed tools
* `--debug`: Enable debug output

### Alternative integration methods

While the `/install-github-app` command is the recommended approach, you can also:

* **Custom GitHub App**: For organizations needing branded usernames or custom authentication flows. Create your own GitHub App with required permissions (contents, issues, pull requests) and use the actions/create-github-app-token action to generate tokens in your workflows.
* **Manual GitHub Actions**: Direct workflow configuration for maximum flexibility
* **MCP Configuration**: Dynamic loading of Model Context Protocol servers

See the [Claude Code Action documentation](https://github.com/anthropics/claude-code-action/blob/main/docs) for detailed guides on authentication, security, and advanced configuration.

### Customizing Claude's behavior

You can configure Claude's behavior in two ways:

1. **CLAUDE.md**: Define coding standards, review criteria, and project-specific rules in a `CLAUDE.md` file at the root of your repository. Claude will follow these guidelines when creating PRs and responding to requests. Check out our [Memory documentation](/en/docs/claude-code/memory) for more details.
2. **Custom prompts**: Use the `prompt` parameter in the workflow file to provide workflow-specific instructions. This allows you to customize Claude's behavior for different workflows or tasks.

Claude will follow these guidelines when creating PRs and responding to requests.

Claude Code GitLab CI/CD

Learn about integrating Claude Code into your development workflow with GitLab CI/CD

<Info> Claude Code for GitLab CI/CD is currently in beta. Features and functionality may evolve as we refine the experience.

This integration is maintained by GitLab. For support, see the following GitLab issue. </Info>

<Note> This integration is built on top of the Claude Code CLI and SDK, enabling programmatic use of Claude in your CI/CD jobs and custom automation workflows. </Note>

Why use Claude Code with GitLab?

• Instant MR creation: Describe what you need, and Claude proposes a complete MR with changes and explanation
• Automated implementation: Turn issues into working code with a single command or mention
• Project-aware: Claude follows your CLAUDE.md guidelines and existing code patterns
• Simple setup: Add one job to .gitlab-ci.yml and a masked CI/CD variable
• Enterprise-ready: Choose Claude API, AWS Bedrock, or Google Vertex AI to meet data residency and procurement needs
• Secure by default: Runs in your GitLab runners with your branch protection and approvals

How it works

Claude Code uses GitLab CI/CD to run AI tasks in isolated jobs and commit results back via MRs:

1. Event-driven orchestration: GitLab listens for your chosen triggers (for example, a comment that mentions @claude in an issue, MR, or review thread). The job collects context from the thread and repository, builds prompts from that input, and runs Claude Code.

2. Provider abstraction: Use the provider that fits your environment:

• Claude API (SaaS)
• AWS Bedrock (IAM-based access, cross-region options)
• Google Vertex AI (GCP-native, Workload Identity Federation)

3. Sandboxed execution: Each interaction runs in a container with strict network and filesystem rules. Claude Code enforces workspace-scoped permissions to constrain writes. Every change flows through an MR so reviewers see the diff and approvals still apply.

Pick regional endpoints to reduce latency and meet data-sovereignty requirements while using existing cloud agreements.

What can Claude do?

Claude Code enables powerful CI/CD workflows that transform how you work with code:

• Create and update MRs from issue descriptions or comments
• Analyze performance regressions and propose optimizations
• Implement features directly in a branch, then open an MR
• Fix bugs and regressions identified by tests or comments
• Respond to follow-up comments to iterate on requested changes

Setup

Quick setup

The fastest way to get started is to add a minimal job to your .gitlab-ci.yml and set your API key as a masked variable.

1. Add a masked CI/CD variable

• Go to Settings → CI/CD → Variables
• Add ANTHROPIC_API_KEY (masked, protected as needed)

2. Add a Claude job to `.gitlab-ci.yml`

```yaml theme={null} stages:

• ai

claude: stage: ai image: node:24-alpine3.21

Adjust rules to fit how you want to trigger the job:

- manual runs

- merge request events

- web/API triggers when a comment contains '@claude'

rules:

• if: '$CI_PIPELINE_SOURCE == "web"'
• if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

variables: GIT_STRATEGY: fetch before_script:

• apk update
• apk add --no-cache git curl bash
• npm install -g @anthropic-ai/claude-code

script:

Optional: start a GitLab MCP server if your setup provides one

• /bin/gitlab-mcp-server || true

Use AI_FLOW_* variables when invoking via web/API triggers with context payloads

• echo "$AI_FLOW_INPUT for $AI_FLOW_CONTEXT on $AI_FLOW_EVENT"
• >

claude -p "${AI_FLOW_INPUT:-'Review this MR and implement the requested changes'}" --permission-mode acceptEdits --allowedTools "Bash() Read() Edit() Write() mcp__gitlab" --debug

After adding the job and your `ANTHROPIC_API_KEY` variable, test by running the job manually from **CI/CD** → **Pipelines**, or trigger it from an MR to let Claude propose updates in a branch and open an MR if needed.

<Note>
  To run on AWS Bedrock or Google Vertex AI instead of the Claude API, see the [Using with AWS Bedrock & Google Vertex AI](#using-with-aws-bedrock--google-vertex-ai) section below for authentication and environment setup.
</Note>

### Manual setup (recommended for production)

If you prefer a more controlled setup or need enterprise providers:

1. **Configure provider access**:
   * **Claude API**: Create and store `ANTHROPIC_API_KEY` as a masked CI/CD variable
   * **AWS Bedrock**: **Configure GitLab** → **AWS OIDC** and create an IAM role for Bedrock
   * **Google Vertex AI**: **Configure Workload Identity Federation for GitLab** → **GCP**

2. **Add project credentials for GitLab API operations**:
   * Use `CI_JOB_TOKEN` by default, or create a Project Access Token with `api` scope
   * Store as `GITLAB_ACCESS_TOKEN` (masked) if using a PAT

3. **Add the Claude job to `.gitlab-ci.yml`** (see examples below)

4. **(Optional) Enable mention-driven triggers**:
   * Add a project webhook for "Comments (notes)" to your event listener (if you use one)
   * Have the listener call the pipeline trigger API with variables like `AI_FLOW_INPUT` and `AI_FLOW_CONTEXT` when a comment contains `@claude`

## Example use cases

### Turn issues into MRs

In an issue comment:

@claude implement this feature based on the issue description

Claude analyzes the issue and codebase, writes changes in a branch, and opens an MR for review.

### Get implementation help

In an MR discussion:

@claude suggest a concrete approach to cache the results of this API call

Claude proposes changes, adds code with appropriate caching, and updates the MR.

### Fix bugs quickly

In an issue or MR comment:

@claude fix the TypeError in the user dashboard component

Claude locates the bug, implements a fix, and updates the branch or opens a new MR.

## Using with AWS Bedrock & Google Vertex AI

For enterprise environments, you can run Claude Code entirely on your cloud infrastructure with the same developer experience.

<Tabs>
  <Tab title="AWS Bedrock">
    ### Prerequisites

    Before setting up Claude Code with AWS Bedrock, you need:

    1. An AWS account with Amazon Bedrock access to the desired Claude models
    2. GitLab configured as an OIDC identity provider in AWS IAM
    3. An IAM role with Bedrock permissions and a trust policy restricted to your GitLab project/refs
    4. GitLab CI/CD variables for role assumption:
       * `AWS_ROLE_TO_ASSUME` (role ARN)
       * `AWS_REGION` (Bedrock region)

    ### Setup instructions

    Configure AWS to allow GitLab CI jobs to assume an IAM role via OIDC (no static keys).

    **Required setup:**

    1. Enable Amazon Bedrock and request access to your target Claude models
    2. Create an IAM OIDC provider for GitLab if not already present
    3. Create an IAM role trusted by the GitLab OIDC provider, restricted to your project and protected refs
    4. Attach least-privilege permissions for Bedrock invoke APIs

    **Required values to store in CI/CD variables:**

    * `AWS_ROLE_TO_ASSUME`
    * `AWS_REGION`

    Add variables in Settings → CI/CD → Variables:

For AWS Bedrock:

• AWS_ROLE_TO_ASSUME
• AWS_REGION

    Use the AWS Bedrock job example above to exchange the GitLab job token for temporary AWS credentials at runtime.
  </Tab>

  <Tab title="Google Vertex AI">
    ### Prerequisites

    Before setting up Claude Code with Google Vertex AI, you need:

    1. A Google Cloud project with:
       * Vertex AI API enabled
       * Workload Identity Federation configured to trust GitLab OIDC
    2. A dedicated service account with only the required Vertex AI roles
    3. GitLab CI/CD variables for WIF:
       * `GCP_WORKLOAD_IDENTITY_PROVIDER` (full resource name)
       * `GCP_SERVICE_ACCOUNT` (service account email)

    ### Setup instructions

    Configure Google Cloud to allow GitLab CI jobs to impersonate a service account via Workload Identity Federation.

    **Required setup:**

    1. Enable IAM Credentials API, STS API, and Vertex AI API
    2. Create a Workload Identity Pool and provider for GitLab OIDC
    3. Create a dedicated service account with Vertex AI roles
    4. Grant the WIF principal permission to impersonate the service account

    **Required values to store in CI/CD variables:**

    * `GCP_WORKLOAD_IDENTITY_PROVIDER`
    * `GCP_SERVICE_ACCOUNT`

    Add variables in Settings → CI/CD → Variables:

For Google Vertex AI:

• GCP_WORKLOAD_IDENTITY_PROVIDER
• GCP_SERVICE_ACCOUNT
• CLOUD_ML_REGION (for example, us-east5)

    Use the Google Vertex AI job example above to authenticate without storing keys.
  </Tab>
</Tabs>

## Configuration examples

Below are ready-to-use snippets you can adapt to your pipeline.

### Basic .gitlab-ci.yml (Claude API)

stages:

• ai

claude: stage: ai image: node:24-alpine3.21 rules:

• if: '$CI_PIPELINE_SOURCE == "web"'
• if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

variables: GIT_STRATEGY: fetch before_script:

• apk update
• apk add --no-cache git curl bash
• npm install -g @anthropic-ai/claude-code

script:

• /bin/gitlab-mcp-server || true
• >

claude -p "${AI_FLOW_INPUT:-'Summarize recent changes and suggest improvements'}" --permission-mode acceptEdits --allowedTools "Bash() Read() Edit() Write() mcp__gitlab" --debug

Claude Code will use ANTHROPIC_API_KEY from CI/CD variables

### AWS Bedrock job example (OIDC)

**Prerequisites:**

* Amazon Bedrock enabled with access to your chosen Claude model(s)
* GitLab OIDC configured in AWS with a role that trusts your GitLab project and refs
* IAM role with Bedrock permissions (least privilege recommended)

**Required CI/CD variables:**

* `AWS_ROLE_TO_ASSUME`: ARN of the IAM role for Bedrock access
* `AWS_REGION`: Bedrock region (for example, `us-west-2`)

claude-bedrock: stage: ai image: node:24-alpine3.21 rules:

• if: '$CI_PIPELINE_SOURCE == "web"'

before_script:

• apk add --no-cache bash curl jq git python3 py3-pip
• pip install --no-cache-dir awscli
• npm install -g @anthropic-ai/claude-code

Exchange GitLab OIDC token for AWS credentials

• export AWS_WEB_IDENTITY_TOKEN_FILE="${CI_JOB_JWT_FILE:-/tmp/oidc_token}"
• if [ -n "${CI_JOB_JWT_V2}" ]; then printf "%s" "$CI_JOB_JWT_V2" > "$AWS_WEB_IDENTITY_TOKEN_FILE"; fi
• >

aws sts assume-role-with-web-identity --role-arn "$AWS_ROLE_TO_ASSUME" --role-session-name "gitlab-claude-$(date +%s)" --web-identity-token "file://$AWS_WEB_IDENTITY_TOKEN_FILE" --duration-seconds 3600 > /tmp/aws_creds.json

• export AWS_ACCESS_KEY_ID="$(jq -r .Credentials.AccessKeyId /tmp/aws_creds.json)"
• export AWS_SECRET_ACCESS_KEY="$(jq -r .Credentials.SecretAccessKey /tmp/aws_creds.json)"
• export AWS_SESSION_TOKEN="$(jq -r .Credentials.SessionToken /tmp/aws_creds.json)"

script:

• /bin/gitlab-mcp-server || true
• >

claude -p "${AI_FLOW_INPUT:-'Implement the requested changes and open an MR'}" --permission-mode acceptEdits --allowedTools "Bash() Read() Edit() Write() mcp__gitlab" --debug variables: AWS_REGION: "us-west-2"

<Note>
  Model IDs for Bedrock include region-specific prefixes and version suffixes (for example, `us.anthropic.claude-3-7-sonnet-20250219-v1:0`). Pass the desired model via your job configuration or prompt if your workflow supports it.
</Note>

### Google Vertex AI job example (Workload Identity Federation)

**Prerequisites:**

* Vertex AI API enabled in your GCP project
* Workload Identity Federation configured to trust GitLab OIDC
* A service account with Vertex AI permissions

**Required CI/CD variables:**

* `GCP_WORKLOAD_IDENTITY_PROVIDER`: Full provider resource name
* `GCP_SERVICE_ACCOUNT`: Service account email
* `CLOUD_ML_REGION`: Vertex region (for example, `us-east5`)

claude-vertex: stage: ai image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim rules:

• if: '$CI_PIPELINE_SOURCE == "web"'

before_script:

• apt-get update && apt-get install -y git nodejs npm && apt-get clean
• npm install -g @anthropic-ai/claude-code

Authenticate to Google Cloud via WIF (no downloaded keys)

• >

gcloud auth login --cred-file=<(cat <<EOF { "type": "external_account", "audience": "${GCP_WORKLOAD_IDENTITY_PROVIDER}", "subject_token_type": "urn:ietf:params:oauth:token-type:jwt", "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${GCP_SERVICE_ACCOUNT}:generateAccessToken", "token_url": "https://sts.googleapis.com/v1/token" } EOF )

• gcloud config set project "$(gcloud projects list --format='value(projectId)' --filter="name:${CI_PROJECT_NAMESPACE}" | head -n1)" || true

script:

• /bin/gitlab-mcp-server || true
• >

CLOUD_ML_REGION="${CLOUD_ML_REGION:-us-east5}" claude -p "${AI_FLOW_INPUT:-'Review and update code as requested'}" --permission-mode acceptEdits --allowedTools "Bash() Read() Edit() Write() mcp__gitlab" --debug variables: CLOUD_ML_REGION: "us-east5"

<Note>
  With Workload Identity Federation, you do not need to store service account keys. Use repository-specific trust conditions and least-privilege service accounts.
</Note>

## Best practices

### CLAUDE.md configuration

Create a `CLAUDE.md` file at the repository root to define coding standards, review criteria, and project-specific rules. Claude reads this file during runs and follows your conventions when proposing changes.

### Security considerations

Never commit API keys or cloud credentials to your repository! Always use GitLab CI/CD variables:

* Add `ANTHROPIC_API_KEY` as a masked variable (and protect it if needed)
* Use provider-specific OIDC where possible (no long-lived keys)
* Limit job permissions and network egress
* Review Claude's MRs like any other contributor

### Optimizing performance

* Keep `CLAUDE.md` focused and concise
* Provide clear issue/MR descriptions to reduce iterations
* Configure sensible job timeouts to avoid runaway runs
* Cache npm and package installs in runners where possible

### CI costs

When using Claude Code with GitLab CI/CD, be aware of associated costs:

* **GitLab Runner time**:
  * Claude runs on your GitLab runners and consumes compute minutes
  * See your GitLab plan's runner billing for details

* **API costs**:
  * Each Claude interaction consumes tokens based on prompt and response size
  * Token usage varies by task complexity and codebase size
  * See [Anthropic pricing](/en/docs/about-claude/pricing) for details

* **Cost optimization tips**:
  * Use specific `@claude` commands to reduce unnecessary turns
  * Set appropriate `max_turns` and job timeout values
  * Limit concurrency to control parallel runs

## Security and governance

* Each job runs in an isolated container with restricted network access
* Claude's changes flow through MRs so reviewers see every diff
* Branch protection and approval rules apply to AI-generated code
* Claude Code uses workspace-scoped permissions to constrain writes
* Costs remain under your control because you bring your own provider credentials

## Troubleshooting

### Claude not responding to @claude commands

* Verify your pipeline is being triggered (manually, MR event, or via a note event listener/webhook)
* Ensure CI/CD variables (`ANTHROPIC_API_KEY` or cloud provider settings) are present and unmasked
* Check that the comment contains `@claude` (not `/claude`) and that your mention trigger is configured

### Job can't write comments or open MRs

* Ensure `CI_JOB_TOKEN` has sufficient permissions for the project, or use a Project Access Token with `api` scope
* Check the `mcp__gitlab` tool is enabled in `--allowedTools`
* Confirm the job runs in the context of the MR or has enough context via `AI_FLOW_*` variables

### Authentication errors

* **For Claude API**: Confirm `ANTHROPIC_API_KEY` is valid and unexpired
* **For Bedrock/Vertex**: Verify OIDC/WIF configuration, role impersonation, and secret names; confirm region and model availability

## Advanced configuration

### Common parameters and variables

Claude Code supports these commonly used inputs:

* `prompt` / `prompt_file`: Provide instructions inline (`-p`) or via a file
* `max_turns`: Limit the number of back-and-forth iterations
* `timeout_minutes`: Limit total execution time
* `ANTHROPIC_API_KEY`: Required for the Claude API (not used for Bedrock/Vertex)
* Provider-specific environment: `AWS_REGION`, project/region vars for Vertex

<Note>
  Exact flags and parameters may vary by version of `@anthropic-ai/claude-code`. Run `claude --help` in your job to see supported options.
</Note>

### Customizing Claude's behavior

You can guide Claude in two primary ways:

1. **CLAUDE.md**: Define coding standards, security requirements, and project conventions. Claude reads this during runs and follows your rules.
2. **Custom prompts**: Pass task-specific instructions via `prompt`/`prompt_file` in the job. Use different prompts for different jobs (for example, review, implement, refactor).

Claude Code on Google Vertex AI

Learn about configuring Claude Code through Google Vertex AI, including setup, IAM configuration, and troubleshooting.

Prerequisites

Before configuring Claude Code with Vertex AI, ensure you have:

• A Google Cloud Platform (GCP) account with billing enabled
• A GCP project with Vertex AI API enabled
• Access to desired Claude models (e.g., Claude Sonnet 4.5)
• Google Cloud SDK (gcloud) installed and configured
• Quota allocated in desired GCP region

Region Configuration

Claude Code can be used with both Vertex AI global and regional endpoints.

<Note> Vertex AI may not support the Claude Code default models on all regions. You may need to switch to a supported region or model. </Note>

<Note> Vertex AI may not support the Claude Code default models on global endpoints. You may need to switch to a regional endpoint or supported model. </Note>

Setup

1. Enable Vertex AI API

Enable the Vertex AI API in your GCP project:

```bash theme={null}

Set your project ID

gcloud config set project YOUR-PROJECT-ID

Enable Vertex AI API

gcloud services enable aiplatform.googleapis.com

### 2. Request model access

Request access to Claude models in Vertex AI:

1. Navigate to the [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)
2. Search for "Claude" models
3. Request access to desired Claude models (e.g., Claude Sonnet 4.5)
4. Wait for approval (may take 24-48 hours)

### 3. Configure GCP credentials

Claude Code uses standard Google Cloud authentication.

For more information, see [Google Cloud authentication documentation](https://cloud.google.com/docs/authentication).

<Note>
  When authenticating, Claude Code will automatically use the project ID from the `ANTHROPIC_VERTEX_PROJECT_ID` environment variable. To override this, set one of these environment variables: `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT`, or `GOOGLE_APPLICATION_CREDENTIALS`.
</Note>

### 4. Configure Claude Code

Set the following environment variables:

Enable Vertex AI integration

export CLAUDE_CODE_USE_VERTEX=1 export CLOUD_ML_REGION=global export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

Optional: Disable prompt caching if needed

export DISABLE_PROMPT_CACHING=1

When CLOUD_ML_REGION=global, override region for unsupported models

export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

Optional: Override regions for other specific models

export VERTEX_REGION_CLAUDE_3_5_SONNET=us-east5 export VERTEX_REGION_CLAUDE_3_7_SONNET=us-east5 export VERTEX_REGION_CLAUDE_4_0_OPUS=europe-west1 export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5 export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west1

<Note>
  [Prompt caching](/en/docs/build-with-claude/prompt-caching) is automatically supported when you specify the `cache_control` ephemeral flag. To disable it, set `DISABLE_PROMPT_CACHING=1`. For heightened rate limits, contact Google Cloud support.
</Note>

<Note>
  When using Vertex AI, the `/login` and `/logout` commands are disabled since authentication is handled through Google Cloud credentials.
</Note>

### 5. Model configuration

Claude Code uses these default models for Vertex AI:

| Model type       | Default value                |
| :--------------- | :--------------------------- |
| Primary model    | `claude-sonnet-4-5@20250929` |
| Small/fast model | `claude-haiku-4-5@20251001`  |

<Note>
  For Vertex AI users, Claude Code will not automatically upgrade from Haiku 3.5 to Haiku 4.5. To manually switch to a newer Haiku model, set the `ANTHROPIC_DEFAULT_HAIKU_MODEL` environment variable to the full model name (e.g., `claude-haiku-4-5@20251001`).
</Note>

To customize models:

export ANTHROPIC_MODEL='claude-opus-4-1@20250805' export ANTHROPIC_SMALL_FAST_MODEL='claude-haiku-4-5@20251001'

## IAM configuration

Assign the required IAM permissions:

The `roles/aiplatform.user` role includes the required permissions:

* `aiplatform.endpoints.predict` - Required for model invocation
* `aiplatform.endpoints.computeTokens` - Required for token counting

For more restrictive permissions, create a custom role with only the permissions above.

For details, see [Vertex IAM documentation](https://cloud.google.com/vertex-ai/docs/general/access-control).

<Note>
  We recommend creating a dedicated GCP project for Claude Code to simplify cost tracking and access control.
</Note>

### 1M token context window

Claude Sonnet 4 and Sonnet 4.5 support the [1M token context window](/en/docs/build-with-claude/context-windows#1m-token-context-window) on Vertex AI.

<Note>
  The 1M token context window is currently in beta. To use the extended context window, include the `context-1m-2025-08-07` beta header in your Vertex AI requests.
</Note>

## Troubleshooting

If you encounter quota issues:

* Check current quotas or request quota increase through [Cloud Console](https://cloud.google.com/docs/quotas/view-manage)

If you encounter "model not found" 404 errors:

* Confirm model is Enabled in [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)
* Verify you have access to the specified region
* If using `CLOUD_ML_REGION=global`, check that your models support global endpoints in [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) under "Supported features". For models that don't support global endpoints, either:
  * Specify a supported model via `ANTHROPIC_MODEL` or `ANTHROPIC_SMALL_FAST_MODEL`, or
  * Set a regional endpoint using `VERTEX_REGION_<MODEL_NAME>` environment variables

If you encounter 429 errors:

* For regional endpoints, ensure the primary model and small/fast model are supported in your selected region
* Consider switching to `CLOUD_ML_REGION=global` for better availability

## Additional resources

* [Vertex AI documentation](https://cloud.google.com/vertex-ai/docs)
* [Vertex AI pricing](https://cloud.google.com/vertex-ai/pricing)
* [Vertex AI quotas and limits](https://cloud.google.com/vertex-ai/docs/quotas)

Legal and compliance

Legal agreements, compliance certifications, and security information for Claude Code.

Legal agreements

License

Your use of Claude Code is subject to:

• Commercial Terms - for Team, Enterprise, and Claude API users
• Consumer Terms - for Free, Pro, and Max users

Commercial agreements

Whether you're using the Claude API directly (1P) or accessing it through AWS Bedrock or Google Vertex (3P), your existing commercial agreement will apply to Claude Code usage, unless we've mutually agreed otherwise.

Compliance

Healthcare compliance (BAA)

If a customer has a Business Associate Agreement (BAA) with us, and wants to use Claude Code, the BAA will automatically extend to cover Claude Code if the customer has executed a BAA and has Zero Data Retention (ZDR) activated. The BAA will be applicable to that customer's API traffic flowing through Claude Code.

Security and trust

Trust and safety

You can find more information in the Anthropic Trust Center and Transparency Hub.

Security vulnerability reporting

Anthropic manages our security program through HackerOne. Use this form to report vulnerabilities.

***

© Anthropic PBC. All rights reserved. Use is subject to applicable Anthropic Terms of Service.