Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation SDK references Agent SDK reference - TypeScript Agent SDK Overview Quickstart Core concepts How the agent loop works Use Claude Code features Work with sessions Input and output Streaming Input Handle approvals and user input Stream responses in real-time Get structured output from agents Extend with tools Give Claude custom tools Connect to external tools with MCP Scale to many tools with tool search Subagents in the SDK Customize behavior Modifying system prompts Slash Commands in the SDK Agent Skills in the SDK Plugins in the SDK Control and observability Configure permissions Intercept and control agent behavior with hooks Rewind file changes with checkpointing Track cost and usage Observability with OpenTelemetry Todo Lists Deployment Hosting the Agent SDK Securely deploying AI agents SDK references TypeScript SDK TypeScript V2 (deprecated) Python SDK Migration Guide Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. ​ Installation npm install @anthropic-ai/claude-agent-sdk The SDK bundles a native Claude Code binary for your platform as an optional dependency such as @anthropic-ai/claude-agent-sdk-darwin-arm64 . You don’t need to install Claude Code separately. If your package manager skips optional dependencies, the SDK throws Native CLI binary for not found ; set pathToClaudeCodeExecutable to a separately installed claude binary instead. ​ Functions ​ query() The primary function for interacting with Claude Code. Creates an async generator that streams messages as they arrive. function query ({ prompt , options } : { prompt : string | AsyncIterable < SDKUserMessage >; options ?: Options ; }) : Query ; ​ Parameters Parameter Type Description prompt string | AsyncIterable< SDKUserMessage > The input prompt as a string or async iterable for streaming mode options Options Optional configuration object (see Options type below) ​ Returns Returns a Query object that extends AsyncGenerator< SDKMessage , void> with additional methods. ​ startup() Pre-warms the CLI subprocess by spawning it and completing the initialize handshake before a prompt is available. The returned WarmQuery handle accepts a prompt later and writes it to an already-ready process, so the first query() call resolves without paying subprocess spawn and initialization cost inline. function startup ( params ?: { options ?: Options ; initializeTimeoutMs ?: number ; }) : Promise < WarmQuery >; ​ Parameters Parameter Type Description options Options Optional configuration object. Same as the options parameter to query() initializeTimeoutMs number Maximum time in milliseconds to wait for subprocess initialization. Defaults to 60000 . If initialization does not complete in time, the promise rejects with a timeout error ​ Returns Returns a Promise< WarmQuery > that resolves once the subprocess has spawned and completed its initialize handshake. ​ Example Call startup() early, for example on application boot, then call .query() on the returned handle once a prompt is ready. This moves subprocess spawn and initialization out of the critical path. import { startup } from "@anthropic-ai/claude-agent-sdk" ; // Pay startup cost upfront const warm = await startup ({ options: { maxTurns: 3 } }); // Later, when a prompt is ready, this is immediate for await ( const message of warm . query ( "What files are here?" )) { console . log ( message ); } ​ tool() Creates a type-safe MCP tool definition for use with SDK MCP servers. function tool < Schema extends AnyZodRawShape >( name : string , description : string , inputSchema : Schema , handler : ( args : InferShape < Schema >, extra : unknown ) => Promise < CallToolResult >, extras ?: { annotations ?: ToolAnnotations } ) : SdkMcpToolDefinition < Schema >; ​ Parameters Parameter Type Description name string The name of the tool description string A description of what the tool does inputSchema Schema extends AnyZodRawShape Zod schema defining the tool’s input parameters (supports both Zod 3 and Zod 4) handler (args, extra) => Promise< CallToolResult > Async function that executes the tool logic extras { annotations?: ToolAnnotations } Optional MCP tool annotations providing behavioral hints to clients ​ ToolAnnotations Re-exported from @modelcontextprotocol/sdk/types.js . All fields are optional hints; clients should not rely on them for security decisions. Field Type Default Description title string undefined Human-readable title for the tool readOnlyHint boolean false If true , the tool does not modify its environment destructiveHint boolean true If true , the tool may perform destructive updates (only meaningful when readOnlyHint is false ) idempotentHint boolean false If true , repeated calls with the same arguments have no additional effect (only meaningful when readOnlyHint is false ) openWorldHint boolean true If true , the tool interacts with external entities (for example, web search). If false , the tool’s domain is closed (for example, a memory tool) import { tool } from "@anthropic-ai/claude-agent-sdk" ; import { z } from "zod" ; const searchTool = tool ( "search" , "Search the web" , { query: z . string () }, async ({ query }) => { return { content: [{ type: "text" , text: `Results for: ${ query } ` }] }; }, { annotations: { readOnlyHint: true , openWorldHint: true } } ); ​ createSdkMcpServer() Creates an MCP server instance that runs in the same process as your application. function createSdkMcpServer ( options : { name : string ; version ?: string ; tools ?: Array < SdkMcpToolDefinition < any >>; }) : McpSdkServerConfigWithInstance ; ​ Parameters Parameter Type Description options.name string The name of the MCP server options.version string Optional version string options.tools Array Array of tool definitions created with tool() ​ listSessions() Discovers and lists past sessions with light metadata. Filter by project directory or list sessions across all projects. function listSessions ( options ?: ListSessionsOptions ) : Promise < SDKSessionInfo []>; ​ Parameters Parameter Type Default Description options.dir string undefined Directory to list sessions for. When omitted, returns sessions across all projects options.limit number undefined Maximum number of sessions to return options.includeWorktrees boolean true When dir is inside a git repository, include sessions from all worktree paths ​ Return type: SDKSessionInfo Property Type Description sessionId string Unique session identifier (UUID) summary string Display title: custom title, auto-generated summary, or first prompt lastModified number Last modified time in milliseconds since epoch fileSize number | undefined Session file size in bytes. Only populated for local JSONL storage customTitle string | undefined User-set session title (via /rename ) firstPrompt string | undefined First meaningful user prompt in the session gitBranch string | undefined Git branch at the end of the session cwd string | undefined Working directory for the session tag string | undefined User-set session tag (see tagSession() ) createdAt number | undefined Creation time in milliseconds since epoch, from the first entry’s timestamp ​ Example Print the 10 most recent sessions for a project. Results are sorted by lastModified descending, so the first item is the newest. Omit dir to search across all projects. import { listSessions } from "@anthropic-ai/claude-agent-sdk" ; const sessions = await listSessions ({ dir: "/path/to/project" , limit: 10 }); for ( const session of sessions ) { console . log ( ` ${ session . summary } ( ${ session . sessionId } )` ); } ​ getSessionMessages() Reads user and assistant messages from a past session transcript. function getSessionMessages ( sessionId : string , options ?: GetSessionMessagesOptions ) : Promise < SessionMessage []>; ​ Parameters Parameter Type Default Description sessionId string required Session UUID to read (see listSessions() ) options.dir string undefined Project directory to find the session in. When omitted, searches all projects options.limit number undefined Maximum number of messages to return options.offset number undefined Number of messages to skip from the start ​ Return type: SessionMessage Property Type Description type "user" | "assistant" Message role uuid string Unique message identifier session_id string Session this message belongs to message unknown Raw message payload from the transcript parent_tool_use_id null Reserved ​ Example import { listSessions , getSessionMessages } from "@anthropic-ai/claude-agent-sdk" ; const [ latest ] = await listSessions ({ dir: "/path/to/project" , limit: 1 }); if ( latest ) { const messages = await getSessionMessages ( latest . sessionId , { dir: "/path/to/project" , limit: 20 }); for ( const msg of messages ) { console . log ( `[ ${ msg . type } ] ${ msg . uuid } ` ); } } ​ getSessionInfo() Reads metadata for a single session by ID without scanning the full project directory. function getSessionInfo ( sessionId : string , options ?: GetSessionInfoOptions ) : Promise < SDKSessionInfo | undefined >; ​ Parameters Parameter Type Default Description sessionId string required UUID of the session to look up options.dir string undefined Project directory path. When omitted, searches all project directories Returns SDKSessionInfo , or undefined if the session is not found. ​ renameSession() Renames a session by appending a custom-title entry. Repeated calls are safe; the most recent title wins. function renameSession ( sessionId : string , title : string , options ?: SessionMutationOptions ) : Promise < void >; ​ Parameters Parameter Type Default Description sessionId string required UUID of the session to rename title string required New title. Must be non-empty after trimming whitespace options.dir string undefined Project directory path. When omitted, searches all project directories ​ tagSession() Tags a session. Pass null to clear the tag. Repeated calls are safe; the most recent tag wins. function tagSession ( sessionId : string , tag : string | null , options ?: SessionMutationOptions ) : Promise < void >; ​ Parameters Parameter Type Default Description sessionId string required UUID of the session to tag tag string | null required Tag string, or null to clear options.dir string undefined Project directory path. When omitted, searches all project directories ​ resolveSettings() Resolves the effective Claude Code settings for a given directory using the same merge engine as the CLI, without spawning the Claude CLI. Use it to inspect what configuration a query() call would see before invoking one. This function is alpha and its API may change before stabilization. It reads MDM sources, including macOS plist and Windows HKLM/HKCU, for parity with CLI startup, but does not execute the admin-configured policyHelper subprocess. The permissions.defaultMode field is returned as-is from all tiers including project settings. The trust filter the CLI applies before honoring escalating permission modes is not applied. function resolveSettings ( options ?: ResolveSettingsOptions ) : Promise < ResolvedSettings >; ​ Parameters resolveSettings() accepts a single options object. All fields are optional. Parameter Type Default Description options.cwd string process.cwd() Directory to resolve project and local settings relative to options.settingSources SettingSource [] All sources Which filesystem sources to load. Pass [] to skip user, project, and local settings. Managed policy settings load in all cases options.managedSettings Settings undefined Restrictive policy-tier settings supplied by the embedding host. Dropped by default when an admin-deployed managed tier is present; merged under that tier when parentSettingsBehavior is "merge" . Non-restrictive keys such as model are silently dropped so this option can tighten managed policy but not loosen it options.serverManagedSettings Settings undefined Server-managed settings payload from /api/claude_code/settings . Non-restrictive keys pass through unfiltered ​ Return type: ResolvedSettings resolveSettings() returns an object describing the merged settings and the source that contributed each key. Property Type Description effective Settings Merged settings after applying all enabled sources in precedence order provenance Partial> For each top-level key in effective , which source supplied the value sources Array<{ source, settings, path?, policyOrigin? }> Per-source raw settings, ordered from lowest to highest precedence ​ Example The example below resolves settings for a project directory and prints the source that controls the cleanup period. import { resolveSettings } from "@anthropic-ai/claude-agent-sdk" ; const { effective , provenance } = await resolveSettings ({ cwd: "/path/to/project" , settingSources: [ "user" , "project" , "local" ], }); console . log ( `Cleanup period: ${ effective . cleanupPeriodDays } days` ); console . log ( `Set by: ${ provenance . cleanupPeriodDays ?. source } ` ); ​ Types ​ Options Configuration object for the query() function. Property Type Default Description abortController AbortController new AbortController() Controller for cancelling operations additionalDirectories string[] [] Additional directories Claude can access agent string undefined Agent name for the main thread. The agent must be defined in the agents option or in settings agents Record undefined Programmatically define subagents allowDangerouslySkipPermissions boolean false Enable bypassing permissions. Required when using permissionMode: 'bypassPermissions' allowedTools string[] [] Tools to auto-approve without prompting. This does not restrict Claude to only these tools; unlisted tools fall through to permissionMode and canUseTool . Use disallowedTools to block tools. See Permissions betas SdkBeta [] [] Enable beta features canUseTool CanUseTool undefined Custom permission function for tool usage continue boolean false Continue the most recent conversation cwd string process.cwd() Current working directory debug boolean false Enable debug mode for the Claude Code process debugFile string undefined Write debug logs to a specific file path. Implicitly enables debug mode disallowedTools string[] [] Tools to always deny. Deny rules are checked first and override allowedTools and permissionMode (including bypassPermissions ) effort 'low' | 'medium' | 'high' | 'xhigh' | 'max' 'high' Controls how much effort Claude puts into its response. Works with adaptive thinking to guide thinking depth enableFileCheckpointing boolean false Enable file change tracking for rewinding. See File checkpointing env Record process.env Environment variables. See Environment variables for variables the underlying CLI reads, and Handle slow or stalled API responses for timeout-related variables. Set CLAUDE_AGENT_SDK_CLIENT_APP to identify your app in the User-Agent header executable 'bun' | 'deno' | 'node' Auto-detected JavaScript runtime to use executableArgs string[] [] Arguments to pass to the executable extraArgs Record {} Additional arguments fallbackModel string undefined Model to use if primary fails forkSession boolean false When resuming with resume , fork to a new session ID instead of continuing the original session hooks Partial> {} Hook callbacks for events includeHookEvents boolean false Include hook lifecycle events in the message stream as SDKHookStartedMessage , SDKHookProgressMessage , and SDKHookResponseMessage includePartialMessages boolean false Include partial message events maxBudgetUsd number undefined Stop the query when the client-side cost estimate reaches this USD value. Compared against the same estimate as total_cost_usd ; see Track cost and usage for accuracy caveats maxThinkingTokens number undefined Deprecated: Use thinking instead. Maximum tokens for thinking process maxTurns number undefined Maximum agentic turns (tool-use round trips) mcpServers Record {} MCP server configurations model string Default from CLI Claude model to use outputFormat { type: 'json_schema', schema: JSONSchema } undefined Define output format for agent results. See Structured outputs for details outputStyle string undefined Name of an output style to activate for the session. The style must exist in a loaded settingSources location, such as .claude/output-styles/ . See Activate an output style pathToClaudeCodeExecutable string Auto-resolved from bundled native binary Path to Claude Code executable. Only needed if optional dependencies were skipped during install or your platform isn’t in the supported set permissionMode PermissionMode 'default' Permission mode for the session permissionPromptToolName string undefined MCP tool name for permission prompts persistSession boolean true When false , disables session persistence to disk. Sessions cannot be resumed later plugins SdkPluginConfig [] [] Load custom plugins from local paths. See Plugins for details promptSuggestions boolean false Enable prompt suggestions. Emits a prompt_suggestion message after each turn with a predicted next user prompt resume string undefined Session ID to resume resumeSessionAt string undefined Resume session at a specific message UUID sandbox SandboxSettings undefined Configure sandbox behavior programmatically. See Sandbox settings for details sessionId string Auto-generated Use a specific UUID for the session instead of auto-generating one sessionStore SessionStore undefined Mirror session transcripts to an external backend so any host can resume them. See Persist sessions to external storage settings string | Settings undefined Inline settings object or path to a settings file. Populates the flag-settings layer in the precedence order . Change at runtime with applyFlagSettings() settingSources SettingSource [] CLI defaults (all sources) Control which filesystem settings to load. Pass [] to disable user, project, and local settings. Managed policy settings load regardless. See Use Claude Code features skills string[] | 'all' undefined Skills available to the session. Pass 'all' to enable every discovered skill, or a list of skill names. When set, the SDK enables the Skill tool automatically without listing it in allowedTools . See Skills spawnClaudeCodeProcess (options: SpawnOptions) => SpawnedProcess undefined Custom function to spawn the Claude Code process. Use to run Claude Code in VMs, containers, or remote environments stderr (data: string) => void undefined Callback for stderr output strictMcpConfig boolean false Enforce strict MCP validation systemPrompt string | { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean } undefined (minimal prompt) System prompt configuration. Pass a string for custom prompt, or { type: 'preset', preset: 'claude_code' } to use Claude Code’s system prompt. When using the preset object form, add append to extend it with additional instructions, and set excludeDynamicSections: true to move per-session context into the first user message for better prompt-cache reuse across machines thinking ThinkingConfig { type: 'adaptive' } for supported models Controls Claude’s thinking/reasoning behavior. See ThinkingConfig for options toolConfig ToolConfig undefined Configuration for built-in tool behavior. See ToolConfig for details tools string[] | { type: 'preset'; preset: 'claude_code' } undefined Tool configuration. Pass an array of tool names or use the preset to get Claude Code’s default tools ​ Handle slow or stalled API responses The CLI subprocess reads several environment variables that control API timeouts and stall detection. Pass them through the env option: const result = query ({ prompt: "Analyze this code" , options: { env: { ... process . env , API_TIMEOUT_MS: "120000" , CLAUDE_CODE_MAX_RETRIES: "2" , CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: "120000" , }, }, }); API_TIMEOUT_MS : per-request timeout on the Anthropic client, in milliseconds. Default 600000 . Applies to the main loop and all subagents. CLAUDE_CODE_MAX_RETRIES : maximum API retries. Default 10 . Each retry gets its own API_TIMEOUT_MS window, so worst-case wall time is roughly API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1) plus backoff. CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS : stall watchdog for subagents launched with run_in_background . Default 600000 . Resets on each stream event; on stall it aborts the subagent, marks the task failed, and surfaces the error to the parent with any partial result. Does not apply to synchronous subagents. CLAUDE_ENABLE_STREAM_WATCHDOG=1 with CLAUDE_STREAM_IDLE_TIMEOUT_MS : aborts the request when headers have arrived but the response body stops streaming. Off by default. CLAUDE_STREAM_IDLE_TIMEOUT_MS defaults to 300000 and is clamped to that minimum. The aborted request goes through the normal retry path. ​ Query object Interface returned by the query() function. interface Query extends AsyncGenerator < SDKMessage , void > { interrupt () : Promise < void >; rewindFiles ( userMessageId : string , options ?: { dryRun ?: boolean } ) : Promise < RewindFilesResult >; setPermissionMode ( mode : PermissionMode ) : Promise < void >; setModel ( model ?: string ) : Promise < void >; setMaxThinkingTokens ( maxThinkingTokens : number | null ) : Promise < void >; applyFlagSettings ( settings : { [ K in keyof Settings ] ?: Settings [ K ] | null }) : Promise < void >; initializationResult () : Promise < SDKControlInitializeResponse >; supportedCommands () : Promise < SlashCommand []>; supportedModels () : Promise < ModelInfo []>; supportedAgents () : Promise < AgentInfo []>; mcpServerStatus () : Promise < McpServerStatus []>; accountInfo () : Promise < AccountInfo >; reconnectMcpServer ( serverName : string ) : Promise < void >; toggleMcpServer ( serverName : string , enabled : boolean ) : Promise < void >; setMcpServers ( servers : Record < string , McpServerConfig >) : Promise < McpSetServersResult >; streamInput ( stream : AsyncIterable < SDKUserMessage >) : Promise < void >; stopTask ( taskId : string ) : Promise < void >; close () : void ; } ​ Methods Method Description interrupt() Interrupts the query (only available in streaming input mode) rewindFiles(userMessageId, options?) Restores files to their state at the specified user message. Pass { dryRun: true } to preview changes. Requires enableFileCheckpointing: true . See File checkpointing setPermissionMode() Changes the permission mode (only available in streaming input mode) setModel() Changes the model (only available in streaming input mode) setMaxThinkingTokens() Deprecated: Use the thinking option instead. Changes the maximum thinking tokens applyFlagSettings(settings) Merges settings into the session’s flag settings layer at runtime (only available in streaming input mode). See applyFlagSettings() initializationResult() Returns the full initialization result including supported commands, models, account info, and output style configuration supportedCommands() Returns available slash commands supportedModels() Returns available models with display info supportedAgents() Returns available subagents as AgentInfo [] mcpServerStatus() Returns status of connected MCP servers accountInfo() Returns account information reconnectMcpServer(serverName) Reconnect an MCP server by name toggleMcpServer(serverName, enabled) Enable or disable an MCP server by name setMcpServers(servers) Dynamically replace the set of MCP servers for this session. Returns info about which servers were added, removed, and any errors streamInput(stream) Stream input messages to the query for multi-turn conversations stopTask(taskId) Stop a running background task by ID close() Close the query and terminate the underlying process. Forcefully ends the query and cleans up all resources ​ applyFlagSettings() Changes any setting on a running session without restarting the query. Use it when a setting that has no dedicated setter needs to change mid-session, such as tightening permissions after the agent reads untrusted input. setModel() and setPermissionMode() are dedicated setters for those two keys; applyFlagSettings() is the general form that accepts any subset of the settings keys, and passing model here behaves the same as setModel() . The values are written to the flag-settings layer, the same layer the inline settings option of query() populates at startup. Flag settings sit near the top of the settings precedence order : they override user, project, and local settings, and only managed policy settings can override them. This is the same tier the on-page precedence section calls programmatic options. Successive calls shallow-merge top-level keys. A second call with { permissions: {...} } replaces the entire permissions object from the prior call rather than deep-merging into it. To clear a key from the flag layer and fall back to lower-precedence sources, pass null for that key. Passing undefined has no effect because JSON serialization drops it. Only available in streaming input mode, the same constraint as setModel() and setPermissionMode() . The example below switches the active model mid-session, then clears the override so the model falls back to whatever the user or project settings specify. const q = query ({ prompt: messageStream }); // Override the model for the rest of the session await q . applyFlagSettings ({ model: "claude-opus-4-6" }); // Later: clear the override and fall back to lower-precedence settings await q . applyFlagSettings ({ model: null }); applyFlagSettings() is TypeScript-only. The Python SDK does not expose an equivalent method. ​ WarmQuery Handle returned by startup() . The subprocess is already spawned and initialized, so calling query() on this handle writes the prompt directly to a ready process with no startup latency. interface WarmQuery extends AsyncDisposable { query ( prompt : string | AsyncIterable < SDKUserMessage >) : Query ; close () : void ; } ​ Methods Method Description query(prompt) Send a prompt to the pre-warmed subprocess and return a Query . Can only be called once per WarmQuery close() Close the subprocess without sending a prompt. Use this to discard a warm query that is no longer needed WarmQuery implements AsyncDisposable , so it can be used with await using for automatic cleanup. ​ SDKControlInitializeResponse Return type of initializationResult() . Contains session initialization data. type SDKControlInitializeResponse = { commands : SlashCommand []; agents : AgentInfo []; output_style : string ; available_output_styles : string []; models : ModelInfo []; account : AccountInfo ; fast_mode_state ?: "off" | "cooldown" | "on" ; }; ​ AgentDefinition Configuration for a subagent defined programmatically. type AgentDefinition = { description : string ; tools ?: string []; disallowedTools ?: string []; prompt : string ; model ?: string ; mcpServers ?: AgentMcpServerSpec []; skills ?: string []; initialPrompt ?: string ; maxTurns ?: number ; background ?: boolean ; memory ?: "user" | "project" | "local" ; effort ?: "low" | "medium" | "high" | "xhigh" | "max" | number ; permissionMode ?: PermissionMode ; criticalSystemReminder_EXPERIMENTAL ?: string ; }; Field Required Description description Yes Natural language description of when to use this agent tools No Array of allowed tool names. If omitted, inherits all tools from parent. To preload Skills into the agent’s context, use the skills field rather than listing 'Skill' here disallowedTools No Array of tool names to explicitly disallow for this agent prompt Yes The agent’s system prompt model No Model override for this agent. Accepts an alias such as 'sonnet' , 'opus' , 'haiku' , 'inherit' , or a full model ID. If omitted or 'inherit' , uses the main model mcpServers No MCP server specifications for this agent skills No Array of skill names to preload into the agent context initialPrompt No Auto-submitted as the first user turn when this agent runs as the main thread agent maxTurns No Maximum number of agentic turns (API round-trips) before stopping background No Run this agent as a non-blocking background task when invoked memory No Memory source for this agent: 'user' , 'project' , or 'local' effort No Reasoning effort level for this agent. Accepts a named level or an integer permissionMode No Permission mode for tool execution within this agent. See PermissionMode criticalSystemReminder_EXPERIMENTAL No Experimental: Critical reminder added to the system prompt ​ AgentMcpServerSpec Specifies MCP servers available to a subagent. Can be a server name (string referencing a server from the parent’s mcpServers config) or an inline server configuration record mapping server names to configs. type AgentMcpServerSpec = string | Record < string , McpServerConfigForProcessTransport >; Where McpServerConfigForProcessTransport is McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig . ​ SettingSource Controls which filesystem-based configuration sources the SDK loads settings from. type SettingSource = "user" | "project" | "local" ; Value Description Location 'user' Global user settings ~/.claude/settings.json 'project' Shared project settings (version controlled) .claude/settings.json 'local' Local project settings (gitignored) .claude/settings.local.json ​ Default behavior When settingSources is omitted or undefined , query() loads the same filesystem settings as the Claude Code CLI: user, project, and local. Managed policy settings are loaded in all cases. See What settingSources does not control for inputs that are read regardless of this option, and how to disable them. ​ Why use settingSources Disable filesystem settings: // Do not load user, project, or local settings from disk const result = query ({ prompt: "Analyze this code" , options: { settingSources: [] } }); Load all filesystem settings explicitly: const result = query ({ prompt: "Analyze this code" , options: { settingSources: [ "user" , "project" , "local" ] // Load all settings } }); Load only specific setting sources: // Load only project settings, ignore user and local const result = query ({ prompt: "Run CI checks" , options: { settingSources: [ "project" ] // Only .claude/settings.json } }); Testing and CI environments: // Ensure consistent behavior in CI by excluding local settings const result = query ({ prompt: "Run tests" , options: { settingSources: [ "project" ], // Only team-shared settings permissionMode: "bypassPermissions" } }); SDK-only applications: // Define everything programmatically. // Pass [] to opt out of filesystem setting sources. const result = query ({ prompt: "Review this PR" , options: { settingSources: [], agents: { /* ... */ }, mcpServers: { /* ... */ }, allowedTools: [ "Read" , "Grep" , "Glob" ] } }); Loading CLAUDE.md project instructions: // Load project settings to include CLAUDE.md files const result = query ({ prompt: "Add a new feature following project conventions" , options: { systemPrompt: { type: "preset" , preset: "claude_code" // Use Claude Code's system prompt }, settingSources: [ "project" ], // Loads CLAUDE.md from project directory allowedTools: [ "Read" , "Write" , "Edit" ] } }); ​ Settings precedence When multiple sources are loaded, settings are merged with this precedence (highest to lowest): Local settings ( .claude/settings.local.json ) Project settings ( .claude/settings.json ) User settings ( ~/.claude/settings.json ) Programmatic options such as agents , allowedTools , and settings override user, project, and local filesystem settings. Managed policy settings take precedence over programmatic options. ​ PermissionMode type PermissionMode = | "default" // Standard permission behavior | "acceptEdits" // Auto-accept file edits | "bypassPermissions" // Bypass all permission checks | "plan" // Planning mode - read-only tools only | "dontAsk" // Don't prompt for permissions, deny if not pre-approved | "auto" ; // Use a model classifier to approve or deny each tool call ​ CanUseTool Custom permission function type for controlling tool usage. type CanUseTool = ( toolName : string , input : Record < string , unknown >, options : { signal : AbortSignal ; suggestions ?: PermissionUpdate []; blockedPath ?: string ; decisionReason ?: string ; toolUseID : string ; agentID ?: string ; } ) => Promise < PermissionResult >; Option Type Description signal AbortSignal Signaled if the operation should be aborted suggestions PermissionUpdate [] Suggested permission updates so the user is not prompted again for this tool. Bash prompts include a suggestion with the localSettings destination , so returning it in updatedPermissions writes the rule to .claude/settings.local.json and persists across sessions. blockedPath string The file path that triggered the permission request, if applicable decisionReason string Explains why this permission request was triggered toolUseID string Unique identifier for this specific tool call within the assistant message agentID string If running within a sub-agent, the sub-agent’s ID ​ PermissionResult Result of a permission check. type PermissionResult = | { behavior : "allow" ; updatedInput ?: Record < string , unknown >; updatedPermissions ?: PermissionUpdate []; toolUseID ?: string ; } | { behavior : "deny" ; message : string ; interrupt ?: boolean ; toolUseID ?: string ; }; ​ ToolConfig Configuration for built-in tool behavior. type ToolConfig = { askUserQuestion ?: { previewFormat ?: "markdown" | "html" ; }; }; Field Type Description askUserQuestion.previewFormat 'markdown' | 'html' Opts into the preview field on AskUserQuestion options and sets its content format. When unset, Claude does not emit previews ​ McpServerConfig Configuration for MCP servers. type McpServerConfig = | McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfigWithInstance ; ​ McpStdioServerConfig type McpStdioServerConfig = { type ?: "stdio" ; command : string ; args ?: string []; env ?: Record < string , string >; }; ​ McpSSEServerConfig type McpSSEServerConfig = { type : "sse" ; url : string ; headers ?: Record < string , string >; }; ​ McpHttpServerConfig type McpHttpServerConfig = { type : "http" ; url : string ; headers ?: Record < string , string >; }; ​ McpSdkServerConfigWithInstance type McpSdkServerConfigWithInstance = { type : "sdk" ; name : string ; instance : McpServer ; }; ​ McpClaudeAIProxyServerConfig type McpClaudeAIProxyServerConfig = { type : "claudeai-proxy" ; url : string ; id : string ; }; ​ SdkPluginConfig Configuration for loading plugins in the SDK. type SdkPluginConfig = { type : "local" ; path : string ; }; Field Type Description type 'local' Must be 'local' (only local plugins currently supported) path string Absolute or relative path to the plugin directory Example: plugins : [ { type: "local" , path: "./my-plugin" }, { type: "local" , path: "/absolute/path/to/plugin" } ]; For complete information on creating and using plugins, see Plugins . ​ Message Types ​ SDKMessage Union type of all possible messages returned by the query. type SDKMessage = | SDKAssistantMessage | SDKUserMessage | SDKUserMessageReplay | SDKResultMessage | SDKSystemMessage | SDKPartialAssistantMessage | SDKCompactBoundaryMessage | SDKStatusMessage | SDKLocalCommandOutputMessage | SDKHookStartedMessage | SDKHookProgressMessage | SDKHookResponseMessage | SDKPluginInstallMessage | SDKToolProgressMessage | SDKAuthStatusMessage | SDKTaskNotificationMessage | SDKTaskStartedMessage | SDKTaskProgressMessage | SDKTaskUpdatedMessage | SDKFilesPersistedEvent | SDKToolUseSummaryMessage | SDKRateLimitEvent | SDKPermissionDeniedMessage | SDKPromptSuggestionMessage ; ​ SDKAssistantMessage Assistant response message. type SDKAssistantMessage = { type : "assistant" ; uuid : UUID ; session_id : string ; message : BetaMessage ; // From Anthropic SDK parent_tool_use_id : string | null ; error ?: SDKAssistantMessageError ; }; The message field is a BetaMessage from the Anthropic SDK. It includes fields like id , content , model , stop_reason , and usage . SDKAssistantMessageError is one of: 'authentication_failed' , 'oauth_org_not_allowed' , 'billing_error' , 'rate_limit' , 'invalid_request' , 'server_error' , 'max_output_tokens' , or 'unknown' . ​ SDKUserMessage User input message. type SDKUserMessage = { type : "user" ; uuid ?: UUID ; session_id ?: string ; message : MessageParam ; // From Anthropic SDK parent_tool_use_id : string | null ; isSynthetic ?: boolean ; shouldQuery ?: boolean ; tool_use_result ?: unknown ; origin ?: SDKMessageOrigin ; }; Set shouldQuery to false to append the message to the transcript without triggering an assistant turn. The message is held and merged into the next user message that does trigger a turn. Use this to inject context, such as the output of a command you ran out of band, without spending a model call on it. ​ SDKUserMessageReplay Replayed user message with required UUID. type SDKUserMessageReplay = { type : "user" ; uuid : UUID ; session_id : string ; message : MessageParam ; parent_tool_use_id : string | null ; isSynthetic ?: boolean ; tool_use_result ?: unknown ; origin ?: SDKMessageOrigin ; isReplay : true ; }; ​ SDKResultMessage Final result message. type SDKResultMessage = | { type : "result" ; subtype : "success" ; uuid : UUID ; session_id : string ; duration_ms : number ; duration_api_ms : number ; is_error : boolean ; num_turns : number ; result : string ; stop_reason : string | null ; total_cost_usd : number ; usage : NonNullableUsage ; modelUsage : { [ modelName : string ] : ModelUsage }; permission_denials : SDKPermissionDenial []; structured_output ?: unknown ; deferred_tool_use ?: { id : string ; name : string ; input : Record < string , unknown > }; origin ?: SDKMessageOrigin ; } | { type : "result" ; subtype : | "error_max_turns" | "error_during_execution" | "error_max_budget_usd" | "error_max_structured_output_retries" ; uuid : UUID ; session_id : string ; duration_ms : number ; duration_api_ms : number ; is_error : boolean ; num_turns : number ; stop_reason : string | null ; total_cost_usd : number ; usage : NonNullableUsage ; modelUsage : { [ modelName : string ] : ModelUsage }; permission_denials : SDKPermissionDenial []; errors : string []; origin ?: SDKMessageOrigin ; }; The origin field forwards the SDKMessageOrigin of the user message that triggered this result. When a background task finishes and the SDK injects a synthetic follow-up turn, the resulting SDKResultMessage carries origin: { kind: "task-notification" } . Check this field to distinguish results that answer your prompt from results emitted for background-task follow-ups, so you can route or suppress the latter. The field is absent for results emitted before any user turn, such as startup errors. When a PreToolUse hook returns permissionDecision: "defer" , the result has stop_reason: "tool_deferred" and deferred_tool_use carries the pending tool’s id , name , and input . Read this field to surface the request in your own UI, then resume with the same session_id to continue. See Defer a tool call for later for the full round trip. ​ SDKSystemMessage System initialization message. type SDKSystemMessage = { type : "system" ; subtype : "init" ; uuid : UUID ; session_id : string ; agents ?: string []; apiKeySource : ApiKeySource ; betas ?: string []; claude_code_version : string ; cwd : string ; tools : string []; mcp_servers : { name : string ; status : string ; }[]; model : string ; permissionMode : PermissionMode ; slash_commands : string []; output_style : string ; skills : string []; plugins : { name : string ; path : string }[]; }; ​ SDKPartialAssistantMessage Streaming partial message (only when includePartialMessages is true). type SDKPartialAssistantMessage = { type : "stream_event" ; event : BetaRawMessageStreamEvent ; // From Anthropic SDK parent_tool_use_id : string | null ; uuid : UUID ; session_id : string ; }; ​ SDKCompactBoundaryMessage Message indicating a conversation compaction boundary. type SDKCompactBoundaryMessage = { type : "system" ; subtype : "compact_boundary" ; uuid : UUID ; session_id : string ; compact_metadata : { trigger : "manual" | "auto" ; pre_tokens : number ; }; }; ​ SDKPluginInstallMessage Plugin installation progress event. Emitted when CLAUDE_CODE_SYNC_PLUGIN_INSTALL is set, so your Agent SDK application can track marketplace plugin installation before the first turn. The started and completed statuses bracket the overall install. The installed and failed statuses report individual marketplaces and include name . type SDKPluginInstallMessage = { type : "system" ; subtype : "plugin_install" ; status : "started" | "installed" | "failed" | "completed" ; name ?: string ; error ?: string ; uuid : UUID ; session_id : string ; }; ​ SDKPermissionDeniedMessage Stream event emitted when the permission system auto-denies a tool call without an interactive prompt. Use it to render the denial in your UI as it happens, rather than only observing the is_error tool result that follows. The interactive ask path reaches your application separately through the canUseTool callback. Denials issued by a PreToolUse hook are not reported through this event. This event requires Claude Code v2.1.136 or later. type SDKPermissionDeniedMessage = { type : "system" ; subtype : "permission_denied" ; tool_name : string ; tool_use_id : string ; agent_id ?: string ; decision_reason_type ?: string ; decision_reason ?: string ; message : string ; uuid : UUID ; session_id : string ; }; Field Type Description tool_name string Name of the tool that was denied tool_use_id string ID of the tool_use block this denial answers agent_id string Subagent ID when the denied call originated inside a subagent. Mirrors the field on can_use_tool for host-side routing decision_reason_type string Discriminator for the component that decided, such as "rule" , "mode" , "classifier" , or "asyncAgent" decision_reason string Human-readable reason from the deciding component, when available message string Rejection message returned to the model in the tool_result ​ SDKPermissionDenial Information about a denied tool use. type SDKPermissionDenial = { tool_name : string ; tool_use_id : string ; tool_input : Record < string , unknown >; }; ​ SDKMessageOrigin Provenance of a user-role message. This appears as origin on SDKUserMessage and is forwarded onto the corresponding SDKResultMessage so you can tell what triggered a given turn. type SDKMessageOrigin = | { kind : "human" } | { kind : "channel" ; server : string } | { kind : "peer" ; from : string ; name ?: string } | { kind : "task-notification" } | { kind : "coordinator" }; kind Meaning human Direct input from the end user. On user messages, an absent origin also means human input. channel Message arriving on a channel . server is the source MCP server name. peer Message from another agent session via SendMessage . from is the sender address; name is the sender’s display name when available. task-notification Synthetic turn injected after a background task finished. See SDKTaskNotificationMessage . coordinator Message from a team coordinator in an agent team . ​ Hook Types For a comprehensive guide on using hooks with examples and common patterns, see the Hooks guide . ​ HookEvent Available hook events. type HookEvent = | "PreToolUse" | "PostToolUse" | "PostToolUseFailure" | "PostToolBatch" | "Notification" | "UserPromptSubmit" | "SessionStart" | "SessionEnd" | "Stop" | "SubagentStart" | "SubagentStop" | "PreCompact" | "PermissionRequest" | "Setup" | "TeammateIdle" | "TaskCompleted" | "ConfigChange" | "WorktreeCreate" | "WorktreeRemove" ; ​ HookCallback Hook callback function type. type HookCallback = ( input : HookInput , // Union of all hook input types toolUseID : string | undefined , options : { signal : AbortSignal } ) => Promise < HookJSONOutput >; ​ HookCallbackMatcher Hook configuration with optional matcher. interface HookCallbackMatcher { matcher ?: string ; hooks : HookCallback []; timeout ?: number ; // Timeout in seconds for all hooks in this matcher } ​ HookInput Union type of all hook input types. type HookInput = | PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | PostToolBatchHookInput | NotificationHookInput | UserPromptSubmitHookInput | SessionStartHookInput | SessionEndHookInput | StopHookInput | SubagentStartHookInput | SubagentStopHookInput | PreCompactHookInput | PermissionRequestHookInput | SetupHookInput | TeammateIdleHookInput | TaskCompletedHookInput | ConfigChangeHookInput | WorktreeCreateHookInput | WorktreeRemoveHookInput ; ​ BaseHookInput Base interface that all hook input types extend. type BaseHookInput = { session_id : string ; transcript_path : string ; cwd : string ; permission_mode ?: string ; effort ?: { level : string }; agent_id ?: string ; agent_type ?: string ; }; ​ PreToolUseHookInput type PreToolUseHookInput = BaseHookInput & { hook_event_name : "PreToolUse" ; tool_name : string ; tool_input : unknown ; tool_use_id : string ; }; ​ PostToolUseHookInput type PostToolUseHookInput = BaseHookInput & { hook_event_name : "PostToolUse" ; tool_name : string ; tool_input : unknown ; tool_response : unknown ; tool_use_id : string ; duration_ms ?: number ; }; ​ PostToolUseFailureHookInput type PostToolUseFailureHookInput = BaseHookInput & { hook_event_name : "PostToolUseFailure" ; tool_name : string ; tool_input : unknown ; tool_use_id : string ; error : string ; is_interrupt ?: boolean ; duration_ms ?: number ; }; ​ PostToolBatchHookInput Fires once after every tool call in a batch has resolved, before the next model request. tool_response carries the serialized tool_result content the model sees; the shape differs from PostToolUseHookInput ’s structured Output object. type PostToolBatchHookInput = BaseHookInput & { hook_event_name : "PostToolBatch" ; tool_calls : PostToolBatchToolCall []; }; type PostToolBatchToolCall = { tool_name : string ; tool_input : unknown ; tool_use_id : string ; tool_response ?: unknown ; }; ​ NotificationHookInput type NotificationHookInput = BaseHookInput & { hook_event_name : "Notification" ; message : string ; title ?: string ; notification_type : string ; }; ​ UserPromptSubmitHookInput type UserPromptSubmitHookInput = BaseHookInput & { hook_event_name : "UserPromptSubmit" ; prompt : string ; }; ​ SessionStartHookInput type SessionStartHookInput = BaseHookInput & { hook_event_name : "SessionStart" ; source : "startup" | "resume" | "clear" | "compact" ; agent_type ?: string ; model ?: string ; }; ​ SessionEndHookInput type SessionEndHookInput = BaseHookInput & { hook_event_name : "SessionEnd" ; reason : ExitReason ; // String from EXIT_REASONS array }; ​ StopHookInput type StopHookInput = BaseHookInput & { hook_event_name : "Stop" ; stop_hook_active : boolean ; last_assistant_message ?: string ; }; ​ SubagentStartHookInput type SubagentStartHookInput = BaseHookInput & { hook_event_name : "SubagentStart" ; agent_id : string ; agent_type : string ; }; ​ SubagentStopHookInput type SubagentStopHookInput = BaseHookInput & { hook_event_name : "SubagentStop" ; stop_hook_active : boolean ; agent_id : string ; agent_transcript_path : string ; agent_type : string ; last_assistant_message ?: string ; }; ​ PreCompactHookInput type PreCompactHookInput = BaseHookInput & { hook_event_name : "PreCompact" ; trigger : "manual" | "auto" ; custom_instructions : string | null ; }; ​ PermissionRequestHookInput type PermissionRequestHookInput = BaseHookInput & { hook_event_name : "PermissionRequest" ; tool_name : string ; tool_input : unknown ; permission_suggestions ?: PermissionUpdate []; }; ​ SetupHookInput type SetupHookInput = BaseHookInput & { hook_event_name : "Setup" ; trigger : "init" | "maintenance" ; }; ​ TeammateIdleHookInput type TeammateIdleHookInput = BaseHookInput & { hook_event_name : "TeammateIdle" ; teammate_name : string ; team_name : string ; }; ​ TaskCompletedHookInput type TaskCompletedHookInput = BaseHookInput & { hook_event_name : "TaskCompleted" ; task_id : string ; task_subject : string ; task_description ?: string ; teammate_name ?: string ; team_name ?: string ; }; ​ ConfigChangeHookInput type ConfigChangeHookInput = BaseHookInput & { hook_event_name : "ConfigChange" ; source : | "user_settings" | "project_settings" | "local_settings" | "policy_settings" | "skills" ; file_path ?: string ; }; ​ WorktreeCreateHookInput type WorktreeCreateHookInput = BaseHookInput & { hook_event_name : "WorktreeCreate" ; name : string ; }; ​ WorktreeRemoveHookInput type WorktreeRemoveHookInput = BaseHookInput & { hook_event_name : "WorktreeRemove" ; worktree_path : string ; }; ​ HookJSONOutput Hook return value. type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput ; ​ AsyncHookJSONOutput type AsyncHookJSONOutput = { async : true ; asyncTimeout ?: number ; }; ​ SyncHookJSONOutput type SyncHookJSONOutput = { continue ?: boolean ; suppressOutput ?: boolean ; stopReason ?: string ; decision ?: "approve" | "block" ; systemMessage ?: string ; reason ?: string ; hookSpecificOutput ?: | { hookEventName : "PreToolUse" ; permissionDecision ?: "allow" | "deny" | "ask" | "defer" ; permissionDecisionReason ?: string ; updatedInput ?: Record < string , unknown >; additionalContext ?: string ; } | { hookEventName : "UserPromptSubmit" ; additionalContext ?: string ; } | { hookEventName : "SessionStart" ; additionalContext ?: string ; } | { hookEventName : "Setup" ; additionalContext ?: string ; } | { hookEventName : "SubagentStart" ; additionalContext ?: string ; } | { hookEventName : "PostToolUse" ; additionalContext ?: string ; updatedToolOutput ?: unknown ; /** @deprecated Use `updatedToolOutput`, which works for all tools. */ updatedMCPToolOutput ?: unknown ; } | { hookEventName : "PostToolUseFailure" ; additionalContext ?: string ; } | { hookEventName : "PostToolBatch" ; additionalContext ?: string ; } | { hookEventName : "Notification" ; additionalContext ?: string ; } | { hookEventName : "PermissionRequest" ; decision : | { behavior : "allow" ; updatedInput ?: Record < string , unknown >; updatedPermissions ?: PermissionUpdate []; } | { behavior : "deny" ; message ?: string ; interrupt ?: boolean ; }; }; }; ​ Tool Input Types Documentation of input schemas for all built-in Claude Code tools. These types are exported from @anthropic-ai/claude-agent-sdk and can be used for type-safe tool interactions. ​ ToolInputSchemas Union of all tool input types, exported from @anthropic-ai/claude-agent-sdk . type ToolInputSchemas = | AgentInput | AskUserQuestionInput | BashInput | TaskOutputInput | EnterWorktreeInput | ExitPlanModeInput | FileEditInput | FileReadInput | FileWriteInput | GlobInput | GrepInput | ListMcpResourcesInput | McpInput | MonitorInput | NotebookEditInput | ReadMcpResourceInput | SubscribeMcpResourceInput | SubscribePollingInput | TaskCreateInput | TaskGetInput | TaskListInput | TaskStopInput | TaskUpdateInput | TodoWriteInput | UnsubscribeMcpResourceInput | UnsubscribePollingInput | WebFetchInput | WebSearchInput ; ​ Agent Tool name: Agent (previously Task , which is still accepted as an alias) type AgentInput = { description : string ; prompt : string ; subagent_type : string ; model ?: "sonnet" | "opus" | "haiku" ; resume ?: string ; run_in_background ?: boolean ; max_turns ?: number ; name ?: string ; team_name ?: string ; mode ?: "acceptEdits" | "bypassPermissions" | "default" | "dontAsk" | "plan" ; isolation ?: "worktree" ; }; Launches a new agent to handle complex, multi-step tasks autonomously. ​ AskUserQuestion Tool name: AskUserQuestion type AskUserQuestionInput = { questions : Array <{ question : string ; header : string ; options : Array <{ label : string ; description : string ; preview ?: string }>; multiSelect : boolean ; }>; }; Asks the user clarifying questions during execution. See Handle approvals and user input for usage details. ​ Bash Tool name: Bash type BashInput = { command : string ; timeout ?: number ; description ?: string ; run_in_background ?: boolean ; dangerouslyDisableSandbox ?: boolean ; }; Executes bash commands in a persistent shell session with optional timeout and background execution. ​ Monitor Tool name: Monitor type MonitorInput = { command : string ; description : string ; timeout_ms ?: number ; persistent ?: boolean ; }; Runs a background script and delivers each stdout line to Claude as an event so it can react without polling. Set persistent: true for session-length watches such as log tails. Monitor follows the same permission rules as Bash. See the Monitor tool reference for behavior and provider availability. ​ TaskOutput Tool name: TaskOutput type TaskOutputInput = { task_id : string ; block : boolean ; timeout : number ; }; Retrieves output from a running or completed background task. ​ Edit Tool name: Edit type FileEditInput = { file_path : string ; old_string : string ; new_string : string ; replace_all ?: boolean ; }; Performs exact string replacements in files. ​ Read Tool name: Read type FileReadInput = { file_path : string ; offset ?: number ; limit ?: number ; pages ?: string ; }; Reads files from the local filesystem, including text, images, PDFs, and Jupyter notebooks. Use pages for PDF page ranges (for example, "1-5" ). ​ Write Tool name: Write type FileWriteInput = { file_path : string ; content : string ; }; Writes a file to the local filesystem, overwriting if it exists. ​ Glob Tool name: Glob type GlobInput = { pattern : string ; path ?: string ; }; Fast file pattern matching that works with any codebase size. ​ Grep Tool name: Grep type GrepInput = { pattern : string ; path ?: string ; glob ?: string ; type ?: string ; output_mode ?: "content" | "files_with_matches" | "count" ; "-i" ?: boolean ; "-n" ?: boolean ; "-B" ?: number ; "-A" ?: number ; "-C" ?: number ; context ?: number ; head_limit ?: number ; offset ?: number ; multiline ?: boolean ; }; Powerful search tool built on ripgrep with regex support. ​ TaskStop Tool name: TaskStop type TaskStopInput = { task_id ?: string ; shell_id ?: string ; // Deprecated: use task_id }; Stops a running background task or shell by ID. ​ NotebookEdit Tool name: NotebookEdit type NotebookEditInput = { notebook_path : string ; cell_id ?: string ; new_source : string ; cell_type ?: "code" | "markdown" ; edit_mode ?: "replace" | "insert" | "delete" ; }; Edits cells in Jupyter notebook files. ​ WebFetch Tool name: WebFetch type WebFetchInput = { url : string ; prompt : string ; }; Fetches content from a URL and processes it with an AI model. ​ WebSearch Tool name: WebSearch type WebSearchInput = { query : string ; allowed_domains ?: string []; blocked_domains ?: string []; }; Searches the web and returns formatted results. ​ TodoWrite Tool name: TodoWrite type TodoWriteInput = { todos : Array <{ content : string ; status : "pending" | "in_progress" | "completed" ; activeForm : string ; }>; }; Creates and manages a structured task list for tracking progress. TodoWrite is deprecated and will be removed in a future release. Use TaskCreate , TaskGet , TaskUpdate , and TaskList instead. Set CLAUDE_CODE_ENABLE_TASKS=1 to opt in. See Migrate to Task tools for how monitoring code changes. ​ TaskCreate Tool name: TaskCreate type TaskCreateInput = { subject : string ; description : string ; activeForm ?: string ; metadata ?: Record < string , unknown >; }; Creates a single task and returns its assigned ID. ​ TaskUpdate Tool name: TaskUpdate type TaskUpdateInput = { taskId : string ; status ?: "pending" | "in_progress" | "completed" | "deleted" ; subject ?: string ; description ?: string ; activeForm ?: string ; addBlocks ?: string []; addBlockedBy ?: string []; owner ?: string ; metadata ?: Record < string , unknown >; }; Patches one task by ID. Set status to "deleted" to remove it. ​ TaskGet Tool name: TaskGet type TaskGetInput = { taskId : string ; }; Returns full details for one task, or null when the ID is not found. ​ TaskList Tool name: TaskList type TaskListInput = {}; Returns a snapshot of all tasks in the current list. ​ ExitPlanMode Tool name: ExitPlanMode type ExitPlanModeInput = { allowedPrompts ?: Array <{ tool : "Bash" ; prompt : string ; }>; }; Exits planning mode. Optionally specifies prompt-based permissions needed to implement the plan. ​ ListMcpResources Tool name: ListMcpResources type ListMcpResourcesInput = { server ?: string ; }; Lists available MCP resources from connected servers. ​ ReadMcpResource Tool name: ReadMcpResource type ReadMcpResourceInput = { server : string ; uri : string ; }; Reads a specific MCP resource from a server. ​ EnterWorktree Tool name: EnterWorktree type EnterWorktreeInput = { name ?: string ; path ?: string ; }; Creates and enters a temporary git worktree for isolated work. Pass path to switch into an existing worktree of the current repository instead of creating a new one. name and path are mutually exclusive. ​ Tool Output Types Documentation of output schemas for all built-in Claude Code tools. These types are exported from @anthropic-ai/claude-agent-sdk and represent the actual response data returned by each tool. ​ ToolOutputSchemas Union of all tool output types. type ToolOutputSchemas = | AgentOutput | AskUserQuestionOutput | BashOutput | EnterWorktreeOutput | ExitPlanModeOutput | FileEditOutput | FileReadOutput | FileWriteOutput | GlobOutput | GrepOutput | ListMcpResourcesOutput | MonitorOutput | NotebookEditOutput | ReadMcpResourceOutput | TaskCreateOutput | TaskGetOutput | TaskListOutput | TaskStopOutput | TaskUpdateOutput | TodoWriteOutput | WebFetchOutput | WebSearchOutput ; ​ Agent Tool name: Agent (previously Task , which is still accepted as an alias) type AgentOutput = | { status : "completed" ; agentId : string ; content : Array <{ type : "text" ; text : string }>; totalToolUseCount : number ; totalDurationMs : number ; totalTokens : number ; usage : { input_tokens : number ; output_tokens : number ; cache_creation_input_tokens : number | null ; cache_read_input_tokens : number | null ; server_tool_use : { web_search_requests : number ; web_fetch_requests : number ; } | null ; service_tier : ( "standard" | "priority" | "batch" ) | null ; cache_creation : { ephemeral_1h_input_tokens : number ; ephemeral_5m_input_tokens : number ; } | null ; }; prompt : string ; } | { status : "async_launched" ; agentId : string ; description : string ; prompt : string ; outputFile : string ; canReadOutputFile ?: boolean ; } | { status : "sub_agent_entered" ; description : string ; message : string ; }; Returns the result from the subagent. Discriminated on the status field: "completed" for finished tasks, "async_launched" for background tasks, and "sub_agent_entered" for interactive subagents. ​ AskUserQuestion Tool name: AskUserQuestion type AskUserQuestionOutput = { questions : Array <{ question : string ; header : string ; options : Array <{ label : string ; description : string ; preview ?: string }>; multiSelect : boolean ; }>; answers : Record < string , string >; }; Returns the questions asked and the user’s answers. ​ Bash Tool name: Bash type BashOutput = { stdout : string ; stderr : string ; rawOutputPath ?: string ; interrupted : boolean ; isImage ?: boolean ; backgroundTaskId ?: string ; backgroundedByUser ?: boolean ; dangerouslyDisableSandbox ?: boolean ; returnCodeInterpretation ?: string ; structuredContent ?: unknown []; persistedOutputPath ?: string ; persistedOutputSize ?: number ; }; Returns command output with stdout/stderr split. Background commands include a backgroundTaskId . ​ Monitor Tool name: Monitor type MonitorOutput = { taskId : string ; timeoutMs : number ; persistent ?: boolean ; }; Returns the background task ID for the running monitor. Use this ID with TaskStop to cancel the watch early. ​ Edit Tool name: Edit type FileEditOutput = { filePath : string ; oldString : string ; newString : string ; originalFile : string ; structuredPatch : Array <{ oldStart : number ; oldLines : number ; newStart : number ; newLines : number ; lines : string []; }>; userModified : boolean ; replaceAll : boolean ; gitDiff ?: { filename : string ; status : "modified" | "added" ; additions : number ; deletions : number ; changes : number ; patch : string ; }; }; Returns the structured diff of the edit operation. ​ Read Tool name: Read type FileReadOutput = | { type : "text" ; file : { filePath : string ; content : string ; numLines : number ; startLine : number ; totalLines : number ; }; } | { type : "image" ; file : { base64 : string ; type : "image/jpeg" | "image/png" | "image/gif" | "image/webp" ; originalSize : number ; dimensions ?: { originalWidth ?: number ; originalHeight ?: number ; displayWidth ?: number ; displayHeight ?: number ; }; }; } | { type : "notebook" ; file : { filePath : string ; cells : unknown []; }; } | { type : "pdf" ; file : { filePath : string ; base64 : string ; originalSize : number ; }; } | { type : "parts" ; file : { filePath : string ; originalSize : number ; count : number ; outputDir : string ; }; }; Returns file contents in a format appropriate to the file type. Discriminated on the type field. ​ Write Tool name: Write type FileWriteOutput = { type : "create" | "update" ; filePath : string ; content : string ; structuredPatch : Array <{ oldStart : number ; oldLines : number ; newStart : number ; newLines : number ; lines : string []; }>; originalFile : string | null ; gitDiff ?: { filename : string ; status : "modified" | "added" ; additions : number ; deletions : number ; changes : number ; patch : string ; }; }; Returns the write result with structured diff information. ​ Glob Tool name: Glob type GlobOutput = { durationMs : number ; numFiles : number ; filenames : string []; truncated : boolean ; }; Returns file paths matching the glob pattern, sorted by modification time. ​ Grep Tool name: Grep type GrepOutput = { mode ?: "content" | "files_with_matches" | "count" ; numFiles : number ; filenames : string []; content ?: string ; numLines ?: number ; numMatches ?: number ; appliedLimit ?: number ; appliedOffset ?: number ; }; Returns search results. The shape varies by mode : file list, content with matches, or match counts. ​ TaskStop Tool name: TaskStop type TaskStopOutput = { message : string ; task_id : string ; task_type : string ; command ?: string ; }; Returns confirmation after stopping the background task. ​ NotebookEdit Tool name: NotebookEdit type NotebookEditOutput = { new_source : string ; cell_id ?: string ; cell_type : "code" | "markdown" ; language : string ; edit_mode : string ; error ?: string ; notebook_path : string ; original_file : string ; updated_file : string ; }; Returns the result of the notebook edit with original and updated file contents. ​ WebFetch Tool name: WebFetch type WebFetchOutput = { bytes : number ; code : number ; codeText : string ; result : string ; durationMs : number ; url : string ; }; Returns the fetched content with HTTP status and metadata. ​ WebSearch Tool name: WebSearch type WebSearchOutput = { query : string ; results : Array < | { tool_use_id : string ; content : Array <{ title : string ; url : string }>; } | string >; durationSeconds : number ; }; Returns search results from the web. ​ TodoWrite Tool name: TodoWrite type TodoWriteOutput = { oldTodos : Array <{ content : string ; status : "pending" | "in_progress" | "completed" ; activeForm : string ; }>; newTodos : Array <{ content : string ; status : "pending" | "in_progress" | "completed" ; activeForm : string ; }>; }; Returns the previous and updated task lists. TodoWrite is deprecated and will be removed in a future release. Use TaskCreate , TaskGet , TaskUpdate , and TaskList instead. Set CLAUDE_CODE_ENABLE_TASKS=1 to opt in. See Migrate to Task tools for how monitoring code changes. ​ TaskCreate Tool name: TaskCreate type TaskCreateOutput = { task : { id : string ; subject : string ; }; }; Returns the created task with its assigned ID. ​ TaskUpdate Tool name: TaskUpdate type TaskUpdateOutput = { success : boolean ; taskId : string ; updatedFields : string []; error ?: string ; statusChange ?: { from : string ; to : string ; }; }; Returns the update result, including which fields changed. ​ TaskGet Tool name: TaskGet type TaskGetOutput = { task : { id : string ; subject : string ; description : string ; status : "pending" | "in_progress" | "completed" ; blocks : string []; blockedBy : string []; } | null ; }; Returns the full task record, or null when the ID is not found. ​ TaskList Tool name: TaskList type TaskListOutput = { tasks : Array <{ id : string ; subject : string ; status : "pending" | "in_progress" | "completed" ; owner ?: string ; blockedBy : string []; }>; }; Returns a snapshot of all tasks in the current list. ​ ExitPlanMode Tool name: ExitPlanMode type ExitPlanModeOutput = { plan : string | null ; isAgent : boolean ; filePath ?: string ; hasTaskTool ?: boolean ; awaitingLeaderApproval ?: boolean ; requestId ?: string ; }; Returns the plan state after exiting plan mode. ​ ListMcpResources Tool name: ListMcpResources type ListMcpResourcesOutput = Array <{ uri : string ; name : string ; mimeType ?: string ; description ?: string ; server : string ; }>; Returns an array of available MCP resources. ​ ReadMcpResource Tool name: ReadMcpResource type ReadMcpResourceOutput = { contents : Array <{ uri : string ; mimeType ?: string ; text ?: string ; }>; }; Returns the contents of the requested MCP resource. ​ EnterWorktree Tool name: EnterWorktree type EnterWorktreeOutput = { worktreePath : string ; worktreeBranch ?: string ; message : string ; }; Returns information about the git worktree. ​ Permission Types ​ PermissionUpdate Operations for updating permissions. type PermissionUpdate = | { type : "addRules" ; rules : PermissionRuleValue []; behavior : PermissionBehavior ; destination : PermissionUpdateDestination ; } | { type : "replaceRules" ; rules : PermissionRuleValue []; behavior : PermissionBehavior ; destination : PermissionUpdateDestination ; } | { type : "removeRules" ; rules : PermissionRuleValue []; behavior : PermissionBehavior ; destination : PermissionUpdateDestination ; } | { type : "setMode" ; mode : PermissionMode ; destination : PermissionUpdateDestination ; } | { type : "addDirectories" ; directories : string []; destination : PermissionUpdateDestination ; } | { type : "removeDirectories" ; directories : string []; destination : PermissionUpdateDestination ; }; ​ PermissionBehavior type PermissionBehavior = "allow" | "deny" | "ask" ; ​ PermissionUpdateDestination type PermissionUpdateDestination = | "userSettings" // Global user settings | "projectSettings" // Per-directory project settings | "localSettings" // Gitignored local settings | "session" // Current session only | "cliArg" ; // CLI argument ​ PermissionRuleValue type PermissionRuleValue = { toolName : string ; ruleContent ?: string ; }; ​ Other Types ​ ApiKeySource type ApiKeySource = "user" | "project" | "org" | "temporary" | "oauth" ; ​ SdkBeta Available beta features that can be enabled via the betas option. See Beta headers for more information. type SdkBeta = "context-1m-2025-08-07" ; The context-1m-2025-08-07 beta is retired as of April 30, 2026. Passing this value with Claude Sonnet 4.5 or Sonnet 4 has no effect, and requests that exceed the standard 200k-token context window return an error. To use a 1M-token context window, migrate to Claude Sonnet 4.6, Claude Opus 4.6, or Claude Opus 4.7 , which include 1M context at standard pricing with no beta header required. ​ SlashCommand Information about an available slash command. type SlashCommand = { name : string ; description : string ; argumentHint : string ; aliases ?: string []; }; ​ ModelInfo Information about an available model. type ModelInfo = { value : string ; displayName : string ; description : string ; supportsEffort ?: boolean ; supportedEffortLevels ?: ( "low" | "medium" | "high" | "xhigh" | "max" )[]; supportsAdaptiveThinking ?: boolean ; supportsFastMode ?: boolean ; }; ​ AgentInfo Information about an available subagent that can be invoked via the Agent tool. type AgentInfo = { name : string ; description : string ; model ?: string ; }; Field Type Description name string Agent type identifier (e.g., "Explore" , "general-purpose" ) description string Description of when to use this agent model string | undefined Model alias this agent uses. If omitted, inherits the parent’s model ​ McpServerStatus Status of a connected MCP server. type McpServerStatus = { name : string ; status : "connected" | "failed" | "needs-auth" | "pending" | "disabled" ; serverInfo ?: { name : string ; version : string ; }; error ?: string ; config ?: McpServerStatusConfig ; scope ?: string ; tools ?: { name : string ; description ?: string ; annotations ?: { readOnly ?: boolean ; destructive ?: boolean ; openWorld ?: boolean ; }; }[]; }; ​ McpServerStatusConfig The configuration of an MCP server as reported by mcpServerStatus() . This is the union of all MCP server transport types. type McpServerStatusConfig = | McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig | McpClaudeAIProxyServerConfig ; See McpServerConfig for details on each transport type. ​ AccountInfo Account information for the authenticated user. type AccountInfo = { email ?: string ; organization ?: string ; subscriptionType ?: string ; tokenSource ?: string ; apiKeySource ?: string ; }; ​ ModelUsage Per-model usage statistics returned in result messages. The costUSD value is a client-side estimate. See Track cost and usage for billing caveats. type ModelUsage = { inputTokens : number ; outputTokens : number ; cacheReadInputTokens : number ; cacheCreationInputTokens : number ; webSearchRequests : number ; costUSD : number ; contextWindow : number ; maxOutputTokens : number ; }; ​ ConfigScope type ConfigScope = "local" | "user" | "project" ; ​ NonNullableUsage A version of Usage with all nullable fields made non-nullable. type NonNullableUsage = { [ K in keyof Usage ] : NonNullable < Usage [ K ]>; }; ​ Usage Token usage statistics (from @anthropic-ai/sdk ). type Usage = { input_tokens : number | null ; output_tokens : number | null ; cache_creation_input_tokens ?: number | null ; cache_read_input_tokens ?: number | null ; }; ​ CallToolResult MCP tool result type (from @modelcontextprotocol/sdk/types.js ). structuredContent is a JSON object that can be returned alongside content , including image blocks. See Return structured data . type CallToolResult = { content : Array <{ type : "text" | "image" | "resource" ; // Additional fields vary by type }>; structuredContent ?: Record < string , unknown >; isError ?: boolean ; }; ​ ThinkingConfig Controls Claude’s thinking/reasoning behavior. Takes precedence over the deprecated maxThinkingTokens . type ThinkingConfig = | { type : "adaptive" } // The model determines when and how much to reason (Opus 4.6+) | { type : "enabled" ; budgetTokens ?: number } // Fixed thinking token budget | { type : "disabled" }; // No extended thinking ​ SpawnedProcess Interface for custom process spawning (used with spawnClaudeCodeProcess option). ChildProcess already satisfies this interface. interface SpawnedProcess { stdin : Writable ; stdout : Readable ; readonly killed : boolean ; readonly exitCode : number | null ; kill ( signal : NodeJS . Signals ) : boolean ; on ( event : "exit" , listener : ( code : number | null , signal : NodeJS . Signals | null ) => void ) : void ; on ( event : "error" , listener : ( error : Error ) => void ) : void ; once ( event : "exit" , listener : ( code : number | null , signal : NodeJS . Signals | null ) => void ) : void ; once ( event : "error" , listener : ( error : Error ) => void ) : void ; off ( event : "exit" , listener : ( code : number | null , signal : NodeJS . Signals | null ) => void ) : void ; off ( event : "error" , listener : ( error : Error ) => void ) : void ; } ​ SpawnOptions Options passed to the custom spawn function. interface SpawnOptions { command : string ; args : string []; cwd ?: string ; env : Record < string , string | undefined >; signal : AbortSignal ; } ​ McpSetServersResult Result of a setMcpServers() operation. type McpSetServersResult = { added : string []; removed : string []; errors : Record < string , string >; }; ​ RewindFilesResult Result of a rewindFiles() operation. type RewindFilesResult = { canRewind : boolean ; error ?: string ; filesChanged ?: string []; insertions ?: number ; deletions ?: number ; }; ​ SDKStatusMessage Status update message (e.g., compacting). type SDKStatusMessage = { type : "system" ; subtype : "status" ; status : "compacting" | null ; permissionMode ?: PermissionMode ; uuid : UUID ; session_id : string ; }; ​ SDKTaskNotificationMessage Notification when a background task completes, fails, or is stopped. Background tasks include run_in_background Bash commands, Monitor watches, and background subagents. type SDKTaskNotificationMessage = { type : "system" ; subtype : "task_notification" ; task_id : string ; tool_use_id ?: string ; status : "completed" | "failed" | "stopped" ; output_file : string ; summary : string ; usage ?: { total_tokens : number ; tool_uses : number ; duration_ms : number ; }; uuid : UUID ; session_id : string ; }; ​ SDKToolUseSummaryMessage Summary of tool usage in a conversation. type SDKToolUseSummaryMessage = { type : "tool_use_summary" ; summary : string ; preceding_tool_use_ids : string []; uuid : UUID ; session_id : string ; }; ​ SDKHookStartedMessage Emitted when a hook begins executing. type SDKHookStartedMessage = { type : "system" ; subtype : "hook_started" ; hook_id : string ; hook_name : string ; hook_event : string ; uuid : UUID ; session_id : string ; }; ​ SDKHookProgressMessage Emitted while a hook is running, with stdout/stderr output. type SDKHookProgressMessage = { type : "system" ; subtype : "hook_progress" ; hook_id : string ; hook_name : string ; hook_event : string ; stdout : string ; stderr : string ; output : string ; uuid : UUID ; session_id : string ; }; ​ SDKHookResponseMessage Emitted when a hook finishes executing. type SDKHookResponseMessage = { type : "system" ; subtype : "hook_response" ; hook_id : string ; hook_name : string ; hook_event : string ; output : string ; stdout : string ; stderr : string ; exit_code ?: number ; outcome : "success" | "error" | "cancelled" ; uuid : UUID ; session_id : string ; }; ​ SDKToolProgressMessage Emitted periodically while a tool is executing to indicate progress. type SDKToolProgressMessage = { type : "tool_progress" ; tool_use_id : string ; tool_name : string ; parent_tool_use_id : string | null ; elapsed_time_seconds : number ; task_id ?: string ; uuid : UUID ; session_id : string ; }; ​ SDKAuthStatusMessage Emitted during authentication flows. type SDKAuthStatusMessage = { type : "auth_status" ; isAuthenticating : boolean ; output : string []; error ?: string ; uuid : UUID ; session_id : string ; }; ​ SDKTaskStartedMessage Emitted when a background task begins. The task_type field is "local_bash" for background Bash commands and Monitor watches, "local_agent" for subagents, or "remote_agent" . type SDKTaskStartedMessage = { type : "system" ; subtype : "task_started" ; task_id : string ; tool_use_id ?: string ; description : string ; task_type ?: string ; uuid : UUID ; session_id : string ; }; ​ SDKTaskProgressMessage Emitted periodically while a background task is running. type SDKTaskProgressMessage = { type : "system" ; subtype : "task_progress" ; task_id : string ; tool_use_id ?: string ; description : string ; usage : { total_tokens : number ; tool_uses : number ; duration_ms : number ; }; last_tool_name ?: string ; uuid : UUID ; session_id : string ; }; ​ SDKTaskUpdatedMessage Emitted when a background task’s state changes, such as when it transitions from running to completed . Merge patch into your local task map keyed by task_id . The end_time field is a Unix epoch timestamp in milliseconds, comparable with Date.now() . type SDKTaskUpdatedMessage = { type : "system" ; subtype : "task_updated" ; task_id : string ; patch : { status ?: "pending" | "running" | "completed" | "failed" | "killed" ; description ?: string ; end_time ?: number ; total_paused_ms ?: number ; error ?: string ; is_backgrounded ?: boolean ; }; uuid : UUID ; session_id : string ; }; ​ SDKFilesPersistedEvent Emitted when file checkpoints are persisted to disk. type SDKFilesPersistedEvent = { type : "system" ; subtype : "files_persisted" ; files : { filename : string ; file_id : string }[]; failed : { filename : string ; error : string }[]; processed_at : string ; uuid : UUID ; session_id : string ; }; ​ SDKRateLimitEvent Emitted when the session encounters a rate limit. type SDKRateLimitEvent = { type : "rate_limit_event" ; rate_limit_info : { status : "allowed" | "allowed_warning" | "rejected" ; resetsAt ?: number ; utilization ?: number ; }; uuid : UUID ; session_id : string ; }; ​ SDKLocalCommandOutputMessage Output from a local slash command (for example, /voice or /usage ). Displayed as assistant-style text in the transcript. type SDKLocalCommandOutputMessage = { type : "system" ; subtype : "local_command_output" ; content : string ; uuid : UUID ; session_id : string ; }; ​ SDKPromptSuggestionMessage Emitted after each turn when promptSuggestions is enabled. Contains a predicted next user prompt. type SDKPromptSuggestionMessage = { type : "prompt_suggestion" ; suggestion : string ; uuid : UUID ; session_id : string ; }; ​ AbortError Custom error class for abort operations. class AbortError extends Error {} ​ Sandbox Configuration ​ SandboxSettings Configuration for sandbox behavior. Use this to enable command sandboxing and configure network restrictions programmatically. type SandboxSettings = { enabled ?: boolean ; autoAllowBashIfSandboxed ?: boolean ; excludedCommands ?: string []; allowUnsandboxedCommands ?: boolean ; network ?: SandboxNetworkConfig ; filesystem ?: SandboxFilesystemConfig ; ignoreViolations ?: Record < string , string []>; enableWeakerNestedSandbox ?: boolean ; ripgrep ?: { command : string ; args ?: string [] }; }; Property Type Default Description enabled boolean false Enable sandbox mode for command execution autoAllowBashIfSandboxed boolean true Auto-approve bash commands when sandbox is enabled excludedCommands string[] [] Commands that always bypass sandbox restrictions (e.g., ['docker'] ). These run unsandboxed automatically without model involvement allowUnsandboxedCommands boolean true Allow the model to request running commands outside the sandbox. When true , the model can set dangerouslyDisableSandbox in tool input, which falls back to the permissions system network SandboxNetworkConfig undefined Network-specific sandbox configuration filesystem SandboxFilesystemConfig undefined Filesystem-specific sandbox configuration for read/write restrictions ignoreViolations Record undefined Map of violation categories to patterns to ignore (e.g., { file: ['/tmp/*'], network: ['localhost'] } ) enableWeakerNestedSandbox boolean false Enable a weaker nested sandbox for compatibility ripgrep { command: string; args?: string[] } undefined Custom ripgrep binary configuration for sandbox environments ​ Example usage import { query } from "@anthropic-ai/claude-agent-sdk" ; for await ( const message of query ({ prompt: "Build and test my project" , options: { sandbox: { enabled: true , autoAllowBashIfSandboxed: true , network: { allowLocalBinding: true } } } })) { if ( "result" in message ) console . log ( message . result ); } Unix socket security: The allowUnixSockets option can grant access to powerful system services. For example, allowing /var/run/docker.sock effectively grants full host system access through the Docker API, bypassing sandbox isolation. Only allow Unix sockets that are strictly necessary and understand the security implications of each. ​ SandboxNetworkConfig Network-specific configuration for sandbox mode. type SandboxNetworkConfig = { allowedDomains ?: string []; deniedDomains ?: string []; allowManagedDomainsOnly ?: boolean ; allowLocalBinding ?: boolean ; allowUnixSockets ?: string []; allowAllUnixSockets ?: boolean ; httpProxyPort ?: number ; socksProxyPort ?: number ; }; Property Type Default Description allowedDomains string[] [] Domain names that sandboxed processes can access deniedDomains string[] [] Domain names that sandboxed processes cannot access. Takes precedence over allowedDomains allowManagedDomainsOnly boolean false Restrict network access to only the domains in allowedDomains allowLocalBinding boolean false Allow processes to bind to local ports (e.g., for dev servers) allowUnixSockets string[] [] Unix socket paths that processes can access (e.g., Docker socket) allowAllUnixSockets boolean false Allow access to all Unix sockets httpProxyPort number undefined HTTP proxy port for network requests socksProxyPort number undefined SOCKS proxy port for network requests The built-in sandbox proxy enforces allowedDomains based on the requested hostname and does not terminate or inspect TLS traffic, so techniques such as domain fronting can potentially bypass it. See Sandboxing security limitations for details and Secure deployment for configuring a TLS-terminating proxy. ​ SandboxFilesystemConfig Filesystem-specific configuration for sandbox mode. type SandboxFilesystemConfig = { allowWrite ?: string []; denyWrite ?: string []; denyRead ?: string []; }; Property Type Default Description allowWrite string[] [] File path patterns to allow write access to denyWrite string[] [] File path patterns to deny write access to denyRead string[] [] File path patterns to deny read access to ​ Permissions Fallback for Unsandboxed Commands When allowUnsandboxedCommands is enabled, the model can request to run commands outside the sandbox by setting dangerouslyDisableSandbox: true in the tool input. These requests fall back to the existing permissions system, meaning your canUseTool handler is invoked, allowing you to implement custom authorization logic. excludedCommands vs allowUnsandboxedCommands : excludedCommands : A static list of commands that always bypass the sandbox automatically (e.g., ['docker'] ). The model has no control over this. allowUnsandboxedCommands : Lets the model decide at runtime whether to request unsandboxed execution by setting dangerouslyDisableSandbox: true in the tool input. import { query } from "@anthropic-ai/claude-agent-sdk" ; for await ( const message of query ({ prompt: "Deploy my application" , options: { sandbox: { enabled: true , allowUnsandboxedCommands: true // Model can request unsandboxed execution }, permissionMode: "default" , canUseTool : async ( tool , input ) => { // Check if the model is requesting to bypass the sandbox if ( tool === "Bash" && input . dangerouslyDisableSandbox ) { // The model is requesting to run this command outside the sandbox console . log ( `Unsandboxed command requested: ${ input . command } ` ); if ( isCommandAuthorized ( input . command )) { return { behavior: "allow" as const , updatedInput: input }; } return { behavior: "deny" as const , message: "Command not authorized for unsandboxed execution" }; } return { behavior: "allow" as const , updatedInput: input }; } } })) { if ( "result" in message ) console . log ( message . result ); } This pattern enables you to: Audit model requests: Log when the model requests unsandboxed execution Implement allowlists: Only permit specific commands to run unsandboxed Add approval workflows: Require explicit authorization for privileged operations Commands running with dangerouslyDisableSandbox: true have full system access. Ensure your canUseTool handler validates these requests carefully. If permissionMode is set to bypassPermissions and allowUnsandboxedCommands is enabled, the model can autonomously execute commands outside the sandbox without any approval prompts. This combination effectively allows the model to escape sandbox isolation silently. ​ See also SDK overview - General SDK concepts Python SDK reference - Python SDK documentation CLI reference - Command-line interface Common workflows - Step-by-step guides Was this page helpful? Yes No Securely deploying AI agents TypeScript V2 (deprecated) Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Troubleshooting Troubleshoot installation and login Agents and parallel work Overview Create custom subagents Agent view Run agent teams Isolate sessions with worktrees Tools and plugins Model Context Protocol (MCP) Discover and install prebuilt plugins Create plugins Extend Claude with skills Automation Automate with hooks Push external events to Claude Run prompts on a schedule Goals Programmatic usage Launch sessions from links Troubleshooting Troubleshoot installation and login Troubleshoot performance and stability Debug configuration Error reference Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. If installation fails or you can’t sign in, find your error below. For runtime issues after Claude Code is working, see Troubleshooting . For configuration problems such as settings not applying or hooks not firing, see Debug your configuration . ​ Find your error Match the error message or symptom you’re seeing to a fix: What you see Solution command not found: claude or 'claude' is not recognized Fix your PATH syntax error near unexpected token '<' Install script returns HTML curl: (56) Failure writing output to destination Check connectivity or use an alternative installer Killed during install on Linux Add swap space for low-memory servers TLS connect error or SSL/TLS secure channel Update CA certificates Failed to fetch version or can’t reach download server Check network and proxy settings irm is not recognized or && is not valid Use the right command for your shell 'bash' is not recognized as the name of a cmdlet Use the Windows installer command Claude Code on Windows requires either Git for Windows (for bash) or PowerShell Install a shell Claude Code does not support 32-bit Windows Open Windows PowerShell, not the x86 entry The process cannot access the file ... because it is being used by another process Clear the downloads folder and retry Error loading shared library Wrong binary variant for your system Illegal instruction Architecture or CPU instruction set mismatch cannot execute binary file: Exec format error in WSL WSL1 native-binary regression PowerShell installer completes but claude is not found or shows an old version Restart your terminal and verify PATH dyld: cannot load , dyld: Symbol not found , or Abort trap on macOS Binary incompatibility Invoke-Expression: Missing argument in parameter list Install script returns HTML App unavailable in region Claude Code is not available in your country. See supported countries . unable to get local issuer certificate Configure corporate CA certificates OAuth error or 403 Forbidden Fix authentication Could not load the default credentials or Could not load credentials from any providers Bedrock, Vertex, or Foundry credentials ChainedTokenCredential authentication failed or CredentialUnavailableError Bedrock, Vertex, or Foundry credentials API Error: 500 , 529 Overloaded , 429 , or other 4xx and 5xx errors not listed above See the Error reference If your issue isn’t listed, work through the diagnostic checks below to narrow down the cause. If you’d rather skip the terminal entirely, the Claude Code Desktop app lets you install and use Claude Code through a graphical interface. Download it for macOS or Windows and start coding without any command-line setup. ​ Run diagnostic checks ​ Check network connectivity The installer downloads from downloads.claude.ai . Verify you can reach it: curl -sI https://downloads.claude.ai/claude-code-releases/latest An HTTP/2 200 line means you reached the server. If you see no output, Could not resolve host , or a connection timeout, your network is blocking the connection. Common causes: Corporate firewalls or proxies blocking downloads.claude.ai Regional network restrictions: try a VPN or alternative network TLS/SSL issues: update your system’s CA certificates, or check if HTTPS_PROXY is configured If you’re behind a corporate proxy, set HTTPS_PROXY and HTTP_PROXY to your proxy’s address before installing. Ask your IT team for the proxy URL if you don’t know it, or check your browser’s proxy settings. This example sets both proxy variables, then runs the installer through your proxy: macOS/Linux Windows PowerShell export HTTP_PROXY = http :// proxy . example . com : 8080 export HTTPS_PROXY = http :// proxy . example . com : 8080 curl -fsSL https://claude.ai/install.sh | bash $ env: HTTP_PROXY = 'http://proxy.example.com:8080' $ env: HTTPS_PROXY = 'http://proxy.example.com:8080' irm https: // claude.ai / install.ps1 | iex ​ Verify your PATH If installation succeeded but you get a command not found or not recognized error when running claude , the install directory isn’t in your PATH. Your shell searches for programs in directories listed in PATH, and the installer places claude at ~/.local/bin/claude on macOS/Linux or %USERPROFILE%\.local\bin\claude.exe on Windows. Check if the install directory is in your PATH by listing your PATH entries and filtering for local/bin : macOS/Linux Windows PowerShell Windows CMD echo $PATH | tr ':' '\n' | grep -Fx " $HOME /.local/bin" If this prints /Users/you/.local/bin or /home/you/.local/bin , the directory is in your PATH and you can skip to Check for conflicting installations . If there’s no output, add it to your shell configuration. For Zsh, the default on macOS: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc For Bash, the default on most Linux distributions: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc source ~/.bashrc Alternatively, close and reopen your terminal. For other shells such as fish or Nushell, add ~/.local/bin to your PATH using your shell’s own configuration syntax, then restart your terminal. Verify the fix worked: claude --version $ env: PATH -split ';' | Select-String '\.local\\bin' If there’s no output, add the install directory to your User PATH: $currentPath = [ Environment ]::GetEnvironmentVariable( 'PATH' , 'User' ) [ Environment ]::SetEnvironmentVariable( 'PATH' , " $currentPath ; $ env: USERPROFILE \.local\bin" , 'User' ) Restart your terminal for the change to take effect. Verify the fix worked: claude -- version echo %PATH% | findstr /i "local\bin" If there’s no output, open System Settings, go to Environment Variables, and add %USERPROFILE%\.local\bin to your User PATH variable. Restart your terminal. Verify the fix worked: claude --version ​ Check for conflicting installations Multiple Claude Code installations can cause version mismatches or unexpected behavior. Check what’s installed: macOS/Linux Windows PowerShell List all claude binaries found in your PATH: which -a claude If this prints nothing, no claude is on your PATH yet. Go back to Verify your PATH . Check the three locations a claude binary can come from. ~/.local/bin/claude is the native installer, ~/.claude/local/ is a legacy local npm install created by older versions of Claude Code, and the npm global list shows a -g install: ls -la ~/.local/bin/claude ls -la ~/.claude/local/ npm -g ls @anthropic-ai/claude-code 2> /dev/null List all claude binaries found in your PATH: where.exe claude Check whether the native installer placed a binary: Test-Path " $ env: USERPROFILE \.local\bin\claude.exe" If you find multiple installations, keep only one. The native install at ~/.local/bin/claude on macOS/Linux or %USERPROFILE%\.local\bin\claude.exe on Windows is recommended. Remove the extras: Uninstall an npm global install: npm uninstall -g @anthropic-ai/claude-code Remove the legacy local npm install: rm -rf ~/.claude/local On Windows, use PowerShell: Remove-Item - Recurse - Force " $ env: USERPROFILE \.claude\local" Remove a Homebrew install on macOS. If you installed the claude-code@latest cask, substitute that name: brew uninstall --cask claude-code Remove a WinGet install on Windows: winget uninstall Anthropic.ClaudeCode ​ Check directory permissions The installer needs write access to ~/.local/bin/ and ~/.claude/ on macOS and Linux. On Windows the install location is under %USERPROFILE% , which is writable by your user by default, so this section rarely applies there. Check whether the directories are writable: test -w ~/.local/bin && echo "writable" || echo "not writable" test -w ~/.claude && echo "writable" || echo "not writable" If either directory isn’t writable, create the install directory and set your user as the owner: sudo mkdir -p ~/.local/bin sudo chown -R $( whoami ) ~/.local ​ Verify the binary works If claude --version prints a version but claude crashes or hangs on startup, run these checks to narrow down the cause. If claude --version says command not found, go to Verify your PATH first; the commands below assume claude is on your PATH. Confirm the binary exists and is executable: ls -la "$( command -v claude)" On Windows, use PowerShell: Get-Command claude | Select-Object Source On Linux, check for missing shared libraries. If ldd shows missing libraries, you may need to install system packages. On Alpine Linux and other musl-based distributions, see Alpine Linux setup . ldd "$( command -v claude)" | grep "not found" Confirm the binary can execute: claude --version ​ Common installation issues These are the most frequently encountered installation problems and their solutions. ​ Install script returns HTML instead of a shell script When running the install command, you may see one of these errors: bash: line 1: syntax error near unexpected token `<' bash: line 1: `' On PowerShell, the same problem appears as: Invoke-Expression: Missing argument in parameter list. This means the install URL returned an HTML page instead of the install script. If the HTML page says “App unavailable in region,” Claude Code is not available in your country. See supported countries . Otherwise, this can happen due to network issues, regional routing, or a temporary service disruption. Solutions: Use an alternative install method : On macOS, install via Homebrew: brew install --cask claude-code On Windows, install via WinGet: winget install Anthropic.ClaudeCode Retry after a few minutes : the issue is often temporary. Wait and try the original command again. ​ command not found: claude after installation The install finished but claude doesn’t work. The exact error varies by platform: Platform Error message macOS zsh: command not found: claude Linux bash: claude: command not found Windows CMD 'claude' is not recognized as an internal or external command PowerShell claude : The term 'claude' is not recognized as the name of a cmdlet This means the install directory isn’t in your shell’s search path. See Verify your PATH for the fix on each platform. ​ curl: (56) Failure writing output to destination The curl ... | bash command downloads the script and pipes it to Bash for execution. This error means the connection broke before the script finished downloading. Common causes include network interruptions, the download being blocked mid-stream, or system resource limits. Solutions: Check network stability : Claude Code binaries are hosted at downloads.claude.ai . Test that you can reach it: curl -sI https://downloads.claude.ai/claude-code-releases/latest An HTTP/2 200 line means you reached the server and the original failure was likely intermittent; retry the install command. If you see Could not resolve host or a connection timeout, your network is blocking the download. Try an alternative install method : On macOS: brew install --cask claude-code On Windows: winget install Anthropic.ClaudeCode ​ TLS or SSL connection errors Errors like curl: (35) TLS connect error , schannel: next InitializeSecurityContext failed , or PowerShell’s Could not establish trust relationship for the SSL/TLS secure channel indicate TLS handshake failures. Solutions: Update your system CA certificates : On Ubuntu/Debian: sudo apt-get update && sudo apt-get install ca-certificates On macOS, the system curl uses the Keychain trust store; updating macOS itself updates the root certificates. On Windows, enable TLS 1.2 in PowerShell before running the installer: [ Net.ServicePointManager ]::SecurityProtocol = [ Net.SecurityProtocolType ]::Tls12 irm https: // claude.ai / install.ps1 | iex Check for proxy or firewall interference : corporate proxies that perform TLS inspection can cause these errors, including unable to get local issuer certificate and SELF_SIGNED_CERT_IN_CHAIN . For the install step, point curl at your corporate CA bundle with --cacert : curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash For Claude Code itself once installed, set NODE_EXTRA_CA_CERTS so API requests trust the same bundle: export NODE_EXTRA_CA_CERTS = / path / to / corporate-ca . pem Ask your IT team for the certificate file if you don’t have it. You can also try on a direct connection to confirm the proxy is the cause. On Windows, bypass certificate revocation checks if you see CRYPT_E_NO_REVOCATION_CHECK (0x80092012) or CRYPT_E_REVOCATION_OFFLINE (0x80092013) . These mean curl reached the server but your network blocks the certificate revocation lookup, which is common behind corporate firewalls. Add --ssl-revoke-best-effort to the install command: curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd Alternatively, install with winget install Anthropic.ClaudeCode , which avoids curl entirely. ​ Failed to fetch version from downloads.claude.ai The installer couldn’t reach the download server. This typically means downloads.claude.ai is blocked on your network. Solutions: Test connectivity directly : curl -sI https://downloads.claude.ai/claude-code-releases/latest If behind a proxy , set HTTPS_PROXY so the installer can route through it. See proxy configuration for details. export HTTPS_PROXY = http :// proxy . example . com : 8080 curl -fsSL https://claude.ai/install.sh | bash If on a restricted network , try a different network or VPN, or use an alternative install method: On macOS: brew install --cask claude-code On Windows: winget install Anthropic.ClaudeCode ​ Wrong install command on Windows If you see 'irm' is not recognized , The token '&&' is not valid , or 'bash' is not recognized as the name of a cmdlet , you copied the install command for a different shell or operating system. irm not recognized : you’re in CMD, not PowerShell. You have two options: Open PowerShell by searching for “PowerShell” in the Start menu, then run the original install command: irm https: // claude.ai / install.ps1 | iex Or stay in CMD and use the CMD installer instead: curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd && not valid : you’re in PowerShell but ran the CMD installer command. Use the PowerShell installer: irm https: // claude.ai / install.ps1 | iex bash not recognized : you ran the macOS/Linux installer on Windows. Use the PowerShell installer instead: irm https: // claude.ai / install.ps1 | iex ​ The process cannot access the file during Windows install If the PowerShell installer fails with Failed to download binary: The process cannot access the file ... because it is being used by another process , the installer couldn’t write to %USERPROFILE%\.claude\downloads . This usually means a previous install attempt is still running, or antivirus software is scanning a partially downloaded binary in that folder. Close any other PowerShell windows running the installer and wait for antivirus scans to release the file. Then delete the downloads folder and run the installer again: Remove-Item - Recurse - Force " $ env: USERPROFILE \.claude\downloads" irm https: // claude.ai / install.ps1 | iex ​ Install killed on low-memory Linux servers If you see Killed during installation on a VPS or cloud instance: Setting up Claude Code... Installing Claude Code native build latest... bash: line 142: 34803 Killed "$binary_path" install ${TARGET:+"$TARGET"} The Linux OOM killer terminated the process because the system ran out of memory. Claude Code requires at least 4 GB of available RAM. Solutions: Add swap space if your server has limited RAM. Swap uses disk space as overflow memory, letting the install complete even with low physical RAM. Create a 2 GB swap file and enable it: sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile Then retry the installation: curl -fsSL https://claude.ai/install.sh | bash Close other processes to free memory before installing. Use a larger instance if possible. Claude Code requires at least 4 GB of RAM. ​ Install hangs in Docker When installing Claude Code in a Docker container, installing as root into / can cause hangs. Solutions: Set a working directory before running the installer. When run from / , the installer scans the entire filesystem, which causes excessive memory usage. Setting WORKDIR limits the scan to a small directory: WORKDIR /tmp RUN curl -fsSL https://claude.ai/install.sh | bash Increase Docker memory limits if using Docker Desktop: docker build --memory=4g . ​ Claude Desktop overrides the claude command on Windows If you installed an older version of Claude Desktop, it may register a Claude.exe in the WindowsApps directory that takes PATH priority over Claude Code CLI. Running claude opens the Desktop app instead of the CLI. Update Claude Desktop to the latest version to fix this issue. ​ Claude Code on Windows requires either Git for Windows (for bash) or PowerShell Claude Code on native Windows needs at least one shell: either Git for Windows for Bash, or PowerShell. When neither is found, this error appears at startup. If only PowerShell is found, Claude Code uses the PowerShell tool instead of Bash. If neither is installed , install one: Git for Windows: download from git-scm.com/downloads/win . During setup, select “Add to PATH.” Restart your terminal after installing. PowerShell 7: download from aka.ms/powershell . If Git is already installed but Claude Code can’t find it, set the path in your settings.json file : { "env" : { "CLAUDE_CODE_GIT_BASH_PATH" : "C: \\ Program Files \\ Git \\ bin \\ bash.exe" } } If your Git is installed somewhere else, find the path by running where.exe git in PowerShell and use the bin\bash.exe path from that directory. ​ Claude Code does not support 32-bit Windows Windows includes two PowerShell entries in the Start menu: Windows PowerShell and Windows PowerShell (x86) . The x86 entry runs as a 32-bit process and triggers this error even on a 64-bit machine. To check which case you’re in, run this in the same window that produced the error: [ Environment ]::Is64BitOperatingSystem If this prints True , your operating system is fine. Close the window, open Windows PowerShell without the x86 suffix, and run the install command again. If this prints False , you are on a 32-bit edition of Windows. Claude Code requires a 64-bit operating system. See the system requirements . ​ Linux musl or glibc binary mismatch If you see errors about missing shared libraries like libstdc++.so.6 or libgcc_s.so.1 after installation, the installer may have downloaded the wrong binary variant for your system. Error loading shared library libstdc++.so.6: No such file or directory This can happen on glibc-based systems that have musl cross-compilation packages installed, causing the installer to misdetect the system as musl. Solutions: Check which libc your system uses : ldd --version 2>&1 | head -1 Output mentioning GNU libc or GLIBC means glibc. Output mentioning musl means musl. If you’re on glibc but got the musl binary , remove the installation and reinstall. You can also manually download the correct binary using the manifest at https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json . File a GitHub issue with the output of ldd --version and ls /lib/libc.musl* . If you’re actually on musl , such as Alpine Linux, install the required packages: apk add libgcc libstdc++ ripgrep ​ Illegal instruction If running claude or the installer prints Illegal instruction , the native binary uses CPU instructions your processor doesn’t support. There are two distinct causes. Architecture mismatch. The installer downloaded the wrong binary, for example x86 on an ARM server. Check with uname -m on macOS or Linux, or $env:PROCESSOR_ARCHITECTURE in PowerShell. If the result doesn’t match the binary you received, file a GitHub issue with the output. Missing AVX instruction set. If your architecture is correct but you still see Illegal instruction , your CPU likely lacks AVX or another instruction the binary requires. This affects roughly pre-2013 Intel and AMD processors, and virtual machines where the hypervisor does not pass AVX through to the guest. On a VPS or VM, run grep -m1 -ow avx /proc/cpuinfo ; an empty result means AVX is not available to the guest. There is no native-binary workaround; track issue #50384 for status, and include your CPU model from grep -m1 "model name" /proc/cpuinfo on Linux or sysctl -n machdep.cpu.brand_string on macOS when reporting. Alternative install methods download the same native binary and won’t resolve either cause. ​ dyld: cannot load on macOS If you see dyld: cannot load , dyld: Symbol not found , or Abort trap: 6 during installation, the binary is incompatible with your macOS version or hardware. dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown) Abort trap: 6 A Symbol not found error that references libicucore also indicates your macOS version is older than the binary supports: dyld: Symbol not found: _ubrk_clone Referenced from: claude-darwin-x64 (which was built for Mac OS X 13.0) Expected in: /usr/lib/libicucore.A.dylib Solutions: Check your macOS version : Claude Code requires macOS 13.0 or later. Open the Apple menu and select About This Mac to check your version. Update macOS if you’re on an older version. The binary uses load commands and system libraries that older macOS versions don’t support. Alternative install methods like Homebrew download the same binary and won’t resolve this error. ​ Exec format error on WSL1 If running claude in WSL prints cannot execute binary file: Exec format error , you’re on WSL1 and hitting a known native-binary regression tracked in issue #38788 . The binary’s program headers changed in a way WSL1’s loader can’t handle. The cleanest fix is to convert your distribution to WSL2 from PowerShell: wsl -- set-version < DistroName > 2 If you need to stay on WSL1, invoke the binary through the dynamic linker. Add this function to ~/.bashrc inside WSL, replacing the path if your home directory differs: claude () { /lib64/ld-linux-x86-64.so.2 "$( readlink -f " $HOME /.local/bin/claude")" " $@ " } Then run source ~/.bashrc and retry claude . ​ npm install errors in WSL These issues apply if you installed Claude Code with npm install -g inside WSL. If you used the native installer , skip this section. OS or platform detection issues. If npm reports a platform mismatch during install, WSL is likely picking up the Windows npm . Run npm config set os linux first, then install with npm install -g @anthropic-ai/claude-code --force . Do not use sudo . exec: node: not found when running claude . Your WSL environment is likely using the Windows installation of Node.js. Confirm with which npm and which node : paths starting with /mnt/c/ are Windows binaries, while Linux paths start with /usr/ . To fix this, install Node via your Linux distribution’s package manager or via nvm . nvm version conflicts. If you have nvm installed in both WSL and Windows, switching Node versions in WSL may break because WSL imports the Windows PATH by default and the Windows nvm takes priority. The most common cause is that nvm isn’t loaded in your shell. Add the nvm loader to ~/.bashrc or ~/.zshrc : export NVM_DIR = " $HOME /.nvm" [ -s " $NVM_DIR /nvm.sh" ] && \. " $NVM_DIR /nvm.sh" [ -s " $NVM_DIR /bash_completion" ] && \. " $NVM_DIR /bash_completion" Or load it in your current session: source ~/.nvm/nvm.sh If nvm is loaded but Windows paths still take priority, prepend your Linux Node path explicitly: export PATH = " $HOME /.nvm/versions/node/$( node -v )/bin: $PATH " Avoid disabling Windows PATH importing via appendWindowsPath = false as this breaks the ability to call Windows executables from WSL. Similarly, avoid uninstalling Node.js from Windows if you use it for Windows development. ​ Permission errors during installation If the native installer fails with permission errors, the target directory may not be writable. See Check directory permissions . If you previously installed with npm and are hitting npm-specific permission errors, switch to the native installer: curl -fsSL https://claude.ai/install.sh | bash ​ Native binary not found after npm install The @anthropic-ai/claude-code npm package pulls in the native binary through a per-platform optional dependency such as @anthropic-ai/claude-code-darwin-arm64 . If running claude after install prints Could not find native binary package "@anthropic-ai/claude-code-" , check the following causes: Optional dependencies are disabled. Remove --omit=optional from your npm install command, --no-optional from pnpm, or --ignore-optional from yarn, and check that .npmrc does not set optional=false . Then reinstall. The native binary is delivered only as an optional dependency, so there is no JavaScript fallback if it is skipped. Unsupported platform. Prebuilt binaries are published for darwin-arm64 , darwin-x64 , linux-x64 , linux-arm64 , linux-x64-musl , linux-arm64-musl , win32-x64 , and win32-arm64 . Claude Code does not ship a binary for other platforms; see the system requirements . Corporate npm mirror is missing the platform packages. Ensure your registry mirrors all eight @anthropic-ai/claude-code-* platform packages in addition to the meta package. Installing with --ignore-scripts does not trigger this error. The postinstall step that links the binary into place is skipped, so Claude Code falls back to a wrapper that locates and spawns the platform binary on each launch. This works but starts more slowly; reinstall with scripts enabled for direct execution. ​ Login and authentication These sections address login failures, OAuth errors, and token issues. ​ Reset your login When login fails and the cause isn’t obvious, a clean re-authentication resolves most cases: Run /logout to sign out completely Close Claude Code Restart with claude and complete the authentication process again If the browser doesn’t open automatically during login, press c to copy the OAuth URL to your clipboard, then paste it into a browser manually. This also works when the URL wraps across lines in a narrow or SSH terminal and can’t be clicked directly. ​ OAuth error: Invalid code If you see OAuth error: Invalid code. Please make sure the full code was copied , the login code expired or was truncated during copy-paste. Solutions: Press Enter to retry and complete the login quickly after the browser opens Type c to copy the full URL if the browser doesn’t open automatically If using a remote/SSH session, the browser may open on the wrong machine. Copy the URL displayed in the terminal and open it in your local browser instead. ​ 403 Forbidden after login If you see API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}} after logging in: Claude Pro/Max users : verify your subscription is active at claude.ai/settings Anthropic Console users : confirm your account has the “Claude Code” or “Developer” role. Admins assign this in the Anthropic Console under Settings → Members. Behind a proxy : corporate proxies can interfere with API requests. See network configuration for proxy setup. ​ This organization has been disabled with an active subscription If you see API Error: 400 ... "This organization has been disabled" despite having an active Claude subscription, an ANTHROPIC_API_KEY environment variable is overriding your subscription. This commonly happens when an old API key from a previous employer or project is still set in your shell profile. When ANTHROPIC_API_KEY is present and you have approved it, Claude Code uses that key instead of your subscription’s OAuth credentials. In non-interactive mode with the -p flag, the key is always used when present. See authentication precedence for the full resolution order. To use your subscription instead, unset the environment variable and remove it from your shell profile: unset ANTHROPIC_API_KEY claude Check ~/.zshrc , ~/.bashrc , or ~/.profile for export ANTHROPIC_API_KEY=... lines and remove them to make the change permanent. On Windows, check your PowerShell profile at $PROFILE and your User environment variables for ANTHROPIC_API_KEY . Run /status inside Claude Code to confirm which authentication method is active. ​ OAuth login fails in WSL2, SSH, or containers When Claude Code runs in WSL2, on a remote machine over SSH, or inside a container, the browser usually opens on a different host and its redirect can’t reach Claude Code’s local callback server. After you sign in, the browser shows a login code instead of redirecting back automatically. Paste that code into the terminal at the Paste code here if prompted prompt to complete login. If the browser doesn’t open at all from WSL2, set the BROWSER environment variable to your Windows browser path: export BROWSER = "/mnt/c/Program Files/Google/Chrome/Application/chrome.exe" claude Alternatively, press c at the interactive login prompt to copy the OAuth URL, or copy the URL that claude auth login prints, and open it in a browser on your local machine. If pasting the code into the interactive prompt does nothing, your terminal’s paste binding likely isn’t reaching the input field. Try your terminal’s alternate paste shortcut, often right-click or Shift+Insert in Windows Terminal, or use claude auth login instead, which reads the pasted code from standard input: claude auth login This fallback also applies on native Windows or any terminal where pasting into the interactive prompt fails. ​ Not logged in or token expired If Claude Code prompts you to log in again after a session, your OAuth token may have expired. Run /login to re-authenticate. If this happens frequently, check that your system clock is accurate, as token validation depends on correct timestamps. On macOS, login can also fail when the Keychain is locked or its password is out of sync with your account password, which prevents Claude Code from saving credentials. Run claude doctor to check Keychain access. To unlock the Keychain manually, run security unlock-keychain ~/Library/Keychains/login.keychain-db . If unlocking doesn’t help, open Keychain Access, select the login keychain, and choose Edit > Change Password for Keychain “login” to resync it with your account password. ​ Bedrock, Vertex, or Foundry credentials not loading If you configured Claude Code to use a cloud provider and see Could not load credentials from any providers on Bedrock, Could not load the default credentials on Vertex, or ChainedTokenCredential authentication failed on Foundry, your cloud provider CLI is likely not authenticated in the current shell. For Bedrock, confirm your AWS credentials are valid: aws sts get-caller-identity For Vertex AI, confirm ANTHROPIC_VERTEX_PROJECT_ID and CLOUD_ML_REGION are set in your shell, then set application default credentials: gcloud auth application-default login For Microsoft Foundry, confirm ANTHROPIC_FOUNDRY_API_KEY is set, or sign in with the Azure CLI so the default credential chain can find your account: az login If credentials work in your terminal but not in the VS Code or JetBrains extension, the IDE process likely didn’t inherit your shell environment. Set the provider environment variables in the IDE’s own settings, or launch the IDE from a terminal where they’re already exported. See Amazon Bedrock , Google Vertex AI , or Microsoft Foundry for full provider setup. ​ Still stuck If none of the above resolves your issue: Check the GitHub repository for known issues, or open a new one with your operating system, the install command you ran, and the full error output If claude --version works but something else is wrong, run claude doctor for an automated diagnostic report If you can start a session, use /feedback inside Claude Code to report the problem Was this page helpful? Yes No Launch sessions from links Troubleshoot performance and stability Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Setup and access Advanced setup Setup and access Administration overview Advanced setup Authentication Server-managed settings Auto mode Deployment Overview Amazon Bedrock Claude Platform on AWS Google Vertex AI Microsoft Foundry Network configuration LLM gateway Development containers Usage and costs Monitoring Costs Track team usage with analytics Plugin distribution Create and distribute a plugin marketplace Plugin dependency versions Security and data Security Data usage Zero data retention Adoption Communications kit Champion kit Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. This page covers system requirements, platform-specific installation details, updates, and uninstallation. For a guided walkthrough of your first session, see the quickstart . If you’ve never used a terminal before, see the terminal guide . ​ System requirements Claude Code runs on the following platforms and configurations: Operating system : macOS 13.0+ Windows 10 1809+ or Windows Server 2019+ Ubuntu 20.04+ Debian 10+ Alpine Linux 3.19+ Hardware : 4 GB+ RAM, x64 or ARM64 processor Network : internet connection required. See network configuration . Shell : Bash, Zsh, PowerShell, or CMD. On native Windows, Git for Windows is recommended; Claude Code falls back to PowerShell when Git Bash is absent. WSL setups do not require Git for Windows. Location : Anthropic supported countries ​ Additional dependencies ripgrep : usually included with Claude Code. If search fails, see search troubleshooting . ​ Install Claude Code Prefer a graphical interface? The Desktop app lets you use Claude Code without the terminal. Download it for macOS or Windows . New to the terminal? See the terminal guide for step-by-step instructions. To install Claude Code, use one of the following methods: Native Install (Recommended) Homebrew WinGet macOS, Linux, WSL: curl -fsSL https://claude.ai/install.sh | bash Windows PowerShell: irm https: // claude.ai / install.ps1 | iex Windows CMD: curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd If you see The token '&&' is not a valid statement separator , you’re in PowerShell, not CMD. If you see 'irm' is not recognized as an internal or external command , you’re in CMD, not PowerShell. Your prompt shows PS C:\ when you’re in PowerShell and C:\ without the PS when you’re in CMD. Git for Windows is recommended on native Windows so Claude Code can use the Bash tool. If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead. WSL setups do not need Git for Windows. Native installations automatically update in the background to keep you on the latest version. brew install --cask claude-code Homebrew offers two casks. claude-code tracks the stable release channel, which is typically about a week behind and skips releases with major regressions. claude-code@latest tracks the latest channel and receives new versions as soon as they ship. Homebrew installations do not auto-update. Run brew upgrade claude-code or brew upgrade claude-code@latest , depending on which cask you installed, to get the latest features and security fixes. winget install Anthropic.ClaudeCode WinGet installations do not auto-update. Run winget upgrade Anthropic.ClaudeCode periodically to get the latest features and security fixes. You can also install with apt, dnf, or apk on Debian, Fedora, RHEL, and Alpine. After installation completes, open a terminal in the project you want to work in and start Claude Code: claude If you encounter any issues during installation, see Troubleshoot installation and login . ​ Set up on Windows You can run Claude Code natively on Windows or inside WSL. Pick based on where your projects are located and which features you need: Option Requires Sandboxing When to use Native Windows Git for Windows recommended; PowerShell used if absent Not supported Windows-native projects and tools WSL 2 WSL 2 enabled Supported Linux toolchains or sandboxed command execution WSL 1 WSL 1 enabled Not supported If WSL 2 is unavailable Option 1: Native Windows with Git Bash Install Git for Windows , then run the install command from PowerShell or CMD. You do not need to run as Administrator. Whether you install from PowerShell or CMD only affects which install command you run. Your prompt shows PS C:\Users\YourName> in PowerShell and C:\Users\YourName> without the PS in CMD. If you’re new to the terminal, the terminal guide walks through each step. After installation, launch claude from PowerShell, CMD, or Git Bash. When Git Bash is installed, Claude Code uses it internally to execute commands regardless of where you launched it. If Claude Code can’t find your Git Bash installation, set the path in your settings.json file : { "env" : { "CLAUDE_CODE_GIT_BASH_PATH" : "C: \\ Program Files \\ Git \\ bin \\ bash.exe" } } Claude Code can also run PowerShell natively on Windows. When Git Bash is installed, the PowerShell tool is rolling out progressively as an additional option: set CLAUDE_CODE_USE_POWERSHELL_TOOL=1 to opt in or 0 to opt out. See PowerShell tool for setup and limitations. Option 2: WSL Open your WSL distribution and run the Linux installer from the install instructions above. You install and launch claude inside the WSL terminal, not from PowerShell or CMD. ​ Alpine Linux and musl-based distributions The native installer on Alpine and other musl/uClibc-based distributions requires libgcc , libstdc++ , and ripgrep . Install these using your distribution’s package manager, then set USE_BUILTIN_RIPGREP=0 . This example installs the required packages on Alpine: apk add libgcc libstdc++ ripgrep Then set USE_BUILTIN_RIPGREP to 0 in your settings.json file: { "env" : { "USE_BUILTIN_RIPGREP" : "0" } } ​ Verify your installation After installing, confirm Claude Code is working: claude --version If this fails with command not found or another error, see Troubleshoot installation and login . For a more detailed check of your installation and configuration, run claude doctor : claude doctor ​ Authenticate Claude Code requires a Pro, Max, Team, Enterprise, or Console account. The free Claude.ai plan does not include Claude Code access. You can also use Claude Code with a third-party API provider like Amazon Bedrock , Google Vertex AI , or Microsoft Foundry . After installing, log in by running claude and following the browser prompts. See Authentication for all account types and team setup options. ​ Update Claude Code Native installations automatically update in the background. You can configure the release channel to control whether you receive updates immediately or on a delayed stable schedule, or disable auto-updates entirely. Homebrew, WinGet, and Linux package manager installations require manual updates by default. ​ Auto-updates Claude Code checks for updates on startup and periodically while running. Updates download and install in the background, then take effect the next time you start Claude Code. Homebrew, WinGet, apt, dnf, and apk installations do not auto-update by default; see below to opt in for Homebrew and WinGet. To upgrade Homebrew manually, run brew upgrade claude-code or brew upgrade claude-code@latest , depending on which cask you installed. For WinGet, run winget upgrade Anthropic.ClaudeCode . For Linux package managers, see the upgrade commands in Install with Linux package managers . To have Claude Code run the upgrade command for you on Homebrew or WinGet, set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE to 1 . Claude Code then runs the upgrade in the background when a new version is available and shows a restart prompt on success. The upgrade targets only the Claude Code package and does not affect other software you have installed. On WinGet the upgrade may fail while Claude Code is running because Windows locks the executable. In that case Claude Code shows the manual command instead. apt, dnf, and apk continue to require a manual upgrade because those commands need elevated privileges. Known issue: Claude Code may notify you of updates before the new version is available in these package managers. If an upgrade fails, wait and try again later. Homebrew keeps old versions on disk after upgrades. Run brew cleanup periodically to reclaim disk space. ​ Configure release channel Control which release channel Claude Code follows for auto-updates and claude update with the autoUpdatesChannel setting: "latest" , the default: receive new features as soon as they’re released "stable" : use a version that is typically about one week old, skipping releases with major regressions Configure this via /config → Auto-update channel , or add it to your settings.json file : { "autoUpdatesChannel" : "stable" } For enterprise deployments, you can enforce a consistent release channel across your organization using managed settings . Homebrew installations choose a channel by cask name instead of this setting: claude-code tracks stable and claude-code@latest tracks latest. ​ Pin a minimum version The minimumVersion setting establishes a floor. Background auto-updates and claude update refuse to install any version below this value, so moving to the "stable" channel does not downgrade you if you are already on a newer "latest" build. Switching from "latest" to "stable" via /config prompts you to either stay on the current version or allow the downgrade. Choosing to stay sets minimumVersion to that version. Switching back to "latest" clears it. Add it to your settings.json file to pin a floor explicitly: { "autoUpdatesChannel" : "stable" , "minimumVersion" : "2.1.100" } In managed settings , this enforces an organization-wide minimum that user and project settings cannot override. ​ Disable auto-updates Set DISABLE_AUTOUPDATER to "1" in the env key of your settings.json file: { "env" : { "DISABLE_AUTOUPDATER" : "1" } } DISABLE_AUTOUPDATER only stops the background check; claude update and claude install still work. To block all update paths, including manual updates, set DISABLE_UPDATES instead. Use this when you distribute Claude Code through your own channels and need users to stay on the version you provide. ​ Update manually To apply an update immediately without waiting for the next background check, run: claude update ​ Advanced installation options These options are for version pinning, Linux package managers, npm, and verifying binary integrity. ​ Install a specific version The native installer accepts either a specific version number or a release channel ( latest or stable ). The channel you choose at install time becomes your default for auto-updates. See configure release channel for more information. To install the latest version (default): macOS, Linux, WSL Windows PowerShell Windows CMD curl -fsSL https://claude.ai/install.sh | bash irm https: // claude.ai / install.ps1 | iex curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd To install the stable version: macOS, Linux, WSL Windows PowerShell Windows CMD curl -fsSL https://claude.ai/install.sh | bash -s stable & ([ scriptblock ]::Create((irm https: // claude.ai / install.ps1))) stable curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd stable && del install.cmd To install a specific version number: macOS, Linux, WSL Windows PowerShell Windows CMD curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89 & ([ scriptblock ]::Create((irm https: // claude.ai / install.ps1))) 2.1 . 89 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 2.1.89 && del install.cmd ​ Install with Linux package managers Claude Code publishes signed apt, dnf, and apk repositories. Replace stable with latest for the rolling channel. Package manager installations do not auto-update through Claude Code; updates arrive through your normal system upgrade workflow. All repositories are signed with the Claude Code release signing key . Before trusting the key, verify it as described in each tab. apt dnf apk For Debian and Ubuntu. To use the rolling channel, change both stable occurrences in the deb line: the URL path and the suite name. sudo install -d -m 0755 /etc/apt/keyrings sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \ -o /etc/apt/keyrings/claude-code.asc echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \ | sudo tee /etc/apt/sources.list.d/claude-code.list sudo apt update sudo apt install claude-code Verify the GPG key fingerprint before trusting it: gpg --show-keys /etc/apt/keyrings/claude-code.asc should report 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE . To upgrade later, run sudo apt update && sudo apt upgrade claude-code . For Fedora and RHEL: sudo tee /etc/yum.repos.d/claude-code.repo << 'EOF' [claude-code] name=Claude Code baseurl=https://downloads.claude.ai/claude-code/rpm/stable enabled=1 gpgcheck=1 gpgkey=https://downloads.claude.ai/keys/claude-code.asc EOF sudo dnf install claude-code dnf downloads the key on first install and prompts you to confirm the fingerprint. Verify it matches 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE before accepting. To upgrade later, run sudo dnf upgrade claude-code . For Alpine Linux: wget -O /etc/apk/keys/claude-code.rsa.pub \ https://downloads.claude.ai/keys/claude-code.rsa.pub echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories apk add claude-code Verify the downloaded key with sha256sum /etc/apk/keys/claude-code.rsa.pub , which should report 395759c1f7449ef4cdef305a42e820f3c766d6090d142634ebdb049f113168b6 . To upgrade later, run apk update && apk upgrade claude-code . ​ Install with npm You can also install Claude Code as a global npm package. The package requires Node.js 18 or later . npm install -g @anthropic-ai/claude-code The npm package installs the same native binary as the standalone installer. npm pulls the binary in through a per-platform optional dependency such as @anthropic-ai/claude-code-darwin-arm64 , and a postinstall step links it into place. The installed claude binary does not itself invoke Node. Supported npm install platforms are darwin-arm64 , darwin-x64 , linux-x64 , linux-arm64 , linux-x64-musl , linux-arm64-musl , win32-x64 , and win32-arm64 . Your package manager must allow optional dependencies. See troubleshooting if the binary is missing after install. To upgrade an npm installation, run npm install -g @anthropic-ai/claude-code@latest . Avoid npm update -g , which respects the semver range from the original install and may not move you to the newest release. Do NOT use sudo npm install -g as this can lead to permission issues and security risks. If you encounter permission errors, see troubleshooting permission errors . ​ Binary integrity and code signing Each release publishes a manifest.json containing SHA256 checksums for every platform binary. The manifest is signed with an Anthropic GPG key, so verifying the signature on the manifest transitively verifies every binary it lists. ​ Verify the manifest signature Steps 1-3 require a POSIX shell with gpg and curl . On Windows, run them in Git Bash or WSL. Step 4 includes a PowerShell option. 1 Download and import the public key The release signing key is published at a fixed URL. curl -fsSL https://downloads.claude.ai/keys/claude-code.asc | gpg --import Display the fingerprint of the imported key. gpg --fingerprint security@anthropic.com Confirm the output includes this fingerprint: 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE 2 Download the manifest and signature Set VERSION to the release you want to verify. REPO = https://downloads.claude.ai/claude-code-releases VERSION = 2.1.89 curl -fsSLO " $REPO / $VERSION /manifest.json" curl -fsSLO " $REPO / $VERSION /manifest.json.sig" 3 Verify the signature Verify the detached signature against the manifest. gpg --verify manifest.json.sig manifest.json A valid result reports Good signature from "Anthropic Claude Code Release Signing " . gpg also prints WARNING: This key is not certified with a trusted signature! for any freshly imported key. This is expected. The Good signature line confirms the cryptographic check passed. The fingerprint comparison in Step 1 confirms the key itself is authentic. 4 Check the binary against the manifest Compare the SHA256 checksum of your downloaded binary with the value listed under platforms..checksum in manifest.json . Linux macOS Windows PowerShell sha256sum claude shasum -a 256 claude ( Get-FileHash claude.exe - Algorithm SHA256).Hash.ToLower() Manifest signatures are available for releases from 2.1.89 onward. Earlier releases publish checksums in manifest.json without a detached signature. ​ Platform code signatures In addition to the signed manifest, individual binaries carry platform-native code signatures where supported. macOS : signed by “Anthropic PBC” and notarized by Apple. Verify with codesign --verify --verbose ./claude . Windows : signed by “Anthropic, PBC”. Verify with Get-AuthenticodeSignature .\claude.exe . Linux : binaries are not individually code-signed. If you download directly from the claude-code-releases bucket or use the native installer, verify integrity with the manifest signature above. If you install with apt, dnf, or apk , your package manager verifies signatures automatically using the repository signing key. ​ Uninstall Claude Code To remove Claude Code, follow the instructions for your installation method. If claude still runs afterward, you likely have a second installation or a leftover shell alias from an older installer. See Check for conflicting installations to find and remove it. ​ Native installation Remove the Claude Code binary and version files: macOS, Linux, WSL Windows PowerShell rm -f ~/.local/bin/claude rm -rf ~/.local/share/claude Remove-Item - Path " $ env: USERPROFILE \.local\bin\claude.exe" - Force Remove-Item - Path " $ env: USERPROFILE \.local\share\claude" - Recurse - Force ​ Homebrew installation Remove the Homebrew cask you installed. If you installed the stable cask: brew uninstall --cask claude-code If you installed the latest cask: brew uninstall --cask claude-code@latest ​ WinGet installation Remove the WinGet package: winget uninstall Anthropic.ClaudeCode ​ apt / dnf / apk Remove the package and the repository configuration: apt dnf apk sudo apt remove claude-code sudo rm /etc/apt/sources.list.d/claude-code.list /etc/apt/keyrings/claude-code.asc sudo dnf remove claude-code sudo rm /etc/yum.repos.d/claude-code.repo apk del claude-code sed -i '\|downloads.claude.ai/claude-code/apk|d' /etc/apk/repositories rm /etc/apk/keys/claude-code.rsa.pub ​ npm Remove the global npm package: npm uninstall -g @anthropic-ai/claude-code ​ Remove configuration files Removing configuration files will delete all your settings, allowed tools, MCP server configurations, and session history. The VS Code extension, the JetBrains plugin, and the Desktop app also write to ~/.claude/ . If any of them is still installed, the directory is recreated the next time it runs. To remove Claude Code completely, uninstall the VS Code extension , the JetBrains plugin, and the Desktop app before deleting these files. To remove Claude Code settings and cached data: macOS, Linux, WSL Windows PowerShell # Remove user settings and state rm -rf ~/.claude rm ~/.claude.json # Remove project-specific settings (run from your project directory) rm -rf .claude rm -f .mcp.json # Remove user settings and state Remove-Item - Path " $ env: USERPROFILE \.claude" - Recurse - Force Remove-Item - Path " $ env: USERPROFILE \.claude.json" - Force # Remove project-specific settings (run from your project directory) Remove-Item - Path ".claude" - Recurse - Force Remove-Item - Path ".mcp.json" - Force Was this page helpful? Yes No Administration overview Authentication Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Settings and permissions Claude Code settings Settings and permissions Settings Permissions Sandboxing Model and responses Model configuration Speed up responses with fast mode Output styles Interface Terminal configuration Fullscreen rendering Voice dictation Customize status line Customize keyboard shortcuts Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. Claude Code offers a variety of settings to configure its behavior to meet your needs. You can configure Claude Code by running the /config command when using the interactive REPL, which opens a tabbed Settings interface where you can view status information and modify configuration options. ​ Configuration scopes Claude Code uses a scope system to determine where configurations apply and who they’re shared with. Understanding scopes helps you decide how to configure Claude Code for personal use, team collaboration, or enterprise deployment. ​ Available scopes Scope Location Who it affects Shared with team? Managed Server-managed settings, plist / registry, or system-level managed-settings.json All users on the machine Yes (deployed by IT) User ~/.claude/ directory You, across all projects No Project .claude/ in repository All collaborators on this repository Yes (committed to git) Local .claude/settings.local.json You, in this repository only No (gitignored) ​ When to use each scope Managed scope is for: Security policies that must be enforced organization-wide Compliance requirements that can’t be overridden Standardized configurations deployed by IT/DevOps User scope is best for: Personal preferences you want everywhere (themes, editor settings) Tools and plugins you use across all projects API keys and authentication (stored securely) Project scope is best for: Team-shared settings (permissions, hooks, MCP servers) Plugins the whole team should have Standardizing tooling across collaborators Local scope is best for: Personal overrides for a specific project Testing configurations before sharing with the team Machine-specific settings that won’t work for others ​ How scopes interact When the same setting appears in multiple scopes, Claude Code applies them in priority order: Managed (highest) - can’t be overridden by anything Command line arguments - temporary session overrides Local - overrides project and user settings Project - overrides user settings User (lowest) - applies when nothing else specifies the setting For example, if your user settings set spinnerTipsEnabled to true and project settings set it to false , the project value applies. Permission rules behave differently because they merge across scopes rather than override. See Settings precedence . ​ What uses scopes Scopes apply to many Claude Code features: Feature User location Project location Local location Settings ~/.claude/settings.json .claude/settings.json .claude/settings.local.json Subagents ~/.claude/agents/ .claude/agents/ None MCP servers ~/.claude.json .mcp.json ~/.claude.json (per-project) Plugins ~/.claude/settings.json .claude/settings.json .claude/settings.local.json CLAUDE.md ~/.claude/CLAUDE.md CLAUDE.md or .claude/CLAUDE.md CLAUDE.local.md On Windows, paths shown as ~/.claude resolve to %USERPROFILE%\.claude . ​ Settings files The settings.json file is the official mechanism for configuring Claude Code through hierarchical settings: User settings are defined in ~/.claude/settings.json and apply to all projects. Project settings are saved in your project directory: .claude/settings.json for settings that are checked into source control and shared with your team .claude/settings.local.json for settings that are not checked in, useful for personal preferences and experimentation. Claude Code will configure git to ignore .claude/settings.local.json when it is created. Managed settings : For organizations that need centralized control, Claude Code supports multiple delivery mechanisms for managed settings. All use the same JSON format and cannot be overridden by user or project settings: Server-managed settings : delivered from Anthropic’s servers via the Claude.ai admin console. See server-managed settings . MDM/OS-level policies : delivered through native device management on macOS and Windows: macOS: com.anthropic.claudecode managed preferences domain. The plist’s top-level keys mirror managed-settings.json , with nested settings as dictionaries and arrays as plist arrays. Deploy via configuration profiles in Jamf, Iru (Kandji), or similar MDM tools. Windows: HKLM\SOFTWARE\Policies\ClaudeCode registry key with a Settings value (REG_SZ or REG_EXPAND_SZ) containing JSON (deployed via Group Policy or Intune) Windows (user-level): HKCU\SOFTWARE\Policies\ClaudeCode (lowest policy priority, only used when no admin-level source exists) File-based : managed-settings.json and managed-mcp.json deployed to system directories: macOS: /Library/Application Support/ClaudeCode/ Linux and WSL: /etc/claude-code/ Windows: C:\Program Files\ClaudeCode\ The legacy Windows path C:\ProgramData\ClaudeCode\managed-settings.json is no longer supported as of v2.1.75. Administrators who deployed settings to that location must migrate files to C:\Program Files\ClaudeCode\managed-settings.json . File-based managed settings also support a drop-in directory at managed-settings.d/ in the same system directory alongside managed-settings.json . This lets separate teams deploy independent policy fragments without coordinating edits to a single file. Following the systemd convention, managed-settings.json is merged first as the base, then all *.json files in the drop-in directory are sorted alphabetically and merged on top. Later files override earlier ones for scalar values; arrays are concatenated and de-duplicated; objects are deep-merged. Hidden files starting with . are ignored. Use numeric prefixes to control merge order, for example 10-telemetry.json and 20-security.json . See managed settings and Managed MCP configuration for details. This repository includes starter deployment templates for Jamf, Iru (Kandji), Intune, and Group Policy. Use these as starting points and adjust them to fit your needs. Managed deployments can also restrict plugin marketplace additions using strictKnownMarketplaces . For more information, see Managed marketplace restrictions . Other configuration is stored in ~/.claude.json . This file contains your OAuth session, MCP server configurations for user and local scopes, per-project state (allowed tools, trust settings), and various caches. Project-scoped MCP servers are stored separately in .mcp.json . Claude Code automatically creates timestamped backups of configuration files and retains the five most recent backups to prevent data loss. Example settings.json { "$schema" : "https://json.schemastore.org/claude-code-settings.json" , "permissions" : { "allow" : [ "Bash(npm run lint)" , "Bash(npm run test *)" , "Read(~/.zshrc)" ], "deny" : [ "Bash(curl *)" , "Read(./.env)" , "Read(./.env.*)" , "Read(./secrets/**)" ] }, "env" : { "CLAUDE_CODE_ENABLE_TELEMETRY" : "1" , "OTEL_METRICS_EXPORTER" : "otlp" }, "companyAnnouncements" : [ "Welcome to Acme Corp! Review our code guidelines at docs.acme.com" , "Reminder: Code reviews required for all PRs" , "New security policy in effect" ] } The $schema line in the example above points to the official JSON schema for Claude Code settings. Adding it to your settings.json enables autocomplete and inline validation in VS Code, Cursor, and any other editor that supports JSON schema validation. The published schema is updated periodically and may not include settings added in the most recent CLI releases, so a validation warning on a recently documented field does not necessarily mean your configuration is invalid. ​ Available settings settings.json supports a number of options: Key Description Example agent Run the main thread as a named subagent. Applies that subagent’s system prompt, tool restrictions, and model. See Invoke subagents explicitly "code-reviewer" allowedChannelPlugins (Managed settings only) Allowlist of channel plugins that may push messages. Replaces the default Anthropic allowlist when set. Undefined = fall back to the default, empty array = block all channel plugins. Requires channelsEnabled: true . See Restrict which channel plugins can run [{ "marketplace": "claude-plugins-official", "plugin": "telegram" }] allowedHttpHookUrls Allowlist of URL patterns that HTTP hooks may target. Supports * as a wildcard. When set, hooks with non-matching URLs are blocked. Undefined = no restriction, empty array = block all HTTP hooks. Arrays merge across settings sources. See Hook configuration ["https://hooks.example.com/*"] allowedMcpServers When set in managed-settings.json, allowlist of MCP servers users can configure. Undefined = no restrictions, empty array = lockdown. Applies to all scopes. Denylist takes precedence. See Managed MCP configuration [{ "serverName": "github" }] allowManagedHooksOnly (Managed settings only) Only managed hooks, SDK hooks, and hooks from plugins force-enabled in managed settings enabledPlugins are loaded. User, project, and all other plugin hooks are blocked. See Hook configuration true allowManagedMcpServersOnly (Managed settings only) Only allowedMcpServers from managed settings are respected. deniedMcpServers still merges from all sources. Users can still add MCP servers, but only the admin-defined allowlist applies. See Managed MCP configuration true allowManagedPermissionRulesOnly (Managed settings only) Prevent user and project settings from defining allow , ask , or deny permission rules. Only rules in managed settings apply. See Managed-only settings true alwaysThinkingEnabled Enable extended thinking by default for all sessions. Typically configured via the /config command rather than editing directly. To force thinking off regardless of this setting, set CLAUDE_CODE_DISABLE_THINKING in env true apiKeyHelper Custom script, to be executed in /bin/sh , to generate an auth value. This value will be sent as X-Api-Key and Authorization: Bearer headers for model requests. Set the refresh interval with CLAUDE_CODE_API_KEY_HELPER_TTL_MS /bin/generate_temp_api_key.sh attribution Customize attribution for git commits and pull requests. See Attribution settings {"commit": "🤖 Generated with Claude Code", "pr": ""} autoMemoryDirectory Custom directory for auto memory storage. Accepts an absolute path or a ~/ -prefixed path. Accepted from policy and user settings, and from the --settings flag. Not accepted from project or local settings, since a cloned repository could supply either file to redirect memory writes to sensitive locations "~/my-memory-dir" autoMemoryEnabled Enable auto memory . When false , Claude does not read from or write to the auto memory directory. Default: true . You can also toggle this with /memory during a session. To disable via environment variable, set CLAUDE_CODE_DISABLE_AUTO_MEMORY in env false autoMode Customize what the auto mode classifier blocks and allows. Contains environment , allow , soft_deny , and hard_deny arrays of prose rules. Include the literal string "$defaults" in an array to inherit the built-in rules at that position. See Configure auto mode . Not read from shared project settings {"soft_deny": ["$defaults", "Never run terraform apply"]} autoScrollEnabled In fullscreen rendering , follow new output to the bottom of the conversation. Default: true . Appears in /config as Auto-scroll . Permission prompts still scroll into view when this is off false autoUpdatesChannel Release channel to follow for updates. Use "stable" for a version that is typically about one week old and skips versions with major regressions, or "latest" (default) for the most recent release. To disable auto-updates entirely, set DISABLE_AUTOUPDATER in env "stable" availableModels Restrict which models users can select via /model , --model , or ANTHROPIC_MODEL . Does not affect the Default option. See Restrict model selection ["sonnet", "haiku"] awaySummaryEnabled Show a one-line session recap when you return to the terminal after a few minutes away. Set to false or turn off Session recap in /config to disable. Same as CLAUDE_CODE_ENABLE_AWAY_SUMMARY true awsAuthRefresh Custom script that modifies the .aws directory (see advanced credential configuration ) aws sso login --profile myprofile awsCredentialExport Custom script that outputs JSON with AWS credentials (see advanced credential configuration ) /bin/generate_aws_grant.sh blockedMarketplaces (Managed settings only) Blocklist of marketplace sources. Enforced on marketplace add and on plugin install, update, refresh, and auto-update, so a marketplace added before the policy was set cannot be used to fetch plugins. Blocked sources are checked before downloading, so they never touch the filesystem. See Managed marketplace restrictions [{ "source": "github", "repo": "untrusted/plugins" }] channelsEnabled (Managed settings only) Allow channels for the organization. On claude.ai Team and Enterprise plans, channels are blocked when this is unset or false . For Anthropic Console accounts using API key authentication, channels are allowed by default unless your organization deploys managed settings, in which case this key must be set to true true claudeMd (Managed settings only) CLAUDE.md-style instructions injected as organization-managed memory. Only honored when set in managed or policy settings and ignored in user, project, and local settings. See organization-wide CLAUDE.md "Always run make lint before committing." claudeMdExcludes Glob patterns or absolute paths of CLAUDE.md files to skip when loading memory . Patterns match against absolute file paths. Only applies to user, project, and local memory; managed policy files cannot be excluded ["**/vendor/**/CLAUDE.md"] cleanupPeriodDays Session files older than this period are deleted at startup (default: 30 days, minimum 1). Setting to 0 is rejected with a validation error. Also controls the age cutoff for automatic removal of orphaned subagent worktrees at startup. To disable transcript writes entirely, set the CLAUDE_CODE_SKIP_PROMPT_HISTORY environment variable, or in non-interactive mode ( -p ) use the --no-session-persistence flag or the persistSession: false SDK option. 20 companyAnnouncements Announcement to display to users at startup. If multiple announcements are provided, they will be cycled through at random. ["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"] defaultShell Default shell for input-box ! commands. Accepts "bash" (default) or "powershell" . Setting "powershell" routes interactive ! commands through PowerShell on Windows. Requires CLAUDE_CODE_USE_POWERSHELL_TOOL=1 . See PowerShell tool "powershell" deniedMcpServers When set in managed-settings.json, denylist of MCP servers that are explicitly blocked. Applies to all scopes including managed servers. Denylist takes precedence over allowlist. See Managed MCP configuration [{ "serverName": "filesystem" }] disableAgentView Set to true to turn off background agents and agent view : claude agents , --bg , /background , and the on-demand supervisor. Typically set in managed settings . Equivalent to setting CLAUDE_CODE_DISABLE_AGENT_VIEW to 1 true disableAllHooks Disable all hooks and any custom status line true disableAutoMode Set to "disable" to prevent auto mode from being activated. Removes auto from the Shift+Tab cycle and rejects --permission-mode auto at startup. Most useful in managed settings where users cannot override it "disable" disableDeepLinkRegistration Set to "disable" to prevent Claude Code from registering the claude-cli:// protocol handler with the operating system on startup. Deep links let external tools open a Claude Code session with a pre-filled prompt. Useful in environments where protocol handler registration is restricted or managed separately "disable" disabledMcpjsonServers List of specific MCP servers from .mcp.json files to reject ["filesystem"] disableRemoteControl Disable Remote Control : blocks claude remote-control , the --remote-control flag, auto-start, and the in-session toggle. Typically placed in managed settings for per-device MDM enforcement, but works from any scope. Requires Claude Code v2.1.128 or later true disableSkillShellExecution Disable inline shell execution for !`...` and ```! blocks in skills and custom commands from user, project, plugin, or additional-directory sources. Commands are replaced with [shell command execution disabled by policy] instead of being run. Bundled and managed skills are not affected. Most useful in managed settings where users cannot override it true editorMode Key binding mode for the input prompt: "normal" or "vim" . Default: "normal" . Appears in /config as Editor mode "vim" effortLevel Persist the effort level across sessions. Accepts "low" , "medium" , "high" , or "xhigh" . Written automatically when you run /effort with one of those values. --effort and CLAUDE_CODE_EFFORT_LEVEL override this for one session. See Adjust effort level for supported models "xhigh" enableAllProjectMcpServers Automatically approve all MCP servers defined in project .mcp.json files true enabledMcpjsonServers List of specific MCP servers from .mcp.json files to approve ["memory", "github"] env Environment variables that will be applied to every session {"FOO": "bar"} fastModePerSessionOptIn When true , fast mode does not persist across sessions. Each session starts with fast mode off, requiring users to enable it with /fast . The user’s fast mode preference is still saved. See Require per-session opt-in true feedbackSurveyRate Probability (0–1) that the session quality survey appears when eligible. Set to 0 to suppress entirely, or set CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY in env . Useful when using Bedrock, Vertex, or Foundry where the default sample rate does not apply 0.05 fileSuggestion Configure a custom script for @ file autocomplete. See File suggestion settings {"type": "command", "command": "~/.claude/file-suggestion.sh"} forceLoginMethod Use claudeai to restrict login to Claude.ai accounts, console to restrict login to Claude Console (API usage billing) accounts claudeai forceLoginOrgUUID Require login to belong to a specific organization. Accepts a single UUID string, which also pre-selects that organization during login, or an array of UUIDs where any listed organization is accepted without pre-selection. When set in managed settings, login fails if the authenticated account does not belong to a listed organization; an empty array fails closed and blocks login with a misconfiguration message "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" or ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"] forceRemoteSettingsRefresh (Managed settings only) Block CLI startup until remote managed settings are freshly fetched from the server. If the fetch fails, the CLI exits rather than continuing with cached or no settings. When not set, startup continues without waiting for remote settings. See fail-closed enforcement true gcpAuthRefresh Custom script that refreshes GCP Application Default Credentials when they expire or cannot be loaded. See advanced credential configuration gcloud auth application-default login hooks Configure custom commands to run at lifecycle events. See hooks documentation for format See hooks httpHookAllowedEnvVars Allowlist of environment variable names HTTP hooks may interpolate into headers. When set, each hook’s effective allowedEnvVars is the intersection with this list. Undefined = no restriction. Arrays merge across settings sources. See Hook configuration ["MY_TOKEN", "HOOK_SECRET"] includeCoAuthoredBy Deprecated : Use attribution instead. Whether to include the co-authored-by Claude byline in git commits and pull requests (default: true ) false includeGitInstructions Include built-in commit and PR workflow instructions and the git status snapshot in Claude’s system prompt (default: true ). Set to false to remove both, for example when using your own git workflow skills. The CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS environment variable takes precedence over this setting when set false language Configure Claude’s preferred response language (e.g., "japanese" , "spanish" , "french" ). Claude will respond in this language by default. Also sets the voice dictation language "japanese" maxSkillDescriptionChars Per-skill character cap on the combined description and when_to_use text in the skill listing Claude sees each turn (default: 1536 ). Text longer than this is truncated. Raise to keep long descriptions intact at the cost of more context per turn; lower to fit more skills under skillListingBudgetFraction . Requires Claude Code v2.1.105 or later 2048 minimumVersion Floor that prevents background auto-updates and claude update from installing a version below this one. Switching from the "latest" channel to "stable" via /config prompts you to stay on the current version or allow the downgrade. Choosing to stay sets this value. Also useful in managed settings to pin an organization-wide minimum "2.1.100" model Override the default model to use for Claude Code. --model and ANTHROPIC_MODEL override this for one session "claude-sonnet-4-6" modelOverrides Map Anthropic model IDs to provider-specific model IDs such as Bedrock inference profile ARNs. Each model picker entry uses its mapped value when calling the provider API. See Override model IDs per version {"claude-opus-4-6": "arn:aws:bedrock:..."} otelHeadersHelper Script to generate dynamic OpenTelemetry headers. Runs at startup and periodically. Set the refresh interval with CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS . See Dynamic headers /bin/generate_otel_headers.sh outputStyle Configure an output style to adjust the system prompt. See output styles documentation "Explanatory" parentSettingsBehavior (Managed settings only) Controls whether managed settings supplied programmatically by an embedding host process, such as the Agent SDK or an IDE extension, apply when an admin-deployed managed tier is also present. "first-wins" : the parent-supplied settings are dropped and only the admin tier applies. "merge" : the parent-supplied settings apply under the admin tier, filtered so they can tighten policy but not loosen it. Has no effect when no admin tier is deployed. Default: "first-wins" . Requires Claude Code v2.1.133 or later "merge" permissions See table below for structure of permissions. plansDirectory Customize where plan files are stored. Path is relative to project root. Default: ~/.claude/plans "./plans" pluginTrustMessage (Managed settings only) Custom message appended to the plugin trust warning shown before installation. Use this to add organization-specific context, for example to confirm that plugins from your internal marketplace are vetted. "All plugins from our marketplace are approved by IT" policyHelper Admin-deployed executable that computes managed settings dynamically at startup. Only honored from MDM or a system managed-settings.json file. See Compute managed settings with a policy helper . Requires Claude Code v2.1.136 or later {"path": "/usr/local/bin/claude-policy"} preferredNotifChannel Method for task-complete and permission-prompt notifications: "auto" , "terminal_bell" , "iterm2" , "iterm2_with_bell" , "kitty" , "ghostty" , or "notifications_disabled" . Default: "auto" , which sends a desktop notification in iTerm2, Ghostty, and Kitty and does nothing in other terminals. Set "terminal_bell" to ring the bell character in any terminal. Appears in /config as Notifications . See Get a terminal bell or notification "terminal_bell" prefersReducedMotion Reduce or disable UI animations (spinners, shimmer, flash effects) for accessibility true prUrlTemplate URL template for the PR badge shown in the footer and in tool-result summaries. Substitutes {host} , {owner} , {repo} , {number} , and {url} from the gh -reported PR URL. Use to point PR links at an internal code-review tool instead of github.com . Does not affect #123 autolinks in Claude’s prose "https://reviews.example.com/{owner}/{repo}/pull/{number}" respectGitignore Control whether the @ file picker respects .gitignore patterns. When true (default), files matching .gitignore patterns are excluded from suggestions false showClearContextOnPlanAccept Show the “clear context” option on the plan accept screen. Defaults to false . Set to true to restore the option true showThinkingSummaries Show extended thinking summaries in interactive sessions. When unset or false (default in interactive mode), thinking blocks are redacted by the API and shown as a collapsed stub. Redaction only changes what you see, not what the model generates: to reduce thinking spend, lower the budget or disable thinking instead. Non-interactive mode ( -p ) and SDK callers always receive summaries regardless of this setting true showTurnDuration Show turn duration messages after responses, e.g. “Cooked for 1m 6s”. Default: true . Appears in /config as Show turn duration false skillListingBudgetFraction Fraction of the model’s context window reserved for the skill listing Claude sees each turn (default: 0.01 = 1%). When the listing exceeds the budget, descriptions for the least-used skills are collapsed to bare names so Claude can still invoke them but won’t see why. Raise to keep more descriptions visible at the cost of more context per turn. /doctor shows the current truncation count and which skills are affected. Requires Claude Code v2.1.105 or later 0.02 skillOverrides Per-skill visibility overrides keyed by skill name. Value is "on" , "name-only" , "user-invocable-only" , or "off" . Lets you hide or collapse a skill without editing its SKILL.md. Does not apply to plugin skills, which are managed through /plugin . The /skills menu writes these to .claude/settings.local.json . See Override skill visibility from settings . Requires Claude Code v2.1.129 or later {"legacy-context": "name-only", "deploy": "off"} skipWebFetchPreflight Skip the WebFetch domain safety check that sends each requested hostname to api.anthropic.com before fetching. Set to true in environments that block traffic to Anthropic, such as Bedrock, Vertex AI, or Foundry deployments with restrictive egress. When skipped, WebFetch attempts any URL without consulting the blocklist true spinnerTipsEnabled Show tips in the spinner while Claude is working. Set to false to disable tips (default: true ) false spinnerTipsOverride Override spinner tips with custom strings. tips : array of tip strings. excludeDefault : if true , only show custom tips; if false or absent, custom tips are merged with built-in tips { "excludeDefault": true, "tips": ["Use our internal tool X"] } spinnerVerbs Customize the action verbs shown in the spinner and turn duration messages. Set mode to "replace" to use only your verbs, or "append" to add them to the defaults {"mode": "append", "verbs": ["Pondering", "Crafting"]} sshConfigs SSH connections to show in the Desktop environment dropdown. Each entry requires id , name , and sshHost ; sshPort , sshIdentityFile , and startDirectory are optional. When set in managed settings, connections are read-only for users. Read from managed and user settings only [{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}] statusLine Configure a custom status line to display context. See statusLine documentation {"type": "command", "command": "~/.claude/statusline.sh"} strictKnownMarketplaces (Managed settings only) Allowlist of plugin marketplace sources. Undefined = no restrictions, empty array = lockdown. Enforced on marketplace add and on plugin install, update, refresh, and auto-update, so a marketplace added before the policy was set cannot be used to fetch plugins. See Managed marketplace restrictions [{ "source": "github", "repo": "acme-corp/plugins" }] syntaxHighlightingDisabled Disable syntax highlighting in diffs, code blocks, and file previews true teammateMode How agent team teammates display: auto (picks split panes in tmux or iTerm2, in-process otherwise), in-process , or tmux . --teammate-mode overrides this for one session. See choose a display mode "in-process" terminalProgressBarEnabled Show the terminal progress bar in supported terminals: ConEmu, Ghostty 1.2.0+, and iTerm2 3.6.6+. Default: true . Appears in /config as Terminal progress bar false tui Terminal UI renderer. Use "fullscreen" for the flicker-free alt-screen renderer with virtualized scrollback. Use "default" for the classic main-screen renderer. Set via /tui . You can also set the CLAUDE_CODE_NO_FLICKER environment variable "fullscreen" useAutoModeDuringPlan Whether plan mode uses auto mode semantics when auto mode is available. Default: true . Not read from shared project settings. Appears in /config as “Use auto mode during plan” false viewMode Default transcript view mode on startup: "default" , "verbose" , or "focus" . Overrides the sticky /focus selection when set. The --verbose flag overrides this for one session "verbose" voice Voice dictation settings: enabled turns dictation on, mode selects "hold" or "tap" , and autoSubmit sends the prompt on key release in hold mode. Written automatically when you run /voice . Requires a Claude.ai account { "enabled": true, "mode": "tap" } voiceEnabled Legacy alias for voice.enabled . Prefer the voice object true wslInheritsWindowsSettings (Windows managed settings only) When true , Claude Code on WSL reads managed settings from the Windows policy chain in addition to /etc/claude-code , with Windows sources taking priority. Only honored when set in the HKLM registry key or C:\Program Files\ClaudeCode\managed-settings.json , both of which require Windows admin to write. For HKCU policy to also apply on WSL, the flag must additionally be set in HKCU itself. Has no effect on native Windows true ​ Global config settings These settings are stored in ~/.claude.json rather than settings.json . Adding them to settings.json will trigger a schema validation error. Versions before v2.1.119 also store autoScrollEnabled , editorMode , showTurnDuration , teammateMode , and terminalProgressBarEnabled here instead of in settings.json . Key Description Example autoConnectIde Automatically connect to a running IDE when Claude Code starts from an external terminal. Default: false . Appears in /config as Auto-connect to IDE (external terminal) when running outside a VS Code or JetBrains terminal. The CLAUDE_CODE_AUTO_CONNECT_IDE environment variable overrides this when set true autoInstallIdeExtension Automatically install the Claude Code IDE extension when running from a VS Code terminal. Default: true . Appears in /config as Auto-install IDE extension when running inside a VS Code or JetBrains terminal. You can also set the CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL environment variable false externalEditorContext Prepend Claude’s previous response as # -commented context when you open the external editor with Ctrl+G . Default: false . Appears in /config as Show last response in external editor true teammateDefaultModel Default model for agent team teammates when the spawn prompt doesn’t specify one. Set to a model alias such as "sonnet" , or null to inherit the lead’s current /model selection. Appears in /config as Default teammate model "sonnet" ​ Worktree settings Configure how --worktree creates and manages git worktrees. Key Description Example worktree.baseRef Which ref new worktrees branch from. "fresh" (default) branches from origin/ for a clean tree matching the remote. "head" branches from your current local HEAD , so unpushed commits and feature-branch state are present in the worktree. Applies to --worktree , the EnterWorktree tool, and subagent isolation "head" worktree.symlinkDirectories Directories to symlink from the main repository into each worktree to avoid duplicating large directories on disk. No directories are symlinked by default ["node_modules", ".cache"] worktree.sparsePaths Directories to check out in each worktree via git sparse-checkout. Only the listed directories plus root-level files are written to disk, which is faster in large monorepos ["packages/my-app", "shared/utils"] To copy gitignored files like .env into new worktrees, use a .worktreeinclude file in your project root instead of a setting. ​ Permission settings Keys Description Example allow Array of permission rules to allow tool use. See Permission rule syntax below for pattern matching details [ "Bash(git diff *)" ] ask Array of permission rules to ask for confirmation upon tool use. See Permission rule syntax below [ "Bash(git push *)" ] deny Array of permission rules to deny tool use. Use this to exclude sensitive files from Claude Code access. See Permission rule syntax and Bash permission limitations [ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ] additionalDirectories Additional working directories for file access. Most .claude/ configuration is not discovered from these directories [ "../docs/" ] defaultMode Default permission mode when opening Claude Code. Valid values: default , acceptEdits , plan , auto , dontAsk , bypassPermissions . The --permission-mode CLI flag overrides this setting for a single session "acceptEdits" disableBypassPermissionsMode Set to "disable" to prevent bypassPermissions mode from being activated. This disables the --dangerously-skip-permissions command-line flag. Typically placed in managed settings to enforce organizational policy, but works from any scope "disable" skipDangerousModePermissionPrompt Skip the confirmation prompt shown before entering bypass permissions mode via --dangerously-skip-permissions or defaultMode: "bypassPermissions" . Ignored when set in project settings ( .claude/settings.json ) to prevent untrusted repositories from auto-bypassing the prompt true ​ Permission rule syntax Permission rules follow the format Tool or Tool(specifier) . Rules are evaluated in order: deny rules first, then ask, then allow. The first matching rule wins. Quick examples: Rule Effect Bash Matches all Bash commands Bash(npm run *) Matches commands starting with npm run Read(./.env) Matches reading the .env file WebFetch(domain:example.com) Matches fetch requests to example.com For the complete rule syntax reference, including wildcard behavior, tool-specific patterns for Read, Edit, WebFetch, MCP, and Agent rules, and security limitations of Bash patterns, see Permission rule syntax . ​ Sandbox settings Configure advanced sandboxing behavior. Sandboxing isolates bash commands from your filesystem and network. See Sandboxing for details. Keys Description Example enabled Enable bash sandboxing (macOS, Linux, and WSL2). Default: false true failIfUnavailable Exit with an error at startup if sandbox.enabled is true but the sandbox cannot start (missing dependencies or unsupported platform). When false (default), a warning is shown and commands run unsandboxed. Intended for managed settings deployments that require sandboxing as a hard gate true autoAllowBashIfSandboxed Auto-approve bash commands when sandboxed. Default: true true excludedCommands Commands that should run outside of the sandbox ["docker *"] allowUnsandboxedCommands Allow commands to run outside the sandbox via the dangerouslyDisableSandbox parameter. When set to false , the dangerouslyDisableSandbox escape hatch is completely disabled and all commands must run sandboxed (or be in excludedCommands ). Useful for enterprise policies that require strict sandboxing. Default: true false filesystem.allowWrite Additional paths where sandboxed commands can write. Arrays are merged across all settings scopes: user, project, and managed paths are combined, not replaced. Also merged with paths from Edit(...) allow permission rules. See path prefixes below. ["/tmp/build", "~/.kube"] filesystem.denyWrite Paths where sandboxed commands cannot write. Arrays are merged across all settings scopes. Also merged with paths from Edit(...) deny permission rules. ["/etc", "/usr/local/bin"] filesystem.denyRead Paths where sandboxed commands cannot read. Arrays are merged across all settings scopes. Also merged with paths from Read(...) deny permission rules. ["~/.aws/credentials"] filesystem.allowRead Paths to re-allow reading within denyRead regions. Takes precedence over denyRead . Arrays are merged across all settings scopes. Use this to create workspace-only read access patterns. ["."] filesystem.allowManagedReadPathsOnly (Managed settings only) Only filesystem.allowRead paths from managed settings are respected. denyRead still merges from all sources. Default: false true network.allowUnixSockets (macOS only) Unix socket paths accessible in sandbox. Ignored on Linux and WSL2, where the seccomp filter cannot inspect socket paths; use allowAllUnixSockets instead. ["~/.ssh/agent-socket"] network.allowAllUnixSockets Allow all Unix socket connections in sandbox. On Linux and WSL2 this is the only way to permit Unix sockets, since it skips the seccomp filter that otherwise blocks socket(AF_UNIX, ...) calls. Default: false true network.allowLocalBinding Allow binding to localhost ports (macOS only). Default: false true network.allowMachLookup Additional XPC/Mach service names the sandbox may look up (macOS only). Supports a single trailing * for prefix matching. Needed for tools that communicate via XPC such as the iOS Simulator or Playwright. ["com.apple.coresimulator.*"] network.allowedDomains Array of domains to allow for outbound network traffic. Supports wildcards (e.g., *.example.com ). ["github.com", "*.npmjs.org"] network.deniedDomains Array of domains to block for outbound network traffic. Supports the same wildcard syntax as allowedDomains . Takes precedence over allowedDomains when both match. Merged from all settings sources regardless of allowManagedDomainsOnly . ["sensitive.cloud.example.com"] network.allowManagedDomainsOnly (Managed settings only) Only allowedDomains and WebFetch(domain:...) allow rules from managed settings are respected. Domains from user, project, and local settings are ignored. Non-allowed domains are blocked automatically without prompting the user. Denied domains are still respected from all sources. Default: false true network.httpProxyPort HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. 8080 network.socksProxyPort SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. 8081 enableWeakerNestedSandbox Enable weaker sandbox for unprivileged Docker environments (Linux and WSL2 only). Reduces security. Default: false true enableWeakerNetworkIsolation (macOS only) Allow access to the system TLS trust service ( com.apple.trustd.agent ) in the sandbox. Required for Go-based tools like gh , gcloud , and terraform to verify TLS certificates when using httpProxyPort with a MITM proxy and custom CA. Reduces security by opening a potential data exfiltration path. Default: false true bwrapPath (Managed settings only, Linux/WSL2) Absolute path to the bubblewrap ( bwrap ) binary. Overrides automatic detection via PATH . Only honored from managed settings , not from user or project settings. Useful when bwrap is installed at a non-standard location in managed environments. /opt/admin/bwrap socatPath (Managed settings only, Linux/WSL2) Absolute path to the socat binary used for the sandbox network proxy. Overrides automatic detection via PATH . Only honored from managed settings. /opt/admin/socat ​ Sandbox path prefixes Paths in filesystem.allowWrite , filesystem.denyWrite , filesystem.denyRead , and filesystem.allowRead support these prefixes: Prefix Meaning Example / Absolute path from filesystem root /tmp/build stays /tmp/build ~/ Relative to home directory ~/.kube becomes $HOME/.kube ./ or no prefix Relative to the project root for project settings, or to ~/.claude for user settings ./output in .claude/settings.json resolves to /output The older //path prefix for absolute paths still works. If you previously used single-slash /path expecting project-relative resolution, switch to ./path . This syntax differs from Read and Edit permission rules , which use //path for absolute and /path for project-relative. Sandbox filesystem paths use standard conventions: /tmp/build is an absolute path. Configuration example: { "sandbox" : { "enabled" : true , "autoAllowBashIfSandboxed" : true , "excludedCommands" : [ "docker *" ], "filesystem" : { "allowWrite" : [ "/tmp/build" , "~/.kube" ], "denyRead" : [ "~/.aws/credentials" ] }, "network" : { "allowedDomains" : [ "github.com" , "*.npmjs.org" , "registry.yarnpkg.com" ], "deniedDomains" : [ "uploads.github.com" ], "allowUnixSockets" : [ "/var/run/docker.sock" ], "allowLocalBinding" : true } } } Filesystem and network restrictions can be configured in two ways that are merged together: sandbox.filesystem settings (shown above): Control paths at the OS-level sandbox boundary. These restrictions apply to all subprocess commands (e.g., kubectl , terraform , npm ), not just Claude’s file tools. Permission rules : Use Edit allow/deny rules to control Claude’s file tool access, Read deny rules to block reads, and WebFetch allow/deny rules to control network domains. Paths from these rules are also merged into the sandbox configuration. ​ Attribution settings Claude Code adds attribution to git commits and pull requests. These are configured separately: Commits use git trailers (like Co-Authored-By ) by default, which can be customized or disabled Pull request descriptions are plain text Keys Description commit Attribution for git commits, including any trailers. Empty string hides commit attribution pr Attribution for pull request descriptions. Empty string hides pull request attribution Default commit attribution: 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.6 Default pull request attribution: 🤖 Generated with [Claude Code](https://claude.com/claude-code) Example: { "attribution" : { "commit" : "Generated with AI \n\n Co-Authored-By: AI " , "pr" : "" } } The attribution setting takes precedence over the deprecated includeCoAuthoredBy setting. To hide all attribution, set commit and pr to empty strings. ​ File suggestion settings Configure a custom command for @ file path autocomplete. The built-in file suggestion uses fast filesystem traversal, but large monorepos may benefit from project-specific indexing such as a pre-built file index or custom tooling. { "fileSuggestion" : { "type" : "command" , "command" : "~/.claude/file-suggestion.sh" } } The command runs with the same environment variables as hooks , including CLAUDE_PROJECT_DIR . It receives JSON via stdin with a query field: { "query" : "src/comp" } Output newline-separated file paths to stdout (currently limited to 15): src/components/Button.tsx src/components/Modal.tsx src/components/Form.tsx Example: #!/bin/bash query = $( cat | jq -r '.query' ) your-repo-file-index --query " $query " | head -20 ​ Hook configuration These settings control which hooks are allowed to run and what HTTP hooks can access. The allowManagedHooksOnly setting can only be configured in managed settings . The URL and env var allowlists can be set at any settings level and merge across sources. Behavior when allowManagedHooksOnly is true : Managed hooks and SDK hooks are loaded Hooks from plugins force-enabled in managed settings enabledPlugins are loaded. This lets administrators distribute vetted hooks through an organization marketplace while blocking everything else. Trust is granted by full plugin@marketplace ID, so a plugin with the same name from a different marketplace stays blocked User hooks, project hooks, and all other plugin hooks are blocked Restrict HTTP hook URLs: Limit which URLs HTTP hooks can target. Supports * as a wildcard for matching. When the array is defined, HTTP hooks targeting non-matching URLs are silently blocked. Hostname matching is case-insensitive and ignores a trailing FQDN dot, matching DNS semantics. { "allowedHttpHookUrls" : [ "https://hooks.example.com/*" , "http://localhost:*" ] } Restrict HTTP hook environment variables: Limit which environment variable names HTTP hooks can interpolate into header values. Each hook’s effective allowedEnvVars is the intersection of its own list and this setting. { "httpHookAllowedEnvVars" : [ "MY_TOKEN" , "HOOK_SECRET" ] } ​ Compute managed settings with a policy helper The policyHelper setting points at an executable that computes managed settings at startup, so admins can derive policy from device posture, identity, or a remote service instead of a static file. Configure it from MDM or a system managed-settings.json file. Claude Code ignores policyHelper when it appears in any other scope, including user settings, project settings, the HKCU registry hive, and server-managed settings . The setting accepts these keys: Key Type Description path string Absolute path to the helper executable timeoutMs number How long to wait for the helper before treating the run as failed refreshIntervalMs number How often to re-run the helper in the background. Set to 0 to disable refresh, or to at least 60000 The helper writes a JSON envelope to stdout. Put the settings under a managedSettings key rather than at the top level, since a bare settings object parses with managedSettings undefined and applies nothing: { "managedSettings" : { "permissions" : { "deny" : [ "Read(//etc/secrets/**)" ] } }, "claudeMd" : "# Organization context \n ..." , "appendSystemPrompt" : "Always cite the internal style guide." } When the helper emits managedSettings , that object replaces the file-based managed settings for the run. When the helper exits non-zero at startup, Claude Code prints the error and refuses to start, so a helper that needs outage resilience should serve from its own cache and exit 0 . ​ Settings precedence Settings apply in order of precedence. From highest to lowest: Managed settings ( server-managed , MDM/OS-level policies , or managed settings ) Policies deployed by IT through server delivery, MDM configuration profiles, registry policies, or managed settings files Cannot be overridden by any other level, including command line arguments Within the managed tier, precedence is: server-managed > MDM/OS-level policies > file-based ( managed-settings.d/*.json + managed-settings.json ) > HKCU registry (Windows only). Only one managed source is used; sources do not merge across tiers. Within the file-based tier, drop-in files and the base file are merged together. Embedding hosts such as Claude Desktop can supply policy via the SDK managedSettings option. By default this is ignored when any managed-settings tier is present. Administrators can opt in by setting parentSettingsBehavior to "merge" . The embedder’s values are filtered so they can tighten managed policy but not loosen it. Command line arguments Temporary overrides for a specific session. JSON passed via --settings merges with file-based settings using the same rules as the other layers: a key set here overrides the same key in local, project, or user settings, and omitting a key leaves the lower-layer value in place Local project settings ( .claude/settings.local.json ) Personal project-specific settings Shared project settings ( .claude/settings.json ) Team-shared project settings in source control User settings ( ~/.claude/settings.json ) Personal global settings This hierarchy ensures that organizational policies are always enforced while still allowing teams and individuals to customize their experience. The same precedence applies whether you run Claude Code from the CLI, the VS Code extension , or a JetBrains IDE . For example, if your user settings set permissions.defaultMode to acceptEdits and a project’s shared settings set it to default , the project value applies. The example below covers how array-valued settings such as permission rules combine instead. Array settings merge across scopes. When the same array-valued setting (such as sandbox.filesystem.allowWrite or permissions.allow ) appears in multiple scopes, the arrays are concatenated and deduplicated , not replaced. This means lower-priority scopes can add entries without overriding those set by higher-priority scopes, and vice versa. For example, if managed settings set allowWrite to ["/opt/company-tools"] and a user adds ["~/.kube"] , both paths are included in the final configuration. ​ Verify active settings Run /status inside Claude Code to see which settings sources are active. The Status tab includes a Setting sources line that lists each layer Claude Code loaded for the current session, such as User settings or Project local settings . When managed settings are in effect, the entry shows the delivery channel in parentheses, for example Enterprise managed settings (remote) , (plist) , (HKLM) , (HKCU) , or (file) . A layer appears in the list only when that source is loaded with at least one key, so an empty list means no settings sources were found. The Setting sources line confirms which sources are being read. It does not show which layer supplied each individual key. The Config tab in the same dialog is an editor for a fixed set of toggles such as theme and verbose output, not a view of your settings.json contents. If a settings file contains errors, such as invalid JSON or a value that fails validation, /status reports the issue so you can fix it. ​ Key points about the configuration system Memory files ( CLAUDE.md ) : Contain instructions and context that Claude loads at startup Settings files (JSON) : Configure permissions, environment variables, and tool behavior Skills : Custom prompts that can be invoked with /skill-name or loaded by Claude automatically MCP servers : Extend Claude Code with additional tools and integrations Precedence : Higher-level configurations (Managed) override lower-level ones (User/Project) Inheritance : Settings merge across scopes; scalar values from higher-priority scopes override, and arrays concatenate ​ System prompt Claude Code’s internal system prompt is not published. To add custom instructions, use CLAUDE.md files or the --append-system-prompt flag. ​ Excluding sensitive files To prevent Claude Code from accessing files containing sensitive information like API keys, secrets, and environment files, use the permissions.deny setting in your .claude/settings.json file: { "permissions" : { "deny" : [ "Read(./.env)" , "Read(./.env.*)" , "Read(./secrets/**)" , "Read(./config/credentials.json)" , "Read(./build)" ] } } This replaces the deprecated ignorePatterns configuration. Files matching these patterns are excluded from file discovery and search results, and read operations on these files are denied. ​ Subagent configuration Claude Code supports custom AI subagents that can be configured at both user and project levels. These subagents are stored as Markdown files with YAML frontmatter: User subagents : ~/.claude/agents/ - Available across all your projects Project subagents : .claude/agents/ - Specific to your project and can be shared with your team Subagent files define specialized AI assistants with custom prompts and tool permissions. Learn more about creating and using subagents in the subagents documentation . ​ Plugin configuration Claude Code supports a plugin system that lets you extend functionality with skills, agents, hooks, and MCP servers. Plugins are distributed through marketplaces and can be configured at both user and repository levels. ​ Plugin settings Plugin-related settings in settings.json : { "enabledPlugins" : { "formatter@acme-tools" : true , "deployer@acme-tools" : true , "analyzer@security-plugins" : false }, "extraKnownMarketplaces" : { "acme-tools" : { "source" : { "source" : "github" , "repo" : "acme-corp/claude-plugins" } } } } ​ enabledPlugins Controls which plugins are enabled. Format: "plugin-name@marketplace-name": true/false Scopes : User settings ( ~/.claude/settings.json ): Personal plugin preferences Project settings ( .claude/settings.json ): Project-specific plugins shared with team Local settings ( .claude/settings.local.json ): Per-machine overrides (not committed) Managed settings ( managed-settings.json ): Organization-wide policy overrides that block installation at all scopes and hide the plugin from the marketplace Project settings take precedence over user settings, so setting a plugin to false in ~/.claude/settings.json does not disable a plugin that the project’s .claude/settings.json enables. To opt out of a project-enabled plugin on your machine, set it to false in .claude/settings.local.json instead. Plugins force-enabled by managed settings cannot be disabled this way, since managed settings override local settings. Example : { "enabledPlugins" : { "code-formatter@team-tools" : true , "deployment-tools@team-tools" : true , "experimental-features@personal" : false } } ​ extraKnownMarketplaces Defines additional marketplaces that should be made available for the repository. Typically used in repository-level settings to ensure team members have access to required plugin sources. When a repository includes extraKnownMarketplaces : Team members are prompted to install the marketplace when they trust the folder Team members are then prompted to install plugins from that marketplace Users can skip unwanted marketplaces or plugins (stored in user settings) Installation respects trust boundaries and requires explicit consent Example : { "extraKnownMarketplaces" : { "acme-tools" : { "source" : { "source" : "github" , "repo" : "acme-corp/claude-plugins" } }, "security-plugins" : { "source" : { "source" : "git" , "url" : "https://git.example.com/security/plugins.git" } } } } Marketplace source types : github : GitHub repository (uses repo ) git : Any git URL (uses url ) directory : Local filesystem path (uses path , for development only) hostPattern : regex pattern to match marketplace hosts (uses hostPattern ) settings : inline marketplace declared directly in settings.json without a separate hosted repository (uses name and plugins ) Each marketplace entry also accepts an optional autoUpdate Boolean. Set "autoUpdate": true alongside source to make Claude Code refresh that marketplace and update its installed plugins at startup. When omitted, official Anthropic marketplaces default to true and all other marketplaces default to false . See Configure auto-updates . Use source: 'settings' to declare a small set of plugins inline without setting up a hosted marketplace repository. Plugins listed here must reference external sources such as GitHub or npm. You still need to enable each plugin separately in enabledPlugins . { "extraKnownMarketplaces" : { "team-tools" : { "source" : { "source" : "settings" , "name" : "team-tools" , "plugins" : [ { "name" : "code-formatter" , "source" : { "source" : "github" , "repo" : "acme-corp/code-formatter" } } ] } } } } ​ strictKnownMarketplaces Managed settings only : Controls which plugin marketplaces users are allowed to add and install plugins from. This setting can only be configured in managed settings and provides administrators with strict control over marketplace sources. Managed settings file locations : macOS : /Library/Application Support/ClaudeCode/managed-settings.json Linux and WSL : /etc/claude-code/managed-settings.json Windows : C:\Program Files\ClaudeCode\managed-settings.json Key characteristics : Only available in managed settings ( managed-settings.json ) Cannot be overridden by user or project settings (highest precedence) Enforced BEFORE network/filesystem operations (blocked sources never execute) Uses exact matching for source specifications (including ref , path for git sources), except hostPattern and pathPattern , which use regex matching Allowlist behavior : undefined (default): No restrictions - users can add any marketplace Empty array [] : Complete lockdown - users cannot add any new marketplaces List of sources: Users can only add marketplaces that match exactly All supported source types : The allowlist supports multiple marketplace source types. Most sources use exact matching, while hostPattern and pathPattern use regex matching against the marketplace host and filesystem path respectively. GitHub repositories : { "source" : "github" , "repo" : "acme-corp/approved-plugins" } { "source" : "github" , "repo" : "acme-corp/security-tools" , "ref" : "v2.0" } { "source" : "github" , "repo" : "acme-corp/plugins" , "ref" : "main" , "path" : "marketplace" } Fields: repo (required), ref (optional: branch/tag/SHA), path (optional: subdirectory) Git repositories : { "source" : "git" , "url" : "https://gitlab.example.com/tools/plugins.git" } { "source" : "git" , "url" : "https://bitbucket.org/acme-corp/plugins.git" , "ref" : "production" } { "source" : "git" , "url" : "ssh://git@git.example.com/plugins.git" , "ref" : "v3.1" , "path" : "approved" } Fields: url (required), ref (optional: branch/tag/SHA), path (optional: subdirectory) URL-based marketplaces : { "source" : "url" , "url" : "https://plugins.example.com/marketplace.json" } { "source" : "url" , "url" : "https://cdn.example.com/marketplace.json" , "headers" : { "Authorization" : "Bearer ${TOKEN}" } } Fields: url (required), headers (optional: HTTP headers for authenticated access) URL-based marketplaces only download the marketplace.json file. They do not download plugin files from the server. Plugins in URL-based marketplaces must use external sources (GitHub, npm, or git URLs) rather than relative paths. For plugins with relative paths, use a Git-based marketplace instead. See Troubleshooting for details. NPM packages : { "source" : "npm" , "package" : "@acme-corp/claude-plugins" } { "source" : "npm" , "package" : "@acme-corp/approved-marketplace" } Fields: package (required, supports scoped packages) File paths : { "source" : "file" , "path" : "/usr/local/share/claude/acme-marketplace.json" } { "source" : "file" , "path" : "/opt/acme-corp/plugins/marketplace.json" } Fields: path (required: absolute path to marketplace.json file) Directory paths : { "source" : "directory" , "path" : "/usr/local/share/claude/acme-plugins" } { "source" : "directory" , "path" : "/opt/acme-corp/approved-marketplaces" } Fields: path (required: absolute path to directory containing .claude-plugin/marketplace.json ) Host pattern matching : { "source" : "hostPattern" , "hostPattern" : "^github \\ .example \\ .com$" } { "source" : "hostPattern" , "hostPattern" : "^gitlab \\ .internal \\ .example \\ .com$" } Fields: hostPattern (required: regex pattern to match against the marketplace host) Use host pattern matching when you want to allow all marketplaces from a specific host without enumerating each repository individually. This is useful for organizations with internal GitHub Enterprise or GitLab servers where developers create their own marketplaces. Host extraction by source type: github : always matches against github.com git : extracts hostname from the URL (supports both HTTPS and SSH formats) url : extracts hostname from the URL npm , file , directory : not supported for host pattern matching Path pattern matching : { "source" : "pathPattern" , "pathPattern" : "^/opt/approved/" } { "source" : "pathPattern" , "pathPattern" : ".*" } Fields: pathPattern (required: regex pattern matched against the path field of file and directory sources) Use path pattern matching to allow filesystem-based marketplaces alongside hostPattern restrictions for network sources. Set ".*" to allow all local paths, or a narrower pattern to restrict to specific directories. Configuration examples : Example: allow specific marketplaces only: { "strictKnownMarketplaces" : [ { "source" : "github" , "repo" : "acme-corp/approved-plugins" }, { "source" : "github" , "repo" : "acme-corp/security-tools" , "ref" : "v2.0" }, { "source" : "url" , "url" : "https://plugins.example.com/marketplace.json" }, { "source" : "npm" , "package" : "@acme-corp/compliance-plugins" } ] } Example - Disable all marketplace additions: { "strictKnownMarketplaces" : [] } Example: allow all marketplaces from an internal git server: { "strictKnownMarketplaces" : [ { "source" : "hostPattern" , "hostPattern" : "^github \\ .example \\ .com$" } ] } Exact matching requirements : Marketplace sources must match exactly for a user’s addition to be allowed. For git-based sources ( github and git ), this includes all optional fields: The repo or url must match exactly The ref field must match exactly (or both be undefined) The path field must match exactly (or both be undefined) Examples of sources that do NOT match : // These are DIFFERENT sources: { "source" : "github" , "repo" : "acme-corp/plugins" } { "source" : "github" , "repo" : "acme-corp/plugins" , "ref" : "main" } // These are also DIFFERENT: { "source" : "github" , "repo" : "acme-corp/plugins" , "path" : "marketplace" } { "source" : "github" , "repo" : "acme-corp/plugins" } Comparison with extraKnownMarketplaces : Aspect strictKnownMarketplaces extraKnownMarketplaces Purpose Organizational policy enforcement Team convenience Settings file managed-settings.json only Any settings file Behavior Blocks non-allowlisted additions Auto-installs missing marketplaces When enforced Before network/filesystem operations After user trust prompt Can be overridden No (highest precedence) Yes (by higher precedence settings) Source format Direct source object Named marketplace with nested source Use case Compliance, security restrictions Onboarding, standardization Format difference : strictKnownMarketplaces uses direct source objects: { "strictKnownMarketplaces" : [ { "source" : "github" , "repo" : "acme-corp/plugins" } ] } extraKnownMarketplaces requires named marketplaces: { "extraKnownMarketplaces" : { "acme-tools" : { "source" : { "source" : "github" , "repo" : "acme-corp/plugins" } } } } Using both together : strictKnownMarketplaces is a policy gate: it controls what users may add but does not register any marketplaces. To both restrict and pre-register a marketplace for all users, set both in managed-settings.json : { "strictKnownMarketplaces" : [ { "source" : "github" , "repo" : "acme-corp/plugins" } ], "extraKnownMarketplaces" : { "acme-tools" : { "source" : { "source" : "github" , "repo" : "acme-corp/plugins" } } } } With only strictKnownMarketplaces set, users can still add the allowed marketplace manually via /plugin marketplace add , but it is not available automatically. Important notes : Restrictions are checked BEFORE any network requests or filesystem operations When blocked, users see clear error messages indicating the source is blocked by managed policy The restriction is enforced on marketplace add and on plugin install, update, refresh, and auto-update. A marketplace added before the policy was set cannot be used to install or update plugins once its source no longer matches the allowlist Managed settings have the highest precedence and cannot be overridden See Managed marketplace restrictions for user-facing documentation. ​ Managing plugins Use the /plugin command to manage plugins interactively: Browse available plugins from marketplaces Install/uninstall plugins Enable/disable plugins View plugin details (skills, agents, hooks provided) Add/remove marketplaces Learn more about the plugin system in the plugins documentation . ​ Environment variables Environment variables let you control Claude Code behavior without editing settings files. Any variable can also be configured in settings.json under the env key to apply it to every session or roll it out to your team. See the environment variables reference for the full list. ​ Tools available to Claude Claude Code has access to a set of tools for reading, editing, searching, running commands, and orchestrating subagents. Tool names are the exact strings you use in permission rules and hook matchers. See the tools reference for the full list and Bash tool behavior details. ​ See also Permissions : permission system, rule syntax, tool-specific patterns, and managed policies Authentication : set up user access to Claude Code Debug your configuration : diagnose why a setting, hook, or MCP server isn’t taking effect Troubleshoot installation and login : installation, authentication, and platform issues Was this page helpful? Yes No Permissions Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Customize behavior Slash Commands in the SDK Agent SDK Overview Quickstart Core concepts How the agent loop works Use Claude Code features Work with sessions Input and output Streaming Input Handle approvals and user input Stream responses in real-time Get structured output from agents Extend with tools Give Claude custom tools Connect to external tools with MCP Scale to many tools with tool search Subagents in the SDK Customize behavior Modifying system prompts Slash Commands in the SDK Agent Skills in the SDK Plugins in the SDK Control and observability Configure permissions Intercept and control agent behavior with hooks Rewind file changes with checkpointing Track cost and usage Observability with OpenTelemetry Todo Lists Deployment Hosting the Agent SDK Securely deploying AI agents SDK references TypeScript SDK TypeScript V2 (deprecated) Python SDK Migration Guide Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. Slash commands provide a way to control Claude Code sessions with special commands that start with / . These commands can be sent through the SDK to perform actions like compacting context, listing context usage, or invoking custom commands. Only commands that work without an interactive terminal are dispatchable through the SDK; the system/init message lists the ones available in your session. ​ Discovering Available Slash Commands The Claude Agent SDK provides information about available slash commands in the system initialization message. Access this information when your session starts: TypeScript Python import { query } from "@anthropic-ai/claude-agent-sdk" ; for await ( const message of query ({ prompt: "Hello Claude" , options: { maxTurns: 1 } })) { if ( message . type === "system" && message . subtype === "init" ) { console . log ( "Available slash commands:" , message . slash_commands ); // Example output: ["/compact", "/context", "/usage"] } } ​ Sending Slash Commands Send slash commands by including them in your prompt string, just like regular text: TypeScript Python import { query } from "@anthropic-ai/claude-agent-sdk" ; // Send a slash command for await ( const message of query ({ prompt: "/compact" , options: { maxTurns: 1 } })) { if ( message . type === "result" && message . subtype === "success" ) { console . log ( "Command executed:" , message . result ); } } ​ Common Slash Commands ​ /compact - Compact Conversation History The /compact command reduces the size of your conversation history by summarizing older messages while preserving important context: TypeScript Python import { query } from "@anthropic-ai/claude-agent-sdk" ; for await ( const message of query ({ prompt: "/compact" , options: { maxTurns: 1 } })) { if ( message . type === "system" && message . subtype === "compact_boundary" ) { console . log ( "Compaction completed" ); console . log ( "Pre-compaction tokens:" , message . compact_metadata . pre_tokens ); console . log ( "Trigger:" , message . compact_metadata . trigger ); } } ​ Clearing the conversation The interactive /clear command is not available in the SDK. Each query() call already starts a fresh conversation, so to clear context, end the current query() and start a new one. The previous conversation stays on disk and can be returned to by passing its session ID to the resume option . ​ Creating Custom Slash Commands In addition to using built-in slash commands, you can create your own custom commands that are available through the SDK. Custom commands are defined as markdown files in specific directories, similar to how subagents are configured. The .claude/commands/ directory is the legacy format. The recommended format is .claude/skills//SKILL.md , which supports the same slash-command invocation ( /name ) plus autonomous invocation by Claude. See Skills for the current format. The CLI continues to support both formats, and the examples below remain accurate for .claude/commands/ . ​ File Locations Custom slash commands are stored in designated directories based on their scope: Project commands : .claude/commands/ - Available only in the current project (legacy; prefer .claude/skills/ ) Personal commands : ~/.claude/commands/ - Available across all your projects (legacy; prefer ~/.claude/skills/ ) ​ File Format Each custom command is a markdown file where: The filename (without .md extension) becomes the command name The file content defines what the command does Optional YAML frontmatter provides configuration ​ Basic Example Create .claude/commands/refactor.md : Refactor the selected code to improve readability and maintainability. Focus on clean code principles and best practices. This creates the /refactor command that you can use through the SDK. ​ With Frontmatter Create .claude/commands/security-check.md : --- allowed-tools : Read, Grep, Glob description : Run security vulnerability scan model : claude-opus-4-7 --- Analyze the codebase for security vulnerabilities including: - SQL injection risks - XSS vulnerabilities - Exposed credentials - Insecure configurations ​ Using Custom Commands in the SDK Once defined in the filesystem, custom commands are automatically available through the SDK: TypeScript Python import { query } from "@anthropic-ai/claude-agent-sdk" ; // Use a custom command for await ( const message of query ({ prompt: "/refactor src/auth/login.ts" , options: { maxTurns: 3 } })) { if ( message . type === "assistant" ) { console . log ( "Refactoring suggestions:" , message . message ); } } // Custom commands appear in the slash_commands list for await ( const message of query ({ prompt: "Hello" , options: { maxTurns: 1 } })) { if ( message . type === "system" && message . subtype === "init" ) { // Will include both built-in and custom commands console . log ( "Available commands:" , message . slash_commands ); // Example: ["/compact", "/context", "/usage", "/refactor", "/security-check"] } } ​ Advanced Features ​ Arguments and Placeholders Custom commands support dynamic arguments using placeholders: Create .claude/commands/fix-issue.md : --- argument-hint : [ issue-number ] [ priority ] description : Fix a GitHub issue --- Fix issue #$1 with priority $2. Check the issue description and implement the necessary changes. Use in SDK: TypeScript Python import { query } from "@anthropic-ai/claude-agent-sdk" ; // Pass arguments to custom command for await ( const message of query ({ prompt: "/fix-issue 123 high" , options: { maxTurns: 5 } })) { // Command will process with $1="123" and $2="high" if ( message . type === "result" && message . subtype === "success" ) { console . log ( "Issue fixed:" , message . result ); } } ​ Bash Command Execution Custom commands can execute bash commands and include their output: Create .claude/commands/git-commit.md : --- allowed-tools : Bash(git add *), Bash(git status *), Bash(git commit *) description : Create a git commit --- ## Context - Current status: ! `git status` - Current diff: ! `git diff HEAD` ## Task Create a git commit with appropriate message based on the changes. ​ File References Include file contents using the @ prefix: Create .claude/commands/review-config.md : --- description : Review configuration files --- Review the following configuration files for issues: - Package config: @package.json - TypeScript config: @tsconfig.json - Environment config: @.env Check for security issues, outdated dependencies, and misconfigurations. ​ Organization with Namespacing Organize commands in subdirectories for better structure: .claude/commands/ ├── frontend/ │ ├── component.md # Creates /component (project:frontend) │ └── style-check.md # Creates /style-check (project:frontend) ├── backend/ │ ├── api-test.md # Creates /api-test (project:backend) │ └── db-migrate.md # Creates /db-migrate (project:backend) └── review.md # Creates /review (project) The subdirectory appears in the command description but doesn’t affect the command name itself. ​ Practical Examples ​ Code Review Command Create .claude/commands/code-review.md : --- allowed-tools : Read, Grep, Glob, Bash(git diff *) description : Comprehensive code review --- ## Changed Files ! `git diff --name-only HEAD~1` ## Detailed Changes ! `git diff HEAD~1` ## Review Checklist Review the above changes for: 1. Code quality and readability 2. Security vulnerabilities 3. Performance implications 4. Test coverage 5. Documentation completeness Provide specific, actionable feedback organized by priority. ​ Test Runner Command Create .claude/commands/test.md : --- allowed-tools : Bash, Read, Edit argument-hint : [ test-pattern ] description : Run tests with optional pattern --- Run tests matching pattern: $ARGUMENTS 1. Detect the test framework (Jest, pytest, etc.) 2. Run tests with the provided pattern 3. If tests fail, analyze and fix them 4. Re-run to verify fixes Use these commands through the SDK: TypeScript Python import { query } from "@anthropic-ai/claude-agent-sdk" ; // Run code review for await ( const message of query ({ prompt: "/code-review" , options: { maxTurns: 3 } })) { // Process review feedback } // Run specific tests for await ( const message of query ({ prompt: "/test auth" , options: { maxTurns: 5 } })) { // Handle test results } ​ See Also Slash Commands - Complete slash command documentation Subagents in the SDK - Similar filesystem-based configuration for subagents TypeScript SDK reference - Complete API documentation SDK overview - General SDK concepts CLI reference - Command-line interface Was this page helpful? Yes No Modifying system prompts Agent Skills in the SDK Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Adoption Champion kit Setup and access Administration overview Advanced setup Authentication Server-managed settings Auto mode Deployment Overview Amazon Bedrock Claude Platform on AWS Google Vertex AI Microsoft Foundry Network configuration LLM gateway Development containers Usage and costs Monitoring Costs Track team usage with analytics Plugin distribution Create and distribute a plugin marketplace Plugin dependency versions Security and data Security Data usage Zero data retention Adoption Communications kit Champion kit Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. This page is for individual engineers who are already using Claude Code and want to help their team adopt it. It covers what to share, how to answer the questions you will get, a thirty-day playbook, and responses to common concerns. Adoption of a developer tool rarely happens because of a rollout announcement. It happens because someone on the team begins using the tool well, talks about it openly, and makes it easy for others to follow. The work you do as a champion has a disproportionate effect: every example you share shortens the learning curve for the engineers who come after you, and every question you answer in public turns one person’s experience into something the whole team can build on. You are acting as a multiplier for your team, not a help desk, and this guide is structured to keep the role sustainable on those terms. ​ The champion role The role consists of three behaviors that reinforce one another. Behavior What it looks like in practice Why it matters Share what you discover Post the prompts, screenshots, and small wins from your own work in the places your team already reads, such as an engineering channel, a standup thread, or a pull-request description. Examples drawn from your own codebase are more persuasive than any external documentation, because colleagues can see exactly how the tool applies to the problems they share with you. Be the person people ask When a colleague asks how you accomplished something, respond with the actual prompt you used so they can apply it directly to their own task. A concrete, runnable example removes the gap between curiosity and a first successful use, which is where most adoption efforts stall. Grow the circle Establish a small number of lightweight, recurring habits, such as a dedicated channel or a weekly thread, so that momentum continues even when your attention is elsewhere. Adoption that depends on a single person is fragile. Adoption that is carried by shared habits continues to compound on its own. Most of this fits naturally inside the work you are already doing. The difference is a small amount of additional intention about where your discoveries are posted and how your answers travel. ​ What this should cost you Set expectations with yourself and with your lead. The activities below are intended to fit inside a normal working week, and the role should remain a multiplier on your existing work rather than an additional support responsibility. Activity Time per week Guidance Posting wins and prompts About 15 minutes Capture these in the moment with a screenshot and one or two sentences; avoid turning them into formal write-ups. Answering questions in a shared channel About 20 minutes Answer publicly once, then link back to that answer when the question recurs. Hosting a weekly show-and-tell thread About 5 minutes You post the opening prompt; the team supplies the content. Optional pairing or walkthroughs 0 to 30 minutes Reserve this for colleagues who are genuinely blocked, and offer the Quickstart link before scheduling time. ​ Share what you discover Your own experience is the most persuasive material your colleagues will encounter, because it is specific to the codebase, workflows, and problems you all share. Documentation tells people what is possible; your posts show them what is actually working in your environment. ​ What is worth sharing The most useful posts describe a technique a colleague can reuse tomorrow rather than an outcome that is already complete. Techniques compound as they spread through a team; status updates do not. Examples of reusable techniques: “I learned that @-mentioning a directory works. Pointing it at @src/components/ and asking which were missing tests surfaced two I had overlooked.” “Plan mode ( Shift+Tab ) shows exactly which files will be touched before any edit is made, which is why I am comfortable using it on shared code.” “I configured a Stop hook so I receive a desktop notification when a long task completes. Configuration is in the thread.” “Running /init generates a CLAUDE.md from the repository so the assistant stops re-asking about our conventions.” ​ Where to share it Post wherever your team already reads. The goal is to place examples in the path of normal work rather than to create a destination. Location Best suited for Recommended format A #claude-code or general engineering channel Discoveries, prompts, and “today I learned” moments A screenshot accompanied by one or two sentences of context Pull-request descriptions Demonstrating the approach on real code that reviewers are already reading A single line such as “Claude and I did this refactor; happy to walk through the approach.” Standups or weekly written updates Normalizing usage with leads and skip-level managers One sentence describing one concrete outcome Team wiki or internal documentation Durable patterns, custom skills, and CLAUDE.md examples A short page, linked from the channel topic so it remains discoverable ​ The format that works A screenshot accompanied by a single line of context, or a brief before-and-after description, is generally the right level of detail. Keep each post short enough that someone scrolling past still absorbs the point. A long write-up tends to be saved for later and forgotten, whereas a short post with a screenshot tends to be copied and tried. The example posts below illustrate tone and length; adapt them rather than copying verbatim. Learned today that @-mentioning a directory works. I pointed it at @src/components/ and asked which components were missing tests, and it surfaced two I had forgotten about. I configured a Stop hook so I receive a desktop notification when a long task completes. I started a refactor, stepped away, and was notified when it finished. Configuration is in the thread. Plan mode is the reason I am comfortable using this on code that matters. Press Shift+Tab until you see "plan"; it lays out exactly which files it intends to touch before changing anything. ​ Be the person people ask Once you have shared a few examples, questions will follow. This is where the champion role has the greatest leverage, because a good answer to one person frequently unblocks several others who are watching the same channel. ​ Answer with a prompt rather than an explanation When a colleague asks how you accomplished something, the most useful response is the prompt you actually used. They will learn more from running that prompt against their own problem than from any description you could write, and it gives them something they can act on immediately. Colleague: How did you get it to find that race condition? Champion: I asked, "The test in @tests/scheduler.test.ts is flaky, figure out why," and it traced two unjoined promises in the scheduler. Try the same phrasing on your test. ​ Point at the feature rather than the documentation A response such as “Try plan mode, press Shift+Tab until you see it” is more useful in the moment than a link to the documentation. If the person needs more depth later they will find it on their own; right now they need the single thing that unblocks them. ​ Questions you are likely to hear Question Suggested response Follow-up resource ”What should I try it on first?” Recommend a real but contained task, ideally a bug or chore the person has been postponing because it is tedious rather than difficult. Common workflows ”How do I trust it with my code?” Introduce plan mode: pressing Shift+Tab cycles into it, Claude proposes exactly what it intends to change, and nothing is modified until the user approves. Permissions ”Is the setup worth the effort?” Installation takes roughly two minutes, runs in the terminal, and requires no IDE extension. Running /init once is sufficient to begin working. Quickstart ”It produced an incorrect result.” Encourage them to provide the failure back to Claude. Pasting the error message or failing test is far more effective than rephrasing the original request. Common workflows ”It does not understand our codebase conventions.” Suggest running /init to generate a CLAUDE.md file, then adding the team’s conventions, test commands, and any directories that should be avoided. Memory ”Is this just autocomplete?” Offer a brief demonstration in which Claude explains an unfamiliar file, traces a bug across services, or drafts a migration plan. These tasks require reasoning across the repository rather than completing a single line. A two-minute live demonstration ”What about security and data handling?” Refer this question to your administrator. Your organization’s deployment and data-handling policy is already configured, and champions should not improvise this answer. Security · Data usage ​ Grow the circle The objective is not to build a program or to own a rollout. It is to establish a small number of lightweight habits that allow momentum to continue after you have stopped actively driving it. When questions in the channel are being answered by people other than you, the role has done its job. ​ Patterns that tend to work Pattern How to run it Effort required A dedicated channel Create a #claude-code channel (or a recurring thread in an existing one), pin the Quickstart link and one strong example, and answer questions publicly so each answer benefits everyone watching. About five minutes to set up, then ambient A weekly show-and-tell thread Each Friday, post “What did Claude help you with this week?” No preparation, slides, or meeting are required; screenshots and short descriptions are sufficient. About two minutes per week Share a custom skill Post your most useful .claude/skills//SKILL.md file, for example a /ship skill that runs tests and lint before committing, with a one-line description. Because skills are plain Markdown, colleagues can adopt them immediately. About five minutes per skill Generate a setup guide from your own usage Run /team-onboarding in a project you have spent real time in. Claude scans your recent sessions, commands, and MCP servers, then produces a guide a new teammate can paste as their first message to replay your setup. Pin it in the channel. About two minutes Pair on a first task Offer a single fifteen-minute pairing session to anyone getting started. One successful outcome on their own code is more persuasive than any presentation. About fifteen minutes per person Identify the next champion The colleague who asks you the most questions is usually ready to take on this role. Forward them this page and divide the channel responsibilities between you. Negligible ​ Thirty-day playbook If a loose plan is helpful, the sequence below reflects what tends to work across most teams. Adjust freely to fit your context. 1 Week 1: Seed the channel Create the channel, pin the Quickstart , and post two or three of your own examples with the prompts included. Signal that it is working: a few colleagues react or reply, and at least one question is asked in the channel. 2 Week 2: Start the rhythm Start the weekly show-and-tell thread, answer every question publicly, and share one custom skill or CLAUDE.md snippet. Signal that it is working: someone other than you posts an example of their own. 3 Week 3: Pair and consolidate Offer two or three short pairing sessions and consolidate the most common questions and answers into a pinned FAQ message. Signal that it is working: you see repeat usage, with the same colleagues returning rather than trying once and stopping. 4 Week 4: Hand off Identify a second champion and share a brief summary of what is working and what is not with your lead or administrator. Signal that it is working: questions in the channel are being answered by people other than you. ​ When someone wants to go deeper You are the warm introduction rather than the onboarding program. When a colleague moves past “should I try this” into “how do I become effective with it,” point them to the Quickstart and Common workflows pages. They contain short sections covering the features that are genuinely useful but difficult to discover on your own. ​ Respond to common concerns Healthy skepticism is expected; engineers should be cautious about tools that touch their code. The most effective response is rarely to argue the general case. Instead, acknowledge the concern, offer a brief reframe, and propose one concrete demonstration on the person’s own code. Most concerns are resolved by a single successful experience. Concern Suggested response Evidence to offer ”I am faster without it.” That is likely true for code the person writes routinely. Suggest trying it on the work they tend to avoid: legacy files, unfamiliar services, or test scaffolding, where the leverage is highest. Time one tedious task both ways and compare. ”I do not trust AI to touch production code.” Agree that no change should land unread. Plan mode combined with normal diff review means nothing is applied that the engineer has not inspected, the same standard as any pull request. Demonstrate plan mode on a real file. ”It will make junior engineers weaker.” Used well, it is an effective explainer. Encourage junior engineers to ask Claude to explain a file and its call sites before asking it to change anything. Run “Explain @file and where it is called from” together. ”I tried it once and it hallucinated.” This is usually a context problem rather than a model problem. @-mentioning the relevant files, running /init , and providing the actual error output typically resolves it. Re-run their original prompt with proper @ -context. ”We do not have time to learn another tool.” Claude Code is a terminal command rather than a platform. If it does not return value within the first session, it is reasonable to set it aside. A two-minute install followed by one real bug. ​ Quick-reference sheet The techniques below are the ones that most reliably move someone from a first trial to daily use. Pin this table in a channel or share it on its own. Technique How to apply it Provide the right context Use @file or @directory/ references, or paste the error or log output directly. Supplying relevant context is more effective than elaborate prompting. Review the plan before the edit Press Shift+Tab to enter plan mode. Claude will describe the intended changes for your approval before executing them. Teach it your repository Run /init to generate a CLAUDE.md file, then add your conventions, test commands, and any directories that should not be modified. See Memory . Reuse a workflow Save a SKILL.md file in .claude/skills// to create a /name skill that the entire team can use. See Skills . Stay informed during long tasks Configure a Stop hook to receive a desktop notification when a long-running task completes. See Hooks . Recover from an incorrect result Rather than rephrasing the request, paste the failing test or stack trace back to Claude and ask it to address that specific failure. Keep edits surgical Ask for a diff, or specify “only change X.” Claude respects scope when scope is stated. Claude Code is updated frequently. Verify version-specific details against the documentation home page before distributing this material internally. Was this page helpful? Yes No Communications kit Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Security and data Zero data retention Setup and access Administration overview Advanced setup Authentication Server-managed settings Auto mode Deployment Overview Amazon Bedrock Claude Platform on AWS Google Vertex AI Microsoft Foundry Network configuration LLM gateway Development containers Usage and costs Monitoring Costs Track team usage with analytics Plugin distribution Create and distribute a plugin marketplace Plugin dependency versions Security and data Security Data usage Zero data retention Adoption Communications kit Champion kit Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. Zero Data Retention (ZDR) is available for Claude Code when used through Claude for Enterprise. When ZDR is enabled, prompts and model responses generated during Claude Code sessions are processed in real time and not stored by Anthropic after the response is returned, except where needed to comply with law or combat misuse. ZDR on Claude for Enterprise gives enterprise customers the ability to use Claude Code with zero data retention and access administrative capabilities: Cost controls per user Analytics dashboard Server-managed settings Audit logs ZDR for Claude Code on Claude for Enterprise applies only to Anthropic’s direct platform. For Claude deployments on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry, refer to those platforms’ data retention policies. ​ ZDR scope ZDR covers Claude Code inference on Claude for Enterprise. ZDR is enabled on a per-organization basis. Each new organization requires ZDR to be enabled separately by your Anthropic account team. ZDR does not automatically apply to new organizations created under the same account. Contact your account team to enable ZDR for any new organizations. ​ What ZDR covers ZDR covers model inference calls made through Claude Code on Claude for Enterprise. When you use Claude Code in your terminal, the prompts you send and the responses Claude generates are not retained by Anthropic. This applies regardless of which Claude model is used. ​ What ZDR does not cover ZDR does not extend to the following, even for organizations with ZDR enabled. These features follow standard data retention policies : Feature Details Chat on claude.ai Chat conversations through the Claude for Enterprise web interface are not covered by ZDR. Cowork Cowork sessions are not covered by ZDR. Claude Code Analytics Does not store prompts or model responses, but collects productivity metadata such as account emails and usage statistics. Contribution metrics are not available for ZDR organizations; the analytics dashboard shows usage metrics only. User and seat management Administrative data such as account emails and seat assignments is retained under standard policies. Third-party integrations Data processed by third-party tools, MCP servers, or other external integrations is not covered by ZDR. Review those services’ data handling practices independently. ​ Features disabled under ZDR When ZDR is enabled for a Claude Code organization on Claude for Enterprise, certain features that require storing prompts or completions are automatically disabled at the backend level: Feature Reason Claude Code on the Web Requires server-side storage of conversation history. Remote sessions from the Desktop app Requires persistent session data that includes prompts and completions. Feedback submission ( /feedback ) Submitting feedback sends conversation data to Anthropic. These features are blocked in the backend regardless of client-side display. If you see a disabled feature in the Claude Code terminal during startup, attempting to use it returns an error indicating the organization’s policies do not allow that action. Future features may also be disabled if they require storing prompts or completions. ​ Data retention for policy violations Even with ZDR enabled, Anthropic may retain data where required by law or to address Usage Policy violations. If a session is flagged for a policy violation, Anthropic may retain the associated inputs and outputs for up to 2 years, consistent with Anthropic’s standard ZDR policy. ​ Request ZDR To request ZDR for Claude Code on Claude for Enterprise, contact sales or your Anthropic account team. Your account team will submit the request internally, and Anthropic will review and enable ZDR on your organization after confirming eligibility. All enablement actions are audit-logged. If you are currently using ZDR for Claude Code via pay-as-you-go API keys, you can transition to Claude for Enterprise to gain access to administrative features while maintaining ZDR for Claude Code. Contact your account team to coordinate the migration. Was this page helpful? Yes No Data usage Communications kit Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Claude Code on the web Use Claude Code on the web Getting started Overview Quickstart Changelog Core concepts How Claude Code works Extend Claude Code Explore the .claude directory Explore the context window Use Claude Code Store instructions and memories Permission modes Common workflows Best practices Platforms and integrations Overview Remote Control Claude Code on the web Get started Reference Routines Plan in the cloud Ultrareview Claude Code on desktop Chrome extension (beta) Computer use (preview) Visual Studio Code JetBrains IDEs Code review & CI/CD Claude Code in Slack Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. Claude Code on the web is in research preview for Pro, Max, and Team users, and for Enterprise users with premium seats or Chat + Claude Code seats. Claude Code on the web runs tasks on Anthropic-managed cloud infrastructure at claude.ai/code . Sessions persist even if you close your browser, and you can monitor them from the Claude mobile app. New to Claude Code on the web? Start with Get started to connect your GitHub account and submit your first task. This page covers: GitHub authentication options : two ways to connect GitHub The cloud environment : what config carries over, what tools are installed, and how to configure environments Setup scripts and dependency management Network access : levels, proxies, and the default allowlist Move tasks between web and terminal with --remote and --teleport Work with sessions : reviewing, sharing, archiving, deleting Auto-fix pull requests : respond automatically to CI failures and review comments Security and isolation : how sessions are isolated Limitations : rate limits and platform restrictions ​ GitHub authentication options Cloud sessions need access to your GitHub repositories to clone code and push branches. You can grant access in two ways: Method How it works Best for GitHub App Authorize the Claude GitHub App during web onboarding . Browser onboarding; teams that want Auto-fix /web-setup Run /web-setup in your terminal to sync your local gh CLI token to your Claude account. Individual developers who already use gh With either method, a cloud session can access any repository the connecting GitHub account can see, not just the repositories the Claude GitHub App is installed on. App installation enables PR webhooks for Auto-fix ; it is not a session-level access control. To restrict which repositories your team can reach from cloud sessions, restrict access on GitHub itself, for example by limiting team or repository membership for the connected GitHub accounts. Either method works. /schedule checks for either form of access and prompts you to run /web-setup if neither is configured. See Connect from your terminal for the /web-setup walkthrough. The GitHub App is required for Auto-fix , which uses the App to receive PR webhooks. If you connect with /web-setup and later want Auto-fix, install the App on those repositories. Team and Enterprise admins can disable /web-setup with the Quick web setup toggle at claude.ai/admin-settings/claude-code . Organizations with Zero Data Retention enabled cannot use /web-setup or other cloud session features. ​ The cloud environment Each session runs in a fresh Anthropic-managed VM with your repository cloned. This section covers what’s available when a session starts and how to customize it. ​ What’s available in cloud sessions Cloud sessions start from a fresh clone of your repository. Anything committed to the repo is available. Anything you’ve installed or configured only on your own machine is not. Available in cloud sessions Why Your repo’s CLAUDE.md Yes Part of the clone Your repo’s .claude/settings.json hooks Yes Part of the clone Your repo’s .mcp.json MCP servers Yes Part of the clone Your repo’s .claude/rules/ Yes Part of the clone Your repo’s .claude/skills/ , .claude/agents/ , .claude/commands/ Yes Part of the clone Plugins declared in .claude/settings.json Yes Installed at session start from the marketplace you declared. Requires network access to reach the marketplace source Your user ~/.claude/CLAUDE.md No Lives on your machine, not in the repo Plugins enabled only in your user settings No User-scoped enabledPlugins lives in ~/.claude/settings.json . Declare them in the repo’s .claude/settings.json instead MCP servers you added with claude mcp add No Those write to your local user config, not the repo. Declare the server in .mcp.json instead Static API tokens and credentials No No dedicated secrets store exists yet. See below Interactive auth like AWS SSO No Not supported. SSO requires browser-based login that can’t run in a cloud session To make configuration available in cloud sessions, commit it to the repo. A dedicated secrets store is not yet available. Both environment variables and setup scripts are stored in the environment configuration, visible to anyone who can edit that environment. If you need secrets in a cloud session, add them as environment variables with that visibility in mind. ​ Installed tools Cloud sessions come with common language runtimes, build tools, and databases pre-installed. The table below summarizes what’s included by category. Category Included Python Python 3.x with pip, poetry, uv, black, mypy, pytest, ruff Node.js 20, 21, and 22 via nvm, with npm, yarn, pnpm, bun¹, eslint, prettier, chromedriver Ruby 3.1, 3.2, 3.3 with gem, bundler, rbenv PHP 8.4 with Composer Java OpenJDK 21 with Maven and Gradle Go latest stable with module support Rust rustc and cargo C/C++ GCC, Clang, cmake, ninja, conan Docker docker, dockerd, docker compose Databases PostgreSQL 16, Redis 7.0 Utilities git, jq, yq, ripgrep, tmux, vim, nano ¹ Bun is installed but has known proxy compatibility issues for package fetching. For exact versions, ask Claude to run check-tools in a cloud session. This command only exists in cloud sessions. ​ Work with GitHub issues and pull requests Cloud sessions include built-in GitHub tools that let Claude read issues, list pull requests, fetch diffs, and post comments without any setup. These tools authenticate through the GitHub proxy using whichever method you configured under GitHub authentication options , so your token never enters the container. The gh CLI is not pre-installed. If you need a gh command the built-in tools don’t cover, like gh release or gh workflow run , install and authenticate it yourself: 1 Install gh in your setup script Add apt update && apt install -y gh to your setup script . 2 Provide a token Add a GH_TOKEN environment variable to your environment settings with a GitHub personal access token. gh reads GH_TOKEN automatically, so no gh auth login step is needed. ​ Link artifacts back to the session Each cloud session has a transcript URL on claude.ai, and the session can read its own ID from the CLAUDE_CODE_REMOTE_SESSION_ID environment variable. Use this to put a traceable link in PR bodies, commit messages, Slack posts, or generated reports so a reviewer can open the run that produced them. The variable’s value uses a cse_ prefix, while the transcript URL path takes the same ID with a session_ prefix. Substitute the prefix when building the link. The following command prints the URL: echo "https://claude.ai/code/${ CLAUDE_CODE_REMOTE_SESSION_ID /# cse_ / session_ }" ​ Run tests, start services, and add packages Claude runs tests as part of working on a task. Ask for it in your prompt, like “fix the failing tests in tests/ ” or “run pytest after each change.” Test runners like pytest, jest, and cargo test work out of the box since they’re pre-installed. PostgreSQL and Redis are pre-installed but not running by default. Ask Claude to start each one during the session: service postgresql start service redis-server start Docker is available for running containerized services. Ask Claude to run docker compose up to start your project’s services. Network access to pull images follows your environment’s access level , and the Trusted defaults include Docker Hub and other common registries. If your images are large or slow to pull, add docker compose pull or docker compose build to your setup script . The pulled images are saved in the cached environment , so each new session has them on disk. The cache stores files only, not running processes, so Claude still starts the containers each session. To add packages that aren’t pre-installed, use a setup script . The script’s output is cached , so packages you install there are available at the start of every session without reinstalling each time. You can also ask Claude to install packages mid-session, but those installs don’t carry over to other sessions. ​ Resource limits Cloud sessions run with approximate resource ceilings that may change over time: 4 vCPUs 16 GB of RAM 30 GB of disk Tasks requiring significantly more memory, such as large build jobs or memory-intensive tests, may fail or be terminated. For workloads beyond these limits, use Remote Control to run Claude Code on your own hardware. ​ Configure your environment Environments control network access , environment variables, and the setup script that runs before a session starts. See Installed tools for what’s available without any configuration. You can manage environments from the web interface or the terminal: Action How Add an environment Select the current environment to open the selector, then select Add environment . The dialog includes name, network access level, environment variables, and setup script. Edit an environment Select the cloud icon showing the current environment’s name to open the selector, hover over an environment, and click the settings icon that appears on the right. Archive an environment Open the environment for editing and select Archive . Archived environments are hidden from the selector but existing sessions keep running. Set the default for --remote Run /remote-env in your terminal. If you have a single environment, this command shows your current configuration. /remote-env only selects the default; add, edit, and archive environments from the web interface. Environment variables use .env format with one KEY=value pair per line. Don’t wrap values in quotes, since quotes are stored as part of the value. NODE_ENV=development LOG_LEVEL=debug DATABASE_URL=postgres://localhost:5432/myapp ​ Setup scripts A setup script is a Bash script that runs when a new cloud session starts, before Claude Code launches. Use setup scripts to install dependencies, configure tools, or fetch anything the session needs that isn’t pre-installed. Scripts run as root on Ubuntu 24.04, so apt install and most language package managers work. To add a setup script, open the environment settings dialog and enter your script in the Setup script field. This example installs the gh CLI, which isn’t pre-installed: #!/bin/bash apt update && apt install -y gh If the script exits non-zero, the session fails to start. Append || true to non-critical commands to avoid blocking the session on an intermittent install failure. Keep the script’s total runtime under roughly five minutes so the environment cache can build. Run independent installs in parallel with & and wait . If a single download won’t fit in the five-minute limit, move it to a SessionStart hook that launches it in the background. Setup scripts that install packages need network access to reach registries. The default Trusted network access allows connections to common package registries including npm, PyPI, RubyGems, and crates.io. Scripts will fail to install packages if your environment uses None network access. ​ Environment caching The setup script runs the first time you start a session in an environment. After it completes, Anthropic snapshots the filesystem and reuses that snapshot as the starting point for later sessions. New sessions start with your dependencies, tools, and Docker images already on disk, and the setup script step is skipped. This keeps startup fast even when the script installs large toolchains or pulls container images. The cache captures files, not running processes. Anything the setup script writes to disk carries over. Services or containers it starts do not, so start those per session by asking Claude or with a SessionStart hook . The setup script runs again to rebuild the cache when you change the environment’s setup script or allowed network hosts, and when the cache reaches its expiry after roughly seven days. Resuming an existing session never re-runs the setup script. You don’t need to enable caching or manage snapshots yourself. ​ Setup scripts vs. SessionStart hooks Use a setup script to install things the cloud needs but your laptop already has, like a language runtime or CLI tool. Use a SessionStart hook for project setup that should run everywhere, cloud and local, like npm install . Both run at the start of a session, but they belong to different places: Setup scripts SessionStart hooks Attached to The cloud environment Your repository Configured in Cloud environment UI .claude/settings.json in your repo Runs Before Claude Code launches, when no cached environment is available After Claude Code launches, on every session including resumed Scope Cloud environments only Both local and cloud SessionStart hooks can also be defined in your user-level ~/.claude/settings.json locally, but user-level settings don’t carry over to cloud sessions. In the cloud, only hooks committed to the repo run. ​ Install dependencies with a SessionStart hook To install dependencies only in cloud sessions, add a SessionStart hook to your repo’s .claude/settings.json : { "hooks" : { "SessionStart" : [ { "matcher" : "startup|resume" , "hooks" : [ { "type" : "command" , "command" : " \" $CLAUDE_PROJECT_DIR \" /scripts/install_pkgs.sh" } ] } ] } } Create the script at scripts/install_pkgs.sh and make it executable with chmod +x . The CLAUDE_CODE_REMOTE environment variable is set to true in cloud sessions, so you can use it to skip local execution: #!/bin/bash if [ " $CLAUDE_CODE_REMOTE " != "true" ]; then exit 0 fi npm install pip install -r requirements.txt exit 0 SessionStart hooks have some limitations in cloud sessions: No cloud-only scoping : hooks run in both local and cloud sessions. To skip local execution, check the CLAUDE_CODE_REMOTE environment variable as shown above. Requires network access : install commands need to reach package registries. If your environment uses None network access, these hooks fail. The default allowlist under Trusted covers npm, PyPI, RubyGems, and crates.io. Proxy compatibility : all outbound traffic passes through a security proxy . Some package managers don’t work correctly with this proxy. Bun is a known example. Adds startup latency : hooks run each time a session starts or resumes, unlike setup scripts which benefit from environment caching . Keep install scripts fast by checking whether dependencies are already present before reinstalling. To persist environment variables for subsequent Bash commands, write to the file at $CLAUDE_ENV_FILE . See SessionStart hooks for details. Replacing the base image with your own Docker image is not yet supported. Use a setup script to install what you need on top of the provided image , or run your image as a container alongside Claude with docker compose . ​ Network access Network access controls outbound connections from the cloud environment. Each environment specifies one access level, and you can extend it with custom allowed domains. The default is Trusted , which allows package registries and other allowlisted domains . To change an environment’s network access, open it for editing and use the Network access selector in the dialog. There is no separate Environments page. The cloud icon appears wherever you start a cloud session or configure a routine . MCP connector traffic is routed through Anthropic’s servers, so the connectors you enable on a session or routine work without adding their hosts to Allowed domains . Connectors are configured per session or per routine; remove any you don’t need to limit which tools Claude can reach. This relies on the same Anthropic-bound channel noted under Security and isolation . ​ Access levels Choose an access level when you create or edit an environment: Level Outbound connections None No outbound network access Trusted Allowlisted domains only: package registries, GitHub, cloud SDKs Full Any domain Custom Your own allowlist, optionally including the defaults GitHub operations use a separate proxy that is independent of this setting. ​ Allow specific domains To allow domains that aren’t in the Trusted list, select Custom in the environment’s network access settings. An Allowed domains field appears. Enter one domain per line: api.example.com *.internal.example.com registry.example.com Use *. for wildcard subdomain matching. Check Also include default list of common package managers to keep the Trusted domains alongside your custom entries, or leave it unchecked to allow only what you list. ​ GitHub proxy For security, all GitHub operations go through a dedicated proxy service that transparently handles all git interactions. Inside the sandbox, the git client authenticates using a custom-built scoped credential. This proxy: Manages GitHub authentication securely: the git client uses a scoped credential inside the sandbox, which the proxy verifies and translates to your actual GitHub authentication token Restricts git push operations to the current working branch for safety Enables cloning, fetching, and PR operations while maintaining security boundaries ​ Security proxy Environments run behind an HTTP/HTTPS network proxy for security and abuse prevention purposes. All outbound internet traffic passes through this proxy, which provides: Protection against malicious requests Rate limiting and abuse prevention Content filtering for enhanced security ​ Default allowed domains When using Trusted network access, the following domains are allowed by default. Domains marked with * indicate wildcard subdomain matching, so *.gcr.io allows any subdomain of gcr.io . Anthropic services api.anthropic.com statsig.anthropic.com docs.claude.com platform.claude.com code.claude.com claude.ai Version control github.com www.github.com api.github.com npm.pkg.github.com raw.githubusercontent.com pkg-npm.githubusercontent.com objects.githubusercontent.com release-assets.githubusercontent.com codeload.github.com avatars.githubusercontent.com camo.githubusercontent.com gist.github.com gitlab.com www.gitlab.com registry.gitlab.com bitbucket.org www.bitbucket.org api.bitbucket.org Container registries registry-1.docker.io auth.docker.io index.docker.io hub.docker.com www.docker.com production.cloudflare.docker.com download.docker.com gcr.io *.gcr.io ghcr.io mcr.microsoft.com *.data.mcr.microsoft.com public.ecr.aws Cloud platforms cloud.google.com accounts.google.com gcloud.google.com *.googleapis.com storage.googleapis.com compute.googleapis.com container.googleapis.com azure.com portal.azure.com microsoft.com www.microsoft.com *.microsoftonline.com packages.microsoft.com dotnet.microsoft.com dot.net visualstudio.com dev.azure.com *.amazonaws.com *.api.aws oracle.com www.oracle.com java.com www.java.com java.net www.java.net download.oracle.com yum.oracle.com JavaScript and Node package managers registry.npmjs.org www.npmjs.com www.npmjs.org npmjs.com npmjs.org yarnpkg.com registry.yarnpkg.com Python package managers pypi.org www.pypi.org files.pythonhosted.org pythonhosted.org test.pypi.org pypi.python.org pypa.io www.pypa.io Ruby package managers rubygems.org www.rubygems.org api.rubygems.org index.rubygems.org ruby-lang.org www.ruby-lang.org rubyforge.org www.rubyforge.org rubyonrails.org www.rubyonrails.org rvm.io get.rvm.io Rust package managers crates.io www.crates.io index.crates.io static.crates.io rustup.rs static.rust-lang.org www.rust-lang.org Go package managers proxy.golang.org sum.golang.org index.golang.org golang.org www.golang.org goproxy.io pkg.go.dev JVM package managers maven.org repo.maven.org central.maven.org repo1.maven.org repo.maven.apache.org jcenter.bintray.com gradle.org www.gradle.org services.gradle.org plugins.gradle.org kotlinlang.org www.kotlinlang.org spring.io repo.spring.io Other package managers packagist.org (PHP Composer) www.packagist.org repo.packagist.org nuget.org (.NET NuGet) www.nuget.org api.nuget.org pub.dev (Dart/Flutter) api.pub.dev hex.pm (Elixir/Erlang) www.hex.pm cpan.org (Perl CPAN) www.cpan.org metacpan.org www.metacpan.org api.metacpan.org cocoapods.org (iOS/macOS) www.cocoapods.org cdn.cocoapods.org haskell.org www.haskell.org hackage.haskell.org swift.org www.swift.org Linux distributions archive.ubuntu.com security.ubuntu.com ubuntu.com www.ubuntu.com *.ubuntu.com ppa.launchpad.net launchpad.net www.launchpad.net *.nixos.org Development tools and platforms dl.k8s.io (Kubernetes) pkgs.k8s.io k8s.io www.k8s.io releases.hashicorp.com (HashiCorp) apt.releases.hashicorp.com rpm.releases.hashicorp.com archive.releases.hashicorp.com hashicorp.com www.hashicorp.com repo.anaconda.com (Anaconda/Conda) conda.anaconda.org anaconda.org www.anaconda.com anaconda.com continuum.io apache.org (Apache) www.apache.org archive.apache.org downloads.apache.org eclipse.org (Eclipse) www.eclipse.org download.eclipse.org nodejs.org (Node.js) www.nodejs.org developer.apple.com developer.android.com pkg.stainless.com binaries.prisma.sh Cloud services and monitoring statsig.com www.statsig.com api.statsig.com sentry.io *.sentry.io downloads.sentry-cdn.com http-intake.logs.datadoghq.com *.datadoghq.com *.datadoghq.eu api.honeycomb.io Content delivery and mirrors sourceforge.net *.sourceforge.net packagecloud.io *.packagecloud.io fonts.googleapis.com fonts.gstatic.com Schema and configuration json-schema.org www.json-schema.org json.schemastore.org www.schemastore.org Model Context Protocol *.modelcontextprotocol.io ​ Move tasks between web and terminal These workflows require the Claude Code CLI signed in to the same claude.ai account. You can start new cloud sessions from your terminal, or pull cloud sessions into your terminal to continue locally. Cloud sessions persist even if you close your laptop, and you can monitor them from anywhere including the Claude mobile app. From the CLI, session handoff is one-way: you can pull cloud sessions into your terminal with --teleport , but you can’t push an existing terminal session to the web. The --remote flag creates a new cloud session for your current repository. The Desktop app provides a Continue in menu that can send a local session to the web. ​ From terminal to web Start a cloud session from the command line with the --remote flag: claude --remote "Fix the authentication bug in src/auth/login.ts" This creates a new cloud session on claude.ai. The session clones your current directory’s GitHub remote at your current branch, so push first if you have local commits, since the VM clones from GitHub rather than your machine. --remote works with a single repository at a time. The task runs in the cloud while you continue working locally. --remote creates cloud sessions. --remote-control is unrelated: it exposes a local CLI session for monitoring from the web. See Remote Control . Use /tasks in the Claude Code CLI to check progress, or open the session on claude.ai or the Claude mobile app to interact directly. From there you can steer Claude, provide feedback, or answer questions just like any other conversation. ​ Tips for cloud tasks Plan locally, execute remotely : for complex tasks, start Claude in plan mode to collaborate on the approach, then send work to the cloud: claude --permission-mode plan In plan mode, Claude reads files, runs commands to explore, and proposes a plan without editing source code. Once you’re satisfied, save the plan to the repo, commit, and push so the cloud VM can clone it. Then start a cloud session for autonomous execution: claude --remote "Execute the migration plan in docs/migration-plan.md" This pattern gives you control over the strategy while letting Claude execute autonomously in the cloud. Plan in the cloud with ultraplan : to draft and review the plan itself in a web session, use ultraplan . Claude generates the plan on Claude Code on the web while you keep working, then you comment on sections in your browser and choose to execute remotely or send the plan back to your terminal. Run tasks in parallel : each --remote command creates its own cloud session that runs independently. You can start multiple tasks and they’ll all run simultaneously in separate sessions: claude --remote "Fix the flaky test in auth.spec.ts" claude --remote "Update the API documentation" claude --remote "Refactor the logger to use structured output" Monitor all sessions with /tasks in the Claude Code CLI. When a session completes, you can create a PR from the web interface or teleport the session to your terminal to continue working. ​ Send local repositories without GitHub When you run claude --remote from a repository that isn’t connected to GitHub, Claude Code bundles your local repository and uploads it directly to the cloud session. The bundle includes your full repository history across all branches, plus any uncommitted changes to tracked files. This fallback activates automatically when GitHub access isn’t available. To force it even when GitHub is connected, set CCR_FORCE_BUNDLE=1 : CCR_FORCE_BUNDLE = 1 claude --remote "Run the test suite and fix any failures" Bundled repositories must meet these limits: The directory must be a git repository with at least one commit The bundled repository must be under 100 MB. Larger repositories fall back to bundling only the current branch, then to a single squashed snapshot of the working tree, and fail only if the snapshot is still too large Untracked files are not included; run git add on files you want the cloud session to see Sessions created from a bundle can’t push back to a remote unless you also have GitHub authentication configured ​ From web to terminal Pull a cloud session into your terminal using any of these: Using --teleport : from the command line, run claude --teleport for an interactive session picker, or claude --teleport to resume a specific session directly. If you have uncommitted changes, you’ll be prompted to stash them first. Using /teleport : inside an existing CLI session, run /teleport (or /tp ) to open the same session picker without restarting Claude Code. From /tasks : run /tasks to see your background sessions, then press t to teleport into one From the web interface : select Open in CLI to copy a command you can paste into your terminal When you teleport a session, Claude verifies you’re in the correct repository, fetches and checks out the branch from the cloud session, and loads the full conversation history into your terminal. --teleport is distinct from --resume . --resume reopens a conversation from this machine’s local history and doesn’t list cloud sessions; --teleport pulls a cloud session and its branch. ​ Teleport requirements Teleport checks these requirements before resuming a session. If any requirement isn’t met, you’ll see an error or be prompted to resolve the issue. Requirement Details Clean git state Your working directory must have no uncommitted changes. Teleport prompts you to stash changes if needed. Correct repository You must run --teleport from a checkout of the same repository, not a fork. Branch available The branch from the cloud session must have been pushed to the remote. Teleport automatically fetches and checks it out. Same account You must be authenticated to the same claude.ai account used in the cloud session. ​ --teleport is unavailable Teleport requires claude.ai subscription authentication. If you’re authenticated via API key, Bedrock, Vertex AI, or Microsoft Foundry, run /login to sign in with your claude.ai account instead. If you’re already signed in via claude.ai and --teleport is still unavailable, your organization may have disabled cloud sessions. ​ Work with sessions Sessions appear in the sidebar at claude.ai/code. From there you can review changes, share with teammates, archive finished work, or delete sessions permanently. ​ Manage context Cloud sessions support built-in commands that produce text output. Commands that open an interactive terminal picker, like /model or /config , are not available. For context management specifically: Command Works in cloud sessions Notes /compact Yes Summarizes the conversation to free up context. Accepts optional focus instructions like /compact keep the test output /context Yes Shows what’s currently in the context window /clear No Start a new session from the sidebar instead Auto-compaction runs automatically when the context window approaches capacity, the same as in the CLI. To trigger it earlier, set CLAUDE_AUTOCOMPACT_PCT_OVERRIDE in your environment variables . For example, CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70 compacts at 70% capacity instead of the default ~95%. To change the effective window size for compaction calculations, use CLAUDE_CODE_AUTO_COMPACT_WINDOW . Subagents work the same way they do locally. Claude can spawn them with the Task tool to offload research or parallel work into a separate context window, keeping the main conversation lighter. Subagents defined in your repo’s .claude/agents/ are picked up automatically. Agent teams are off by default but can be enabled by adding CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 to your environment variables . ​ Review changes Each session shows a diff indicator with lines added and removed, like +42 -18 . Select it to open the diff view, leave inline comments on specific lines, and send them to Claude with your next message. See Review and iterate for the full walkthrough including PR creation. To have Claude monitor the PR for CI failures and review comments automatically, see Auto-fix pull requests . ​ Share sessions To share a session, toggle its visibility according to the account types below. After that, share the session link as-is. Recipients see the latest state when they open the link, but their view doesn’t update in real time. ​ Share from an Enterprise or Team account For Enterprise and Team accounts, the two visibility options are Private and Team . Team visibility makes the session visible to other members of your claude.ai organization. Repository access verification is enabled by default, based on the GitHub account connected to the recipient’s account. Your account’s display name is visible to all recipients with access. Claude in Slack sessions are automatically shared with Team visibility. ​ Share from a Max or Pro account For Max and Pro accounts, the two visibility options are Private and Public . Public visibility makes the session visible to any user logged into claude.ai. Check your session for sensitive content before sharing. Sessions may contain code and credentials from private GitHub repositories. Repository access verification is not enabled by default. To require recipients to have repository access, or to hide your name from shared sessions, go to Settings > Claude Code > Sharing settings. ​ Archive sessions You can archive sessions to keep your session list organized. Archived sessions are hidden from the default session list but can be viewed by filtering for archived sessions. To archive a session, hover over the session in the sidebar and select the archive icon. ​ Delete sessions Deleting a session permanently removes the session and its data. This action cannot be undone. You can delete a session in two ways: From the sidebar : filter for archived sessions, then hover over the session you want to delete and select the delete icon From the session menu : open a session, select the dropdown next to the session title, and select Delete You will be asked to confirm before a session is deleted. ​ Auto-fix pull requests Claude can watch a pull request and automatically respond to CI failures and review comments. Claude subscribes to GitHub activity on the PR, and when a check fails or a reviewer leaves a comment, Claude investigates and pushes a fix if one is clear. Auto-fix requires the Claude GitHub App to be installed on your repository. If you haven’t already, install it from the GitHub App page or when prompted during setup . There are a few ways to turn on auto-fix depending on where the PR came from and what device you’re using: PRs created in Claude Code on the web : open the CI status bar and select Auto-fix From your terminal : run /autofix-pr while on the PR’s branch. Claude Code detects the open PR with gh , spawns a web session, and turns on auto-fix in one step From the mobile app : tell Claude to auto-fix the PR, for example “watch this PR and fix any CI failures or review comments” Any existing PR : paste the PR URL into a session and tell Claude to auto-fix it Auto-fix is a per-PR toggle. To stop monitoring, open the CI status bar in the web session and clear the Auto-fix toggle, or tell Claude to stop watching the PR. ​ How Claude responds to PR activity When auto-fix is active, Claude receives GitHub events for the PR including new review comments and CI check failures. For each event, Claude investigates and decides how to proceed: Clear fixes : if Claude is confident in a fix and it doesn’t conflict with earlier instructions, Claude makes the change, pushes it, and explains what was done in the session Ambiguous requests : if a reviewer’s comment could be interpreted multiple ways or involves something architecturally significant, Claude asks you before acting Duplicate or no-action events : if an event is a duplicate or requires no change, Claude notes it in the session and moves on Claude may reply to review comment threads on GitHub as part of resolving them. These replies are posted using your GitHub account, so they appear under your username, but each reply is labeled as coming from Claude Code so reviewers know it was written by the agent and not by you directly. If your repository uses comment-triggered automation such as Atlantis, Terraform Cloud, or custom GitHub Actions that run on issue_comment events, be aware that Claude can reply on your behalf, which can trigger those workflows. Review your repository’s automation before enabling auto-fix, and consider disabling auto-fix for repositories where a PR comment can deploy infrastructure or run privileged operations. ​ Security and isolation Each cloud session is separated from your machine and from other sessions through several layers: Isolated virtual machines : each session runs in an isolated, Anthropic-managed VM Network access controls : network access is limited by default, and can be disabled. When running with network access disabled, Claude Code can still communicate with the Anthropic API, which may allow data to exit the VM. Credential protection : sensitive credentials such as git credentials or signing keys are never inside the sandbox with Claude Code. Authentication is handled through a secure proxy using scoped credentials. Secure analysis : code is analyzed and modified within isolated VMs before creating PRs ​ Troubleshooting For runtime API errors that appear in the conversation such as API Error: 500 , 529 Overloaded , 429 , or Prompt is too long , see the Error reference . Those errors and their fixes are shared with the CLI and Desktop app. The sections below cover issues specific to cloud sessions. ​ Session creation failed If a new session fails to start with Session creation failed or stalls at provisioning, Claude Code could not allocate a cloud environment. Check status.claude.com for cloud session incidents Retry after a minute, as capacity is provisioned on demand Confirm your repository is reachable. The connecting GitHub account must have access to the repository on GitHub, either through the Claude GitHub App authorization or a gh token synced via /web-setup — installing the App on the repository is not required. See GitHub authentication options . ​ Remote Control session expired or access denied --teleport connects through the same Remote Control session infrastructure that cloud sessions use, so authentication and session-expiry errors surface with Remote Control wording. You may see Remote Control session expired or Access denied . The connection token is short-lived and scoped to your account. Run /login locally to refresh your credentials, then reconnect Confirm you are signed in to the same account that owns the session If you see Remote Control may not be available for this organization , your admin has not enabled remote sessions for your plan ​ Environment expired Cloud sessions stop after a period of inactivity and the underlying environment is reclaimed. From a local terminal, this surfaces as Could not resume session ... its environment has expired. Creating a fresh session instead. On the web, the session is marked expired in the session list. Reopen the session from claude.ai/code to provision a fresh environment with your conversation history restored. ​ Limitations Before relying on cloud sessions for a workflow, account for these constraints: Rate limits : Claude Code on the web shares rate limits with all other Claude and Claude Code usage within your account. Running multiple tasks in parallel consumes more rate limits proportionately. There is no separate compute charge for the cloud VM. Repository authentication : you can only move sessions from web to local when you are authenticated to the same account Platform restrictions : repository cloning and pull request creation require GitHub. Self-hosted GitHub Enterprise Server instances are supported for Team and Enterprise plans. GitLab, Bitbucket, and other non-GitHub repositories can be sent to cloud sessions as a local bundle , but the session can’t push results back to the remote Organization IP allowlist : cloud sessions call the Anthropic API from Anthropic-managed infrastructure, not your network. If your organization has IP allowlisting enabled, every cloud session fails with an authentication error. The same applies to Code Review and Routines . Contact Anthropic support to exempt Anthropic-hosted services from your organization’s IP allowlist. ​ Related resources Ultraplan : draft a plan in a cloud session and review it in your browser Ultrareview : run a deep multi-agent code review in a cloud sandbox Routines : automate work on a schedule, via API call, or in response to GitHub events Hooks configuration : run scripts at session lifecycle events Settings reference : all configuration options Security : isolation guarantees and data handling Data usage : what Anthropic retains from cloud sessions Was this page helpful? Yes No Get started Routines Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Core concepts How the agent loop works Agent SDK Overview Quickstart Core concepts How the agent loop works Use Claude Code features Work with sessions Input and output Streaming Input Handle approvals and user input Stream responses in real-time Get structured output from agents Extend with tools Give Claude custom tools Connect to external tools with MCP Scale to many tools with tool search Subagents in the SDK Customize behavior Modifying system prompts Slash Commands in the SDK Agent Skills in the SDK Plugins in the SDK Control and observability Configure permissions Intercept and control agent behavior with hooks Rewind file changes with checkpointing Track cost and usage Observability with OpenTelemetry Todo Lists Deployment Hosting the Agent SDK Securely deploying AI agents SDK references TypeScript SDK TypeScript V2 (deprecated) Python SDK Migration Guide Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. The Agent SDK lets you embed Claude Code’s autonomous agent loop in your own applications. The SDK is a standalone package that gives you programmatic control over tools, permissions, cost limits, and output. You don’t need the Claude Code CLI installed to use it. When you start an agent, the SDK runs the same execution loop that powers Claude Code : Claude evaluates your prompt, calls tools to take action, receives the results, and repeats until the task is complete. This page explains what happens inside that loop so you can build, debug, and optimize your agents effectively. ​ The loop at a glance Every agent session follows the same cycle: Receive prompt. Claude receives your prompt, along with the system prompt, tool definitions, and conversation history. The SDK yields a SystemMessage with subtype "init" containing session metadata. Evaluate and respond. Claude evaluates the current state and determines how to proceed. It may respond with text, request one or more tool calls, or both. The SDK yields an AssistantMessage containing the text and any tool call requests. Execute tools. The SDK runs each requested tool and collects the results. Each set of tool results feeds back to Claude for the next decision. You can use hooks to intercept, modify, or block tool calls before they run. Repeat. Steps 2 and 3 repeat as a cycle. Each full cycle is one turn. Claude continues calling tools and processing results until it produces a response with no tool calls. Return result. The SDK yields a final AssistantMessage with the text response (no tool calls), followed by a ResultMessage with the final text, token usage, cost, and session ID. A quick question (“what files are here?”) might take one or two turns of calling Glob and responding with the results. A complex task (“refactor the auth module and update the tests”) can chain dozens of tool calls across many turns, reading files, editing code, and running tests, with Claude adjusting its approach based on each result. ​ Turns and messages A turn is one round trip inside the loop: Claude produces output that includes tool calls, the SDK executes those tools, and the results feed back to Claude automatically. This happens without yielding control back to your code. Turns continue until Claude produces output with no tool calls, at which point the loop ends and the final result is delivered. Consider what a full session might look like for the prompt “Fix the failing tests in auth.ts”. First, the SDK sends your prompt to Claude and yields a SystemMessage with the session metadata. Then the loop begins: Turn 1: Claude calls Bash to run npm test . The SDK yields an AssistantMessage with the tool call, executes the command, then yields a UserMessage with the output (three failures). Turn 2: Claude calls Read on auth.ts and auth.test.ts . The SDK returns the file contents and yields an AssistantMessage . Turn 3: Claude calls Edit to fix auth.ts , then calls Bash to re-run npm test . All three tests pass. The SDK yields an AssistantMessage . Final turn: Claude produces a text-only response with no tool calls: “Fixed the auth bug, all three tests pass now.” The SDK yields a final AssistantMessage with this text, then a ResultMessage with the same text plus cost and usage. That was four turns: three with tool calls, one final text-only response. You can cap the loop with max_turns / maxTurns , which counts tool-use turns only. For example, max_turns=2 in the loop above would have stopped before the edit step. You can also use max_budget_usd / maxBudgetUsd to cap turns based on a spend threshold. Without limits, the loop runs until Claude finishes on its own, which is fine for well-scoped tasks but can run long on open-ended prompts (“improve this codebase”). Setting a budget is a good default for production agents. See Turns and budget below for the option reference. ​ Message types As the loop runs, the SDK yields a stream of messages. Each message carries a type that tells you what stage of the loop it came from. The five core types are: SystemMessage : session lifecycle events. The subtype field distinguishes them: "init" is the first message (session metadata), and "compact_boundary" fires after compaction . In TypeScript, the compact boundary is its own SDKCompactBoundaryMessage type rather than a subtype of SDKSystemMessage . AssistantMessage : emitted after each Claude response, including the final text-only one. Contains text content blocks and tool call blocks from that turn. UserMessage : emitted after each tool execution with the tool result content sent back to Claude. Also emitted for any user inputs you stream mid-loop. StreamEvent : only emitted when partial messages are enabled. Contains raw API streaming events (text deltas, tool input chunks). See Stream responses . ResultMessage : marks the end of the agent loop. Contains the final text result, token usage, cost, and session ID. Check the subtype field to determine whether the task succeeded or hit a limit. A small number of trailing system events, such as prompt_suggestion , can arrive after it, so iterate the stream to completion rather than breaking on the result. See Handle the result . These five types cover the full agent loop lifecycle in both SDKs. The TypeScript SDK also yields additional observability events (hook events, tool progress, rate limits, task notifications) that provide extra detail but are not required to drive the loop. See the Python message types reference and TypeScript message types reference for the complete lists. ​ Handle messages Which messages you handle depends on what you’re building: Final results only: handle ResultMessage to get the output, cost, and whether the task succeeded or hit a limit. Progress updates: handle AssistantMessage to see what Claude is doing each turn, including which tools it called. Live streaming: enable partial messages ( include_partial_messages in Python, includePartialMessages in TypeScript) to get StreamEvent messages in real time. See Stream responses in real-time . How you check message types depends on the SDK: Python: check message types with isinstance() against classes imported from claude_agent_sdk (for example, isinstance(message, ResultMessage) ). TypeScript: check the type string field (for example, message.type === "result" ). AssistantMessage and UserMessage wrap the raw API message in a .message field, so content blocks are at message.message.content , not message.content . Example: Check message types and handle results Python TypeScript from claude_agent_sdk import query, AssistantMessage, ResultMessage async for message in query( prompt = "Summarize this project" ): if isinstance (message, AssistantMessage): print ( f "Turn completed: { len (message.content) } content blocks" ) if isinstance (message, ResultMessage): if message.subtype == "success" : print (message.result) else : print ( f "Stopped: { message.subtype } " ) ​ Tool execution Tools give your agent the ability to take action. Without tools, Claude can only respond with text. With tools, Claude can read files, run commands, search code, and interact with external services. ​ Built-in tools The SDK includes the same tools that power Claude Code: Category Tools What they do File operations Read , Edit , Write Read, modify, and create files Search Glob , Grep Find files by pattern, search content with regex Execution Bash Run shell commands, scripts, git operations Web WebSearch , WebFetch Search the web, fetch and parse pages Discovery ToolSearch Dynamically find and load tools on-demand instead of preloading all of them Orchestration Agent , Skill , AskUserQuestion , TodoWrite Spawn subagents, invoke skills, ask the user, track tasks Beyond built-in tools, you can: Connect external services with MCP servers (databases, browsers, APIs) Define custom tools with custom tool handlers Load project skills via setting sources for reusable workflows ​ Tool permissions Claude determines which tools to call based on the task, but you control whether those calls are allowed to execute. You can auto-approve specific tools, block others entirely, or require approval for everything. Three options work together to determine what runs: allowed_tools / allowedTools auto-approves listed tools. A read-only agent with ["Read", "Glob", "Grep"] in its allowed tools list runs those tools without prompting. Tools not listed are still available but require permission. disallowed_tools / disallowedTools blocks listed tools, regardless of other settings. See Permissions for the order that rules are checked before a tool runs. permission_mode / permissionMode controls what happens to tools that aren’t covered by allow or deny rules. See Permission mode for available modes. You can also scope individual tools with rules like "Bash(npm *)" to allow only specific commands. See Permissions for the full rule syntax. When a tool is denied, Claude receives a rejection message as the tool result and typically attempts a different approach or reports that it couldn’t proceed. ​ Parallel tool execution When Claude requests multiple tool calls in a single turn, both SDKs can run them concurrently or sequentially depending on the tool. Read-only tools (like Read , Glob , Grep , and MCP tools marked as read-only) can run concurrently. Tools that modify state (like Edit , Write , and Bash ) run sequentially to avoid conflicts. Custom tools default to sequential execution. To enable parallel execution for a custom tool, set readOnlyHint in its annotations. Both the TypeScript and Python SDKs use this field name from the MCP SDK. ​ Control how the loop runs You can limit how many turns the loop takes, how much it costs, how deeply Claude reasons, and whether tools require approval before running. All of these are fields on ClaudeAgentOptions (Python) / Options (TypeScript). ​ Turns and budget Option What it controls Default Max turns ( max_turns / maxTurns ) Maximum tool-use round trips No limit Max budget ( max_budget_usd / maxBudgetUsd ) Maximum cost before stopping No limit When either limit is hit, the SDK returns a ResultMessage with a corresponding error subtype ( error_max_turns or error_max_budget_usd ). See Handle the result for how to check these subtypes and ClaudeAgentOptions / Options for syntax. ​ Effort level The effort option controls how much reasoning Claude applies. Lower effort levels use fewer tokens per turn and reduce cost. Not all models support the effort parameter. See Effort for which models support it. Level Behavior Good for "low" Minimal reasoning, fast responses File lookups, listing directories "medium" Balanced reasoning Routine edits, standard tasks "high" Thorough analysis Refactors, debugging "xhigh" Extended reasoning depth Coding and agentic tasks; recommended on Opus 4.7 "max" Maximum reasoning depth Multi-step problems requiring deep analysis If you don’t set effort , the Python SDK leaves the parameter unset and defers to the model’s default behavior. The TypeScript SDK defaults to "high" . effort trades latency and token cost for reasoning depth within each response. Extended thinking is a separate feature that produces visible chain-of-thought blocks in the output. They are independent: you can set effort: "low" with extended thinking enabled, or effort: "max" without it. Use lower effort for agents doing simple, well-scoped tasks (like listing files or running a single grep) to reduce cost and latency. Set effort in the top-level query() options for the whole session, or per subagent with the effort field on AgentDefinition to override the session level. ​ Permission mode The permission mode option ( permission_mode in Python, permissionMode in TypeScript) controls whether the agent asks for approval before using tools: Mode Behavior "default" Tools not covered by allow rules trigger your approval callback; no callback means deny "acceptEdits" Auto-approves file edits and common filesystem commands ( mkdir , touch , mv , cp , etc.); other Bash commands follow default rules "plan" Read-only tools run; Claude explores and produces a plan without editing your source files "dontAsk" Never prompts. Tools pre-approved by permission rules run, everything else is denied "auto" (TypeScript only) Uses a model classifier to approve or deny each tool call. See Auto mode for availability and behavior "bypassPermissions" Runs all allowed tools without asking. Cannot be used when running as root on Unix. Use only in isolated environments where the agent’s actions cannot affect systems you care about For interactive applications, use "default" with a tool approval callback to surface approval prompts. For autonomous agents on a dev machine, "acceptEdits" auto-approves file edits and common filesystem commands ( mkdir , touch , mv , cp , etc.) while still gating other Bash commands behind allow rules. Reserve "bypassPermissions" for CI, containers, or other isolated environments. See Permissions for full details. ​ Model If you don’t set model , the SDK uses Claude Code’s default, which depends on your authentication method and subscription. Set it explicitly (for example, model="claude-sonnet-4-6" ) to pin a specific model or to use a smaller model for faster, cheaper agents. See models for available IDs. ​ The context window The context window is the total amount of information available to Claude during a session. It does not reset between turns within a session. Everything accumulates: the system prompt, tool definitions, conversation history, tool inputs, and tool outputs. Content that stays the same across turns (system prompt, tool definitions, CLAUDE.md) is automatically prompt cached , which reduces cost and latency for repeated prefixes. ​ What consumes context Here’s how each component affects context in the SDK: Source When it loads Impact System prompt Every request Small fixed cost, always present CLAUDE.md files Session start, via settingSources Full content in every request (but prompt-cached, so only the first request pays full cost) Tool definitions Every request; MCP schemas deferred by default Built-in tool schemas load every request. Tool search defers MCP tool schemas by default, falling back to upfront loading on Vertex AI or a non-first-party ANTHROPIC_BASE_URL . See Configure tool search for the full matrix Conversation history Accumulates over turns Grows with each turn: prompts, responses, tool inputs, tool outputs Skill descriptions Session start, via setting sources Short summaries; full content loads only when invoked Large tool outputs consume significant context. Reading a big file or running a command with verbose output can use thousands of tokens in a single turn. Context accumulates across turns, so longer sessions with many tool calls build up significantly more context than short ones. ​ Automatic compaction When the context window approaches its limit, the SDK automatically compacts the conversation: it summarizes older history to free space, keeping your most recent exchanges and key decisions intact. The SDK emits a message with type: "system" and subtype: "compact_boundary" in the stream when this happens (in Python this is a SystemMessage ; in TypeScript it is a separate SDKCompactBoundaryMessage type). Compaction replaces older messages with a summary, so specific instructions from early in the conversation may not be preserved. Persistent rules belong in CLAUDE.md (loaded via settingSources ) rather than in the initial prompt, because CLAUDE.md content is re-injected on every request. You can customize compaction behavior in several ways: Summarization instructions in CLAUDE.md: The compactor reads your CLAUDE.md like any other context, so you can include a section telling it what to preserve when summarizing. The section header is free-form (not a magic string); the compactor matches on intent. PreCompact hook: Run custom logic before compaction occurs, for example to archive the full transcript. The hook receives a trigger field ( manual or auto ). See hooks . Manual compaction: Send /compact as a prompt string to trigger compaction on demand. (Slash commands sent this way are SDK inputs, not CLI-only shortcuts. See slash commands in the SDK .) Example: Summarization instructions in CLAUDE.md Add a section to your project’s CLAUDE.md telling the compactor what to preserve. The header name isn’t special; use any clear label. CLAUDE.md # Summary instructions When summarizing this conversation, always preserve: - The current task objective and acceptance criteria - File paths that have been read or modified - Test results and error messages - Decisions made and the reasoning behind them ​ Keep context efficient A few strategies for long-running agents: Use subagents for subtasks. Each subagent starts with a fresh conversation (no prior message history, though it does load its own system prompt and project-level context like CLAUDE.md). It does not see the parent’s turns, and only its final response returns to the parent as a tool result. The main agent’s context grows by that summary, not by the full subtask transcript. See What subagents inherit for details. Be selective with tools. Every tool definition takes context space. Use the tools field on AgentDefinition to scope subagents to the minimum set they need. Watch MCP server costs. MCP tool search defers MCP tool schemas by default and loads them on demand. When tool search is off, on Vertex AI, or behind a non-first-party ANTHROPIC_BASE_URL , each MCP server adds all its tool schemas to every request, so a few servers with many tools can consume significant context before the agent does any work. Use lower effort for routine tasks. Set effort to "low" for agents that only need to read files or list directories. This reduces token usage and cost. For a detailed breakdown of per-feature context costs, see Understand context costs . ​ Sessions and continuity Each interaction with the SDK creates or continues a session. Capture the session ID from ResultMessage.session_id (available in both SDKs) to resume later. The TypeScript SDK also exposes it as a direct field on the init SystemMessage ; in Python it’s nested in SystemMessage.data . When you resume, the full context from previous turns is restored: files that were read, analysis that was performed, and actions that were taken. You can also fork a session to branch into a different approach without modifying the original. See Session management for the full guide on resume, continue, and fork patterns. In Python, ClaudeSDKClient handles session IDs automatically across multiple calls. See the Python SDK reference for details. ​ Handle the result When the loop ends, the ResultMessage tells you what happened and gives you the output. The subtype field (available in both SDKs) is the primary way to check termination state. Result subtype What happened result field available? success Claude finished the task normally Yes error_max_turns Hit the maxTurns limit before finishing No error_max_budget_usd Hit the maxBudgetUsd limit before finishing No error_during_execution An error interrupted the loop (for example, an API failure or cancelled request) No error_max_structured_output_retries Structured output validation failed after the configured retry limit No The result field (the final text output) is only present on the success variant, so always check the subtype before reading it. All result subtypes carry total_cost_usd , usage , num_turns , and session_id so you can track cost and resume even after errors. In Python, total_cost_usd and usage are typed as optional and may be None on some error paths, so guard before formatting them. See Tracking costs and usage for details on interpreting the usage fields. The result also includes a stop_reason field ( string | null in TypeScript, str | None in Python) indicating why the model stopped generating on its final turn. Common values are end_turn (model finished normally), max_tokens (hit the output token limit), and refusal (the model declined the request). On error result subtypes, stop_reason carries the value from the last assistant response before the loop ended. To detect refusals, check stop_reason === "refusal" (TypeScript) or stop_reason == "refusal" (Python). See SDKResultMessage (TypeScript) or ResultMessage (Python) for the full type. ​ Hooks Hooks are callbacks that fire at specific points in the loop: before a tool runs, after it returns, when the agent finishes, and so on. Some commonly used hooks are: Hook When it fires Common uses PreToolUse Before a tool executes Validate inputs, block dangerous commands PostToolUse After a tool returns Audit outputs, trigger side effects UserPromptSubmit When a prompt is sent Inject additional context into prompts Stop When the agent finishes Validate the result, save session state SubagentStart / SubagentStop When a subagent spawns or completes Track and aggregate parallel task results PreCompact Before context compaction Archive full transcript before summarizing Hooks run in your application process, not inside the agent’s context window, so they don’t consume context. Hooks can also short-circuit the loop: a PreToolUse hook that rejects a tool call prevents it from executing, and Claude receives the rejection message instead. Both SDKs support all the events above. The TypeScript SDK includes additional events that Python does not yet support. See Control execution with hooks for the complete event list, per-SDK availability, and the full callback API. ​ Put it all together This example combines the key concepts from this page into a single agent that fixes failing tests. It configures the agent with allowed tools (auto-approved so the agent runs autonomously), project settings, and safety limits on turns and reasoning effort. As the loop runs, it captures the session ID for potential resumption, handles the final result, and prints the total cost. Python TypeScript import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage async def run_agent (): session_id = None async for message in query( prompt = "Find and fix the bug causing test failures in the auth module" , options = ClaudeAgentOptions( allowed_tools = [ "Read" , "Edit" , "Bash" , "Glob" , "Grep" , ], # Listing tools here auto-approves them (no prompting) setting_sources = [ "project" ], # Load CLAUDE.md, skills, hooks from current directory max_turns = 30 , # Prevent runaway sessions effort = "high" , # Thorough reasoning for complex debugging ), ): # Handle the final result if isinstance (message, ResultMessage): session_id = message.session_id # Save for potential resumption if message.subtype == "success" : print ( f "Done: { message.result } " ) elif message.subtype == "error_max_turns" : # Agent ran out of turns. Resume with a higher limit. print ( f "Hit turn limit. Resume session { session_id } to continue." ) elif message.subtype == "error_max_budget_usd" : print ( "Hit budget limit." ) else : print ( f "Stopped: { message.subtype } " ) if message.total_cost_usd is not None : print ( f "Cost: $ { message.total_cost_usd :.4f} " ) asyncio.run(run_agent()) ​ Next steps Now that you understand the loop, here’s where to go depending on what you’re building: Haven’t run an agent yet? Start with the quickstart to get the SDK installed and see a full example running end to end. Ready to hook into your project? Load CLAUDE.md, skills, and filesystem hooks so the agent follows your project conventions automatically. Building an interactive UI? Enable streaming to show live text and tool calls as the loop runs. Need tighter control over what the agent can do? Lock down tool access with permissions , and use hooks to audit, block, or transform tool calls before they execute. Running long or expensive tasks? Offload isolated work to subagents to keep your main context lean. For the broader conceptual picture of the agentic loop (not SDK-specific), see How Claude Code works . Was this page helpful? Yes No Quickstart Use Claude Code features Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation What's New Week 19 · May 4–8, 2026 What's New What's new Week 19 · May 4–8 Week 18 · Apr 27 – May 1 Week 17 · Apr 20–24 Week 16 · Apr 13–17 Week 15 · Apr 6–10 Week 14 · Mar 30 – Apr 3 Week 13 · Mar 23–27 Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. Releases v2.1.128 → v2.1.136 2 features · May 4–8 Plugins from .zip archives and URLs --plugin-dir now accepts a .zip plugin archive in addition to a directory, and the new --plugin-url flag fetches a plugin archive from a URL for the current session. Useful for trying a plugin before adding it to a marketplace, or for shipping internal plugins from an artifact store. Load a plugin straight from a URL: terminal claude --plugin-url https://example.com/my-plugin.zip Plugins guide History search across all your projects v2.1.129 Ctrl+R reverse-search now defaults to all prompts across every project, restoring the behavior from before v2.1.124. Press Ctrl+S while searching to narrow back to the current project or session. Handy when you remember a command you ran in another repo last week and don’t want to go digging for it. Interactive mode: command history Other wins New worktree.baseRef setting ( fresh | head ) controls whether —worktree , the EnterWorktree tool, and agent-isolation worktrees branch from the remote default branch or local HEAD ; the default fresh keeps unpushed commits out of new worktrees New settings.autoMode.hard_deny rules block matching actions unconditionally in auto mode, regardless of allow exceptions, for actions that should never run automatically even when broader allow rules apply Hooks now receive the active effort level via the effort.level JSON input field and the $CLAUDE_EFFORT environment variable, and Bash tool commands can read $CLAUDE_EFFORT CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 opts out of the fullscreen alternate-screen renderer and keeps the conversation in the terminal’s native scrollback CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE lets Homebrew or WinGet installations run the upgrade in the background and prompt to restart CLAUDE_CODE_SESSION_ID is now in the Bash tool subprocess environment, matching the session_id passed to hooks /mcp now shows the tool count for connected servers and flags servers that connected with 0 tools —channels now works with console (API key) authentication Subprocesses such as Bash, hooks, MCP, and LSP no longer inherit OTEL_* environment variables, so OTEL-instrumented apps run via the Bash tool no longer pick up the CLI’s own OTLP endpoint Sub-agent progress summaries now hit the prompt cache, cutting cache_creation token cost by roughly 3x Several OAuth and credential reliability fixes: parallel sessions no longer dead-end at 401 after a refresh-token race, MCP OAuth refresh tokens are no longer lost when multiple servers refresh concurrently, and a rare login loop from a concurrent credential write is fixed New parentSettingsBehavior admin key lets admins opt SDK managedSettings into the policy merge Full changelog for v2.1.128–v2.1.136 → Was this page helpful? Yes No What's new Week 18 · Apr 27 – May 1 Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Deployment Enterprise deployment overview Setup and access Administration overview Advanced setup Authentication Server-managed settings Auto mode Deployment Overview Amazon Bedrock Claude Platform on AWS Google Vertex AI Microsoft Foundry Network configuration LLM gateway Development containers Usage and costs Monitoring Costs Track team usage with analytics Plugin distribution Create and distribute a plugin marketplace Plugin dependency versions Security and data Security Data usage Zero data retention Adoption Communications kit Champion kit Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. Organizations can deploy Claude Code through Anthropic directly or through a cloud provider. This page helps you choose the right configuration. Deploying Claude Code across your organization? Talk to sales about enterprise plans, SSO, and centralized billing. View plans Contact sales ​ Compare deployment options For most organizations, Claude for Teams or Claude for Enterprise provides the best experience. Team members get access to both Claude Code and Claude on the web with a single subscription, centralized billing, and no infrastructure setup required. Claude for Teams is self-service and includes collaboration features, admin tools, and billing management. Best for smaller teams that need to get started quickly. Claude for Enterprise adds SSO and domain capture, role-based permissions, compliance API access, and managed policy settings for deploying organization-wide Claude Code configurations. Best for larger organizations with security and compliance requirements. Learn more about Team plans and Enterprise plans . If your organization has specific infrastructure requirements, compare the options below: Feature Claude for Teams/Enterprise Anthropic Console Amazon Bedrock Claude Platform on AWS Google Vertex AI Microsoft Foundry Best for Most organizations (recommended) Individual developers AWS-native deployments AWS Marketplace billing with Claude API features GCP-native deployments Azure-native deployments Billing Teams: $150/seat (Premium) with PAYG available Enterprise: Contact Sales PAYG PAYG through AWS PAYG through AWS Marketplace PAYG through GCP PAYG through Azure Regions Supported countries Supported countries Multiple AWS regions Multiple AWS regions Multiple GCP regions Multiple Azure regions Prompt caching Enabled by default Enabled by default Enabled by default Enabled by default Enabled by default Enabled by default Authentication Claude.ai SSO or email API key API key or AWS credentials API key or AWS credentials GCP credentials API key or Microsoft Entra ID Cost tracking Usage dashboard Usage dashboard AWS Cost Explorer AWS Cost Explorer GCP Billing Azure Cost Management Includes Claude on web Yes No No No No No Enterprise features Team management, SSO, usage monitoring None IAM policies, CloudTrail IAM policies, CloudTrail IAM roles, Cloud Audit Logs RBAC policies, Azure Monitor Select a deployment option to view setup instructions: Claude for Teams or Enterprise Anthropic Console Amazon Bedrock Claude Platform on AWS Google Vertex AI Microsoft Foundry ​ Configure proxies and gateways Most organizations can use a cloud provider directly without additional configuration. However, you may need to configure a corporate proxy or LLM gateway if your organization has specific network or management requirements. These are different configurations that can be used together: Corporate proxy : Routes traffic through an HTTP/HTTPS proxy. Use this if your organization requires all outbound traffic to pass through a proxy server for security monitoring, compliance, or network policy enforcement. Configure with the HTTPS_PROXY or HTTP_PROXY environment variables. Learn more in Enterprise network configuration . LLM Gateway : A service that sits between Claude Code and the cloud provider to handle authentication and routing. Use this if you need centralized usage tracking across teams, custom rate limiting or budgets, or centralized authentication management. Configure with the ANTHROPIC_BASE_URL , ANTHROPIC_BEDROCK_BASE_URL , ANTHROPIC_AWS_BASE_URL , or ANTHROPIC_VERTEX_BASE_URL environment variables. Learn more in LLM gateway configuration . The following examples show the environment variables to set in your shell or shell profile ( .bashrc , .zshrc ). See Settings for other configuration methods. ​ Amazon Bedrock Corporate proxy LLM Gateway Route Bedrock traffic through your corporate proxy by setting the following environment variables : # Enable Bedrock export CLAUDE_CODE_USE_BEDROCK = 1 export AWS_REGION = us-east-1 # Configure corporate proxy export HTTPS_PROXY = 'https://proxy.example.com:8080' Route Bedrock traffic through your LLM gateway by setting the following environment variables : # Enable Bedrock export CLAUDE_CODE_USE_BEDROCK = 1 # Configure LLM gateway export ANTHROPIC_BEDROCK_BASE_URL = 'https://your-llm-gateway.com/bedrock' export CLAUDE_CODE_SKIP_BEDROCK_AUTH = 1 # If gateway handles AWS auth ​ Microsoft Foundry Corporate proxy LLM Gateway Route Foundry traffic through your corporate proxy by setting the following environment variables : # Enable Microsoft Foundry export CLAUDE_CODE_USE_FOUNDRY = 1 export ANTHROPIC_FOUNDRY_RESOURCE = your-resource export ANTHROPIC_FOUNDRY_API_KEY = your-api-key # Or omit for Entra ID auth # Configure corporate proxy export HTTPS_PROXY = 'https://proxy.example.com:8080' Route Foundry traffic through your LLM gateway by setting the following environment variables : # Enable Microsoft Foundry export CLAUDE_CODE_USE_FOUNDRY = 1 # Configure LLM gateway export ANTHROPIC_FOUNDRY_BASE_URL = 'https://your-llm-gateway.com' export CLAUDE_CODE_SKIP_FOUNDRY_AUTH = 1 # If gateway handles Azure auth ​ Google Vertex AI Corporate proxy LLM Gateway Route Vertex AI traffic through your corporate proxy by setting the following environment variables : # Enable Vertex export CLAUDE_CODE_USE_VERTEX = 1 export CLOUD_ML_REGION = us-east5 export ANTHROPIC_VERTEX_PROJECT_ID = your-project-id # Configure corporate proxy export HTTPS_PROXY = 'https://proxy.example.com:8080' Route Vertex AI traffic through your LLM gateway by setting the following environment variables : # Enable Vertex export CLAUDE_CODE_USE_VERTEX = 1 # Configure LLM gateway export ANTHROPIC_VERTEX_BASE_URL = 'https://your-llm-gateway.com/vertex' export CLAUDE_CODE_SKIP_VERTEX_AUTH = 1 # If gateway handles GCP auth Use /status in Claude Code to verify your proxy and gateway configuration is applied correctly. ​ Best practices for organizations ​ Invest in documentation and memory We strongly recommend investing in documentation so that Claude Code understands your codebase. Organizations can deploy CLAUDE.md files at multiple levels: Organization-wide : Deploy to system directories like /Library/Application Support/ClaudeCode/CLAUDE.md (macOS) for company-wide standards Repository-level : Create CLAUDE.md files in repository roots containing project architecture, build commands, and contribution guidelines. Check these into source control so all users benefit Learn more in Memory and CLAUDE.md files . ​ Simplify deployment If you have a custom development environment, we find that creating a “one click” way to install Claude Code is key to growing adoption across an organization. ​ Start with guided usage Encourage new users to try Claude Code for codebase Q&A, or on smaller bug fixes or feature requests. Ask Claude Code to make a plan. Check Claude’s suggestions and give feedback if it’s off-track. Over time, as users understand this new paradigm better, then they’ll be more effective at letting Claude Code run more agentically. ​ Pin model versions for cloud providers If you deploy through Bedrock , Vertex AI , Foundry , or Claude Platform on AWS , pin specific model versions using ANTHROPIC_DEFAULT_OPUS_MODEL , ANTHROPIC_DEFAULT_SONNET_MODEL , and ANTHROPIC_DEFAULT_HAIKU_MODEL . Without pinning, model aliases resolve to the latest version, which may not yet be enabled in your account when Anthropic releases an update. Pinning lets you control when your users move to a new model. See Model configuration for what each provider does when the latest version is unavailable. ​ Configure security policies Security teams can configure managed permissions for what Claude Code is and is not allowed to do, which cannot be overwritten by local configuration. Learn more . ​ Leverage MCP for integrations MCP is a great way to give Claude Code more information, such as connecting to ticket management systems or error logs. We recommend that one central team configures MCP servers and checks a .mcp.json configuration into the codebase so that all users benefit. Learn more . At Anthropic, we trust Claude Code to power development across every Anthropic codebase. We hope you enjoy using Claude Code as much as we do. ​ Next steps Once you’ve chosen a deployment option and configured access for your team: Roll out to your team : Share installation instructions and have team members install Claude Code and authenticate with their credentials. Set up shared configuration : Create a CLAUDE.md file in your repositories to help Claude Code understand your codebase and coding standards. Configure permissions : Review security settings to define what Claude Code can and cannot do in your environment. Was this page helpful? Yes No Auto mode Amazon Bedrock Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Agents and parallel work Run agents in parallel Agents and parallel work Overview Create custom subagents Agent view Run agent teams Isolate sessions with worktrees Tools and plugins Model Context Protocol (MCP) Discover and install prebuilt plugins Create plugins Extend Claude with skills Automation Automate with hooks Push external events to Claude Run prompts on a schedule Goals Programmatic usage Launch sessions from links Troubleshooting Troubleshoot installation and login Troubleshoot performance and stability Debug configuration Error reference Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. Subagents , agent view , agent teams , and worktrees each parallelize work in a different way. The right one depends on whether you want to stay in each conversation yourself, hand tasks off and check back later, or have Claude coordinate a group of workers for you. Approach What it gives you Use it when Subagents Delegated workers inside one session that do a side task in their own context and return a summary A side task would flood your main conversation with search results, logs, or file contents you won’t reference again Agent view One screen to dispatch and monitor sessions running in the background, opened with claude agents . Research preview You have several independent tasks and want to hand them off, check status at a glance, and step in only when one needs you Agent teams Multiple coordinated sessions with a shared task list and inter-agent messaging, managed by a lead. Experimental and disabled by default You want Claude to split a project into pieces, assign them, and keep the workers in sync Worktrees Separate git checkouts so parallel sessions never touch each other’s files You’re running several sessions yourself, or your subagents edit overlapping files /batch A planned split of one large change into 5 to 30 worktree-isolated subagents that each open a pull request A repo-wide migration or mechanical refactor you can describe in one instruction In every approach the workers are Claude sessions. To involve a different tool, expose it to Claude as an MCP server . You can combine these approaches. Agent view automatically moves each dispatched session into its own worktree when it needs to edit files, and a session you’re working in can spawn subagents that each get their own worktree. Running several sessions or subagents at once multiplies token usage. See Costs for usage and rate-limit details. ​ Choose an approach The right approach depends on who coordinates the work, whether the workers need to communicate, and whether they edit the same files: Who coordinates the work? If you want Claude to delegate and collect results inside one conversation, use subagents . If you’re handing off independent tasks and checking back on them, use agent view . If you want Claude to plan, assign, and supervise a group of workers, use agent teams , which are experimental and disabled by default. Do the workers need to talk to each other? Subagents report results back to the conversation that spawned them, and agent view sessions report only to you. Teammates in an agent team share a task list and message each other directly. Do the tasks touch the same files? Isolate the work with worktrees . Subagents and sessions you run yourself can each use a separate worktree. Agent teams don’t isolate teammates in worktrees, so partition the work so each teammate owns a different set of files. ​ Check on running work The command for checking on running work depends on which approach you used: For background sessions, claude agents opens agent view : one screen showing every session, its state, and which ones need your input. For subagents in the current session, /agents opens a panel with a Running tab listing live subagents and a Library tab where you create and edit custom subagents . Despite the similar name, this is separate from claude agents . For anything running in the background of the current session, /tasks lists each item and lets you check on, attach to, or stop it. For a desktop view of all your sessions, see parallel sessions in the desktop app . ​ Learn more Each guide below covers setup and configuration for one approach: Create custom subagents : define reusable specialists and control which tools they can use. Manage agents with agent view : dispatch sessions, watch their state, and attach when one needs you. Orchestrate agent teams : set up a lead and teammates, assign tasks, and review their work. Run parallel sessions with worktrees : start Claude in an isolated checkout, control what gets copied in, and clean up afterward. Was this page helpful? Yes No Create custom subagents Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Platforms and integrations Let Claude use your computer from the CLI Getting started Overview Quickstart Changelog Core concepts How Claude Code works Extend Claude Code Explore the .claude directory Explore the context window Use Claude Code Store instructions and memories Permission modes Common workflows Best practices Platforms and integrations Overview Remote Control Claude Code on the web Claude Code on desktop Chrome extension (beta) Computer use (preview) Visual Studio Code JetBrains IDEs Code review & CI/CD Claude Code in Slack Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. Computer use is a research preview on macOS that requires a Pro or Max plan. It is not available on Team or Enterprise plans. It requires Claude Code v2.1.85 or later and an interactive session, so it is not available in non-interactive mode with the -p flag. Computer use lets Claude open apps, control your screen, and work on your machine the way you would. From the CLI, Claude can compile a Swift app, launch it, click through every button, and screenshot the result, all in the same conversation where it wrote the code. This page covers how computer use works in the CLI. For the Desktop app on macOS or Windows, see computer use in Desktop . ​ What you can do with computer use Computer use handles tasks that require a GUI: anything you’d normally have to leave the terminal and do by hand. Build and validate native apps : ask Claude to build a macOS menu bar app. Claude writes the Swift, compiles it, launches it, and clicks through every control to verify it works before you ever open it. End-to-end UI testing : point Claude at a local Electron app and say “test the onboarding flow.” Claude opens the app, clicks through signup, and screenshots each step. No Playwright config, no test harness. Debug visual and layout issues : tell Claude “the modal is clipping on small windows.” Claude resizes the window, reproduces the bug, screenshots it, patches the CSS, and verifies the fix. Claude sees what you see. Drive GUI-only tools : interact with design tools, hardware control panels, the iOS Simulator, or proprietary apps that have no CLI or API. ​ When computer use applies Claude has several ways to interact with an app or service. Computer use is the broadest and slowest, so Claude tries the most precise tool first: If you have an MCP server for the service, Claude uses that. If the task is a shell command, Claude uses Bash. If the task is browser work and you have Claude in Chrome set up, Claude uses that. If none of those apply, Claude uses computer use. Screen control is reserved for things nothing else can reach: native apps, simulators, and tools without an API. ​ Enable computer use Computer use is available as a built-in MCP server called computer-use . It’s off by default until you enable it. 1 Open the MCP menu In an interactive Claude Code session, run: /mcp Find computer-use in the server list. It shows as disabled. 2 Enable the server Select computer-use and choose Enable . The setting persists per project, so you only do this once for each project where you want computer use. 3 Grant macOS permissions The first time Claude tries to use your computer, you’ll see a prompt to grant two macOS permissions: Accessibility : lets Claude click, type, and scroll Screen Recording : lets Claude see what’s on your screen The prompt includes links to open the relevant System Settings pane. Grant both, then select Try again in the prompt. macOS may require you to restart Claude Code after granting Screen Recording. After setup, ask Claude to do something that needs the GUI: Build the app target, launch it, and click through each tab to make sure nothing crashes. Screenshot any error states you find. ​ Approve apps per session Enabling the computer-use server doesn’t grant Claude access to every app on your machine. The first time Claude needs a specific app in a session, a prompt appears in your terminal showing: Which apps Claude wants to control Any extra permissions requested, such as clipboard access How many other apps will be hidden while Claude works Choose Allow for this session or Deny . Approvals last for the current session. You can approve multiple apps at once when Claude requests them together. Apps with broad reach show an extra warning in the prompt so you know what approving them grants: Warning Applies to Equivalent to shell access Terminal, iTerm, VS Code, Warp, and other terminals and IDEs Can read or write any file Finder Can change system settings System Settings These apps aren’t blocked. The warning lets you decide whether the task warrants that level of access. Claude’s level of control also varies by app category: browsers and trading platforms are view-only, terminals and IDEs are click-only, and everything else gets full control. See app permissions in Desktop for the complete tier breakdown. ​ How Claude works on your screen Understanding the flow helps you anticipate what Claude will do and how to intervene. ​ One session at a time Computer use holds a machine-wide lock while active. If another Claude Code session is already using your computer, new attempts fail with a message telling you which session holds the lock. Finish or exit that session first. ​ Apps are hidden while Claude works When Claude starts controlling your screen, other visible apps are hidden so Claude interacts with only the approved apps. Your terminal window stays visible and is excluded from screenshots, so you can watch the session and Claude never sees its own output. When Claude finishes the turn, hidden apps are restored automatically. ​ Screenshots are downscaled automatically Claude Code downscales every screenshot before sending it to the model. You don’t need to lower your display resolution or resize windows on Retina or other high-resolution displays. A 16-inch MacBook Pro at native Retina resolution captures at 3456×2234 and downscales to roughly 1372×887, preserving aspect ratio. There is no setting to change the target size. If on-screen text or controls are too small for Claude to read after downscaling, increase their size in the app rather than changing your display resolution. ​ Stop at any time When Claude acquires the lock, a macOS notification appears: “Claude is using your computer · press Esc to stop.” Press Esc anywhere to abort the current action immediately, or press Ctrl+C in the terminal. Either way, Claude releases the lock, unhides your apps, and returns control to you. A second notification appears when Claude is done. ​ Safety and the trust boundary Unlike the sandboxed Bash tool , computer use runs on your actual desktop with access to the apps you approve. Claude checks each action and flags potential prompt injection from on-screen content, but the trust boundary is different. See the computer use safety guide for best practices. The built-in guardrails reduce risk without requiring configuration: Per-app approval : Claude can only control apps you’ve approved in the current session. Sentinel warnings : apps that grant shell, filesystem, or system settings access are flagged before you approve. Terminal excluded from screenshots : Claude never sees your terminal window, so on-screen prompts in your session can’t feed back into the model. Global escape : the Esc key aborts computer use from anywhere, and the key press is consumed so prompt injection can’t use it to dismiss dialogs. Lock file : only one session can control your machine at a time. ​ Example workflows These examples show common ways to combine computer use with coding tasks. ​ Validate a native build After making changes to a macOS or iOS app, have Claude compile and verify in one pass: Build the MenuBarStats target, launch it, open the preferences window, and verify the interval slider updates the label. Screenshot the preferences window when you're done. Claude runs xcodebuild , launches the app, interacts with the UI, and reports what it finds. ​ Reproduce a layout bug When a visual bug only appears at certain window sizes, let Claude find it: The settings modal clips its footer on narrow windows. Resize the app window down until you can reproduce it, screenshot the clipped state, then check the CSS for the modal container. Claude resizes the window, captures the broken state, and reads the relevant stylesheets. ​ Test a simulator flow Drive the iOS Simulator without writing XCTest: Open the iOS Simulator, launch the app, tap through the onboarding screens, and tell me if any screen takes more than a second to load. Claude controls the simulator the same way you would with a mouse. ​ Differences from the Desktop app The CLI and Desktop surfaces share the same computer use engine, with a few differences: Feature Desktop CLI Platforms macOS and Windows macOS only Enable Toggle in Settings > General (under Desktop app ) Enable computer-use in /mcp Denied apps list Configurable in Settings Not yet available Auto-unhide toggle Optional Always on Dispatch integration Dispatch-spawned sessions can use computer use Not applicable ​ Troubleshooting ​ ”Computer use is in use by another Claude session” Another Claude Code session holds the lock. Finish the task in that session or exit it. If the other session crashed, the lock is released automatically when Claude detects the process is no longer running. ​ macOS permissions prompt keeps reappearing macOS sometimes requires a restart of the requesting process after you grant Screen Recording. Quit Claude Code completely and start a new session. If the prompt persists, open System Settings > Privacy & Security > Screen Recording and confirm your terminal app is listed and enabled. ​ computer-use doesn’t appear in /mcp The server only appears on eligible setups. Check that: You’re on macOS. Computer use in the CLI is not available on Linux or Windows. On Windows, use computer use in Desktop instead. You’re running Claude Code v2.1.85 or later. Run claude --version to check. You’re on a Pro or Max plan. Run /status to confirm your subscription. You’re authenticated through claude.ai. Computer use is not available with third-party providers like Amazon Bedrock, Google Cloud Vertex AI, or Microsoft Foundry. If you access Claude exclusively through a third-party provider, you need a separate claude.ai account to use this feature. You’re in an interactive session. Computer use is not available in non-interactive mode with the -p flag. ​ See also Computer use in Desktop : the same capability with a graphical settings page Claude in Chrome : browser automation for web-based tasks MCP : connect Claude to structured tools and APIs Sandboxing : how Claude’s Bash tool isolates filesystem and network access Computer use safety guide : best practices for safe computer use Was this page helpful? Yes No Chrome extension (beta) Visual Studio Code Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Extend with tools Subagents in the SDK Agent SDK Overview Quickstart Core concepts How the agent loop works Use Claude Code features Work with sessions Input and output Streaming Input Handle approvals and user input Stream responses in real-time Get structured output from agents Extend with tools Give Claude custom tools Connect to external tools with MCP Scale to many tools with tool search Subagents in the SDK Customize behavior Modifying system prompts Slash Commands in the SDK Agent Skills in the SDK Plugins in the SDK Control and observability Configure permissions Intercept and control agent behavior with hooks Rewind file changes with checkpointing Track cost and usage Observability with OpenTelemetry Todo Lists Deployment Hosting the Agent SDK Securely deploying AI agents SDK references TypeScript SDK TypeScript V2 (deprecated) Python SDK Migration Guide Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. Subagents are separate agent instances that your main agent can spawn to handle focused subtasks. Use subagents to isolate context for focused subtasks, run multiple analyses in parallel, and apply specialized instructions without bloating the main agent’s prompt. This guide explains how to define and use subagents in the SDK using the agents parameter. ​ Overview You can create subagents in three ways: Programmatically : use the agents parameter in your query() options ( TypeScript , Python ) Filesystem-based : define agents as markdown files in .claude/agents/ directories (see defining subagents as files ) Built-in general-purpose : Claude can invoke the built-in general-purpose subagent at any time via the Agent tool without you defining anything This guide focuses on the programmatic approach, which is recommended for SDK applications. When you define subagents, Claude determines whether to invoke them based on each subagent’s description field. Write clear descriptions that explain when the subagent should be used, and Claude will automatically delegate appropriate tasks. You can also explicitly request a subagent by name in your prompt (for example, “Use the code-reviewer agent to…”). ​ Benefits of using subagents ​ Context isolation Each subagent runs in its own fresh conversation. Intermediate tool calls and results stay inside the subagent; only its final message returns to the parent. See What subagents inherit for exactly what’s in the subagent’s context. Example: a research-assistant subagent can explore dozens of files without any of that content accumulating in the main conversation. The parent receives a concise summary, not every file the subagent read. ​ Parallelization Multiple subagents can run concurrently, dramatically speeding up complex workflows. Example: during a code review, you can run style-checker , security-scanner , and test-coverage subagents simultaneously, reducing review time from minutes to seconds. ​ Specialized instructions and knowledge Each subagent can have tailored system prompts with specific expertise, best practices, and constraints. Example: a database-migration subagent can have detailed knowledge about SQL best practices, rollback strategies, and data integrity checks that would be unnecessary noise in the main agent’s instructions. ​ Tool restrictions Subagents can be limited to specific tools, reducing the risk of unintended actions. Example: a doc-reviewer subagent might only have access to Read and Grep tools, ensuring it can analyze but never accidentally modify your documentation files. ​ Creating subagents ​ Programmatic definition (recommended) Define subagents directly in your code using the agents parameter. This example creates two subagents: a code reviewer with read-only access and a test runner that can execute commands. The Agent tool must be included in allowedTools since Claude invokes subagents through the Agent tool. Python TypeScript import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition async def main (): async for message in query( prompt = "Review the authentication module for security issues" , options = ClaudeAgentOptions( # Agent tool is required for subagent invocation allowed_tools = [ "Read" , "Grep" , "Glob" , "Agent" ], agents = { "code-reviewer" : AgentDefinition( # description tells Claude when to use this subagent description = "Expert code review specialist. Use for quality, security, and maintainability reviews." , # prompt defines the subagent's behavior and expertise prompt = """You are a code review specialist with expertise in security, performance, and best practices. When reviewing code: - Identify security vulnerabilities - Check for performance issues - Verify adherence to coding standards - Suggest specific improvements Be thorough but concise in your feedback.""" , # tools restricts what the subagent can do (read-only here) tools = [ "Read" , "Grep" , "Glob" ], # model overrides the default model for this subagent model = "sonnet" , ), "test-runner" : AgentDefinition( description = "Runs and analyzes test suites. Use for test execution and coverage analysis." , prompt = """You are a test execution specialist. Run tests and provide clear analysis of results. Focus on: - Running test commands - Analyzing test output - Identifying failing tests - Suggesting fixes for failures""" , # Bash access lets this subagent run test commands tools = [ "Bash" , "Read" , "Grep" ], ), }, ), ): if hasattr (message, "result" ): print (message.result) asyncio.run(main()) ​ AgentDefinition configuration Field Type Required Description description string Yes Natural language description of when to use this agent prompt string Yes The agent’s system prompt defining its role and behavior tools string[] No Array of allowed tool names. If omitted, inherits all tools disallowedTools string[] No Array of tool names to remove from the agent’s tool set model string No Model override for this agent. Accepts an alias such as 'sonnet' , 'opus' , 'haiku' , 'inherit' , or a full model ID. Defaults to main model if omitted skills string[] No List of skill names to preload into the agent’s context at startup. Unlisted skills remain invocable through the Skill tool memory 'user' | 'project' | 'local' No Memory source for this agent mcpServers (string | object)[] No MCP servers available to this agent, by name or inline config maxTurns number No Maximum number of agentic turns before the agent stops background boolean No Run this agent as a non-blocking background task when invoked effort 'low' | 'medium' | 'high' | 'xhigh' | 'max' | number No Reasoning effort level for this agent permissionMode PermissionMode No Permission mode for tool execution within this agent In the Python SDK, these field names use camelCase to match the wire format. See the AgentDefinition reference for details. Subagents cannot spawn their own subagents. Don’t include Agent in a subagent’s tools array. ​ Filesystem-based definition (alternative) You can also define subagents as markdown files in .claude/agents/ directories. See the Claude Code subagents documentation for details on this approach. Programmatically defined agents take precedence over filesystem-based agents with the same name. Even without defining custom subagents, Claude can spawn the built-in general-purpose subagent when Agent is in your allowedTools . This is useful for delegating research or exploration tasks without creating specialized agents. ​ What subagents inherit A subagent’s context window starts fresh (no parent conversation) but isn’t empty. The only channel from parent to subagent is the Agent tool’s prompt string, so include any file paths, error messages, or decisions the subagent needs directly in that prompt. The subagent receives The subagent does not receive Its own system prompt ( AgentDefinition.prompt ) and the Agent tool’s prompt The parent’s conversation history or tool results Project CLAUDE.md (loaded via settingSources ) Preloaded skill content, unless listed in AgentDefinition.skills Tool definitions (inherited from parent, or the subset in tools ) The parent’s system prompt The parent receives the subagent’s final message verbatim as the Agent tool result, but may summarize it in its own response. To preserve subagent output verbatim in the user-facing response, include an instruction to do so in the prompt or systemPrompt option you pass to the main query() call. ​ Invoking subagents ​ Automatic invocation Claude automatically decides when to invoke subagents based on the task and each subagent’s description . For example, if you define a performance-optimizer subagent with the description “Performance optimization specialist for query tuning”, Claude will invoke it when your prompt mentions optimizing queries. Write clear, specific descriptions so Claude can match tasks to the right subagent. ​ Explicit invocation To guarantee Claude uses a specific subagent, mention it by name in your prompt: "Use the code-reviewer agent to check the authentication module" This bypasses automatic matching and directly invokes the named subagent. ​ Dynamic agent configuration You can create agent definitions dynamically based on runtime conditions. This example creates a security reviewer with different strictness levels, using a more powerful model for strict reviews. Python TypeScript import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition # Factory function that returns an AgentDefinition # This pattern lets you customize agents based on runtime conditions def create_security_agent ( security_level : str ) -> AgentDefinition: is_strict = security_level == "strict" return AgentDefinition( description = "Security code reviewer" , # Customize the prompt based on strictness level prompt = f "You are a { 'strict' if is_strict else 'balanced' } security reviewer..." , tools = [ "Read" , "Grep" , "Glob" ], # Key insight: use a more capable model for high-stakes reviews model = "opus" if is_strict else "sonnet" , ) async def main (): # The agent is created at query time, so each request can use different settings async for message in query( prompt = "Review this PR for security issues" , options = ClaudeAgentOptions( allowed_tools = [ "Read" , "Grep" , "Glob" , "Agent" ], agents = { # Call the factory with your desired configuration "security-reviewer" : create_security_agent( "strict" ) }, ), ): if hasattr (message, "result" ): print (message.result) asyncio.run(main()) ​ Detecting subagent invocation Subagents are invoked via the Agent tool. To detect when a subagent is invoked, check for tool_use blocks where name is "Agent" . Messages from within a subagent’s context include a parent_tool_use_id field. The tool name was renamed from "Task" to "Agent" in Claude Code v2.1.63. Current SDK releases emit "Agent" in tool_use blocks but still use "Task" in the system:init tools list and in result.permission_denials[].tool_name . Checking both values in block.name ensures compatibility across SDK versions. This example iterates through streamed messages, logging when a subagent is invoked and when subsequent messages originate from within that subagent’s execution context. The message structure differs between SDKs. In Python, content blocks are accessed directly via message.content . In TypeScript, SDKAssistantMessage wraps the Claude API message, so content is accessed via message.message.content . Python TypeScript import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ToolUseBlock async def main (): async for message in query( prompt = "Use the code-reviewer agent to review this codebase" , options = ClaudeAgentOptions( allowed_tools = [ "Read" , "Glob" , "Grep" , "Agent" ], agents = { "code-reviewer" : AgentDefinition( description = "Expert code reviewer." , prompt = "Analyze code quality and suggest improvements." , tools = [ "Read" , "Glob" , "Grep" ], ) }, ), ): # Check for subagent invocation. Match both names: older SDK # versions emitted "Task", current versions emit "Agent". if hasattr (message, "content" ) and message.content: for block in message.content: if isinstance (block, ToolUseBlock) and block.name in ( "Task" , "Agent" , ): print ( f "Subagent invoked: { block.input.get( 'subagent_type' ) } " ) # Check if this message is from within a subagent's context if hasattr (message, "parent_tool_use_id" ) and message.parent_tool_use_id: print ( " (running inside subagent)" ) if hasattr (message, "result" ): print (message.result) asyncio.run(main()) ​ Resuming subagents Subagents can be resumed to continue where they left off. Resumed subagents retain their full conversation history, including all previous tool calls, results, and reasoning. The subagent picks up exactly where it stopped rather than starting fresh. When a subagent completes, Claude receives its agent ID in the Agent tool result. To resume a subagent programmatically: Capture the session ID : Extract session_id from messages during the first query Extract the agent ID : Parse agentId from the message content Resume the session : Pass resume: sessionId in the second query’s options, and include the agent ID in your prompt You must resume the same session to access the subagent’s transcript. Each query() call starts a new session by default, so pass resume: sessionId to continue in the same session. If you’re using a custom agent (not a built-in one), you also need to pass the same agent definition in the agents parameter for both queries. The example below demonstrates this flow: the first query runs a subagent and captures the session ID and agent ID, then the second query resumes the session to ask a follow-up question that requires context from the first analysis. TypeScript Python import { query , type SDKMessage } from "@anthropic-ai/claude-agent-sdk" ; // Helper to extract agentId from message content // Stringify to avoid traversing different block types (TextBlock, ToolResultBlock, etc.) function extractAgentId ( message : SDKMessage ) : string | undefined { if ( message . type !== "assistant" && message . type !== "user" ) return undefined ; // Stringify the content so we can search it without traversing nested blocks const content = JSON . stringify ( message . message . content ); const match = content . match ( /agentId: \s * ( [ a-f0-9- ] + ) / ); return match ?.[ 1 ]; } let agentId : string | undefined ; let sessionId : string | undefined ; // First invocation - use the Explore agent to find API endpoints for await ( const message of query ({ prompt: "Use the Explore agent to find all API endpoints in this codebase" , options: { allowedTools: [ "Read" , "Grep" , "Glob" , "Agent" ] } })) { // Capture session_id from ResultMessage (needed to resume this session) if ( "session_id" in message ) sessionId = message . session_id ; // Search message content for the agentId (appears in Agent tool results) const extractedId = extractAgentId ( message ); if ( extractedId ) agentId = extractedId ; // Print the final result if ( "result" in message ) console . log ( message . result ); } // Second invocation - resume and ask follow-up if ( agentId && sessionId ) { for await ( const message of query ({ prompt: `Resume agent ${ agentId } and list the top 3 most complex endpoints` , options: { allowedTools: [ "Read" , "Grep" , "Glob" , "Agent" ], resume: sessionId } })) { if ( "result" in message ) console . log ( message . result ); } } Subagent transcripts persist independently of the main conversation: Main conversation compaction : When the main conversation compacts, subagent transcripts are unaffected. They’re stored in separate files. Session persistence : Subagent transcripts persist within their session. You can resume a subagent after restarting Claude Code by resuming the same session. Automatic cleanup : Transcripts are cleaned up based on the cleanupPeriodDays setting (default: 30 days). ​ Tool restrictions Subagents can have restricted tool access via the tools field: Omit the field : agent inherits all available tools (default) Specify tools : agent can only use listed tools This example creates a read-only analysis agent that can examine code but cannot modify files or run commands. Python TypeScript import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition async def main (): async for message in query( prompt = "Analyze the architecture of this codebase" , options = ClaudeAgentOptions( allowed_tools = [ "Read" , "Grep" , "Glob" , "Agent" ], agents = { "code-analyzer" : AgentDefinition( description = "Static code analysis and architecture review" , prompt = """You are a code architecture analyst. Analyze code structure, identify patterns, and suggest improvements without making changes.""" , # Read-only tools: no Edit, Write, or Bash access tools = [ "Read" , "Grep" , "Glob" ], ) }, ), ): if hasattr (message, "result" ): print (message.result) asyncio.run(main()) ​ Common tool combinations Use case Tools Description Read-only analysis Read , Grep , Glob Can examine code but not modify or execute Test execution Bash , Read , Grep Can run commands and analyze output Code modification Read , Edit , Write , Grep , Glob Full read/write access without command execution Full access All tools Inherits all tools from parent (omit tools field) ​ Troubleshooting ​ Claude not delegating to subagents If Claude completes tasks directly instead of delegating to your subagent: Include the Agent tool : subagents are invoked via the Agent tool, so it must be in allowedTools Use explicit prompting : mention the subagent by name in your prompt (for example, “Use the code-reviewer agent to…”) Write a clear description : explain exactly when the subagent should be used so Claude can match tasks appropriately ​ Filesystem-based agents not loading Agents defined in .claude/agents/ are loaded at startup only. If you create a new agent file while Claude Code is running, restart the session to load it. ​ Windows: long prompt failures On Windows, subagents with very long prompts may fail due to command line length limits (8191 chars). Keep prompts concise or use filesystem-based agents for complex instructions. ​ Related documentation Claude Code subagents : comprehensive subagent documentation including filesystem-based definitions SDK overview : getting started with the Claude Agent SDK Was this page helpful? Yes No Scale to many tools with tool search Modifying system prompts Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Deployment Claude Code on Amazon Bedrock Setup and access Administration overview Advanced setup Authentication Server-managed settings Auto mode Deployment Overview Amazon Bedrock Claude Platform on AWS Google Vertex AI Microsoft Foundry Network configuration LLM gateway Development containers Usage and costs Monitoring Costs Track team usage with analytics Plugin distribution Create and distribute a plugin marketplace Plugin dependency versions Security and data Security Data usage Zero data retention Adoption Communications kit Champion kit Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. Deploying Claude Code across your organization? Talk to sales about enterprise plans, SSO, and centralized billing. View plans Contact sales ​ Prerequisites Before configuring Claude Code with Bedrock, ensure you have: An AWS account with Bedrock access enabled Access to desired Claude models (for example, Claude Sonnet 4.6) in Bedrock AWS CLI installed and configured (optional - only needed if you don’t have another mechanism for getting credentials) Appropriate IAM permissions To sign in with your own Bedrock credentials, follow Sign in with Bedrock below. To deploy Claude Code across a team, use the manual setup steps and pin your model versions before rolling out. ​ Sign in with Bedrock If you have AWS credentials and want to start using Claude Code through Bedrock, the login wizard walks you through it. You complete the AWS-side prerequisites once per account; the wizard handles the Claude Code side. 1 Enable Anthropic models in your AWS account In the Amazon Bedrock console , open the Model catalog, select an Anthropic model, and submit the use case form. Access is granted immediately after submission. See Submit use case details for AWS Organizations and IAM configuration for the permissions your role needs. 2 Start Claude Code and choose Bedrock Run claude . At the login prompt, select 3rd-party platform , then Amazon Bedrock . 3 Follow the wizard prompts Choose how you authenticate to AWS: an AWS profile detected from your ~/.aws directory, a Bedrock API key, an access key and secret, or credentials already in your environment. The wizard picks up your region, verifies which Claude models your account can invoke, and lets you pin them. It saves the result to the env block of your user settings file , so you don’t need to export environment variables yourself. After you’ve signed in, run /setup-bedrock any time to reopen the wizard and change your credentials, region, or model pins. ​ Set up manually To configure Bedrock through environment variables instead of the wizard, for example in CI or a scripted enterprise rollout, follow the steps below. ​ 1. Submit use case details First-time users of Anthropic models are required to submit use case details before invoking a model. This is done once per AWS account. Ensure you have the right IAM permissions described below Navigate to the Amazon Bedrock console Select an Anthropic model from the Model catalog Complete the use case form. Access is granted immediately after submission. If you use AWS Organizations, you can submit the form once from the management account using the PutUseCaseForModelAccess API . This call requires the bedrock:PutUseCaseForModelAccess IAM permission. Approval extends to child accounts automatically. ​ 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 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: AWS Management Console credentials aws login Learn more about aws login . Option E: 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 . ​ 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 for file locations). These two settings have different trigger conditions: awsAuthRefresh : runs only when Claude Code detects that your AWS credentials are expired, either locally based on their timestamp or when Bedrock returns a credential error, then retries the request with refreshed credentials. awsCredentialExport : runs at session start and on each credential reload, even when the credentials in your AWS default credential provider chain are still valid. Use this when your Bedrock account requires cross-account credentials that differ from the ones the default provider chain would resolve. 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, such as updating credentials, SSO cache, or config files. The command’s output is displayed to the user, but interactive input isn’t supported. This works well for browser-based SSO flows where the CLI displays a URL or code and you complete authentication in the browser. awsCredentialExport : Only use this if you can’t modify .aws and must directly return credentials. This command runs whenever credentials need to be refreshed, not only when credentials are expired. Output is captured silently and 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 AWS region for the small/fast model (Bedrock and Mantle). # On Bedrock, has no effect without ANTHROPIC_DEFAULT_HAIKU_MODEL # or the deprecated ANTHROPIC_SMALL_FAST_MODEL set. export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION = us-west-2 # Optional: Override the Bedrock endpoint URL for custom endpoints or gateways # export ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com 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 for more information. ​ 4. Pin model versions Pin specific model versions when deploying to multiple users. Without pinning, model aliases such as sonnet and opus resolve to the latest version, which may not yet be available in your Bedrock account when Anthropic releases an update. Claude Code falls back to the previous version at startup when the latest is unavailable, but pinning lets you control when your users move to a new model. Set these environment variables to specific Bedrock model IDs. Without ANTHROPIC_DEFAULT_OPUS_MODEL , the opus alias on Bedrock resolves to Opus 4.6. Set it to the Opus 4.7 ID to use the latest model: export ANTHROPIC_DEFAULT_OPUS_MODEL = 'us.anthropic.claude-opus-4-7' export ANTHROPIC_DEFAULT_SONNET_MODEL = 'us.anthropic.claude-sonnet-4-6' export ANTHROPIC_DEFAULT_HAIKU_MODEL = 'us.anthropic.claude-haiku-4-5-20251001-v1:0' These variables use cross-region inference profile IDs (with the us. prefix). If you use a different region prefix or application inference profiles, adjust accordingly. For current and legacy model IDs, see Models overview . See Model configuration for the full list of environment variables. Claude Code uses these default models when no pinning variables are set: Model type Default value Primary model us.anthropic.claude-sonnet-4-5-20250929-v1:0 Small/fast model Same as primary model Background tasks such as session title generation use the small/fast model, normally a Haiku-class model. On Bedrock, Claude Code defaults this to the primary model because Haiku may not be enabled in every account or region. To use Haiku for background tasks, set ANTHROPIC_DEFAULT_HAIKU_MODEL to a model ID that is available in your account. To customize models further, use one of these methods: # Using inference profile ID export ANTHROPIC_MODEL = 'us.anthropic.claude-sonnet-4-6' export ANTHROPIC_DEFAULT_HAIKU_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 # Optional: Request 1-hour prompt cache TTL instead of the 5-minute default export ENABLE_PROMPT_CACHING_1H = 1 Prompt caching may not be available in all regions. Cache writes with a 1-hour TTL are billed at a higher rate than 5-minute writes. ​ Map each model version to an inference profile The ANTHROPIC_DEFAULT_*_MODEL environment variables configure one inference profile per model family. If your organization needs to expose several versions of the same family in the /model picker, each routed to its own application inference profile ARN, use the modelOverrides setting in your settings file instead. This example maps four Opus versions to distinct ARNs so users can switch between them without bypassing your organization’s inference profiles: { "modelOverrides" : { "claude-opus-4-7" : "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-47-prod" , "claude-opus-4-6" : "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-46-prod" , "claude-opus-4-5-20251101" : "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-45-prod" , "claude-opus-4-1-20250805" : "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-41-prod" } } When a user selects one of these versions in /model , Claude Code calls Bedrock with the mapped ARN. Versions without an override fall back to the built-in Bedrock model ID or any matching inference profile discovered at startup. See Override model IDs per version for details on how overrides interact with availableModels and other model settings. ​ Startup model checks When Claude Code starts with Bedrock configured, it verifies that the models it intends to use are accessible in your account. This check requires Claude Code v2.1.94 or later. If you have pinned a model version that is older than the current Claude Code default, and your account can invoke the newer version, Claude Code prompts you to update the pin. Accepting writes the new model ID to your user settings file and restarts Claude Code. Declining is remembered until the next default version change. Pins that point to an application inference profile ARN are skipped, since those are managed by your administrator. If you have not pinned a model and the current default is unavailable in your account, Claude Code falls back to the previous version for the current session and shows a notice. The fallback is not persisted. Enable the newer model in your Bedrock account or pin a version to make the choice permanent. ​ IAM configuration Create an IAM policy with the required permissions for Claude Code: { "Version" : "2012-10-17" , "Statement" : [ { "Sid" : "AllowModelAndInferenceProfileAccess" , "Effect" : "Allow" , "Action" : [ "bedrock:InvokeModel" , "bedrock:InvokeModelWithResponseStream" , "bedrock:ListInferenceProfiles" , "bedrock:GetInferenceProfile" ], "Resource" : [ "arn:aws:bedrock:*:*:inference-profile/*" , "arn:aws:bedrock:*:*:application-inference-profile/*" , "arn:aws:bedrock:*:*:foundation-model/*" ] }, { "Sid" : "AllowMarketplaceSubscription" , "Effect" : "Allow" , "Action" : [ "aws-marketplace:ViewSubscriptions" , "aws-marketplace:Subscribe" ], "Resource" : "*" , "Condition" : { "StringEquals" : { "aws:CalledViaLast" : "bedrock.amazonaws.com" } } } ] } For more restrictive permissions, you can limit the Resource to specific inference profile ARNs. bedrock:GetInferenceProfile lets Claude Code resolve an application inference profile ARN to its backing foundation model, which is used to select the correct request shape for that model. If the token is missing this permission, Claude Code recovers automatically by retrying once with the alternate shape, so requests still succeed but each new model adds an extra round-trip. Granting the permission avoids the retry. This applies most often to AWS_BEARER_TOKEN_BEDROCK deployments, where the token’s policy is typically narrower than a full IAM role. For details, see Bedrock IAM documentation . Create a dedicated AWS account for Claude Code to simplify cost tracking and access control. ​ 1M token context window Claude Opus 4.7, Opus 4.6, and Sonnet 4.6 support the 1M token context window on Amazon Bedrock. Claude Code automatically enables the extended context window when you select a 1M model variant. The setup wizard offers a 1M context option when it pins models. To enable it for a manually pinned model instead, append [1m] to the model ID. See Pin models for third-party deployments for details. ​ Service tiers Amazon Bedrock service tiers let you trade off cost against latency. Set ANTHROPIC_BEDROCK_SERVICE_TIER to default , flex , or priority : export ANTHROPIC_BEDROCK_SERVICE_TIER = priority Claude Code sends this as the X-Amzn-Bedrock-Service-Tier header on each request. Tier availability varies by model and region. Reserved capacity uses a provisioned throughput ARN as the model ID instead of this setting. ​ AWS Guardrails Amazon Bedrock Guardrails let you implement content filtering for Claude Code. Create a Guardrail in the Amazon Bedrock console , publish a version, then add the Guardrail headers to your settings file . Enable Cross-Region inference on your Guardrail if you’re using cross-region inference profiles. Example configuration: { "env" : { "ANTHROPIC_CUSTOM_HEADERS" : "X-Amzn-Bedrock-GuardrailIdentifier: your-guardrail-id \n X-Amzn-Bedrock-GuardrailVersion: 1" } } ​ Use the Mantle endpoint Mantle is an Amazon Bedrock endpoint that serves Claude models through the native Anthropic API shape rather than the Bedrock Invoke API. It uses the same AWS credentials, IAM permissions, and awsAuthRefresh configuration described earlier on this page. Mantle requires Claude Code v2.1.94 or later. Run claude --version to check. ​ Enable Mantle With AWS credentials already configured, set CLAUDE_CODE_USE_MANTLE to route requests to the Mantle endpoint: export CLAUDE_CODE_USE_MANTLE = 1 export AWS_REGION = us-east-1 Claude Code constructs the endpoint URL from AWS_REGION . To override it for a custom endpoint or gateway, set ANTHROPIC_BEDROCK_MANTLE_BASE_URL . Run /status inside Claude Code to confirm. The provider line shows Amazon Bedrock (Mantle) when Mantle is active. ​ Select a Mantle model Mantle uses model IDs prefixed with anthropic. and without a version suffix, for example anthropic.claude-haiku-4-5 . The models available to your account depend on what your organization has been granted; additional model IDs are listed in your onboarding materials from AWS. Contact your AWS account team to request access to allowlisted models. Set the model with the --model flag or with /model inside Claude Code: claude --model anthropic.claude-haiku-4-5 ​ Run Mantle alongside the Invoke API The models available to you on Mantle may not include every model you use today. Setting both CLAUDE_CODE_USE_BEDROCK and CLAUDE_CODE_USE_MANTLE lets Claude Code call both endpoints from the same session. Model IDs that match the Mantle format are routed to Mantle, and all other model IDs go to the Bedrock Invoke API. export CLAUDE_CODE_USE_BEDROCK = 1 export CLAUDE_CODE_USE_MANTLE = 1 To surface a Mantle model in the /model picker, list its ID in availableModels in your settings file . This setting also restricts the picker to the listed entries, so include every alias you want to keep available: { "availableModels" : [ "opus" , "sonnet" , "haiku" , "anthropic.claude-haiku-4-5" ] } Entries with the anthropic. prefix are added as custom picker options and routed to Mantle. Replace anthropic.claude-haiku-4-5 with the model ID your account has been granted. See Restrict model selection for how availableModels interacts with other model settings. When both providers are active, /status shows Amazon Bedrock + Amazon Bedrock (Mantle) . ​ Route Mantle through a gateway If your organization routes model traffic through a centralized LLM gateway that injects AWS credentials server-side, disable client-side authentication so Claude Code sends requests without SigV4 signatures or x-api-key headers: export CLAUDE_CODE_USE_MANTLE = 1 export CLAUDE_CODE_SKIP_MANTLE_AUTH = 1 export ANTHROPIC_BEDROCK_MANTLE_BASE_URL = https :// your-gateway . example . com ​ Mantle environment variables These variables are specific to the Mantle endpoint. See Environment variables for the full list. Variable Purpose CLAUDE_CODE_USE_MANTLE Enable the Mantle endpoint. Set to 1 or true . ANTHROPIC_BEDROCK_MANTLE_BASE_URL Override the default Mantle endpoint URL CLAUDE_CODE_SKIP_MANTLE_AUTH Skip client-side authentication for proxy setups ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION Override AWS region for the Haiku-class model (shared with Bedrock) ​ Troubleshooting ​ Authentication loop with SSO and corporate proxies If browser tabs spawn repeatedly when using AWS SSO, remove the awsAuthRefresh setting from your settings file . This can occur when corporate VPNs or TLS inspection proxies interrupt the SSO browser flow. Claude Code treats the interrupted connection as an authentication failure, re-runs awsAuthRefresh , and loops indefinitely. If your network environment interferes with automatic browser-based SSO flows, use aws sso login manually before starting Claude Code instead of relying on awsAuthRefresh . ​ Region issues 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 ID Claude Code uses the Bedrock Invoke API and does not support the Converse API. ​ Mantle endpoint errors If /status does not show Amazon Bedrock (Mantle) after you set CLAUDE_CODE_USE_MANTLE , the variable is not reaching the process. Confirm it is exported in the shell where you launched claude , or set it in the env block of your settings file . A 403 from the Mantle endpoint with valid credentials means your AWS account has not been granted access to the model you requested. Contact your AWS account team to request access. A 400 that names the model ID means that model is not served on Mantle. Mantle has its own model lineup separate from the standard Bedrock catalog, so inference profile IDs such as us.anthropic.claude-sonnet-4-6 will not work. Use a Mantle-format ID, or enable both endpoints so Claude Code routes each request to the endpoint where the model is available. ​ Additional resources Bedrock documentation Bedrock pricing Bedrock inference profiles Bedrock token burndown and quotas Claude Code on Amazon Bedrock: Quick Setup Guide Claude Code Monitoring Implementation (Bedrock) Was this page helpful? Yes No Overview Claude Platform on AWS Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Platforms and integrations Use Claude Code with Chrome (beta) Getting started Overview Quickstart Changelog Core concepts How Claude Code works Extend Claude Code Explore the .claude directory Explore the context window Use Claude Code Store instructions and memories Permission modes Common workflows Best practices Platforms and integrations Overview Remote Control Claude Code on the web Claude Code on desktop Chrome extension (beta) Computer use (preview) Visual Studio Code JetBrains IDEs Code review & CI/CD Claude Code in Slack Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. Claude Code integrates with the Claude in Chrome browser extension to give you browser automation capabilities from the CLI or the VS Code extension . Build your code, then test and debug in the browser without switching contexts. Claude opens new tabs for browser tasks and shares your browser’s login state, so it can access any site you’re already signed into. Browser actions run in a visible Chrome window in real time. When Claude encounters a login page or CAPTCHA, it pauses and asks you to handle it manually. Chrome integration is in beta and currently works with Google Chrome and Microsoft Edge. It is not yet supported on Brave, Arc, or other Chromium-based browsers. WSL (Windows Subsystem for Linux) is also not supported. ​ Capabilities With Chrome connected, you can chain browser actions with coding tasks in a single workflow: Live debugging : read console errors and DOM state directly, then fix the code that caused them Design verification : build a UI from a Figma mock, then open it in the browser to verify it matches Web app testing : test form validation, check for visual regressions, or verify user flows Authenticated web apps : interact with Google Docs, Gmail, Notion, or any app you’re logged into without API connectors Data extraction : pull structured information from web pages and save it locally Task automation : automate repetitive browser tasks like data entry, form filling, or multi-site workflows Session recording : record browser interactions as GIFs to document or share what happened ​ Prerequisites Before using Claude Code with Chrome, you need: Google Chrome or Microsoft Edge browser Claude in Chrome extension version 1.0.36 or higher, available in the Chrome Web Store for both browsers Claude Code version 2.0.73 or higher A direct Anthropic plan (Pro, Max, Team, or Enterprise) Chrome integration is not available through third-party providers like Amazon Bedrock, Google Cloud Vertex AI, or Microsoft Foundry. If you access Claude exclusively through a third-party provider, you need a separate claude.ai account to use this feature. ​ Get started in the CLI 1 Launch Claude Code with Chrome Start Claude Code with the --chrome flag: claude --chrome You can also enable Chrome from within an existing session by running /chrome . 2 Ask Claude to use the browser This example navigates to a page, interacts with it, and reports what it finds, all from your terminal or editor: Go to code.claude.com/docs, click on the search box, type "hooks", and tell me what results appear Run /chrome at any time to check the connection status, manage permissions, or reconnect the extension. For VS Code, see browser automation in VS Code . ​ Enable Chrome by default To avoid passing --chrome each session, run /chrome and select “Enabled by default”. In the VS Code extension , Chrome is available whenever the Chrome extension is installed. No additional flag is needed. Enabling Chrome by default in the CLI increases context usage since browser tools are always loaded. If you notice increased context consumption, disable this setting and use --chrome only when needed. ​ Manage site permissions Site-level permissions are inherited from the Chrome extension. Manage permissions in the Chrome extension settings to control which sites Claude can browse, click, and type on. ​ Example workflows These examples show common ways to combine browser actions with coding tasks. Run /mcp and select claude-in-chrome to see the full list of available browser tools. ​ Test a local web application When developing a web app, ask Claude to verify your changes work correctly: I just updated the login form validation. Can you open localhost:3000, try submitting the form with invalid data, and check if the error messages appear correctly? Claude navigates to your local server, interacts with the form, and reports what it observes. ​ Debug with console logs Claude can read console output to help diagnose problems. Tell Claude what patterns to look for rather than asking for all console output, since logs can be verbose: Open the dashboard page and check the console for any errors when the page loads. Claude reads the console messages and can filter for specific patterns or error types. ​ Automate form filling Speed up repetitive data entry tasks: I have a spreadsheet of customer contacts in contacts.csv. For each row, go to the CRM at crm.example.com, click "Add Contact", and fill in the name, email, and phone fields. Claude reads your local file, navigates the web interface, and enters the data for each record. ​ Draft content in Google Docs Use Claude to write directly in your documents without API setup: Draft a project update based on the recent commits and add it to my Google Doc at docs.google.com/document/d/abc123 Claude opens the document, clicks into the editor, and types the content. This works with any web app you’re logged into: Gmail, Notion, Sheets, and more. ​ Extract data from web pages Pull structured information from websites: Go to the product listings page and extract the name, price, and availability for each item. Save the results as a CSV file. Claude navigates to the page, reads the content, and compiles the data into a structured format. ​ Run multi-site workflows Coordinate tasks across multiple websites: Check my calendar for meetings tomorrow, then for each meeting with an external attendee, look up their company website and add a note about what they do. Claude works across tabs to gather information and complete the workflow. ​ Record a demo GIF Create shareable recordings of browser interactions: Record a GIF showing how to complete the checkout flow, from adding an item to the cart through to the confirmation page. Claude records the interaction sequence and saves it as a GIF file. ​ Troubleshooting ​ Extension not detected If Claude Code shows “Chrome extension not detected”: Verify the Chrome extension is installed and enabled in chrome://extensions Verify Claude Code is up to date by running claude --version Check that Chrome is running Run /chrome and select “Reconnect extension” to re-establish the connection If the issue persists, restart both Claude Code and Chrome The first time you enable Chrome integration, Claude Code installs a native messaging host configuration file. Chrome reads this file on startup, so if the extension isn’t detected on your first attempt, restart Chrome to pick up the new configuration. If the connection still fails, verify the host configuration file exists at: For Chrome: macOS : ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json Linux : ~/.config/google-chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json Windows : check HKCU\Software\Google\Chrome\NativeMessagingHosts\ in the Windows Registry For Edge: macOS : ~/Library/Application Support/Microsoft Edge/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json Linux : ~/.config/microsoft-edge/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json Windows : check HKCU\Software\Microsoft\Edge\NativeMessagingHosts\ in the Windows Registry ​ Browser not responding If Claude’s browser commands stop working: Check if a modal dialog (alert, confirm, prompt) is blocking the page. JavaScript dialogs block browser events and prevent Claude from receiving commands. Dismiss the dialog manually, then tell Claude to continue. Ask Claude to create a new tab and try again Restart the Chrome extension by disabling and re-enabling it in chrome://extensions ​ Connection drops during long sessions The Chrome extension’s service worker can go idle during extended sessions, which breaks the connection. If browser tools stop working after a period of inactivity, run /chrome and select “Reconnect extension”. ​ Windows-specific issues On Windows, you may encounter: Named pipe conflicts (EADDRINUSE) : if another process is using the same named pipe, restart Claude Code. Close any other Claude Code sessions that might be using Chrome. Native messaging host errors : if the native messaging host crashes on startup, try reinstalling Claude Code to regenerate the host configuration. ​ Common error messages These are the most frequently encountered errors and how to resolve them: Error Cause Fix ”Browser extension is not connected” Native messaging host cannot reach the extension Restart Chrome and Claude Code, then run /chrome to reconnect ”Extension not detected” Chrome extension is not installed or is disabled Install or enable the extension in chrome://extensions ”No tab available” Claude tried to act before a tab was ready Ask Claude to create a new tab and retry ”Receiving end does not exist” Extension service worker went idle Run /chrome and select “Reconnect extension” ​ See also Computer use : control native macOS apps when a task can’t be done in a browser Use Claude Code in VS Code : browser automation in the VS Code extension CLI reference : command-line flags including --chrome Common workflows : more ways to use Claude Code Data and privacy : how Claude Code handles your data Getting started with Claude in Chrome : full documentation for the Chrome extension, including shortcuts, scheduling, and permissions Was this page helpful? Yes No Desktop changelog Computer use (preview) Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Claude Code on desktop Schedule recurring tasks in Claude Code Desktop Getting started Overview Quickstart Changelog Core concepts How Claude Code works Extend Claude Code Explore the .claude directory Explore the context window Use Claude Code Store instructions and memories Permission modes Common workflows Best practices Platforms and integrations Overview Remote Control Claude Code on the web Claude Code on desktop Get started Reference Scheduled tasks Desktop changelog Chrome extension (beta) Computer use (preview) Visual Studio Code JetBrains IDEs Code review & CI/CD Claude Code in Slack Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. Scheduled tasks start a new session automatically at a time and frequency you choose. Use them for recurring work like daily code reviews, dependency update checks, or morning briefings that pull from your calendar and inbox. The Desktop app’s Routines page lets you create both local scheduled tasks and remote routines . A local task runs on your machine with direct access to your files and tools, but only fires while the app is open and your computer is awake. A remote routine runs on Anthropic-managed cloud infrastructure even when your computer is off, and can also fire on API calls or GitHub events. This page covers local scheduled tasks; for remote routines and their trigger options, see Routines . ​ Compare scheduling options Claude Code offers three ways to schedule recurring or one-off work: Cloud Desktop /loop Runs on Anthropic cloud Your machine Your machine Requires machine on No Yes Yes Requires open session No No Yes Persistent across restarts Yes Yes Restored on --resume if unexpired Access to local files No (fresh clone) Yes Yes MCP servers Connectors configured per task Config files and connectors Inherits from session Permission prompts No (runs autonomously) Configurable per task Inherits from session Customizable schedule Via /schedule in the CLI Yes Yes Minimum interval 1 hour 1 minute 1 minute Use cloud tasks for work that should run reliably without your machine. Use Desktop tasks when you need access to local files and tools. Use /loop for quick polling during a session. By default, scheduled tasks run against whatever state your working directory is in, including uncommitted changes. Enable the worktree toggle when creating the task to give each run its own isolated Git worktree, the same way parallel sessions work. ​ Create a scheduled task Click Routines in the sidebar, then click New routine and choose Local . Configure these fields: Field Description Name Identifier for the task. Converted to lowercase kebab-case and used as the folder name on disk. Must be unique across your tasks. Description Short summary shown in the task list. Instructions What Claude should do when the task runs. Write this the same way you’d write any message in the prompt box. The instructions input includes pickers for the permission mode and model, and below it you select the working folder and whether to run in an isolated worktree. Schedule How often the task runs. See schedule options below. A folder is required before you can save the task. If you haven’t trusted that folder yet, Desktop prompts you to trust it before saving. You can also create a task by describing what you want in any session. For example, “set up a daily code review that runs every morning at 9am” creates a recurring task, and “remind me at 3pm tomorrow to check the deploy” creates a one-time task that disables itself after it fires. ​ Schedule options Pick a preset from the Schedule control: Manual : no schedule, only runs when you click Run now . Useful for saving a prompt you trigger on demand Hourly : runs every hour Daily : shows a time picker, defaults to 9:00 AM local time Weekdays : same as Daily but skips Saturday and Sunday Weekly : shows a time picker and a day picker For intervals the picker doesn’t offer, such as every 15 minutes, the first of each month, or a single run at a specific future time, ask Claude in any Desktop session to set the schedule. Use plain language; for example, “schedule a task to run all the tests every 6 hours.” ​ How scheduled tasks run Scheduled tasks run on your machine. Desktop checks the schedule every minute while the app is open and starts a fresh session when a task is due, independent of any manual sessions you have open. Each task gets a small delay of a few minutes after the scheduled time to stagger API traffic. The delay is deterministic: the same task always starts at the same offset. When a task fires, you get a desktop notification and a new session appears under a Scheduled section in the sidebar. Open it to see what Claude did, review changes, or respond to permission prompts. The session works like any other: Claude can edit files, run commands, create commits, and open pull requests. Tasks only run while the desktop app is running and your computer is awake. If your computer sleeps through a scheduled time, the run is skipped. To prevent idle-sleep, enable Keep computer awake in Settings under Desktop app → General . Closing the laptop lid still puts it to sleep. For tasks that need to run even when your computer is off, or that should trigger on an API call or GitHub event, create a remote routine instead. ​ Missed runs When the app starts or your computer wakes, Desktop checks whether each task missed any runs in the last seven days. If it did, Desktop starts exactly one catch-up run for the most recently missed time and discards anything older. A daily task that missed six days runs once on wake. Desktop shows a notification when a catch-up run starts. Keep this in mind when writing prompts. A task scheduled for 9am might run at 11pm if your computer was asleep all day. If timing matters, add guardrails to the prompt itself, for example: “Only review today’s commits. If it’s after 5pm, skip the review and just post a summary of what was missed.” ​ Permissions for scheduled tasks Each task has its own permission mode, which you set when creating or editing the task. Allow rules from ~/.claude/settings.json also apply to scheduled task sessions. If a task runs in Ask mode and needs to run a tool it doesn’t have permission for, the run stalls until you approve it. The session stays open in the sidebar so you can answer later. To avoid stalls, click Run now after creating a task, watch for permission prompts, and select “always allow” for each one. Future runs of that task auto-approve the same tools without prompting. You can review and revoke these approvals from the task’s detail page. ​ Manage scheduled tasks Click a task in the Routines list to open its detail page. From here you can: Run now : start the task immediately without waiting for the next scheduled time Status : toggle between Active and Paused to pause or resume scheduled runs without deleting the task Edit : change the instructions, schedule, folder, or other settings Review history : see every past run, including skipped runs. Hover a skipped entry to see why: your computer was asleep, the previous run was still in progress, or other scheduled tasks were already running. Click Show more to load older entries. Review allowed permissions : see and revoke saved tool approvals for this task from the Always allowed panel Delete : remove the task and archive all sessions it created. An Also delete files on disk checkbox appears in the confirmation dialog; check it to also remove the task’s SKILL.md file and associated data from ~/.claude/scheduled-tasks/ . You can also list, create, edit, and pause tasks by asking Claude in any Desktop session. For example, “pause my dependency-audit task” or “show me my scheduled tasks.” To delete a task, use the Delete button on its detail page. A scheduled task can also modify its own schedule or prompt from within a running session using the update_scheduled_task MCP tool. This lets a task reschedule itself based on what it finds, for example, rescheduling a code review to run earlier when it detects a release branch has been created. To edit a task’s prompt on disk, open ~/.claude/scheduled-tasks//SKILL.md (or under CLAUDE_CONFIG_DIR if set). The file uses YAML frontmatter for name and description , with the prompt as the body. Changes take effect on the next run. Schedule, folder, model, and enabled state are not in this file: change them through the Edit form or ask Claude. ​ Related resources Routines : run tasks on Anthropic-managed infrastructure on a schedule, via API call, or in response to GitHub events, even when your computer is off Run prompts on a schedule : session-scoped scheduling with /loop in the CLI Claude Code GitHub Actions : run Claude on a schedule in CI instead of on your machine Use Claude Code Desktop : the full Desktop app guide Was this page helpful? Yes No Reference Desktop changelog Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Claude Code on the web Automate work with routines Getting started Overview Quickstart Changelog Core concepts How Claude Code works Extend Claude Code Explore the .claude directory Explore the context window Use Claude Code Store instructions and memories Permission modes Common workflows Best practices Platforms and integrations Overview Remote Control Claude Code on the web Get started Reference Routines Plan in the cloud Ultrareview Claude Code on desktop Chrome extension (beta) Computer use (preview) Visual Studio Code JetBrains IDEs Code review & CI/CD Claude Code in Slack Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. Routines are in research preview. Behavior, limits, and the API surface may change. A routine is a saved Claude Code configuration: a prompt, one or more repositories, and a set of connectors , packaged once and run automatically. Routines execute on Anthropic-managed cloud infrastructure, so they keep working when your laptop is closed. Each routine can have one or more triggers attached to it: Scheduled : run on a recurring cadence like hourly, nightly, or weekly, or once at a specific future time API : trigger on demand by sending an HTTP POST to a per-routine endpoint with a bearer token GitHub : run automatically in response to repository events such as pull requests or releases A single routine can combine triggers. For example, a PR review routine can run nightly, trigger from a deploy script, and also react to every new PR. Routines are available on Pro, Max, Team, and Enterprise plans with Claude Code on the web enabled. Create and manage them at claude.ai/code/routines , or from the CLI with /schedule . Team and Enterprise admins can disable routines for all members with the Routines toggle at claude.ai/admin-settings/claude-code . When disabled, existing routines stop running and members cannot create new ones. This page covers creating a routine, configuring each trigger type, managing runs, and how usage limits apply. ​ Example use cases Each example pairs a trigger type with the kind of work routines are suited to: unattended, repeatable, and tied to a clear outcome. Backlog maintenance. A schedule trigger runs every weeknight against your issue tracker via a connector. The routine reads issues opened since the last run, applies labels, assigns owners based on the area of code referenced, and posts a summary to Slack so the team starts the day with a groomed queue. Alert triage. Your monitoring tool calls the routine’s API endpoint when an error threshold is crossed, passing the alert body as text . The routine pulls the stack trace, correlates it with recent commits in the repository, and opens a draft pull request with a proposed fix and a link back to the alert. On-call reviews the PR instead of starting from a blank terminal. Bespoke code review. A GitHub trigger runs on pull_request.opened . The routine applies your team’s own review checklist, leaves inline comments for security, performance, and style issues, and adds a summary comment so human reviewers can focus on design instead of mechanical checks. Deploy verification. Your CD pipeline calls the routine’s API endpoint after each production deploy. The routine runs smoke checks against the new build, scans error logs for regressions, and posts a go or no-go to the release channel before the deploy window closes. Docs drift. A schedule trigger runs weekly. The routine scans merged PRs since the last run, flags documentation that references changed APIs, and opens update PRs against the docs repository for an editor to review. Library port. A GitHub trigger runs on pull_request.closed filtered to merged PRs in one SDK repository. The routine ports the change to a parallel SDK in another language and opens a matching PR, keeping the two libraries in step without a human re-implementing each change. The sections below walk through creating a routine and configuring each of these trigger types. ​ Create a routine Create a routine from the web at claude.ai/code/routines , from the Desktop app, or from the CLI. All three surfaces write to the same cloud account, so a routine you create in one shows up in the others immediately. In the Desktop app, click Routines in the sidebar, then New routine , and choose Remote ; choosing Local instead creates a Desktop scheduled task , which runs on your machine rather than in the cloud. The creation form sets up the routine’s prompt, repositories, environment, connectors, and triggers. Routines run autonomously as full Claude Code cloud sessions: there is no permission-mode picker and no approval prompts during a run. The session can run shell commands, use skills committed to the cloned repository, and call any connectors you include. What a routine can reach is determined by the repositories you select and their branch-push setting, the environment’s network access and variables, and the connectors you include. Scope each of those to what the routine actually needs. Routines belong to your individual claude.ai account. They are not shared with teammates, and they count against your account’s daily run allowance. Anything a routine does through your connected GitHub identity or connectors appears as you: commits and pull requests carry your GitHub user, and Slack messages, Linear tickets, or other connector actions use your linked accounts for those services. ​ Create from the web 1 Open the creation form Visit claude.ai/code/routines and click New routine . 2 Name the routine and write the prompt Give the routine a descriptive name and write the prompt Claude runs each time. The prompt is the most important part: the routine runs autonomously, so the prompt must be self-contained and explicit about what to do and what success looks like. The prompt input includes a model selector. Claude uses the selected model on every run. 3 Select repositories Add one or more GitHub repositories for Claude to work in. Each repository is cloned at the start of a run, starting from the default branch. Claude creates claude/ -prefixed branches for its changes. 4 Select an environment Pick a cloud environment for the routine. Environments control what the cloud session has access to: Network access : set the level of internet access available during each run Environment variables : provide API keys, tokens, or other secrets Claude can use Setup script : install dependencies and tools the routine needs. The result is cached , so the script doesn’t re-run on every session A Default environment is provided with Trusted network access, which allows the default set of package registries, cloud provider APIs, container registries, and common development domains, but blocks everything else. If your routine needs to reach your own services or a domain outside that list, edit the environment’s network access before running. To use a separate environment, create one first. 5 Select a trigger Under Select a trigger , choose how the routine starts. You can pick one trigger type or combine several. Schedule GitHub event API Pick a preset frequency for a recurring run, or schedule a single one-off run at a specific timestamp. See Add a schedule trigger for timezone handling, stagger, custom cron intervals, and one-off runs. Select the repository, the event to react to, and optional filters. See Add a GitHub trigger for the full list of supported events and filter fields. Select API here, then save the routine. The URL and token are generated after the routine is saved, since they depend on the routine ID. See Add an API trigger to copy the URL and generate a token. 6 Review connectors and permissions The Connectors and Permissions tabs at the bottom of the form control what the routine can reach. Under Connectors, all of your connected MCP connectors are included by default. Remove any the routine doesn’t need. Claude can use every tool from an included connector, including writes, without asking for permission during a run. Under Permissions, enable Allow unrestricted branch pushes for any repository where Claude should be able to push to existing branches instead of only claude/ -prefixed ones. 7 Create the routine Click Create . The routine appears in the list and runs the next time one of its triggers matches. To start a run immediately, click Run now on the routine’s detail page. Each run creates a new session alongside your other sessions, where you can see what Claude did, review changes, and create a pull request. ​ Create from the CLI Run /schedule in any session to create a scheduled routine conversationally. You can also pass a description directly, for a recurring routine like /schedule daily PR review at 9am or a one-off like /schedule clean up feature flag in one week . Claude walks through the same information the web form collects, then saves the routine to your account. /schedule in the CLI creates scheduled routines only. To add an API or GitHub trigger, edit the routine on the web at claude.ai/code/routines . The CLI also supports managing existing routines. Run /schedule list to see all routines, /schedule update to change one, or /schedule run to trigger it immediately. ​ Configure triggers A routine starts when one of its triggers matches. You can attach any combination of schedule, API, and GitHub triggers to the same routine, and add or remove them at any time from the Select a trigger section of the routine’s edit form. ​ Add a schedule trigger A schedule trigger runs the routine on a recurring cadence, or once at a specific future time. Pick a preset frequency in the Select a trigger section: hourly, daily, weekdays, or weekly. Times are entered in your local zone and converted automatically, so the routine runs at that wall-clock time regardless of where the cloud infrastructure is located. Runs may start a few minutes after the scheduled time due to stagger. The offset is consistent for each routine. For a custom interval such as every two hours or the first of each month, pick the closest preset in the form, then run /schedule update in the CLI to set a specific cron expression. The minimum interval is one hour; expressions that run more frequently are rejected. ​ Schedule a one-off run A one-off schedule fires the routine a single time at a specific timestamp. Use it to remind yourself later in the week, to open a cleanup PR after a rollout finishes, or to kick off a follow-up task when an upstream change lands. After the routine fires, it auto-disables and the web UI marks it as Ran . To run it again, edit the routine and set a new one-off time. Create a one-off run from the CLI by describing the time in natural language. Claude resolves the phrase against the current time and confirms the absolute timestamp before saving. /schedule tomorrow at 9am, summarize yesterday's merged PRs /schedule in 2 weeks, open a cleanup PR that removes the feature flag The same local-to-UTC conversion as recurring schedules applies to one-off timestamps. One-off runs do not count against the daily routine run cap. They consume your plan’s regular subscription usage like any other session. See Usage and limits for details. ​ Add an API trigger An API trigger gives a routine a dedicated HTTP endpoint. POSTing to the endpoint with the routine’s bearer token starts a new session and returns a session URL. Use this to wire Claude Code into alerting systems, deploy pipelines, internal tools, or anywhere you can make an authenticated HTTP request. API triggers are added to an existing routine from the web. The CLI cannot currently create or revoke tokens. 1 Open the routine for editing Go to claude.ai/code/routines , click the routine you want to trigger via API, then click the pencil icon to open Edit routine . 2 Add an API trigger Scroll to the Select a trigger section below the Instructions box, click Add another trigger , and choose API . 3 Copy the URL and generate a token The modal shows the URL for this routine along with a sample curl command. Copy the URL, then click Generate token and copy the token immediately. The token is shown once and cannot be retrieved later, so store it somewhere secure such as your alerting tool’s secret store. 4 Call the endpoint Send the token in the Authorization: Bearer header when you POST to the URL. The Trigger a routine section below shows a complete example. Each routine has its own token, scoped to triggering that routine only. To rotate or revoke it, return to the same modal and click Regenerate or Revoke . ​ Trigger a routine Send a POST request to the /fire endpoint with the bearer token in the Authorization header. The request body accepts an optional text field for run-specific context such as an alert body or a failing log, passed to the routine alongside its saved prompt. The value is freeform text and is not parsed: if you send JSON or another structured payload, the routine receives it as a literal string. The example below triggers a routine from a shell: curl -X POST https://api.anthropic.com/v1/claude_code/routines/trig_01ABCDEFGHJKLMNOPQRSTUVW/fire \ -H "Authorization: Bearer sk-ant-oat01-xxxxx" \ -H "anthropic-beta: experimental-cc-routine-2026-04-01" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{"text": "Sentry alert SEN-4521 fired in prod. Stack trace attached."}' A successful request returns a JSON body with the new session ID and URL: { "type" : "routine_fire" , "claude_code_session_id" : "session_01HJKLMNOPQRSTUVWXYZ" , "claude_code_session_url" : "https://claude.ai/code/session_01HJKLMNOPQRSTUVWXYZ" } Open the session URL in a browser to watch the run in real time, review changes, or continue the conversation manually. The /fire endpoint ships under the experimental-cc-routine-2026-04-01 beta header. Request and response shapes, rate limits, and token semantics may change while the feature is in research preview. Breaking changes ship behind new dated beta header versions, and the two most recent previous header versions continue to work so that callers have time to migrate. ​ API reference For the full API reference, including all error responses, validation rules, and field limits, see Trigger a routine via API in the Claude Platform documentation. The /fire endpoint is available to claude.ai users only and is not part of the Claude Platform API surface. ​ Add a GitHub trigger A GitHub trigger starts a new session automatically when a matching event occurs on a connected repository. Each matching event starts its own session. During the research preview, GitHub webhook events are subject to per-routine and per-account hourly caps. Events beyond the limit are dropped until the window resets. See your current limits at claude.ai/code/routines . GitHub triggers are configured from the web UI only. 1 Open the routine for editing Go to claude.ai/code/routines , click the routine, then click the pencil icon to open Edit routine . 2 Add a GitHub event trigger Scroll to the Select a trigger section, click Add another trigger , and choose GitHub event . 3 Install the Claude GitHub App The Claude GitHub App must be installed on the repository you want to subscribe to. The trigger setup prompts you to install it if it isn’t already. Running /web-setup in the CLI grants repository access for cloning, but it does not install the Claude GitHub App and does not enable webhook delivery. GitHub triggers require installing the Claude GitHub App, which the trigger setup prompts you to do. 4 Configure the trigger Select the repository, choose an event from the supported events list, and optionally add filters. Save the trigger. ​ Supported events GitHub triggers can subscribe to either of the following event categories. Within each category you can pick a specific action, such as pull_request.opened , or react to all actions in the category. Event Triggers when Pull request A PR is opened, closed, assigned, labeled, synchronized, or otherwise updated Release A release is created, published, edited, or deleted ​ Filter pull requests Use filters to narrow which pull requests start a new session. All filter conditions must match for the routine to trigger. The available filter fields are: Filter Matches Author PR author’s GitHub username Title PR title text Body PR description text Base branch Branch the PR targets Head branch Branch the PR comes from Labels Labels applied to the PR Is draft Whether the PR is in draft state Is merged Whether the PR has been merged Each filter pairs a field with an operator: equals, contains, starts with, is one of, is not one of, or matches regex. The matches regex operator tests the entire field value, not a substring within it. To match any title containing hotfix , write .*hotfix.* . Without the surrounding .* , the filter matches only a title that is exactly hotfix with nothing before or after. For literal substring matching without regex syntax, use the contains operator instead. A few example filter combinations: Auth module review : base branch main , head branch contains auth-provider . Sends any PR that touches authentication to a focused reviewer. Ready-for-review only : is draft is false . Skips drafts so the routine only runs when the PR is ready for review. Label-gated backport : labels include needs-backport . Triggers a port-to-another-branch routine only when a maintainer tags the PR. ​ How sessions map to events Each matching GitHub event starts a new session. Session reuse across events is not available for GitHub-triggered routines, so two PR updates produce two independent sessions. ​ Manage routines Click a routine in the list to open its detail page. The detail page shows the routine’s repositories, connectors, prompt, schedule, API tokens, GitHub triggers, and a list of past runs. ​ View and interact with runs Click any run to open it as a full session. From there you can see what Claude did, review changes, create a pull request, or continue the conversation. Each run session works like any other session: use the dropdown menu next to the session title to rename, archive, or delete it. A green status in the run list means the session started and exited without an infrastructure error. It does not mean the task in your prompt succeeded. Open the run to read the transcript and confirm what Claude actually did. Blocked network requests, missing connector tools, and task-level failures all surface there rather than in the status indicator. ​ Edit and control routines From the routine detail page you can: Click Run now to start a run immediately without waiting for the next scheduled time. Use the toggle in the Repeats section to pause or resume the schedule. Paused routines keep their configuration but don’t run until you re-enable them. Click the pencil icon to open Edit routine and change the name, prompt, repositories, environment, connectors, or any of the routine’s triggers. The Select a trigger section is where you add or remove schedules, API tokens, and GitHub event triggers. Click the delete icon to remove the routine. Past sessions created by the routine remain in your session list. ​ Repositories and branch permissions Routines need GitHub access to clone repositories. When you create a routine from the CLI with /schedule , Claude checks whether your account has GitHub connected and prompts you to run /web-setup if it doesn’t. See GitHub authentication options for the two ways to grant access. Each repository you add is cloned on every run. Claude starts from the repository’s default branch unless your prompt specifies otherwise. By default, Claude can only push to branches prefixed with claude/ . This prevents routines from accidentally modifying protected or long-lived branches. To remove this restriction for a specific repository, enable Allow unrestricted branch pushes for that repository when creating or editing the routine. ​ Connectors Routines can use your connected MCP connectors to read from and write to external services during each run. For example, a routine that triages support requests might read from a Slack channel and create issues in Linear. Connectors are the claude.ai integrations on your account. MCP servers you added locally in the CLI with claude mcp add are stored on your machine rather than your claude.ai account, so they do not appear in the connectors list. To use one of those servers in a routine, add it as a connector at claude.ai/customize/connectors , or declare it in a committed .mcp.json so it is part of the cloned repository. When you create a routine, all of your currently connected connectors are included by default. Remove any that aren’t needed to limit which tools Claude has access to during the run. You can also add connectors directly from the routine form. To manage or add connectors outside of the routine form, visit Settings > Connectors on claude.ai or use /schedule update in the CLI. ​ Environments and network access Each routine runs in a cloud environment that controls network access, environment variables, and setup scripts. The routine inherits the environment’s network policy on every run. The Default environment uses Trusted network access: the default allowlist of package registries, cloud provider APIs, container registries, and common development domains is reachable, but arbitrary domains are not. Outbound requests to other hosts fail with 403 and x-deny-reason: host_not_allowed . MCP connector traffic is routed through Anthropic’s servers, so the connectors you add to the routine work without adding their hosts to Allowed domains . Remove any connectors you don’t need under Connectors . To allow additional domains: 1 Open the routine for editing On the routine’s detail page, click the pencil icon to open Edit routine . 2 Open the environment selector Below the Instructions box, select the cloud icon showing your environment’s name, such as Default . 3 Open the environment settings Hover over the environment in the list and click the settings icon that appears on the right. 4 Change the network access level In the Update cloud environment dialog, change Network access to Custom and enter your domains in Allowed domains . Check Also include default list of common package managers to keep the default allowlist alongside your custom domains. Select Full instead for unrestricted access. 5 Save Click Save changes . The new policy applies from the next run. See Network access for details on access levels and the default allowlist. ​ Usage and limits Routines draw down subscription usage the same way interactive sessions do. In addition to the standard subscription limits, routines have a daily cap on how many runs can start per account. See your current consumption and remaining daily routine runs at claude.ai/code/routines or claude.ai/settings/usage . When a routine hits the daily cap or your subscription usage limit, organizations with extra usage enabled can keep running routines on metered overage. Without extra usage, additional runs are rejected until the window resets. Enable extra usage from Settings > Billing on claude.ai. One-off runs do not count against the daily routine cap. They draw down your regular subscription usage like any other session, but they are exempt from the per-account daily routine run allowance. ​ Troubleshooting ​ ”Routines are disabled by your organization’s policy” Your Team or Enterprise admin has likely turned off the Routines toggle at claude.ai/admin-settings/claude-code . This is a server-side organization setting, so it cannot be overridden from your local configuration. Contact your admin to request that routines be enabled for your organization. ​ Related resources /loop and in-session scheduling : schedule local tasks within an open CLI session Desktop scheduled tasks : local scheduled tasks that run on your machine with access to local files Cloud environment : configure the runtime environment for cloud sessions MCP connectors : connect external services like Slack, Linear, and Google Drive GitHub Actions : run Claude in your CI pipeline on repository events Was this page helpful? Yes No Reference Plan in the cloud Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Deployment Development containers Setup and access Administration overview Advanced setup Authentication Server-managed settings Auto mode Deployment Overview Amazon Bedrock Claude Platform on AWS Google Vertex AI Microsoft Foundry Network configuration LLM gateway Development containers Usage and costs Monitoring Costs Track team usage with analytics Plugin distribution Create and distribute a plugin marketplace Plugin dependency versions Security and data Security Data usage Zero data retention Adoption Communications kit Champion kit Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. A development container , or dev container, lets you define an identical, isolated environment that every engineer on your team can run. With Claude Code installed in that container, commands Claude runs execute inside it rather than on the host machine, while edits to your project files appear in your local repository as you work. This page covers installing Claude Code in a dev container and the configuration topics that follow. Each topic is self-contained, so jump to the ones that match what you need to set up: Persist authentication and settings across rebuilds Enforce organization policy Restrict network egress Run without permission prompts While the dev container provides substantial protections, no system is completely immune to all attacks. When executed with --dangerously-skip-permissions , dev containers do not prevent a malicious project from exfiltrating anything accessible inside the container, including the Claude Code credentials stored in ~/.claude . Only use dev containers when developing with trusted repositories, and monitor Claude’s activities. Avoid mounting host secrets such as ~/.ssh or cloud credential files into the container; prefer repository-scoped or short-lived tokens. How dev containers work with your editor A dev container runs as a Docker container, either on your machine or on a cloud host such as GitHub Codespaces. An editor that supports the Dev Containers spec, such as VS Code, GitHub Codespaces, a JetBrains IDE, or Cursor, connects to that container: you browse and edit files in the editor as usual, but the integrated terminal, language servers, and build tools all run inside the container rather than on your host. Editors without dev container support, such as plain Vim, are not part of this workflow. Claude Code runs inside the container, so it sees the same files, dependencies, and tools as the rest of your project’s toolchain. In VS Code you can use either the Claude Code extension panel or run claude in the integrated terminal; both run inside the container and share the same ~/.claude configuration. ​ Add Claude Code to your dev container Claude Code installs into any dev container through the Claude Code Dev Container Feature . The settings work with any tool that supports the Dev Containers spec, such as VS Code, GitHub Codespaces, or JetBrains IDEs. The steps below use VS Code as an example. When you open the container in VS Code or Codespaces, the feature also adds the Claude Code VS Code extension; other editors ignore that part. New to dev containers? The VS Code Dev Containers tutorial walks through installing Docker, the extension, and opening your first container. For a fuller hardened example with a firewall and persistent volumes, see Try the reference container . 1 Create or update devcontainer.json Save the following as .devcontainer/devcontainer.json in your repository, or add the features block to your existing file. The version tag at the end, such as :1.0 , pins the feature’s install script, not the Claude Code release. The feature installs the latest Claude Code, and Claude Code auto-updates itself inside the container by default. To pin the CLI version or disable auto-update, see Enforce organization policy . .devcontainer/devcontainer.json { "image" : "mcr.microsoft.com/devcontainers/base:ubuntu" , "features" : { "ghcr.io/anthropics/devcontainer-features/claude-code:1.0" : {} } } Replace the image line with your project’s base image or remove it if your existing file uses a Dockerfile. 2 Rebuild the container Open the VS Code Command Palette with Cmd+Shift+P on Mac or Ctrl+Shift+P on Windows and Linux, and run Dev Containers: Rebuild Container . For other tools, follow that tool’s rebuild action: see rebuilding in GitHub Codespaces , the Dev Containers CLI , or your IDE’s dev container documentation. 3 Sign in to Claude Code Open a terminal in the rebuilt container and run claude , then follow the authentication prompt. What you see at the authentication prompt depends on your provider: Anthropic : sign in through a browser with your Claude or Anthropic Console account Amazon Bedrock, Google Vertex AI, or Microsoft Foundry : Claude Code uses your cloud provider credentials, with no browser prompt For cloud providers, pass credentials into the container as environment variables through containerEnv , a Codespaces secret, or your cloud’s workload identity rather than mounting credential files from the host. See Amazon Bedrock , Google Vertex AI , or Microsoft Foundry for the credential chain Claude Code reads. See Choose your API provider to decide which path fits your organization. If the browser sign-in completes but the callback never reaches the container, copy the code shown in the browser and paste it at the Paste code here if prompted prompt in the terminal. This can happen when the editor’s port forwarding doesn’t route the localhost callback. ​ Persist authentication and settings across rebuilds By default, the container’s home directory is discarded on rebuild, so engineers must sign in again each time. Claude Code stores its authentication token, user settings, and session history under ~/.claude . Mount a named volume at that path to keep this state across rebuilds. The following example mounts a volume at the home directory of the node user: devcontainer.json "mounts" : [ "source=claude-code-config,target=/home/node/.claude,type=volume" ] Replace /home/node with the home directory of your container’s remoteUser . If you mount the volume somewhere other than ~/.claude , set CLAUDE_CONFIG_DIR to the mount path so Claude Code reads and writes there. To isolate state per project rather than sharing one volume across all repositories, include the ${devcontainerId} variable in the source name. The reference configuration uses source=claude-code-config-${devcontainerId} for this purpose. In GitHub Codespaces, ~/.claude persists across stopping and starting a codespace, but is still cleared when you rebuild the container, so the volume mount above applies there too. To carry authentication across codespaces, store ANTHROPIC_API_KEY or a CLAUDE_CODE_OAUTH_TOKEN from claude setup-token as a Codespaces secret ; Codespaces makes secrets available as environment variables inside the container automatically. ​ Enforce organization policy A dev container is a convenient place to apply organization policy, because the same image and configuration run on every engineer’s machine. Claude Code reads /etc/claude-code/managed-settings.json on Linux and applies it at the highest precedence in the settings hierarchy , so values there override anything an engineer sets in ~/.claude or the project’s .claude/ directory. Copy the file into place from your Dockerfile: Dockerfile RUN mkdir -p /etc/claude-code COPY managed-settings.json /etc/claude-code/managed-settings.json Because the Dockerfile lives in the repository, anyone with write access can change or remove this step. For policy that engineers cannot bypass by editing repository files, deliver managed settings through server-managed settings or your MDM instead. See managed settings files for the available keys and the other delivery paths. To set environment variables that apply to every Claude Code session in the container, add them to containerEnv in your devcontainer.json . The following example opts out of telemetry and error reporting and prevents Claude Code from auto-updating after install: devcontainer.json "containerEnv" : { "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC" : "1" , "DISABLE_AUTOUPDATER" : "1" } The Dev Container Feature always installs the latest Claude Code release. To pin a specific Claude Code version for reproducible builds, install it from your Dockerfile with npm install -g @anthropic-ai/claude-code@X.Y.Z instead of using the feature, and set DISABLE_AUTOUPDATER as shown above. For the full list of policy controls including permission rules, tool restrictions, and MCP server allowlists, see Set up Claude Code for your organization . To make MCP servers available inside the container, define them at project scope in a .mcp.json file at the repository root so they are checked in alongside your dev container configuration. Install any binaries that local stdio servers depend on in your Dockerfile, and add remote server domains to your network allowlist. ​ Restrict network egress You can limit the container’s outbound traffic to only the domains Claude Code needs. See Network access requirements for the inference and authentication domains, and Telemetry services for the optional telemetry and error reporting connections and how to disable them. The reference container includes an init-firewall.sh script that blocks all outbound traffic except the domains Claude Code and your development tools need. Running a firewall inside a container requires extra permissions, so the reference adds the NET_ADMIN and NET_RAW capabilities through runArgs . The firewall script and these capabilities are not required for Claude Code itself: you can leave them out and rely on your own network controls instead. ​ Run without permission prompts Because the container runs Claude Code as a non-root user and confines command execution to the container, you can pass --dangerously-skip-permissions for unattended operation. The CLI rejects this flag when launched as root, so confirm remoteUser is set to a non-root account. Skipping permission prompts removes your opportunity to review tool calls before they run. Claude can still modify any file in the bind-mounted workspace, which appears directly on your host, and reach anything the container’s network policy allows. Pair this flag with the network egress restrictions above to limit what a bypassed session can reach. If you want fewer prompts without disabling safety checks, consider auto mode instead, which has a classifier review actions before they run. To prevent engineers from using --dangerously-skip-permissions at all, set permissions.disableBypassPermissionsMode to "disable" in managed settings . ​ Try the reference container The anthropics/claude-code repository includes an example dev container that combines the CLI, the egress firewall, persistent volumes, and a Zsh-based shell. It is provided as a working example rather than a maintained base image; use it to see how the pieces fit together before applying them to your own configuration. 1 Install prerequisites Install VS Code and the Dev Containers extension . 2 Clone the reference Clone the Claude Code repository and open it in VS Code. 3 Reopen in container When prompted, click Reopen in Container , or run Dev Containers: Reopen in Container from the Command Palette. 4 Start Claude Code Once the container finishes building, open a terminal with Ctrl+` and run claude to sign in and start your first session. To use this configuration with your own project, copy the .devcontainer/ directory into your repository and adjust the Dockerfile for your toolchain, or return to Add Claude Code to your dev container to add only the feature to a setup you already have. The reference configuration consists of three files. None of them are required when you add Claude Code to your own dev container through the feature, but they show one way to combine the pieces. File Purpose devcontainer.json Volume mounts, runArgs capabilities, VS Code extensions, and containerEnv Dockerfile Base image, development tools, and the Claude Code install init-firewall.sh Blocks all outbound network traffic except the allowed domains ​ Next steps Once Claude Code is running in your dev container, the pages below cover the rest of an organization rollout: choosing an authentication path, delivering managed policy outside the repository, monitoring usage, and understanding what Claude Code stores and sends. Set up Claude Code for your organization : choose an authentication provider, decide how policy reaches devices, and plan the rollout Server-managed settings : deliver managed policy from the Claude.ai admin console so engineers cannot bypass it by editing repository files Monitor usage and audit activity : export OpenTelemetry metrics and review what your team is running Network access requirements : the full domain allowlist for proxies and firewalls Telemetry services and opt-out : what Claude Code sends by default and the environment variables that disable it Explore the .claude directory : what the volume mount holds, including credentials, settings, and session history Security model : how Claude Code’s permission system, sandboxing, and prompt-injection protections fit together Permission modes : the full range from plan mode to auto mode to bypass, and when to use each Was this page helpful? Yes No LLM gateway Monitoring Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Extend with tools Scale to many tools with tool search Agent SDK Overview Quickstart Core concepts How the agent loop works Use Claude Code features Work with sessions Input and output Streaming Input Handle approvals and user input Stream responses in real-time Get structured output from agents Extend with tools Give Claude custom tools Connect to external tools with MCP Scale to many tools with tool search Subagents in the SDK Customize behavior Modifying system prompts Slash Commands in the SDK Agent Skills in the SDK Plugins in the SDK Control and observability Configure permissions Intercept and control agent behavior with hooks Rewind file changes with checkpointing Track cost and usage Observability with OpenTelemetry Todo Lists Deployment Hosting the Agent SDK Securely deploying AI agents SDK references TypeScript SDK TypeScript V2 (deprecated) Python SDK Migration Guide Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. Tool search enables your agent to work with hundreds or thousands of tools by dynamically discovering and loading them on demand. Instead of loading all tool definitions into the context window upfront, the agent searches your tool catalog and loads only the tools it needs. This approach solves two challenges as tool libraries scale: Context efficiency: Tool definitions can consume large portions of the context window (50 tools can use 10-20K tokens), leaving less room for actual work. Tool selection accuracy: Tool selection accuracy degrades with more than 30-50 tools loaded at once. Tool search is enabled by default. This page covers how it works , how to configure it , and how to optimize tool discovery . ​ How tool search works When tool search is active, tool definitions are withheld from the context window. The agent receives a summary of available tools and searches for relevant ones when the task requires a capability not already loaded. The 3-5 most relevant tools are loaded into context, where they stay available for subsequent turns. If the conversation is long enough that the SDK compacts earlier messages to free space, previously discovered tools may be removed, and the agent searches again as needed. Tool search adds one extra round-trip the first time Claude discovers a tool (the search step), but for large tool sets this is offset by smaller context on every turn. With fewer than ~10 tools, loading everything upfront is typically faster. For details on the underlying API mechanism, see Tool search in the API . Tool search requires Claude Sonnet 4 or later, or Claude Opus 4 or later. Haiku models do not support tool search. ​ Configure tool search Tool search is on by default. It is disabled by default on Vertex AI, where it is supported for Claude Sonnet 4.5 and later and Claude Opus 4.5 and later. It is also disabled when ANTHROPIC_BASE_URL points to a non-first-party host, since most proxies do not forward tool_reference blocks. You can override either default with the ENABLE_TOOL_SEARCH environment variable: Value Behavior (unset) Tool search is on. Tool definitions are deferred and discovered on demand. Falls back to loading upfront on Vertex AI or a non-first-party ANTHROPIC_BASE_URL . true Tool search is always on. The SDK sends the beta header even on Vertex AI and through proxies. Requests fail on Vertex AI models earlier than Sonnet 4.5 or Opus 4.5, or on proxies that do not support tool_reference blocks. auto Checks the combined token count of all tool definitions against the model’s context window. If they exceed 10%, tool search activates. If they’re under 10%, all tools are loaded into context normally. auto:N Same as auto with a custom percentage. auto:5 activates when tool definitions exceed 5% of the context window. Lower values activate sooner. false Tool search is off. All tool definitions are loaded into context on every turn. Tool search applies to all registered tools, whether they come from remote MCP servers or custom SDK MCP servers . When using auto , the threshold is based on the combined size of all tool definitions across all servers. Set the value in the env option on query() . This example connects to a remote MCP server that exposes many tools, pre-approves all of them with a wildcard, and uses auto:5 so tool search activates when their definitions exceed 5% of the context window: TypeScript Python import { query } from "@anthropic-ai/claude-agent-sdk" ; for await ( const message of query ({ prompt: "Find and run the appropriate database query" , options: { mcpServers: { "enterprise-tools" : { // Connect to a remote MCP server type: "http" , url: "https://tools.example.com/mcp" } }, allowedTools: [ "mcp__enterprise-tools__*" ], // Wildcard pre-approves all tools from this server env: { ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when tools exceed 5% of context } } })) { if ( message . type === "result" && message . subtype === "success" ) { console . log ( message . result ); } } Setting ENABLE_TOOL_SEARCH to "false" disables tool search and loads all tool definitions into context on every turn. This removes the search round-trip, which can be faster when the tool set is small (fewer than ~10 tools) and the definitions fit comfortably in the context window. ​ Optimize tool discovery The search mechanism matches queries against tool names and descriptions. Names like search_slack_messages surface for a wider range of requests than query_slack . Descriptions with specific keywords (“Search Slack messages by keyword, channel, or date range”) match more queries than generic ones (“Query Slack”). You can also add a system prompt section listing available tool categories. This gives the agent context about what kinds of tools are available to search for: You can search for tools to interact with Slack, GitHub, and Jira. ​ Limits Maximum tools: 10,000 tools in your catalog Search results: Returns 3-5 most relevant tools per search Model support: Claude Sonnet 4 and later, Claude Opus 4 and later (no Haiku) ​ Related documentation Tool search in the API : Full API documentation for tool search, including custom implementations Connect MCP servers : Connect to external tools via MCP servers Custom tools : Build your own tools with SDK MCP servers TypeScript SDK reference : Full API reference Python SDK reference : Full API reference Was this page helpful? Yes No Connect to external tools with MCP Subagents in the SDK Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Plugin distribution Create and distribute a plugin marketplace Setup and access Administration overview Advanced setup Authentication Server-managed settings Auto mode Deployment Overview Amazon Bedrock Claude Platform on AWS Google Vertex AI Microsoft Foundry Network configuration LLM gateway Development containers Usage and costs Monitoring Costs Track team usage with analytics Plugin distribution Create and distribute a plugin marketplace Plugin dependency versions Security and data Security Data usage Zero data retention Adoption Communications kit Champion kit Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. A plugin marketplace is a catalog that lets you distribute plugins to others. Marketplaces provide centralized discovery, version tracking, automatic updates, and support for multiple source types (git repositories, local paths, and more). This guide shows you how to create your own marketplace to share plugins with your team or community. Looking to install plugins from an existing marketplace? See Discover and install prebuilt plugins . ​ Overview Creating and distributing a marketplace involves: Creating plugins : build one or more plugins with skills, agents, hooks, MCP servers, or LSP servers. This guide assumes you already have plugins to distribute; see Create plugins for details on how to create them. Creating a marketplace file : define a marketplace.json that lists your plugins and where to find them (see Create the marketplace file ). Host the marketplace : push to GitHub, GitLab, or another git host (see Host and distribute marketplaces ). Share with users : users add your marketplace with /plugin marketplace add and install individual plugins (see Discover and install plugins ). Once your marketplace is live, you can update it by pushing changes to your repository. Users refresh their local copy with /plugin marketplace update . ​ Walkthrough: create a local marketplace This example creates a marketplace with one plugin: a quality-review skill for code reviews. You’ll create the directory structure, add a skill, create the plugin manifest and marketplace catalog, then install and test it. 1 Create the directory structure mkdir -p my-marketplace/.claude-plugin mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review 2 Create the skill Create a SKILL.md file that defines what the quality-review skill does. my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md --- description : Review code for bugs, security, and performance disable-model-invocation : true --- Review the code I've selected or the recent changes for: - Potential bugs or edge cases - Security concerns - Performance issues - Readability improvements Be concise and actionable. 3 Create the plugin manifest Create a plugin.json file that describes the plugin. The manifest goes in the .claude-plugin/ directory. my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json { "name" : "quality-review-plugin" , "description" : "Adds a quality-review skill for quick code reviews" , "version" : "1.0.0" } Setting version means users only receive updates when you change this field, so bump it on every release. If you omit version and host this marketplace in git, every commit automatically counts as a new version. See Version resolution to choose the right approach. 4 Create the marketplace file Create the marketplace catalog that lists your plugin. my-marketplace/.claude-plugin/marketplace.json { "name" : "my-plugins" , "owner" : { "name" : "Your Name" }, "plugins" : [ { "name" : "quality-review-plugin" , "source" : "./plugins/quality-review-plugin" , "description" : "Adds a quality-review skill for quick code reviews" } ] } 5 Add and install Add the marketplace and install the plugin. /plugin marketplace add ./my-marketplace /plugin install quality-review-plugin@my-plugins 6 Try it out Select some code in your editor and run your new skill. Plugin skills are namespaced with the plugin name. /quality-review-plugin:quality-review To learn more about what plugins can do, including hooks, agents, MCP servers, and LSP servers, see Plugins . How plugins are installed : When users install a plugin, Claude Code copies the plugin directory to a cache location. This means plugins can’t reference files outside their directory using paths like ../shared-utils , because those files won’t be copied. If you need to share files across plugins, use symlinks. See Plugin caching and file resolution for details. ​ Create the marketplace file Create .claude-plugin/marketplace.json in your repository root. This file defines your marketplace’s name, owner information, and a list of plugins with their sources. Each plugin entry needs at minimum a name and source (where to fetch it from). See the full schema below for all available fields. { "name" : "company-tools" , "owner" : { "name" : "DevTools Team" , "email" : "devtools@example.com" }, "plugins" : [ { "name" : "code-formatter" , "source" : "./plugins/formatter" , "description" : "Automatic code formatting on save" , "version" : "2.1.0" , "author" : { "name" : "DevTools Team" } }, { "name" : "deployment-tools" , "source" : { "source" : "github" , "repo" : "company/deploy-plugin" }, "description" : "Deployment automation tools" } ] } ​ Marketplace schema ​ Required fields Field Type Description Example name string Marketplace identifier (kebab-case, no spaces). This is public-facing: users see it when installing plugins (for example, /plugin install my-tool@your-marketplace ). "acme-tools" owner object Marketplace maintainer information ( see fields below ) plugins array List of available plugins See below Reserved names : The following marketplace names are reserved for official Anthropic use and cannot be used by third-party marketplaces: claude-code-marketplace , claude-code-plugins , claude-plugins-official , anthropic-marketplace , anthropic-plugins , agent-skills , knowledge-work-plugins , life-sciences . Names that impersonate official marketplaces (like official-claude-plugins or anthropic-tools-v2 ) are also blocked. ​ Owner fields Field Type Required Description name string Yes Name of the maintainer or team email string No Contact email for the maintainer ​ Optional fields Field Type Description $schema string JSON Schema URL for editor autocomplete and validation. Claude Code ignores this field at load time. description string Brief marketplace description version string Marketplace manifest version metadata.pluginRoot string Base directory prepended to relative plugin source paths (for example, "./plugins" lets you write "source": "formatter" instead of "source": "./plugins/formatter" ) allowCrossMarketplaceDependenciesOn array Other marketplaces that plugins in this marketplace may depend on. Dependencies from a marketplace not listed here are blocked at install. See Depend on a plugin from another marketplace . description and version are also accepted under metadata for backward compatibility. ​ Plugin entries Each plugin entry in the plugins array describes a plugin and where to find it. You can include any field from the plugin manifest schema (like description , version , author , commands , hooks , etc.), plus these marketplace-specific fields: source , category , tags , and strict . ​ Required fields Field Type Description name string Plugin identifier (kebab-case, no spaces). This is public-facing: users see it when installing (for example, /plugin install my-plugin@marketplace ). source string|object Where to fetch the plugin from (see Plugin sources below) ​ Optional plugin fields Standard metadata fields: Field Type Description description string Brief plugin description version string Plugin version. If set (here or in plugin.json ), the plugin is pinned to this string and users only receive updates when it changes. Omit to fall back to the git commit SHA. See Version resolution . author object Plugin author information ( name required, email optional) homepage string Plugin homepage or documentation URL repository string Source code repository URL license string SPDX license identifier (for example, MIT, Apache-2.0) keywords array Tags for plugin discovery and categorization category string Plugin category for organization tags array Tags for searchability strict boolean Controls whether plugin.json is the authority for component definitions (default: true). See Strict mode below. Component configuration fields: Field Type Description skills string|array Custom paths to skill directories containing /SKILL.md commands string|array Custom paths to flat .md skill files or directories agents string|array Custom paths to agent files hooks string|object Custom hooks configuration or path to hooks file mcpServers string|object MCP server configurations or path to MCP config lspServers string|object LSP server configurations or path to LSP config ​ Plugin sources Plugin sources tell Claude Code where to fetch each individual plugin listed in your marketplace. These are set in the source field of each plugin entry in marketplace.json . Once a plugin is cloned or copied into the local machine, it is copied into the local versioned plugin cache at ~/.claude/plugins/cache . Source Type Fields Notes Relative path string (e.g. "./my-plugin" ) none Local directory within the marketplace repo. Must start with ./ . Resolved relative to the marketplace root, not the .claude-plugin/ directory github object repo , ref? , sha? url object url , ref? , sha? Git URL source git-subdir object url , path , ref? , sha? Subdirectory within a git repo. Clones sparsely to minimize bandwidth for monorepos npm object package , version? , registry? Installed via npm install Marketplace sources vs plugin sources : These are different concepts that control different things. Marketplace source — where to fetch the marketplace.json catalog itself. Set when users run /plugin marketplace add or in extraKnownMarketplaces settings. Supports ref (branch/tag) but not sha . Plugin source — where to fetch an individual plugin listed in the marketplace. Set in the source field of each plugin entry inside marketplace.json . Supports both ref (branch/tag) and sha (exact commit). For example, a marketplace hosted at acme-corp/plugin-catalog (marketplace source) can list a plugin fetched from acme-corp/code-formatter (plugin source). The marketplace source and plugin source point to different repositories and are pinned independently. ​ Relative paths For plugins in the same repository, use a path starting with ./ : { "name" : "my-plugin" , "source" : "./plugins/my-plugin" } Paths resolve relative to the marketplace root, which is the directory containing .claude-plugin/ . In the example above, ./plugins/my-plugin points to /plugins/my-plugin , even though marketplace.json lives at /.claude-plugin/marketplace.json . Do not use ../ to reference paths outside the marketplace root. Relative paths only work when users add your marketplace via Git (GitHub, GitLab, or git URL). If users add your marketplace via a direct URL to the marketplace.json file, relative paths will not resolve correctly. For URL-based distribution, use GitHub, npm, or git URL sources instead. See Troubleshooting for details. ​ GitHub repositories { "name" : "github-plugin" , "source" : { "source" : "github" , "repo" : "owner/plugin-repo" } } You can pin to a specific branch, tag, or commit: { "name" : "github-plugin" , "source" : { "source" : "github" , "repo" : "owner/plugin-repo" , "ref" : "v2.0.0" , "sha" : "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0" } } Field Type Description repo string Required. GitHub repository in owner/repo format ref string Optional. Git branch or tag (defaults to repository default branch) sha string Optional. Full 40-character git commit SHA to pin to an exact version ​ Git repositories { "name" : "git-plugin" , "source" : { "source" : "url" , "url" : "https://gitlab.com/team/plugin.git" } } You can pin to a specific branch, tag, or commit: { "name" : "git-plugin" , "source" : { "source" : "url" , "url" : "https://gitlab.com/team/plugin.git" , "ref" : "main" , "sha" : "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0" } } Field Type Description url string Required. Full git repository URL ( https:// or git@ ). The .git suffix is optional, so Azure DevOps and AWS CodeCommit URLs without the suffix work ref string Optional. Git branch or tag (defaults to repository default branch) sha string Optional. Full 40-character git commit SHA to pin to an exact version ​ Git subdirectories Use git-subdir to point to a plugin that lives inside a subdirectory of a git repository. Claude Code uses a sparse, partial clone to fetch only the subdirectory, minimizing bandwidth for large monorepos. { "name" : "my-plugin" , "source" : { "source" : "git-subdir" , "url" : "https://github.com/acme-corp/monorepo.git" , "path" : "tools/claude-plugin" } } You can pin to a specific branch, tag, or commit: { "name" : "my-plugin" , "source" : { "source" : "git-subdir" , "url" : "https://github.com/acme-corp/monorepo.git" , "path" : "tools/claude-plugin" , "ref" : "v2.0.0" , "sha" : "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0" } } The url field also accepts a GitHub shorthand ( owner/repo ) or SSH URLs ( git@github.com:owner/repo.git ). Field Type Description url string Required. Git repository URL, GitHub owner/repo shorthand, or SSH URL path string Required. Subdirectory path within the repo containing the plugin (for example, "tools/claude-plugin" ) ref string Optional. Git branch or tag (defaults to repository default branch) sha string Optional. Full 40-character git commit SHA to pin to an exact version ​ npm packages Plugins distributed as npm packages are installed using npm install . This works with any package on the public npm registry or a private registry your team hosts. { "name" : "my-npm-plugin" , "source" : { "source" : "npm" , "package" : "@acme/claude-plugin" } } To pin to a specific version, add the version field: { "name" : "my-npm-plugin" , "source" : { "source" : "npm" , "package" : "@acme/claude-plugin" , "version" : "2.1.0" } } To install from a private or internal registry, add the registry field: { "name" : "my-npm-plugin" , "source" : { "source" : "npm" , "package" : "@acme/claude-plugin" , "version" : "^2.0.0" , "registry" : "https://npm.example.com" } } Field Type Description package string Required. Package name or scoped package (for example, @org/plugin ) version string Optional. Version or version range (for example, 2.1.0 , ^2.0.0 , ~1.5.0 ) registry string Optional. Custom npm registry URL. Defaults to the system npm registry (typically npmjs.org) ​ Advanced plugin entries This example shows a plugin entry using many of the optional fields, including custom paths for commands, agents, hooks, and MCP servers: { "name" : "enterprise-tools" , "source" : { "source" : "github" , "repo" : "company/enterprise-plugin" }, "description" : "Enterprise workflow automation tools" , "version" : "2.1.0" , "author" : { "name" : "Enterprise Team" , "email" : "enterprise@example.com" }, "homepage" : "https://docs.example.com/plugins/enterprise-tools" , "repository" : "https://github.com/company/enterprise-plugin" , "license" : "MIT" , "keywords" : [ "enterprise" , "workflow" , "automation" ], "category" : "productivity" , "commands" : [ "./commands/core/" , "./commands/enterprise/" , "./commands/experimental/preview.md" ], "agents" : [ "./agents/security-reviewer.md" , "./agents/compliance-checker.md" ], "hooks" : { "PostToolUse" : [ { "matcher" : "Write|Edit" , "hooks" : [ { "type" : "command" , "command" : "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh" } ] } ] }, "mcpServers" : { "enterprise-db" : { "command" : "${CLAUDE_PLUGIN_ROOT}/servers/db-server" , "args" : [ "--config" , "${CLAUDE_PLUGIN_ROOT}/config.json" ] } }, "strict" : false } Key things to notice: commands and agents : You can specify multiple directories or individual files. Paths are relative to the plugin root. ${CLAUDE_PLUGIN_ROOT} : use this variable in hooks and MCP server configs to reference files within the plugin’s installation directory. This is necessary because plugins are copied to a cache location when installed. For dependencies or state that should survive plugin updates, use ${CLAUDE_PLUGIN_DATA} instead. strict: false : Since this is set to false, the plugin doesn’t need its own plugin.json . The marketplace entry defines everything. See Strict mode below. ​ Strict mode The strict field controls whether plugin.json is the authority for component definitions (skills, agents, hooks, MCP servers, output styles). Value Behavior true (default) plugin.json is the authority. The marketplace entry can supplement it with additional components, and both sources are merged. false The marketplace entry is the entire definition. If the plugin also has a plugin.json that declares components, that’s a conflict and the plugin fails to load. When to use each mode: strict: true : the plugin has its own plugin.json and manages its own components. The marketplace entry can add extra skills or hooks on top. This is the default and works for most plugins. strict: false : the marketplace operator wants full control. The plugin repo provides raw files, and the marketplace entry defines which of those files are exposed as skills, agents, hooks, etc. Useful when the marketplace restructures or curates a plugin’s components differently than the plugin author intended. ​ Host and distribute marketplaces ​ Host on GitHub (recommended) GitHub provides the easiest distribution method: Create a repository : Set up a new repository for your marketplace Add marketplace file : Create .claude-plugin/marketplace.json with your plugin definitions Share with teams : Users add your marketplace with /plugin marketplace add owner/repo Benefits : Built-in version control, issue tracking, and team collaboration features. ​ Host on other git services Any git hosting service works, such as GitLab, Bitbucket, and self-hosted servers. Users add with the full repository URL: /plugin marketplace add https://gitlab.com/company/plugins.git ​ Private repositories Claude Code supports installing plugins from private repositories. For manual installation and updates, Claude Code uses your existing git credential helpers, so HTTPS access via gh auth login , macOS Keychain, or git-credential-store works the same as in your terminal. SSH access works as long as the host is already in your known_hosts file and the key is loaded in ssh-agent , since Claude Code suppresses interactive SSH prompts for the host fingerprint and key passphrase. Background auto-updates run at startup without credential helpers, since interactive prompts would block Claude Code from starting. To enable auto-updates for private marketplaces, set the appropriate authentication token in your environment: Provider Environment variables Notes GitHub GITHUB_TOKEN or GH_TOKEN Personal access token or GitHub App token GitLab GITLAB_TOKEN or GL_TOKEN Personal access token or project token Bitbucket BITBUCKET_TOKEN App password or repository access token Set the token in your shell configuration (for example, .bashrc , .zshrc ) or pass it when running Claude Code: export GITHUB_TOKEN = ghp_xxxxxxxxxxxxxxxxxxxx For CI/CD environments, configure the token as a secret environment variable. GitHub Actions automatically provides GITHUB_TOKEN for repositories in the same organization. ​ Test locally before distribution Test your marketplace locally before sharing: /plugin marketplace add ./my-local-marketplace /plugin install test-plugin@my-local-marketplace For the full range of add commands (GitHub, Git URLs, local paths, remote URLs), see Add marketplaces . ​ Require marketplaces for your team You can configure your repository so team members are automatically prompted to install your marketplace when they trust the project folder. Add your marketplace to .claude/settings.json : { "extraKnownMarketplaces" : { "company-tools" : { "source" : { "source" : "github" , "repo" : "your-org/claude-plugins" } } } } You can also specify which plugins should be enabled by default: { "enabledPlugins" : { "code-formatter@company-tools" : true , "deployment-tools@company-tools" : true } } For full configuration options, see Plugin settings . If you use a local directory or file source with a relative path, the path resolves against your repository’s main checkout. When you run Claude Code from a git worktree, the path still points at the main checkout, so all worktrees share the same marketplace location. Marketplace state is stored once per user in ~/.claude/plugins/known_marketplaces.json , not per project. ​ Pre-populate plugins for containers For container images and CI environments, you can pre-populate a plugins directory at build time so Claude Code starts with marketplaces and plugins already available, without cloning anything at runtime. Set the CLAUDE_CODE_PLUGIN_SEED_DIR environment variable to point at this directory. To layer multiple seed directories, separate paths with : on Unix or ; on Windows. Claude Code searches each directory in order, and the first seed that contains a given marketplace or plugin cache wins. The seed directory mirrors the structure of ~/.claude/plugins : $CLAUDE_CODE_PLUGIN_SEED_DIR/ known_marketplaces.json marketplaces//... cache////... To build a seed directory, run Claude Code once during image build, install the plugins you need, then copy the resulting ~/.claude/plugins directory into your image and point CLAUDE_CODE_PLUGIN_SEED_DIR at it. To skip the copy step, set CLAUDE_CODE_PLUGIN_CACHE_DIR to your target seed path during the build so plugins install directly there: CLAUDE_CODE_PLUGIN_CACHE_DIR = /opt/claude-seed claude plugin marketplace add your-org/plugins CLAUDE_CODE_PLUGIN_CACHE_DIR = /opt/claude-seed claude plugin install my-tool@your-plugins Then set CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed in your container’s runtime environment so Claude Code reads from the seed on startup. At startup, Claude Code registers marketplaces found in the seed’s known_marketplaces.json into the primary configuration, and uses plugin caches found under cache/ in place without re-cloning. This works in both interactive mode and non-interactive mode with the -p flag. Behavior details: Read-only : the seed directory is never written to. Auto-updates are disabled for seed marketplaces since git pull would fail on a read-only filesystem. Seed entries take precedence : marketplaces declared in the seed overwrite any matching entries in the user’s configuration on each startup. To opt out of a seed plugin, use /plugin disable rather than removing the marketplace. Path resolution : Claude Code locates marketplace content by probing $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces// at runtime, not by trusting paths stored inside the seed’s JSON. This means the seed works correctly even when mounted at a different path than where it was built. Mutation is blocked : running /plugin marketplace remove or /plugin marketplace update against a seed-managed marketplace fails with guidance to ask your administrator to update the seed image. Composes with settings : if extraKnownMarketplaces or enabledPlugins declare a marketplace that already exists in the seed, Claude Code uses the seed copy instead of cloning. ​ Managed marketplace restrictions For organizations requiring strict control over plugin sources, administrators can restrict which plugin marketplaces users are allowed to add using the strictKnownMarketplaces setting in managed settings. When strictKnownMarketplaces is configured in managed settings, the restriction behavior depends on the value: Value Behavior Undefined (default) No restrictions. Users can add any marketplace Empty array [] Complete lockdown. Users cannot add any new marketplaces List of sources Users can only add marketplaces that match the allowlist exactly ​ Common configurations Disable all marketplace additions: { "strictKnownMarketplaces" : [] } Allow specific marketplaces only: { "strictKnownMarketplaces" : [ { "source" : "github" , "repo" : "acme-corp/approved-plugins" }, { "source" : "github" , "repo" : "acme-corp/security-tools" , "ref" : "v2.0" }, { "source" : "url" , "url" : "https://plugins.example.com/marketplace.json" } ] } Allow all marketplaces from an internal git server using regex pattern matching on the host. This is the recommended approach for GitHub Enterprise Server or self-hosted GitLab instances: { "strictKnownMarketplaces" : [ { "source" : "hostPattern" , "hostPattern" : "^github \\ .example \\ .com$" } ] } Allow filesystem-based marketplaces from a specific directory using regex pattern matching on the path: { "strictKnownMarketplaces" : [ { "source" : "pathPattern" , "pathPattern" : "^/opt/approved/" } ] } Use ".*" as the pathPattern to allow any filesystem path while still controlling network sources with hostPattern . strictKnownMarketplaces restricts what users can add, but does not register marketplaces on its own. To make allowed marketplaces available automatically without users running /plugin marketplace add , pair it with extraKnownMarketplaces in the same managed-settings.json . See Using both together . ​ How restrictions work Restrictions are checked before any network or filesystem operation. The check runs on marketplace add and on plugin install, update, refresh, and auto-update. If a marketplace was added before the policy was configured and its source no longer matches the allowlist, Claude Code refuses to install or update plugins from it. The same enforcement applies to blockedMarketplaces . The allowlist uses exact matching for most source types. For a marketplace to be allowed, all specified fields must match exactly: For GitHub sources: repo is required, and ref or path must also match if specified in the allowlist For URL sources: the full URL must match exactly For hostPattern sources: the marketplace host is matched against the regex pattern For pathPattern sources: the marketplace’s filesystem path is matched against the regex pattern Exact matching does not normalize URLs: a trailing slash, .git suffix, or ssh:// versus https:// form are treated as different values. If your organization’s marketplace can be cloned by more than one URL form, prefer a hostPattern entry over a literal URL so all forms match. Because strictKnownMarketplaces is set in managed settings , individual users and project configurations cannot override these restrictions. For complete configuration details including all supported source types and comparison with extraKnownMarketplaces , see the strictKnownMarketplaces reference . ​ Version resolution and release channels Plugin versions determine cache paths and update detection: if the resolved version matches what a user already has, /plugin update and auto-update skip the plugin. Claude Code resolves a plugin’s version from the first of these that is set: version in the plugin’s plugin.json version in the plugin’s marketplace entry The git commit SHA of the plugin’s source For the git-based source types github , url , git-subdir , and relative paths inside a git-hosted marketplace, you can omit version entirely and every new commit is treated as a new version. This is the simplest setup for internal or actively-developed plugins. Setting version pins the plugin. If plugin.json declares "version": "1.0.0" , pushing new commits without changing that string does nothing for existing users, because Claude Code sees the same version and keeps the cached copy. Bump the field on every release, or omit it to use the commit SHA. Avoid setting version in both plugin.json and the marketplace entry. The plugin.json value always wins silently, so a stale manifest version can mask a version you set in marketplace.json . ​ Set up release channels To support “stable” and “latest” release channels for your plugins, you can set up two marketplaces that point to different refs or SHAs of the same repo. You can then assign the two marketplaces to different user groups through managed settings . Each channel must resolve to a different version. If you use explicit versions, plugin.json must declare a different version at each pinned ref. If you omit version , the distinct commit SHAs already distinguish the channels. If two refs resolve to the same version string, Claude Code treats them as identical and skips the update. Example { "name" : "stable-tools" , "plugins" : [ { "name" : "code-formatter" , "source" : { "source" : "github" , "repo" : "acme-corp/code-formatter" , "ref" : "stable" } } ] } { "name" : "latest-tools" , "plugins" : [ { "name" : "code-formatter" , "source" : { "source" : "github" , "repo" : "acme-corp/code-formatter" , "ref" : "latest" } } ] } Assign channels to user groups Assign each marketplace to the appropriate user group through managed settings. For example, the stable group receives: { "extraKnownMarketplaces" : { "stable-tools" : { "source" : { "source" : "github" , "repo" : "acme-corp/stable-tools" } } } } The early-access group receives latest-tools instead: { "extraKnownMarketplaces" : { "latest-tools" : { "source" : { "source" : "github" , "repo" : "acme-corp/latest-tools" } } } } ​ Pin dependency versions A plugin can constrain its dependencies to a semver range so that updates to a dependency do not break the dependent plugin. See Constrain plugin dependency versions for the {plugin-name}--v{version} git-tag convention, range syntax, and how multiple constraints on the same dependency are combined. ​ Validation and testing Test your marketplace before sharing. Validate your marketplace JSON syntax: claude plugin validate . Or from within Claude Code: /plugin validate . Add the marketplace for testing: /plugin marketplace add ./path/to/marketplace Install a test plugin to verify everything works: /plugin install test-plugin@marketplace-name For complete plugin testing workflows, see Test your plugins locally . For technical troubleshooting, see Plugins reference . ​ Manage marketplaces from the CLI Claude Code provides non-interactive claude plugin marketplace subcommands for scripting and automation. These are equivalent to the /plugin marketplace commands available inside an interactive session. ​ Plugin marketplace add Add a marketplace from a GitHub repository, git URL, remote URL, or local path. claude plugin marketplace add < sourc e > [options] Arguments: : GitHub owner/repo shorthand, git URL, remote URL to a marketplace.json file, or local directory path. To pin to a branch or tag, append @ref to the GitHub shorthand or #ref to a git URL Options: Option Description Default --scope Where to declare the marketplace: user , project , or local . See Plugin installation scopes user --sparse Limit checkout to specific directories via git sparse-checkout. Useful for monorepos Add a marketplace from GitHub using owner/repo shorthand: claude plugin marketplace add acme-corp/claude-plugins Pin to a specific branch or tag with @ref : claude plugin marketplace add acme-corp/claude-plugins@v2.0 Add from a git URL on a non-GitHub host: claude plugin marketplace add https://gitlab.example.com/team/plugins.git Add from a remote URL that serves the marketplace.json file directly: claude plugin marketplace add https://example.com/marketplace.json Add from a local directory for testing: claude plugin marketplace add ./my-marketplace Declare the marketplace at project scope so it is shared with your team via .claude/settings.json : claude plugin marketplace add acme-corp/claude-plugins --scope project For a monorepo, limit the checkout to the directories that contain plugin content: claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins ​ Plugin marketplace list List all configured marketplaces. claude plugin marketplace list [options] Options: Option Description --json Output as JSON ​ Plugin marketplace remove Remove a configured marketplace. The alias rm is also accepted. claude plugin marketplace remove < nam e > Arguments: : marketplace name to remove, as shown by claude plugin marketplace list . This is the name from marketplace.json , not the source you passed to add Removing a marketplace also uninstalls any plugins you installed from it. To refresh a marketplace without losing installed plugins, use claude plugin marketplace update instead. ​ Plugin marketplace update Refresh marketplaces from their sources to retrieve new plugins and version changes. claude plugin marketplace update [name] Arguments: [name] : marketplace name to update, as shown by claude plugin marketplace list . Updates all marketplaces if omitted Both remove and update fail when run against a seed-managed marketplace, which is read-only. When updating all marketplaces, seed-managed entries are skipped and other marketplaces still update. To change seed-provided plugins, ask your administrator to update the seed image. See Pre-populate plugins for containers . ​ Troubleshooting ​ Marketplace not loading Symptoms : Can’t add marketplace or see plugins from it Solutions : Verify the marketplace URL is accessible Check that .claude-plugin/marketplace.json exists at the specified path Ensure JSON syntax is valid and frontmatter is well-formed using claude plugin validate or /plugin validate For private repositories, confirm you have access permissions ​ Marketplace validation errors Run claude plugin validate . or /plugin validate . from your marketplace directory to check for issues. The validator checks plugin.json , skill/agent/command frontmatter, and hooks/hooks.json for syntax and schema errors. Common errors: Error Cause Solution File not found: .claude-plugin/marketplace.json Missing manifest Create .claude-plugin/marketplace.json with required fields Invalid JSON syntax: Unexpected token... JSON syntax error in marketplace.json Check for missing commas, extra commas, or unquoted strings Duplicate plugin name "x" found in marketplace Two plugins share the same name Give each plugin a unique name value plugins[0].source: Path contains ".." Source path contains .. Use paths relative to the marketplace root without .. . See Relative paths YAML frontmatter failed to parse: ... Invalid YAML in a skill, agent, or command file Fix the YAML syntax in the frontmatter block. At runtime this file loads with no metadata. Invalid JSON syntax: ... (hooks.json) Malformed hooks/hooks.json Fix JSON syntax. A malformed hooks/hooks.json prevents the entire plugin from loading. Warnings (non-blocking): Marketplace has no plugins defined : add at least one plugin to the plugins array No marketplace description provided : add a top-level description to help users understand your marketplace Plugin name "x" is not kebab-case : the plugin name contains uppercase letters, spaces, or special characters. Rename to lowercase letters, digits, and hyphens only (for example, my-plugin ). Claude Code accepts other forms, but the Claude.ai marketplace sync rejects them. ​ Plugin installation failures Symptoms : Marketplace appears but plugin installation fails Solutions : Verify plugin source URLs are accessible Check that plugin directories contain required files For GitHub sources, ensure repositories are public or you have access Test plugin sources manually by cloning/downloading ​ Private repository authentication fails Symptoms : Authentication errors when installing plugins from private repositories Solutions : For manual installation and updates: Verify you’re authenticated with your git provider (for example, run gh auth status for GitHub) Check that your credential helper is configured correctly: git config --global credential.helper Try cloning the repository manually to verify your credentials work For background auto-updates: Set the appropriate token in your environment: echo $GITHUB_TOKEN Check that the token has the required permissions (read access to the repository) For GitHub, ensure the token has the repo scope for private repositories For GitLab, ensure the token has at least read_repository scope Verify the token hasn’t expired ​ Marketplace updates fail in offline environments Symptoms : Marketplace git pull fails and Claude Code wipes the existing cache, causing plugins to become unavailable. Cause : By default, when a git pull fails, Claude Code removes the stale clone and attempts to re-clone. In offline or airgapped environments, re-cloning fails the same way, leaving the marketplace directory empty. Solution : Set CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 to keep the existing cache when the pull fails instead of wiping it: export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE = 1 With this variable set, Claude Code retains the stale marketplace clone on git pull failure and continues using the last-known-good state. For fully offline deployments where the repository will never be reachable, use CLAUDE_CODE_PLUGIN_SEED_DIR to pre-populate the plugins directory at build time instead. ​ Git operations time out Symptoms : Plugin installation or marketplace updates fail with a timeout error like “Git clone timed out after 120s” or “Git pull timed out after 120s”. Cause : Claude Code uses a 120-second timeout for all git operations, including cloning plugin repositories and pulling marketplace updates. Large repositories or slow network connections may exceed this limit. Solution : Increase the timeout using the CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS environment variable. The value is in milliseconds: export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS = 300000 # 5 minutes ​ Plugins with relative paths fail in URL-based marketplaces Symptoms : Added a marketplace via URL (such as https://example.com/marketplace.json ), but plugins with relative path sources like "./plugins/my-plugin" fail to install with “path not found” errors. Cause : URL-based marketplaces only download the marketplace.json file itself. They do not download plugin files from the server. Relative paths in the marketplace entry reference files on the remote server that were not downloaded. Solutions : Use external sources : Change plugin entries to use GitHub, npm, or git URL sources instead of relative paths: { "name" : "my-plugin" , "source" : { "source" : "github" , "repo" : "owner/repo" } } Use a Git-based marketplace : Host your marketplace in a Git repository and add it with the git URL. Git-based marketplaces clone the entire repository, making relative paths work correctly. ​ Files not found after installation Symptoms : Plugin installs but references to files fail, especially files outside the plugin directory Cause : Plugins are copied to a cache directory rather than used in-place. Paths that reference files outside the plugin’s directory (such as ../shared-utils ) won’t work because those files aren’t copied. Solutions : See Plugin caching and file resolution for workarounds including symlinks and directory restructuring. For additional debugging tools and common issues, see Debugging and development tools . ​ See also Discover and install prebuilt plugins - Installing plugins from existing marketplaces Plugins - Creating your own plugins Plugins reference - Complete technical specifications and schemas Plugin settings - Plugin configuration options strictKnownMarketplaces reference - Managed marketplace restrictions Was this page helpful? Yes No Track team usage with analytics Plugin dependency versions Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Input and output Stream responses in real-time Agent SDK Overview Quickstart Core concepts How the agent loop works Use Claude Code features Work with sessions Input and output Streaming Input Handle approvals and user input Stream responses in real-time Get structured output from agents Extend with tools Give Claude custom tools Connect to external tools with MCP Scale to many tools with tool search Subagents in the SDK Customize behavior Modifying system prompts Slash Commands in the SDK Agent Skills in the SDK Plugins in the SDK Control and observability Configure permissions Intercept and control agent behavior with hooks Rewind file changes with checkpointing Track cost and usage Observability with OpenTelemetry Todo Lists Deployment Hosting the Agent SDK Securely deploying AI agents SDK references TypeScript SDK TypeScript V2 (deprecated) Python SDK Migration Guide Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. By default, the Agent SDK yields complete AssistantMessage objects after Claude finishes generating each response. To receive incremental updates as text and tool calls are generated, enable partial message streaming by setting include_partial_messages (Python) or includePartialMessages (TypeScript) to true in your options. This page covers output streaming (receiving tokens in real-time). For input modes (how you send messages), see Send messages to agents . You can also stream responses using the Agent SDK via the CLI . ​ Enable streaming output To enable streaming, set include_partial_messages (Python) or includePartialMessages (TypeScript) to true in your options. This causes the SDK to yield StreamEvent messages containing raw API events as they arrive, in addition to the usual AssistantMessage and ResultMessage . Your code then needs to: Check each message’s type to distinguish StreamEvent from other message types For StreamEvent , extract the event field and check its type Look for content_block_delta events where delta.type is text_delta , which contain the actual text chunks The example below enables streaming and prints text chunks as they arrive. Notice the nested type checks: first for StreamEvent , then for content_block_delta , then for text_delta : Python TypeScript from claude_agent_sdk import query, ClaudeAgentOptions from claude_agent_sdk.types import StreamEvent import asyncio async def stream_response (): options = ClaudeAgentOptions( include_partial_messages = True , allowed_tools = [ "Bash" , "Read" ], ) async for message in query( prompt = "List the files in my project" , options = options): if isinstance (message, StreamEvent): event = message.event if event.get( "type" ) == "content_block_delta" : delta = event.get( "delta" , {}) if delta.get( "type" ) == "text_delta" : print (delta.get( "text" , "" ), end = "" , flush = True ) asyncio.run(stream_response()) ​ StreamEvent reference When partial messages are enabled, you receive raw Claude API streaming events wrapped in an object. The type has different names in each SDK: Python : StreamEvent (import from claude_agent_sdk.types ) TypeScript : SDKPartialAssistantMessage with type: 'stream_event' Both contain raw Claude API events, not accumulated text. You need to extract and accumulate text deltas yourself. Here’s the structure of each type: Python TypeScript @dataclass class StreamEvent : uuid: str # Unique identifier for this event session_id: str # Session identifier event: dict[ str , Any] # The raw Claude API stream event parent_tool_use_id: str | None # Parent tool ID if from a subagent The event field contains the raw streaming event from the Claude API . Common event types include: Event Type Description message_start Start of a new message content_block_start Start of a new content block (text or tool use) content_block_delta Incremental update to content content_block_stop End of a content block message_delta Message-level updates (stop reason, usage) message_stop End of the message ​ Message flow With partial messages enabled, you receive messages in this order: StreamEvent (message_start) StreamEvent (content_block_start) - text block StreamEvent (content_block_delta) - text chunks... StreamEvent (content_block_stop) StreamEvent (content_block_start) - tool_use block StreamEvent (content_block_delta) - tool input chunks... StreamEvent (content_block_stop) StreamEvent (message_delta) StreamEvent (message_stop) AssistantMessage - complete message with all content ... tool executes ... ... more streaming events for next turn ... ResultMessage - final result Without partial messages enabled ( include_partial_messages in Python, includePartialMessages in TypeScript), you receive all message types except StreamEvent . Common types include SystemMessage (session initialization), AssistantMessage (complete responses), ResultMessage (final result), and a compact boundary message indicating when conversation history was compacted ( SDKCompactBoundaryMessage in TypeScript; SystemMessage with subtype "compact_boundary" in Python). ​ Stream text responses To display text as it’s generated, look for content_block_delta events where delta.type is text_delta . These contain the incremental text chunks. The example below prints each chunk as it arrives: Python TypeScript from claude_agent_sdk import query, ClaudeAgentOptions from claude_agent_sdk.types import StreamEvent import asyncio async def stream_text (): options = ClaudeAgentOptions( include_partial_messages = True ) async for message in query( prompt = "Explain how databases work" , options = options): if isinstance (message, StreamEvent): event = message.event if event.get( "type" ) == "content_block_delta" : delta = event.get( "delta" , {}) if delta.get( "type" ) == "text_delta" : # Print each text chunk as it arrives print (delta.get( "text" , "" ), end = "" , flush = True ) print () # Final newline asyncio.run(stream_text()) ​ Stream tool calls Tool calls also stream incrementally. You can track when tools start, receive their input as it’s generated, and see when they complete. The example below tracks the current tool being called and accumulates the JSON input as it streams in. It uses three event types: content_block_start : tool begins content_block_delta with input_json_delta : input chunks arrive content_block_stop : tool call complete Python TypeScript from claude_agent_sdk import query, ClaudeAgentOptions from claude_agent_sdk.types import StreamEvent import asyncio async def stream_tool_calls (): options = ClaudeAgentOptions( include_partial_messages = True , allowed_tools = [ "Read" , "Bash" ], ) # Track the current tool and accumulate its input JSON current_tool = None tool_input = "" async for message in query( prompt = "Read the README.md file" , options = options): if isinstance (message, StreamEvent): event = message.event event_type = event.get( "type" ) if event_type == "content_block_start" : # New tool call is starting content_block = event.get( "content_block" , {}) if content_block.get( "type" ) == "tool_use" : current_tool = content_block.get( "name" ) tool_input = "" print ( f "Starting tool: { current_tool } " ) elif event_type == "content_block_delta" : delta = event.get( "delta" , {}) if delta.get( "type" ) == "input_json_delta" : # Accumulate JSON input as it streams in chunk = delta.get( "partial_json" , "" ) tool_input += chunk print ( f " Input chunk: { chunk } " ) elif event_type == "content_block_stop" : # Tool call complete - show final input if current_tool: print ( f "Tool { current_tool } called with: { tool_input } " ) current_tool = None asyncio.run(stream_tool_calls()) ​ Build a streaming UI This example combines text and tool streaming into a cohesive UI. It tracks whether the agent is currently executing a tool (using an in_tool flag) to show status indicators like [Using Read...] while tools run. Text streams normally when not in a tool, and tool completion triggers a “done” message. This pattern is useful for chat interfaces that need to show progress during multi-step agent tasks. Python TypeScript from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage from claude_agent_sdk.types import StreamEvent import asyncio import sys async def streaming_ui (): options = ClaudeAgentOptions( include_partial_messages = True , allowed_tools = [ "Read" , "Bash" , "Grep" ], ) # Track whether we're currently in a tool call in_tool = False async for message in query( prompt = "Find all TODO comments in the codebase" , options = options ): if isinstance (message, StreamEvent): event = message.event event_type = event.get( "type" ) if event_type == "content_block_start" : content_block = event.get( "content_block" , {}) if content_block.get( "type" ) == "tool_use" : # Tool call is starting - show status indicator tool_name = content_block.get( "name" ) print ( f " \n [Using { tool_name } ...]" , end = "" , flush = True ) in_tool = True elif event_type == "content_block_delta" : delta = event.get( "delta" , {}) # Only stream text when not executing a tool if delta.get( "type" ) == "text_delta" and not in_tool: sys.stdout.write(delta.get( "text" , "" )) sys.stdout.flush() elif event_type == "content_block_stop" : if in_tool: # Tool call finished print ( " done" , flush = True ) in_tool = False elif isinstance (message, ResultMessage): # Agent finished all work print ( f " \n\n --- Complete ---" ) asyncio.run(streaming_ui()) ​ Known limitations Some SDK features are incompatible with streaming: Extended thinking : when you explicitly set max_thinking_tokens (Python) or maxThinkingTokens (TypeScript), StreamEvent messages are not emitted. You’ll only receive complete messages after each turn. Note that thinking is disabled by default in the SDK, so streaming works unless you enable it. Structured output : the JSON result appears only in the final ResultMessage.structured_output , not as streaming deltas. See structured outputs for details. ​ Next steps Now that you can stream text and tool calls in real-time, explore these related topics: Interactive vs one-shot queries : choose between input modes for your use case Structured outputs : get typed JSON responses from the agent Permissions : control which tools the agent can use Was this page helpful? Yes No Handle approvals and user input Get structured output from agents Ctrl +I Assistant Responses are generated using AI and may contain mistakes.

Claude Code Docs home page English Search... Ctrl K Ask AI Search... Navigation Reference Commands Reference CLI reference Commands Environment variables Tools reference Interactive mode Checkpointing Hooks reference Plugins reference Channels reference Glossary Glossary Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. Commands control Claude Code from inside a session. They provide a quick way to switch models, manage permissions, clear context, run a workflow, and more. Type / to see every command available to you, or type / followed by letters to filter. A command is only recognized at the start of your message. Text that follows the command name is passed to it as arguments. ​ Commands across a typical workflow Most commands are useful at a specific point in a session, from setting up a project to shipping a change. First session in a repo. Run /init to generate a starter CLAUDE.md , then /memory to refine it. Use /mcp and /agents to set up any servers or subagents the project needs, and /permissions to set the approval rules you want. During a task. /plan switches into plan mode before a large change. /model and /effort adjust how much reasoning you’re spending. When the conversation gets long, /context shows where the window is going and /compact summarizes it down; use /btw for a quick aside that shouldn’t bloat history. Running work in parallel. /agents opens the manager for the subagents Claude can delegate side tasks to, and /tasks lists what’s running in the background of the current session. /background detaches the whole session to keep running as a background agent and frees your terminal. For a large change that spans the codebase, /batch decomposes it into independent units and runs each in its own worktree . See Run agents in parallel for how these approaches relate. Before you ship. /diff shows what changed, /simplify reviews recent files and applies quality and efficiency fixes, and /review or /security-review give a deeper read-only pass. Between sessions. /clear starts fresh on a new task while keeping project memory. /resume and /branch let you return to or fork an earlier conversation. /teleport pulls a web session into this terminal, and /remote-control lets you continue this local session from another device. When something is wrong. /rewind rolls code and conversation back to a checkpoint, or summarizes part of the conversation. /doctor and /debug diagnose install and runtime issues, and /feedback reports a bug with session context attached. ​ All commands The table below lists all the commands included in Claude Code. Entries marked Skill are bundled skills. They use the same mechanism as skills you write yourself: a prompt handed to Claude, which Claude can also invoke automatically when relevant. Everything else is a built-in command whose behavior is coded into the CLI. To add your own commands, see skills . In the table below, indicates a required argument and [arg] indicates an optional one. Not every command appears for every user. Availability depends on your platform, plan, and environment. For example, /desktop only shows on macOS and Windows, and /upgrade only shows on Pro and Max plans. Command Purpose /add-dir Add a working directory for file access during the current session. Most .claude/ configuration is not discovered from the added directory. You can later resume the session from the added directory with --continue or --resume /agents Manage agent configurations /autofix-pr [prompt] Spawn a Claude Code on the web session that watches the current branch’s PR and pushes fixes when CI fails or reviewers leave comments. Detects the open PR from your checked-out branch with gh pr view ; to watch a different PR, check out its branch first. By default the remote session is told to fix every CI failure and review comment; pass a prompt to give it different instructions, for example /autofix-pr only fix lint and type errors . Requires the gh CLI and access to Claude Code on the web /background [prompt] Detach the current session to run as a background agent and free this terminal. Pass a prompt to send one more instruction before detaching. Monitor the session with claude agents . Alias: /bg /batch Skill . Orchestrate large-scale changes across a codebase in parallel. Researches the codebase, decomposes the work into 5 to 30 independent units, and presents a plan. Once approved, spawns one background subagent per unit in an isolated git worktree . Each subagent implements its unit, runs tests, and opens a pull request. Requires a git repository. Example: /batch migrate src/ from Solid to React /branch [name] Create a branch of the current conversation at this point. Switches you into the branch and preserves the original, which you can return to with /resume . Alias: /fork . When CLAUDE_CODE_FORK_SUBAGENT is set, /fork instead spawns a forked subagent and is no longer an alias for this command /btw Ask a quick side question without adding to the conversation /chrome Configure Claude in Chrome settings /claude-api [migrate|managed-agents-onboard] Skill . Load Claude API reference material for your project’s language (Python, TypeScript, Java, Go, Ruby, C#, PHP, or cURL) and Managed Agents reference. Covers tool use, streaming, batches, structured outputs, and common pitfalls. Also activates automatically when your code imports anthropic or @anthropic-ai/sdk . Run /claude-api migrate to upgrade existing Claude API code to a newer model: Claude asks which files to scan and which model to target, then updates model IDs, thinking configuration, and other parameters that changed between versions. Run /claude-api managed-agents-onboard for an interactive walkthrough that creates a new Managed Agent from scratch /clear [name] Start a new conversation with empty context. The previous conversation stays available in /resume . Pass a name to label the previous conversation in the /resume picker. To free up context while continuing the same conversation, use /compact instead. Aliases: /reset , /new /color [color|default] Set the prompt bar color for the current session. Available colors: red , blue , green , yellow , purple , orange , pink , cyan . Use default to reset, or run with no argument to pick a random color. When Remote Control is connected, the color syncs to claude.ai/code /compact [instructions] Free up context by summarizing the conversation so far. Optionally pass focus instructions for the summary. See how compaction handles rules, skills, and memory files /config Open the Settings interface to adjust theme, model, output style , and other preferences. Alias: /settings /context [all] Visualize current context usage as a colored grid. Shows optimization suggestions for context-heavy tools, memory bloat, and capacity warnings. In fullscreen mode the per-item breakdown is collapsed to keep the grid visible. Pass all to expand it /copy [N] Copy the last assistant response to clipboard. Pass a number N to copy the Nth-latest response: /copy 2 copies the second-to-last. When code blocks are present, shows an interactive picker to select individual blocks or the full response. Press w in the picker to write the selection to a file instead of the clipboard, which is useful over SSH /cost Alias for /usage /debug [description] Skill . Enable debug logging for the current session and troubleshoot issues by reading the session debug log. Debug logging is off by default unless you started with claude --debug , so running /debug mid-session starts capturing logs from that point forward. Optionally describe the issue to focus the analysis /desktop Continue the current session in the Claude Code Desktop app. macOS and Windows only. Alias: /app /diff Open an interactive diff viewer showing uncommitted changes and per-turn diffs. Use left/right arrows to switch between the current git diff and individual Claude turns, and up/down to browse files /doctor Diagnose and verify your Claude Code installation and settings. Results show with status icons. Press f to have Claude fix any reported issues /effort [level|auto] Set the model effort level . Accepts low , medium , high , xhigh , or max ; available levels depend on the model and max is session-only. auto resets to the model default. Without an argument, opens an interactive slider; use left and right arrows to pick a level and Enter to apply. Takes effect immediately without waiting for the current response to finish /exit Exit the CLI. In an attached background session , this detaches and the session keeps running. Alias: /quit /export [filename] Export the current conversation as plain text. With a filename, writes directly to that file. Without, opens a dialog to copy to clipboard or save to a file /extra-usage Configure extra usage to keep working when rate limits are hit /fast [on|off] Toggle fast mode on or off /feedback [report] Submit feedback about Claude Code. Alias: /bug /fewer-permission-prompts Skill . Scan your transcripts for common read-only Bash and MCP tool calls, then add a prioritized allowlist to project .claude/settings.json to reduce permission prompts /focus Toggle the focus view, which shows only your last prompt, a one-line tool-call summary with edit diffstats, and the final response. The selection persists across sessions; set viewMode in settings to override it. Only available in fullscreen rendering /goal [condition|clear] Set a goal : Claude keeps working across turns until the condition is met. With no argument, shows the current or most recently achieved goal. clear , stop , off , reset , none , or cancel removes an active goal early /heapdump Write a JavaScript heap snapshot and a memory breakdown to ~/Desktop , or your home directory on Linux without a Desktop folder, for diagnosing high memory usage. See troubleshooting /help Show help and available commands /hooks View hook configurations for tool events /ide Manage IDE integrations and show status /init Initialize project with a CLAUDE.md guide. Set CLAUDE_CODE_NEW_INIT=1 for an interactive flow that also walks through skills, hooks, and personal memory files /insights Generate a report analyzing your Claude Code sessions, including project areas, interaction patterns, and friction points /install-github-app Set up the Claude GitHub Actions app for a repository. Walks you through selecting a repo and configuring the integration /install-slack-app Install the Claude Slack app. Opens a browser to complete the OAuth flow /keybindings Open or create your keybindings configuration file /login Sign in to your Anthropic account /logout Sign out from your Anthropic account /loop [interval] [prompt] Skill . Run a prompt repeatedly while the session stays open. Omit the interval and Claude self-paces between iterations. Omit the prompt and Claude runs an autonomous maintenance check, or the prompt in .claude/loop.md if present. Example: /loop 5m check if the deploy finished . See Run prompts on a schedule . Alias: /proactive /mcp Manage MCP server connections and OAuth authentication /memory Edit CLAUDE.md memory files, enable or disable auto-memory , and view auto-memory entries /mobile Show QR code to download the Claude mobile app. Aliases: /ios , /android /model [model] Select or change the AI model. For models that support it, use left/right arrows to adjust effort level . With no argument, opens a picker that asks for confirmation when the conversation has prior output, since the next response re-reads the full history without cached context. Once confirmed, the change applies without waiting for the current response to finish /passes Share a free week of Claude Code with friends. Only visible if your account is eligible /permissions Manage allow, ask, and deny rules for tool permissions. Opens an interactive dialog where you can view rules by scope, add or remove rules, manage working directories, and review recent auto mode denials . Alias: /allowed-tools /plan [description] Enter plan mode directly from the prompt. Pass an optional description to enter plan mode and immediately start with that task, for example /plan fix the auth bug /plugin Manage Claude Code plugins /powerup Discover Claude Code features through quick interactive lessons with animated demos /pr-comments [PR] Removed in v2.1.91. Ask Claude directly to view pull request comments instead. On earlier versions, fetches and displays comments from a GitHub pull request; automatically detects the PR for the current branch, or pass a PR URL or number. Requires the gh CLI /privacy-settings View and update your privacy settings. Only available for Pro and Max plan subscribers /radio Open Claude FM lo-fi radio in your browser. Prints the stream URL when no browser is available. Not available on Bedrock, Vertex, or Foundry /recap Generate a one-line summary of the current session on demand. See Session recap for the automatic recap that appears after you’ve been away /release-notes View the changelog in an interactive version picker. Select a specific version to see its release notes, or choose to show all versions /reload-plugins Reload all active plugins to apply pending changes without restarting. Reports counts for each reloaded component and flags any load errors /remote-control Make this session available for remote control from claude.ai. Alias: /rc /remote-env Configure the default remote environment for web sessions started with --remote /rename [name] Rename the current session and show the name on the prompt bar. Without a name, auto-generates one from conversation history /resume [session] Resume a conversation by ID or name, or open the session picker. Alias: /continue /review [PR] Review a pull request locally in your current session. For a deeper cloud-based review, see /ultrareview /rewind Rewind the conversation and/or code to a previous point, or summarize from a selected message. See checkpointing . Aliases: /checkpoint , /undo /sandbox Toggle sandbox mode . Available on supported platforms only /schedule [description] Create, update, list, or run routines , which execute on Anthropic-managed cloud infrastructure. Claude walks you through the setup conversationally. Alias: /routines /scroll-speed Adjust mouse wheel scroll speed interactively, with a ruler you can scroll while the dialog is open to preview the change. Available in fullscreen rendering only and not in the JetBrains IDE terminal /security-review Analyze pending changes on the current branch for security vulnerabilities. Reviews the git diff and identifies risks like injection, auth issues, and data exposure /setup-bedrock Configure Amazon Bedrock authentication, region, and model pins through an interactive wizard. Only visible when CLAUDE_CODE_USE_BEDROCK=1 is set. First-time Bedrock users can also access this wizard from the login screen /setup-vertex Configure Google Vertex AI authentication, project, region, and model pins through an interactive wizard. Only visible when CLAUDE_CODE_USE_VERTEX=1 is set. First-time Vertex AI users can also access this wizard from the login screen /simplify [focus] Skill . Review your recently changed files for code reuse, quality, and efficiency issues, then fix them. Spawns three review agents in parallel, aggregates their findings, and applies fixes. Pass text to focus on specific concerns: /simplify focus on memory efficiency /skills List available skills . Press t to sort by token count. Press Space to hide a skill from Claude or the / menu , then Enter to save /stats Alias for /usage . Opens on the Stats tab /status Open the Settings interface (Status tab) showing version, model, account, and connectivity. Works while Claude is responding, without waiting for the current response to finish /statusline Configure Claude Code’s status line . Describe what you want, or run without arguments to auto-configure from your shell prompt /stickers Order Claude Code stickers /stop Stop the current background session . Only available while attached to a background session; the transcript and any worktree are kept. To detach without stopping, use /exit or press ← /tasks List and manage background tasks. Also available as /bashes /team-onboarding Generate a team onboarding guide from your Claude Code usage history. Claude analyzes your sessions, commands, and MCP server usage from the past 30 days and produces a markdown guide a teammate can paste as a first message to get set up quickly. For claude.ai subscribers on Pro, Max, Team, and Enterprise plans, also returns a share link teammates can open directly in Claude Code /teleport Pull a Claude Code on the web session into this terminal: opens a picker, then fetches the branch and conversation. Also available as /tp . Requires a claude.ai subscription /terminal-setup Configure terminal keybindings for Shift+Enter and other shortcuts. Only visible in terminals that need it, like VS Code, Cursor, Windsurf, Alacritty, or Zed /theme Change the color theme. Includes an auto option that matches your terminal’s light or dark background, light and dark variants, colorblind-accessible (daltonized) themes, ANSI themes that use your terminal’s color palette, and any custom themes from ~/.claude/themes/ or plugins. Select New custom theme… to create one /tui [default|fullscreen] Set the terminal UI renderer and relaunch into it with your conversation intact. fullscreen enables the flicker-free alt-screen renderer . With no argument, prints the active renderer /ultraplan Draft a plan in an ultraplan session, review it in your browser, then execute remotely or send it back to your terminal /ultrareview [PR] Run a deep, multi-agent code review in a cloud sandbox with ultrareview . Includes 3 free runs on Pro and Max, then requires extra usage /upgrade Open the upgrade page to switch to a higher plan tier /usage Show session cost, plan usage limits, and activity stats. See the cost tracking guide for subscription-specific details. /cost and /stats are aliases /vim Removed in v2.1.92. To toggle between Vim and Normal editing modes, use /config → Editor mode /voice [hold|tap|off] Toggle voice dictation , or enable it in a specific mode. Requires a Claude.ai account /web-setup Connect your GitHub account to Claude Code on the web using your local gh CLI credentials. /schedule prompts for this automatically if GitHub isn’t connected ​ MCP prompts MCP servers can expose prompts that appear as commands. These use the format /mcp____ and are dynamically discovered from connected servers. See MCP prompts for details. ​ See also Skills : create your own commands Interactive mode : keyboard shortcuts, Vim mode, and command history CLI reference : launch-time flags Was this page helpful? Yes No CLI reference Environment variables Ctrl +I Assistant Responses are generated using AI and may contain mistakes.