Documentation 2026-06-13 21:59 UTC to 2026-06-15 23:02 UTC

37 37 

38The following diagram shows the message stream from a single `query()` call, with token usage reported at each step and the cumulative estimate at the end:38The following diagram shows the message stream from a single `query()` call, with token usage reported at each step and the cumulative estimate at the end:

39 39 

40<img src="https://mintcdn.com/claude-code/Dujg43sxTkuhSELI/images/agent-sdk/message-usage-flow.svg?fit=max&auto=format&n=Dujg43sxTkuhSELI&q=85&s=c542f51ff58547ef9c0e57b16d03f33c" alt="Diagram showing a query producing two steps of messages. Step 1 has four assistant messages sharing the same ID and usage (count once), Step 2 has one assistant message with a new ID, and the final result message shows the estimated total_cost_usd." width="760" height="520" data-path="images/agent-sdk/message-usage-flow.svg" />40<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-sdk/message-usage-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=68497aee338e01cc745323af7aea378e" alt="Diagram showing a query producing two steps of messages. Step 1 has four assistant messages sharing the same ID and usage (count once), Step 2 has one assistant message with a new ID, and the final result message shows the estimated total_cost_usd." width="760" height="520" data-path="images/agent-sdk/message-usage-flow.svg" />

41 41 

42<Steps>42<Steps>

43 <Step title="Each step produces assistant messages">43 <Step title="Each step produces assistant messages">

20 20 

21Every hosting decision on this page follows from how the SDK runs the agent. When your code calls `query()`, the SDK spawns a separate `claude` CLI process and talks to it over stdio. That subprocess owns the shell, the working directory, and the JSONL session transcripts on local disk.21Every hosting decision on this page follows from how the SDK runs the agent. When your code calls `query()`, the SDK spawns a separate `claude` CLI process and talks to it over stdio. That subprocess owns the shell, the working directory, and the JSONL session transcripts on local disk.

22 22 

23<img src="https://mintcdn.com/claude-code/Akpoo6g0xDlAmvHv/images/agent-sdk/hosting-subprocess.svg?fit=max&auto=format&n=Akpoo6g0xDlAmvHv&q=85&s=d348cc9687d47e0bc954075fd88d0e60" alt="Request flow: client to your app, which spawns a claude CLI subprocess over stdio inside the container; the subprocess writes to local disk and calls api.anthropic.com over HTTPS" width="920" height="220" data-path="images/agent-sdk/hosting-subprocess.svg" />23<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-sdk/hosting-subprocess.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=9dac857ca9d3b1410c3734900c386004" alt="Request flow: client to your app, which spawns a claude CLI subprocess over stdio inside the container; the subprocess writes to local disk and calls api.anthropic.com over HTTPS" width="920" height="220" data-path="images/agent-sdk/hosting-subprocess.svg" />

24 24 

25One agent session maps to one subprocess. Running N concurrent sessions means N subprocesses, each with its own process tree and transcript file. By default they all inherit your application's working directory, so pass `cwd` on each `query()` call when sessions need separate filesystems:25One agent session maps to one subprocess. Running N concurrent sessions means N subprocesses, each with its own process tree and transcript file. By default they all inherit your application's working directory, so pass `cwd` on each `query()` call when sessions need separate filesystems:

26 26 

6 6 

7> Build production AI agents with Claude Code as a library7> Build production AI agents with Claude Code as a library

8 8 

9<Note>

10 Starting June 15, 2026, Agent SDK and `claude -p` usage on subscription plans will draw from a new monthly Agent SDK credit, separate from your interactive usage limits. See [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for details.

11</Note>

12 

13Build AI agents that autonomously read files, run commands, search the web, edit code, and more. The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript.9Build AI agents that autonomously read files, run commands, search the web, edit code, and more. The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript.

14 10 

15<CodeGroup>11<CodeGroup>

143 143 

144### Generate a long-lived token144### Generate a long-lived token

145 145 

146<Note>

147 Starting June 15, 2026, Agent SDK and `claude -p` usage on subscription plans will draw from a new monthly Agent SDK credit, separate from your interactive usage limits. See [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for details.

148</Note>

149 

150For CI pipelines, scripts, or other environments where interactive browser login isn't available, generate a one-year OAuth token with `claude setup-token`:146For CI pipelines, scripts, or other environments where interactive browser login isn't available, generate a one-year OAuth token with `claude setup-token`:

151 147 

152```bash theme={null}148```bash theme={null}

782 782 

783### Still stuck?783### Still stuck?

784 784 

785* Search or file a bug on [GitHub Issues](https://github.com/anthropics/claude-code/issues)785* Open Help → Get Support in the desktop app, or visit the [Claude support center](https://support.claude.com/) directly

786* Visit the [Claude support center](https://support.claude.com/)786* For problems that also reproduce in the standalone `claude` CLI, search or file a bug on [GitHub Issues](https://github.com/anthropics/claude-code/issues)

787 787 

788When filing a bug, include your desktop app version, your operating system, the exact error message, and relevant logs. On macOS, check Console.app. On Windows, check Event Viewer → Windows Logs → Application.788When reporting a problem, include your desktop app version, your operating system, the exact error message, and relevant logs. On macOS, check Console.app. On Windows, check Event Viewer → Windows Logs → Application.

229 229 

230Each feature loads at different points in your session. The tabs below explain when each one loads and what goes into context.230Each feature loads at different points in your session. The tabs below explain when each one loads and what goes into context.

231 231 

232<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="Context loading: CLAUDE.md loads at session start and stays in every request. MCP tool names load at start with full schemas deferred until use. Skills load descriptions at start, full content on invocation. Subagents get isolated context. Hooks run externally." width="720" height="410" data-path="images/context-loading.svg" />232<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/context-loading.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=aab139e750494a237ae2e0c8f9139b0a" alt="Context loading: CLAUDE.md loads at session start and stays in every request. MCP tool names load at start with full schemas deferred until use. Skills load descriptions at start, full content on invocation. Subagents get isolated context. Hooks run externally." width="720" height="382" data-path="images/context-loading.svg" />

233 233 

234<Tabs>234<Tabs>

235 <Tab title="CLAUDE.md">235 <Tab title="CLAUDE.md">

6 6 

7> Use the Agent SDK to run Claude Code programmatically from the CLI, Python, or TypeScript.7> Use the Agent SDK to run Claude Code programmatically from the CLI, Python, or TypeScript.

8 8 

9<Note>

10 Starting June 15, 2026, Agent SDK and `claude -p` usage on subscription plans will draw from a new monthly Agent SDK credit, separate from your interactive usage limits. See [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for details.

11</Note>

12 

13The [Agent SDK](/en/agent-sdk/overview) gives you the same tools, agent loop, and context management that power Claude Code. It's available as a CLI for scripts and CI/CD, or as [Python](/en/agent-sdk/python) and [TypeScript](/en/agent-sdk/typescript) packages for full programmatic control.9The [Agent SDK](/en/agent-sdk/overview) gives you the same tools, agent loop, and context management that power Claude Code. It's available as a CLI for scripts and CI/CD, or as [Python](/en/agent-sdk/python) and [TypeScript](/en/agent-sdk/typescript) packages for full programmatic control.

14 10 

15To run Claude Code in non-interactive mode, pass `-p` with your prompt and any [CLI options](/en/cli-reference):11To run Claude Code in non-interactive mode, pass `-p` with your prompt and any [CLI options](/en/cli-reference):

6 6 

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

8 8 

9<Note>

10 Starting June 15, 2026, Agent SDK and `claude -p` usage on subscription plans will draw from a new monthly Agent SDK credit, separate from your interactive usage limits. See [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for details.

11</Note>

12 

13## Legal agreements9## Legal agreements

14 10 

15### License11### License

22 <Tab title="Native Install (Recommended)">22 <Tab title="Native Install (Recommended)">

23 **macOS, Linux, WSL:**23 **macOS, Linux, WSL:**

24 24 

25 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}25 ```bash theme={null}

26 curl -fsSL https://claude.ai/install.sh | bash26 curl -fsSL https://claude.ai/install.sh | bash

27 ```27 ```

28 28 

29 **Windows PowerShell:**29 **Windows PowerShell:**

30 30 

31 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}31 ```powershell theme={null}

32 irm https://claude.ai/install.ps1 | iex32 irm https://claude.ai/install.ps1 | iex

33 ```33 ```

34 34 

35 **Windows CMD:**35 **Windows CMD:**

36 36 

37 ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}37 ```batch theme={null}

38 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd38 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

39 ```39 ```

40 40 

48 </Tab>48 </Tab>

49 49 

50 <Tab title="Homebrew">50 <Tab title="Homebrew">

51 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}51 ```bash theme={null}

52 brew install --cask claude-code52 brew install --cask claude-code

53 ```53 ```

54 54 

60 </Tab>60 </Tab>

61 61 

62 <Tab title="WinGet">62 <Tab title="WinGet">

63 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}63 ```powershell theme={null}

64 winget install Anthropic.ClaudeCode64 winget install Anthropic.ClaudeCode

65 ```65 ```

66 66 

122 122 

123A deny or ask rule whose tool name matches no known tool produces a startup warning to catch typos. Tool names containing `_` or `*` are exempt from the check.123A deny or ask rule whose tool name matches no known tool produces a startup warning to catch typos. Tool names containing `_` or `*` are exempt from the check.

124 124 

125The label shown for a tool in the transcript and permission dialog can differ from its canonical name. For example, the tool labeled `Stop Task` in the transcript has the canonical name `TaskStop`. Permission rules and [hook matchers](/en/hooks) match the canonical name only, so a rule written as `Stop Task` does not match. For deny and ask rules, the startup warning above catches the mismatch. Use the canonical names listed in the [tools reference](/en/tools-reference).

126 

125## Tool-specific permission rules127## Tool-specific permission rules

126 128 

127### Bash129### Bash

29 <Tab title="Native Install (Recommended)">29 <Tab title="Native Install (Recommended)">

30 **macOS, Linux, WSL:**30 **macOS, Linux, WSL:**

31 31 

32 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}32 ```bash theme={null}

33 curl -fsSL https://claude.ai/install.sh | bash33 curl -fsSL https://claude.ai/install.sh | bash

34 ```34 ```

35 35 

36 **Windows PowerShell:**36 **Windows PowerShell:**

37 37 

38 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}38 ```powershell theme={null}

39 irm https://claude.ai/install.ps1 | iex39 irm https://claude.ai/install.ps1 | iex

40 ```40 ```

41 41 

42 **Windows CMD:**42 **Windows CMD:**

43 43 

44 ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}44 ```batch theme={null}

45 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd45 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

46 ```46 ```

47 47 

55 </Tab>55 </Tab>

56 56 

57 <Tab title="Homebrew">57 <Tab title="Homebrew">

58 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}58 ```bash theme={null}

59 brew install --cask claude-code59 brew install --cask claude-code

60 ```60 ```

61 61 

67 </Tab>67 </Tab>

68 68 

69 <Tab title="WinGet">69 <Tab title="WinGet">

70 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}70 ```powershell theme={null}

71 winget install Anthropic.ClaudeCode71 winget install Anthropic.ClaudeCode

72 ```72 ```

73 73 

22| `TLS connect error` or `SSL/TLS secure channel` | [Update CA certificates](#tls-or-ssl-connection-errors) |22| `TLS connect error` or `SSL/TLS secure channel` | [Update CA certificates](#tls-or-ssl-connection-errors) |

23| `Failed to fetch version` or can't reach download server | [Check network and proxy settings](#check-network-connectivity) |23| `Failed to fetch version` or can't reach download server | [Check network and proxy settings](#check-network-connectivity) |

24| `irm is not recognized` or `&& is not valid` | [Use the right command for your shell](#wrong-install-command-on-windows) |24| `irm is not recognized` or `&& is not valid` | [Use the right command for your shell](#wrong-install-command-on-windows) |

25| `Cask 'claude-code' is unavailable: No Cask with this name exists` | [Update Homebrew](#homebrew-cask-unavailable-or-outdated) |

25| `'bash' is not recognized as the name of a cmdlet` | [Use the Windows installer command](#wrong-install-command-on-windows) |26| `'bash' is not recognized as the name of a cmdlet` | [Use the Windows installer command](#wrong-install-command-on-windows) |

26| `Claude Code on Windows requires either Git for Windows (for bash) or PowerShell` | [Install a shell](#claude-code-on-windows-requires-either-git-for-windows-for-bash-or-powershell) |27| `Claude Code on Windows requires either Git for Windows (for bash) or PowerShell` | [Install a shell](#claude-code-on-windows-requires-either-git-for-windows-for-bash-or-powershell) |

27| `Claude Code does not support 32-bit Windows` | [Open Windows PowerShell, not the x86 entry](#claude-code-does-not-support-32-bit-windows) |28| `Claude Code does not support 32-bit Windows` | [Open Windows PowerShell, not the x86 entry](#claude-code-does-not-support-32-bit-windows) |

376 winget install Anthropic.ClaudeCode377 winget install Anthropic.ClaudeCode

377 ```378 ```

378 379 

380### Homebrew cask unavailable or outdated

381 

382Homebrew reports `Error: Cask 'claude-code' is unavailable: No Cask with this name exists` when your local copy of the Homebrew cask index predates the cask's publication. Refresh the index and retry:

383 

384```bash theme={null}

385brew update

386brew install --cask claude-code

387```

388 

389If Homebrew installs an older Claude Code version than you expect, the same stale index is usually the cause. The `claude-code` cask tracks the stable channel and is typically about one week behind the latest release; for the newest version run `brew install --cask claude-code@latest` instead. See [Configure release channel](/en/setup#configure-release-channel) for the difference between the two casks.

390 

379### TLS or SSL connection errors391### TLS or SSL connection errors

380 392 

381Errors 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.393Errors 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.