Documentation 2026-10-29 23:57 UTC to 2026-10-30 23:01 UTC

77* **Python:** check message types with `isinstance()` against classes imported from `claude_agent_sdk` (for example, `isinstance(message, ResultMessage)`).77* **Python:** check message types with `isinstance()` against classes imported from `claude_agent_sdk` (for example, `isinstance(message, ResultMessage)`).

78* **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`.78* **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`.

79 79 

80> **Example: Check message types and handle results**80> [accordion] Example: Check message types and handle results

81>81>

82> ```python Python theme={null}82> ```python Python theme={null}

83> import asyncio83> import asyncio

273* **`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](https://code.claude.com/docs/en/agent-sdk/hooks.md).273* **`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](https://code.claude.com/docs/en/agent-sdk/hooks.md).

274* **Manual compaction:** Send `/compact` as a prompt string to trigger compaction on demand. Commands sent this way are ordinary SDK inputs. See [dispatch commands by name](https://code.claude.com/docs/en/agent-sdk/skills.md#dispatch-commands-by-name).274* **Manual compaction:** Send `/compact` as a prompt string to trigger compaction on demand. Commands sent this way are ordinary SDK inputs. See [dispatch commands by name](https://code.claude.com/docs/en/agent-sdk/skills.md#dispatch-commands-by-name).

275 275 

276> **Example: Summarization instructions in CLAUDE.md**276> [accordion] Example: Summarization instructions in CLAUDE.md

277>277>

278> 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.278> 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.

279>279>

42 42 

43Python examples on this page that make HTTP requests use [httpx](https://www.python-httpx.org/). Add it with the package manager your project uses:43Python examples on this page that make HTTP requests use [httpx](https://www.python-httpx.org/). Add it with the package manager your project uses:

44 44 

45**Python (uv)**45> [tab] Python (uv)

46 46>

47```bash theme={null}47> ```bash theme={null}

48uv add httpx48> uv add httpx

49```49> ```

50 

51**Python (pip)**

52 50 

53```bash theme={null}51> [tab] Python (pip)

54pip install httpx52>

55```53> ```bash theme={null}

54> pip install httpx

55> ```

56 56 

57### Weather tool example57### Weather tool example

58 58 

198 198 

199Combine this snippet with the tool and server definitions from the [weather tool example](#weather-tool-example) in one file, `weather.py` or `weather.ts`, then run it from your terminal:199Combine this snippet with the tool and server definitions from the [weather tool example](#weather-tool-example) in one file, `weather.py` or `weather.ts`, then run it from your terminal:

200 200 

201**TypeScript**201> [tab] TypeScript

202 202>

203```bash theme={null}203> ```bash theme={null}

204npx tsx weather.ts204> npx tsx weather.ts

205```205> ```

206 

207**Python (uv)**

208 

209```bash theme={null}

210uv run weather.py

211```

212 

213**Python (pip)**

214 206 

215Activate the virtual environment where you installed the SDK, then run:207> [tab] Python (uv)

208>

209> ```bash theme={null}

210> uv run weather.py

211> ```

216 212 

217```bash theme={null}213> [tab] Python (pip)

218python weather.py214>

219```215> Activate the virtual environment where you installed the SDK, then run:

216>

217> ```bash theme={null}

218> python weather.py

219> ```

220 220 

221Claude calls `get_temperature` and the script prints a one-line answer with the current temperature in San Francisco.221Claude calls `get_temperature` and the script prints a one-line answer with the current temperature in San Francisco.

222 222 

585>585>

586> Open your utility file (`utils.py` or `utils.ts`) in your IDE or editor before running the script. You'll see the file update in real-time as the agent adds doc comments, then revert back to the original when you choose to rewind.586> Open your utility file (`utils.py` or `utils.ts`) in your IDE or editor before running the script. You'll see the file update in real-time as the agent adds doc comments, then revert back to the original when you choose to rewind.

587 587 

588**Python**588> [tab] Python

589 589>

590```bash theme={null}590> ```bash theme={null}

591python try_checkpointing.py591> python try_checkpointing.py

592```592> ```

593 

594**TypeScript**

595 593 

596```bash theme={null}594> [tab] TypeScript

597npx tsx try_checkpointing.ts595>

598```596> ```bash theme={null}

597> npx tsx try_checkpointing.ts

598> ```

599 599 

600You'll see the agent add doc comments, then a prompt asking if you want to rewind. If you choose yes, the file is restored to its original state.600You'll see the agent add doc comments, then a prompt asking if you want to rewind. If you choose yes, the file is restored to its original state.

601 601 

386 386 

387Use the `env` field to pass API keys, tokens, and other credentials to the MCP server:387Use the `env` field to pass API keys, tokens, and other credentials to the MCP server:

388 388 

389**In code**389> [tab] In code

390 390>

391```typescript TypeScript hidelines={1,-1} theme={null}391> ```typescript TypeScript hidelines={1,-1} theme={null}

392const _ = {392> const _ = {

393 options: {393> options: {

394 mcpServers: {394> mcpServers: {

395 "api-server": {395> "api-server": {

396 command: "npx",396> command: "npx",

397 args: ["-y", "@your-org/api-mcp-server"],397> args: ["-y", "@your-org/api-mcp-server"],

398 env: {398> env: {

399 API_KEY: process.env.API_KEY399> API_KEY: process.env.API_KEY

400 }400> }

401 }401> }

402 },402> },

403 allowedTools: ["mcp__api-server__*"]403> allowedTools: ["mcp__api-server__*"]

404 }404> }

405};405> };

406```406> ```

407 407>

408```python Python theme={null}408> ```python Python theme={null}

409options = ClaudeAgentOptions(409> options = ClaudeAgentOptions(

410 mcp_servers={410> mcp_servers={

411 "api-server": {411> "api-server": {

412 "command": "npx",412> "command": "npx",

413 "args": ["-y", "@your-org/api-mcp-server"],413> "args": ["-y", "@your-org/api-mcp-server"],

414 "env": {"API_KEY": os.environ["API_KEY"]},414> "env": {"API_KEY": os.environ["API_KEY"]},

415 }415> }

416 },416> },

417 allowed_tools=["mcp__api-server__*"],417> allowed_tools=["mcp__api-server__*"],

418)418> )

419```419> ```

420 420 

421**.mcp.json**421> [tab] .mcp.json

422 422>

423```json theme={null}423> ```json theme={null}

424{424> {

425 "mcpServers": {425> "mcpServers": {

426 "api-server": {426> "api-server": {

427 "command": "npx",427> "command": "npx",

428 "args": ["-y", "@your-org/api-mcp-server"],428> "args": ["-y", "@your-org/api-mcp-server"],

429 "env": {429> "env": {

430 "API_KEY": "${API_KEY}"430> "API_KEY": "${API_KEY}"

431 }431> }

432 }432> }

433 }433> }

434}434> }

435```435> ```

436 436>

437The `${API_KEY}` syntax expands environment variables at runtime.437> The `${API_KEY}` syntax expands environment variables at runtime.

438 438 

439### HTTP headers for remote servers439### HTTP headers for remote servers

440 440 

441For HTTP and SSE servers, pass authentication headers directly in the server configuration:441For HTTP and SSE servers, pass authentication headers directly in the server configuration:

442 442 

443**In code**443> [tab] In code

444 444>

445```typescript TypeScript hidelines={1,-1} theme={null}445> ```typescript TypeScript hidelines={1,-1} theme={null}

446const _ = {446> const _ = {

447 options: {447> options: {

448 mcpServers: {448> mcpServers: {

449 "secure-api": {449> "secure-api": {

450 type: "http",450> type: "http",

451 url: "https://api.example.com/mcp",451> url: "https://api.example.com/mcp",

452 headers: {452> headers: {

453 Authorization: `Bearer ${process.env.API_TOKEN}`453> Authorization: `Bearer ${process.env.API_TOKEN}`

454 }454> }

455 }455> }

456 },456> },

457 allowedTools: ["mcp__secure-api__*"]457> allowedTools: ["mcp__secure-api__*"]

458 }458> }

459};459> };

460```460> ```

461 461>

462```python Python theme={null}462> ```python Python theme={null}

463options = ClaudeAgentOptions(463> options = ClaudeAgentOptions(

464 mcp_servers={464> mcp_servers={

465 "secure-api": {465> "secure-api": {

466 "type": "http",466> "type": "http",

467 "url": "https://api.example.com/mcp",467> "url": "https://api.example.com/mcp",

468 "headers": {"Authorization": f"Bearer {os.environ['API_TOKEN']}"},468> "headers": {"Authorization": f"Bearer {os.environ['API_TOKEN']}"},

469 }469> }

470 },470> },

471 allowed_tools=["mcp__secure-api__*"],471> allowed_tools=["mcp__secure-api__*"],

472)472> )

473```473> ```

474 474 

475**.mcp.json**475> [tab] .mcp.json

476 476>

477```json theme={null}477> ```json theme={null}

478{478> {

479 "mcpServers": {479> "mcpServers": {

480 "secure-api": {480> "secure-api": {

481 "type": "http",481> "type": "http",

482 "url": "https://api.example.com/mcp",482> "url": "https://api.example.com/mcp",

483 "headers": {483> "headers": {

484 "Authorization": "Bearer ${API_TOKEN}"484> "Authorization": "Bearer ${API_TOKEN}"

485 }485> }

486 }486> }

487 }487> }

488}488> }

489```489> ```

490 490>

491The `${API_TOKEN}` syntax expands environment variables at runtime.491> The `${API_TOKEN}` syntax expands environment variables at runtime.

492 492 

493For a complete working example of a remote server authenticated with headers, see [List issues from a repository](#list-issues-from-a-repository).493For a complete working example of a remote server authenticated with headers, see [List issues from a repository](#list-issues-from-a-repository).

494 494 

163 163 

164You can set the permission mode once when starting a query, or change it dynamically while the session is active.164You can set the permission mode once when starting a query, or change it dynamically while the session is active.

165 165 

166**At query time**166> [tab] At query time

167 167>

168Pass `permission_mode` (Python) or `permissionMode` (TypeScript) when creating a query.168> Pass `permission_mode` (Python) or `permissionMode` (TypeScript) when creating a query.

169 169>

170```python Python theme={null}170> ```python Python theme={null}

171import asyncio171> import asyncio

172from claude_agent_sdk import query, ClaudeAgentOptions172> from claude_agent_sdk import query, ClaudeAgentOptions

173 173>

174 174>

175async def main():175> async def main():

176 async for message in query(176> async for message in query(

177 prompt="Help me refactor this code",177> prompt="Help me refactor this code",

178 options=ClaudeAgentOptions(178> options=ClaudeAgentOptions(

179 permission_mode="default", # Set the mode here179> permission_mode="default", # Set the mode here

180 ),180> ),

181 ):181> ):

182 if hasattr(message, "result"):182> if hasattr(message, "result"):

183 print(message.result)183> print(message.result)

184 184>

185 185>

186asyncio.run(main())186> asyncio.run(main())

187```187> ```

188 188>

189```typescript TypeScript theme={null}189> ```typescript TypeScript theme={null}

190import { query } from "@anthropic-ai/claude-agent-sdk";190> import { query } from "@anthropic-ai/claude-agent-sdk";

191 191>

192async function main() {192> async function main() {

193 for await (const message of query({193> for await (const message of query({

194 prompt: "Help me refactor this code",194> prompt: "Help me refactor this code",

195 options: {195> options: {

196 permissionMode: "default" // Set the mode here196> permissionMode: "default" // Set the mode here

197 }197> }

198 })) {198> })) {

199 if ("result" in message) {199> if ("result" in message) {

200 console.log(message.result);200> console.log(message.result);

201 }201> }

202 }202> }

203}203> }

204 204>

205main();205> main();

206```206> ```

207 

208**During streaming**

209 

210Call `set_permission_mode()` (Python) or `setPermissionMode()` (TypeScript) to change the mode mid-session. The new mode takes effect immediately for all subsequent tool requests. This lets you start restrictive and loosen permissions as trust builds, for example switching to `acceptEdits` after reviewing Claude's initial approach.

211 

212```python Python theme={null}

213import asyncio

214from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

215 

216 

217async def main():

218 async with ClaudeSDKClient(

219 options=ClaudeAgentOptions(

220 permission_mode="default", # Start in default mode

221 )

222 ) as client:

223 await client.query("Help me refactor this code")

224 

225 # Change mode dynamically mid-session

226 await client.set_permission_mode("acceptEdits")

227 

228 # Process messages with the new permission mode

229 async for message in client.receive_response():

230 if hasattr(message, "result"):

231 print(message.result)

232 

233 

234asyncio.run(main())

235```

236 207 

237```typescript TypeScript theme={null}208> [tab] During streaming

238import { query } from "@anthropic-ai/claude-agent-sdk";209>

239 210> Call `set_permission_mode()` (Python) or `setPermissionMode()` (TypeScript) to change the mode mid-session. The new mode takes effect immediately for all subsequent tool requests. This lets you start restrictive and loosen permissions as trust builds, for example switching to `acceptEdits` after reviewing Claude's initial approach.

240async function main() {211>

241 const q = query({212> ```python Python theme={null}

242 prompt: "Help me refactor this code",213> import asyncio

243 options: {214> from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

244 permissionMode: "default" // Start in default mode215>

245 }216>

246 });217> async def main():

247 218> async with ClaudeSDKClient(

248 // Change mode dynamically mid-session219> options=ClaudeAgentOptions(

249 await q.setPermissionMode("acceptEdits");220> permission_mode="default", # Start in default mode

250 221> )

251 // Process messages with the new permission mode222> ) as client:

252 for await (const message of q) {223> await client.query("Help me refactor this code")

253 if ("result" in message) {224>

254 console.log(message.result);225> # Change mode dynamically mid-session

255 }226> await client.set_permission_mode("acceptEdits")

256 }227>

257}228> # Process messages with the new permission mode

258 229> async for message in client.receive_response():

259main();230> if hasattr(message, "result"):

260```231> print(message.result)

232>

233>

234> asyncio.run(main())

235> ```

236>

237> ```typescript TypeScript theme={null}

238> import { query } from "@anthropic-ai/claude-agent-sdk";

239>

240> async function main() {

241> const q = query({

242> prompt: "Help me refactor this code",

243> options: {

244> permissionMode: "default" // Start in default mode

245> }

246> });

247>

248> // Change mode dynamically mid-session

249> await q.setPermissionMode("acceptEdits");

250>

251> // Process messages with the new permission mode

252> for await (const message of q) {

253> if ("result" in message) {

254> console.log(message.result);

255> }

256> }

257> }

258>

259> main();

260> ```

261 261 

262### Mode details262### Mode details

263 263 

36 36 

37Install the Agent SDK package for your language:37Install the Agent SDK package for your language:

38 38 

39**TypeScript (new project)**39> [tab] TypeScript (new project)

40 40>

41```bash theme={null}41> ```bash theme={null}

42npm init -y42> npm init -y

43npm pkg set type=module43> npm pkg set type=module

44npm install @anthropic-ai/claude-agent-sdk44> npm install @anthropic-ai/claude-agent-sdk

45npm install --save-dev tsx45> npm install --save-dev tsx

46```46> ```

47 47>

48Setting `"type": "module"` in `package.json` lets your agent script use top-level `await`, and [tsx](https://tsx.hirok.io) runs TypeScript files directly. npm prints `added N packages` when the install succeeds.48> Setting `"type": "module"` in `package.json` lets your agent script use top-level `await`, and [tsx](https://tsx.hirok.io) runs TypeScript files directly. npm prints `added N packages` when the install succeeds.

49 

50**TypeScript (existing project)**

51 

52```bash theme={null}

53npm install @anthropic-ai/claude-agent-sdk

54npm install --save-dev tsx

55```

56 

57[tsx](https://tsx.hirok.io) runs TypeScript files directly. If your project uses CommonJS, name your agent script `agent.mts` instead of `agent.ts`. The `.mts` extension makes tsx treat the file as an ES module, so top-level `await` works without converting your whole project to ES modules. Use `agent.mts` in place of `agent.ts` in the create and run steps later in this quickstart.

58 

59**Python (uv)**

60 

61[Install uv](https://docs.astral.sh/uv/), a fast Python package manager that handles virtual environments automatically. Then initialize a project and add the SDK:

62 

63```bash theme={null}

64uv init

65uv add claude-agent-sdk

66```

67 

68**Python (pip)**

69 

70Create and activate a virtual environment, then install the package.

71 

72On macOS or Linux:

73 

74```bash theme={null}

75python3 -m venv .venv

76source .venv/bin/activate

77pip install claude-agent-sdk

78```

79 49 

80On Windows:50> [tab] TypeScript (existing project)

51>

52> ```bash theme={null}

53> npm install @anthropic-ai/claude-agent-sdk

54> npm install --save-dev tsx

55> ```

56>

57> [tsx](https://tsx.hirok.io) runs TypeScript files directly. If your project uses CommonJS, name your agent script `agent.mts` instead of `agent.ts`. The `.mts` extension makes tsx treat the file as an ES module, so top-level `await` works without converting your whole project to ES modules. Use `agent.mts` in place of `agent.ts` in the create and run steps later in this quickstart.

81 58 

82```powershell theme={null}59> [tab] Python (uv)

83py -m venv .venv60>

84.venv\Scripts\Activate.ps161> [Install uv](https://docs.astral.sh/uv/), a fast Python package manager that handles virtual environments automatically. Then initialize a project and add the SDK:

85pip install claude-agent-sdk62>

86```63> ```bash theme={null}

64> uv init

65> uv add claude-agent-sdk

66> ```

87 67 

88If PowerShell blocks `Activate.ps1` with an execution policy error, run `Set-ExecutionPolicy -Scope Process RemoteSigned` first.68> [tab] Python (pip)

69>

70> Create and activate a virtual environment, then install the package.

71>

72> On macOS or Linux:

73>

74> ```bash theme={null}

75> python3 -m venv .venv

76> source .venv/bin/activate

77> pip install claude-agent-sdk

78> ```

79>

80> On Windows:

81>

82> ```powershell theme={null}

83> py -m venv .venv

84> .venv\Scripts\Activate.ps1

85> pip install claude-agent-sdk

86> ```

87>

88> If PowerShell blocks `Activate.ps1` with an execution policy error, run `Set-ExecutionPolicy -Scope Process RemoteSigned` first.

89 89 

90> [!NOTE]90> [!NOTE]

91>91>

98 98 

99Get an API key from the [Claude Console](https://platform.claude.com/), then set it as an environment variable in the shell where you'll run your agent:99Get an API key from the [Claude Console](https://platform.claude.com/), then set it as an environment variable in the shell where you'll run your agent:

100 100 

101**macOS / Linux**101> [tab] macOS / Linux

102 102>

103```bash theme={null}103> ```bash theme={null}

104export ANTHROPIC_API_KEY=your-api-key104> export ANTHROPIC_API_KEY=your-api-key

105```105> ```

106 

107**Windows (PowerShell)**

108 106 

109```powershell theme={null}107> [tab] Windows (PowerShell)

110$env:ANTHROPIC_API_KEY = "your-api-key"108>

111```109> ```powershell theme={null}

110> $env:ANTHROPIC_API_KEY = "your-api-key"

111> ```

112 112 

113The SDK reads the key from the environment of the process that runs your agent; it doesn't load `.env` files automatically. If you keep the key in a `.env` file, load it yourself, for example with the `dotenv` package, before calling the SDK.113The SDK reads the key from the environment of the process that runs your agent; it doesn't load `.env` files automatically. If you keep the key in a `.env` file, load it yourself, for example with the `dotenv` package, before calling the SDK.

114 114 

224 224 

225Your agent is ready. Run it with the following command:225Your agent is ready. Run it with the following command:

226 226 

227**TypeScript**227> [tab] TypeScript

228 228>

229```bash theme={null}229> ```bash theme={null}

230npx tsx agent.ts230> npx tsx agent.ts

231```231> ```

232 232>

233If you named your script `agent.mts`, run `npx tsx agent.mts` instead.233> If you named your script `agent.mts`, run `npx tsx agent.mts` instead.

234 

235**Python (uv)**

236 

237```bash theme={null}

238uv run agent.py

239```

240 

241**Python (pip)**

242 234 

243With your virtual environment still activated:235> [tab] Python (uv)

236>

237> ```bash theme={null}

238> uv run agent.py

239> ```

244 240 

245```bash theme={null}241> [tab] Python (pip)

246python agent.py242>

247```243> With your virtual environment still activated:

244>

245> ```bash theme={null}

246> python agent.py

247> ```

248 248 

249As it works, the agent prints its reasoning and each tool it calls, ending with `Done: success`. After running, check `utils.py`. You'll see defensive code handling empty lists and null users. Your agent autonomously:249As it works, the agent prints its reasoning and each tool it calls, ending with `Done: success`. After running, check `utils.py`. You'll see defensive code handling empty lists and null users. Your agent autonomously:

250 250 

470 470 

471Each SDK surfaces the rejection differently:471Each SDK surfaces the rejection differently:

472 472 

473**TypeScript**473> [tab] TypeScript

474 474>

475The TypeScript SDK throws an `Error` stating the rule the entry broke. For example, `skills: ["docs:*"]` throws:475> The TypeScript SDK throws an `Error` stating the rule the entry broke. For example, `skills: ["docs:*"]` throws:

476 476>

477```text theme={null}477> ```text theme={null}

478Invalid skill name "docs:*": wildcard-suffix names are not allowed; list each skill by its exact name.478> Invalid skill name "docs:*": wildcard-suffix names are not allowed; list each skill by its exact name.

479```479> ```

480 480>

481An empty name reports `Skill names must be non-empty strings.`481> An empty name reports `Skill names must be non-empty strings.`

482 482>

483Before TypeScript Agent SDK 0.3.221, the SDK didn't run this check.483> Before TypeScript Agent SDK 0.3.221, the SDK didn't run this check.

484 

485**Python**

486 

487The Python SDK raises `ValueError` stating the rule the entry broke. For example, `skills=["docs:*"]` raises:

488 

489```text theme={null}

490ValueError: Invalid skill name 'docs:*': wildcard-suffix names are not allowed; list each skill by its exact name.

491```

492 

493An empty name reports `Skill names must be non-empty strings`.

494 484 

495Before Python Agent SDK 0.2.129, the SDK didn't run this check.485> [tab] Python

486>

487> The Python SDK raises `ValueError` stating the rule the entry broke. For example, `skills=["docs:*"]` raises:

488>

489> ```text theme={null}

490> ValueError: Invalid skill name 'docs:*': wildcard-suffix names are not allowed; list each skill by its exact name.

491> ```

492>

493> An empty name reports `Skill names must be non-empty strings`.

494>

495> Before Python Agent SDK 0.2.129, the SDK didn't run this check.

496 496 

497### Additional troubleshooting497### Additional troubleshooting

498 498 

16 16 

17Consider a recipe app where an agent searches the web and brings back recipes. Without structured outputs, you get free-form text that you'd need to parse yourself. With structured outputs, you define the shape you want and get typed data you can use directly in your app.17Consider a recipe app where an agent searches the web and brings back recipes. Without structured outputs, you get free-form text that you'd need to parse yourself. With structured outputs, you define the shape you want and get typed data you can use directly in your app.

18 18 

19> **Without structured outputs**19> [accordion] Without structured outputs

20>20>

21> ```text theme={null}21> ```text theme={null}

22> Here's a classic chocolate chip cookie recipe!22> Here's a classic chocolate chip cookie recipe!

32>32>

33> To use this in your app, you'd need to parse out the title, convert "15 minutes" to a number, separate ingredients from instructions, and handle inconsistent formatting across responses.33> To use this in your app, you'd need to parse out the title, convert "15 minutes" to a number, separate ingredients from instructions, and handle inconsistent formatting across responses.

34 34 

35> **With structured outputs**35> [accordion] With structured outputs

36>36>

37> ```jsonc theme={null}37> ```jsonc theme={null}

38> {38> {

225 225 

226The `ask_user` and `askUser` helpers in the following snippets stand in for your application's own prompt UI.226The `ask_user` and `askUser` helpers in the following snippets stand in for your application's own prompt UI.

227 227 

228**Approve**228> [tab] Approve

229 229>

230The user approves the action as-is. Pass through the `input` from your callback unchanged and the tool executes exactly as Claude requested.230> The user approves the action as-is. Pass through the `input` from your callback unchanged and the tool executes exactly as Claude requested.

231 231>

232```python Python theme={null}232> ```python Python theme={null}

233async def can_use_tool(tool_name, input_data, context):233> async def can_use_tool(tool_name, input_data, context):

234 print(f"Claude wants to use {tool_name}")234> print(f"Claude wants to use {tool_name}")

235 approved = await ask_user("Allow this action?")235> approved = await ask_user("Allow this action?")

236 236>

237 if approved:237> if approved:

238 return PermissionResultAllow(updated_input=input_data)238> return PermissionResultAllow(updated_input=input_data)

239 return PermissionResultDeny(message="User declined")239> return PermissionResultDeny(message="User declined")

240```240> ```

241 241>

242```typescript TypeScript theme={null}242> ```typescript TypeScript theme={null}

243canUseTool: async (toolName, input) => {243> canUseTool: async (toolName, input) => {

244 console.log(`Claude wants to use ${toolName}`);244> console.log(`Claude wants to use ${toolName}`);

245 const approved = await askUser("Allow this action?");245> const approved = await askUser("Allow this action?");

246 246>

247 if (approved) {247> if (approved) {

248 return { behavior: "allow", updatedInput: input };248> return { behavior: "allow", updatedInput: input };

249 }249> }

250 return { behavior: "deny", message: "User declined" };250> return { behavior: "deny", message: "User declined" };

251};251> };

252```252> ```

253 253 

254**Approve with changes**254> [tab] Approve with changes

255 255>

256The user approves but wants to modify the request first. You can change the input before the tool executes. Claude sees the result but isn't told you changed anything. Useful for sanitizing parameters, adding constraints, or scoping access.256> The user approves but wants to modify the request first. You can change the input before the tool executes. Claude sees the result but isn't told you changed anything. Useful for sanitizing parameters, adding constraints, or scoping access.

257 257>

258```python Python theme={null}258> ```python Python theme={null}

259async def can_use_tool(tool_name, input_data, context):259> async def can_use_tool(tool_name, input_data, context):

260 if tool_name == "Bash":260> if tool_name == "Bash":

261 # User approved, but scope all commands to sandbox261> # User approved, but scope all commands to sandbox

262 sandboxed_input = {**input_data}262> sandboxed_input = {**input_data}

263 sandboxed_input["command"] = input_data["command"].replace(263> sandboxed_input["command"] = input_data["command"].replace(

264 "/tmp", "/tmp/sandbox"264> "/tmp", "/tmp/sandbox"

265 )265> )

266 return PermissionResultAllow(updated_input=sandboxed_input)266> return PermissionResultAllow(updated_input=sandboxed_input)

267 return PermissionResultAllow(updated_input=input_data)267> return PermissionResultAllow(updated_input=input_data)

268```268> ```

269 269>

270```typescript TypeScript theme={null}270> ```typescript TypeScript theme={null}

271canUseTool: async (toolName, input) => {271> canUseTool: async (toolName, input) => {

272 if (toolName === "Bash") {272> if (toolName === "Bash") {

273 // User approved, but scope all commands to sandbox273> // User approved, but scope all commands to sandbox

274 const sandboxedInput = {274> const sandboxedInput = {

275 ...input,275> ...input,

276 command: input.command.replace("/tmp", "/tmp/sandbox")276> command: input.command.replace("/tmp", "/tmp/sandbox")

277 };277> };

278 return { behavior: "allow", updatedInput: sandboxedInput };278> return { behavior: "allow", updatedInput: sandboxedInput };

279 }279> }

280 return { behavior: "allow", updatedInput: input };280> return { behavior: "allow", updatedInput: input };

281};281> };

282```282> ```

283 283 

284**Approve and remember**284> [tab] Approve and remember

285 285>

286The user approves and doesn't want to be asked again for this kind of call. The third callback argument carries `suggestions`, an array of ready-made [`PermissionUpdate`](https://code.claude.com/docs/en/agent-sdk/typescript#permissionupdate) entries. Echo one back in `updatedPermissions` to apply it. A suggestion with the `localSettings` destination writes the rule to `.claude/settings.local.json` so future sessions skip the prompt for matching calls.286> The user approves and doesn't want to be asked again for this kind of call. The third callback argument carries `suggestions`, an array of ready-made [`PermissionUpdate`](https://code.claude.com/docs/en/agent-sdk/typescript#permissionupdate) entries. Echo one back in `updatedPermissions` to apply it. A suggestion with the `localSettings` destination writes the rule to `.claude/settings.local.json` so future sessions skip the prompt for matching calls.

287 287>

288In TypeScript, skip the always-allow choice for a request whose options carry [`suppressAlwaysAllowRule: true`](https://code.claude.com/docs/en/agent-sdk/typescript#canusetool). The hint requires Agent SDK v0.3.268 or later, and the Python `context` doesn't carry it.288> In TypeScript, skip the always-allow choice for a request whose options carry [`suppressAlwaysAllowRule: true`](https://code.claude.com/docs/en/agent-sdk/typescript#canusetool). The hint requires Agent SDK v0.3.268 or later, and the Python `context` doesn't carry it.

289 289>

290The Python example requires `claude-agent-sdk` 0.1.80 or later.290> The Python example requires `claude-agent-sdk` 0.1.80 or later.

291 291>

292```python Python theme={null}292> ```python Python theme={null}

293async def can_use_tool(tool_name, input_data, context):293> async def can_use_tool(tool_name, input_data, context):

294 choice = await ask_user(f"Allow {tool_name}?", ["once", "always", "no"])294> choice = await ask_user(f"Allow {tool_name}?", ["once", "always", "no"])

295 295>

296 if choice == "always":296> if choice == "always":

297 persist = [297> persist = [

298 s for s in context.suggestions if s.destination == "localSettings"298> s for s in context.suggestions if s.destination == "localSettings"

299 ]299> ]

300 return PermissionResultAllow(300> return PermissionResultAllow(

301 updated_input=input_data, updated_permissions=persist301> updated_input=input_data, updated_permissions=persist

302 )302> )

303 if choice == "once":303> if choice == "once":

304 return PermissionResultAllow(updated_input=input_data)304> return PermissionResultAllow(updated_input=input_data)

305 return PermissionResultDeny(message="User declined")305> return PermissionResultDeny(message="User declined")

306```306> ```

307 307>

308```typescript TypeScript theme={null}308> ```typescript TypeScript theme={null}

309canUseTool: async (toolName, input, { suggestions = [] }) => {309> canUseTool: async (toolName, input, { suggestions = [] }) => {

310 const choice = await askUser(`Allow ${toolName}?`, ["once", "always", "no"]);310> const choice = await askUser(`Allow ${toolName}?`, ["once", "always", "no"]);

311 311>

312 if (choice === "always") {312> if (choice === "always") {

313 const persist = suggestions.filter(313> const persist = suggestions.filter(

314 (s) => s.destination === "localSettings"314> (s) => s.destination === "localSettings"

315 );315> );

316 return {316> return {

317 behavior: "allow",317> behavior: "allow",

318 updatedInput: input,318> updatedInput: input,

319 updatedPermissions: persist319> updatedPermissions: persist

320 };320> };

321 }321> }

322 if (choice === "once") {322> if (choice === "once") {

323 return { behavior: "allow", updatedInput: input };323> return { behavior: "allow", updatedInput: input };

324 }324> }

325 return { behavior: "deny", message: "User declined" };325> return { behavior: "deny", message: "User declined" };

326};326> };

327```327> ```

328 328 

329**Reject**329> [tab] Reject

330 330>

331The user doesn't want this action to happen. Block the tool and provide a message explaining why. Claude sees this message and may try a different approach.331> The user doesn't want this action to happen. Block the tool and provide a message explaining why. Claude sees this message and may try a different approach.

332 332>

333```python Python theme={null}333> ```python Python theme={null}

334async def can_use_tool(tool_name, input_data, context):334> async def can_use_tool(tool_name, input_data, context):

335 approved = await ask_user(f"Allow {tool_name}?")335> approved = await ask_user(f"Allow {tool_name}?")

336 336>

337 if not approved:337> if not approved:

338 return PermissionResultDeny(message="User rejected this action")338> return PermissionResultDeny(message="User rejected this action")

339 return PermissionResultAllow(updated_input=input_data)339> return PermissionResultAllow(updated_input=input_data)

340```340> ```

341 341>

342```typescript TypeScript theme={null}342> ```typescript TypeScript theme={null}

343canUseTool: async (toolName, input) => {343> canUseTool: async (toolName, input) => {

344 const approved = await askUser(`Allow ${toolName}?`);344> const approved = await askUser(`Allow ${toolName}?`);

345 345>

346 if (!approved) {346> if (!approved) {

347 return {347> return {

348 behavior: "deny",348> behavior: "deny",

349 message: "User rejected this action"349> message: "User rejected this action"

350 };350> };

351 }351> }

352 return { behavior: "allow", updatedInput: input };352> return { behavior: "allow", updatedInput: input };

353};353> };

354```354> ```

355 355 

356**Suggest alternative**356> [tab] Suggest alternative

357 357>

358The user doesn't want this specific action, but has a different idea. Block the tool and include guidance in your message. Claude will read this and decide how to proceed based on your feedback.358> The user doesn't want this specific action, but has a different idea. Block the tool and include guidance in your message. Claude will read this and decide how to proceed based on your feedback.

359 359>

360```python Python theme={null}360> ```python Python theme={null}

361async def can_use_tool(tool_name, input_data, context):361> async def can_use_tool(tool_name, input_data, context):

362 if tool_name == "Bash" and "rm" in input_data.get("command", ""):362> if tool_name == "Bash" and "rm" in input_data.get("command", ""):

363 # User doesn't want to delete, suggest archiving instead363> # User doesn't want to delete, suggest archiving instead

364 return PermissionResultDeny(364> return PermissionResultDeny(

365 message="User doesn't want to delete files. They asked if you could compress them into an archive instead."365> message="User doesn't want to delete files. They asked if you could compress them into an archive instead."

366 )366> )

367 return PermissionResultAllow(updated_input=input_data)367> return PermissionResultAllow(updated_input=input_data)

368```368> ```

369 369>

370```typescript TypeScript theme={null}370> ```typescript TypeScript theme={null}

371canUseTool: async (toolName, input) => {371> canUseTool: async (toolName, input) => {

372 if (toolName === "Bash" && input.command.includes("rm")) {372> if (toolName === "Bash" && input.command.includes("rm")) {

373 // User doesn't want to delete, suggest archiving instead373> // User doesn't want to delete, suggest archiving instead

374 return {374> return {

375 behavior: "deny",375> behavior: "deny",

376 message:376> message:

377 "User doesn't want to delete files. They asked if you could compress them into an archive instead."377> "User doesn't want to delete files. They asked if you could compress them into an archive instead."

378 };378> };

379 }379> }

380 return { behavior: "allow", updatedInput: input };380> return { behavior: "allow", updatedInput: input };

381};381> };

382```382> ```

383 383 

384**Redirect entirely**384> [tab] Redirect entirely

385 385>

386For a complete change of direction (not just a nudge), use [streaming input](https://code.claude.com/docs/en/agent-sdk/streaming-vs-single-mode.md) to send Claude a new instruction directly. This bypasses the current tool request and gives Claude entirely new instructions to follow.386> For a complete change of direction (not just a nudge), use [streaming input](https://code.claude.com/docs/en/agent-sdk/streaming-vs-single-mode.md) to send Claude a new instruction directly. This bypasses the current tool request and gives Claude entirely new instructions to follow.

387 387 

388## Handle clarifying questions388## Handle clarifying questions

389 389 

13| [Subagents](https://code.claude.com/docs/en/sub-agents.md) | 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 |13| [Subagents](https://code.claude.com/docs/en/sub-agents.md) | 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 |

14| [Agent view](https://code.claude.com/docs/en/agent-view.md) | 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 |14| [Agent view](https://code.claude.com/docs/en/agent-view.md) | 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 |

15| [Agent teams](https://code.claude.com/docs/en/agent-teams.md) | 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 |15| [Agent teams](https://code.claude.com/docs/en/agent-teams.md) | 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 |

16| [Projects](https://code.claude.com/docs/en/claude-projects.md) | One ongoing conversation at claude.ai/code or in the desktop app. Claude starts parallel sessions called threads, in the cloud or, when you ask, on your computer through Remote Control, gives each one the project's instructions, and shows you which ones need you. Public beta on Pro and Max | The work spans many tasks over days or weeks, should keep running when your machine is off, and you'd rather describe it once than dispatch and track each session |16| [Projects](https://code.claude.com/docs/en/claude-projects.md) | One ongoing conversation at claude.ai/code or in the desktop app. Claude starts parallel sessions called threads, in the cloud or, when you ask, on your computer through Remote Control. It gives each one the project's instructions and shows you which ones need you. Public beta on Pro, Max, and Ultra | The work spans many tasks over days or weeks, should keep running when your machine is off, and you'd rather describe it once than dispatch and track each session |

17| [Dynamic workflows](https://code.claude.com/docs/en/workflows.md) | A script that runs many subagents and cross-checks their results, for work too big to coordinate one turn at a time or that needs more than a single pass | A job outgrows a handful of subagents, or you want findings verified against each other: a codebase-wide audit, a 500-file migration, cross-checked research, or a plan drafted from several angles |17| [Dynamic workflows](https://code.claude.com/docs/en/workflows.md) | A script that runs many subagents and cross-checks their results, for work too big to coordinate one turn at a time or that needs more than a single pass | A job outgrows a handful of subagents, or you want findings verified against each other: a codebase-wide audit, a 500-file migration, cross-checked research, or a plan drafted from several angles |

18 18 

19In every approach the workers are Claude sessions. To involve a different tool, expose it to Claude as an [MCP server](https://code.claude.com/docs/en/mcp.md).19In every approach the workers are Claude sessions. To involve a different tool, expose it to Claude as an [MCP server](https://code.claude.com/docs/en/mcp.md).

8 8 

9> [!NOTE]9> [!NOTE]

10>10>

11> Artifacts are available on Pro, Max, Team, and Enterprise plans and require a session signed in with [`/login`](https://code.claude.com/docs/en/setup#authenticate). See [Availability](#availability) for the full set of requirements.11> Artifacts are available on Pro, Max, Ultra, Team, and Enterprise plans and require a session signed in with [`/login`](https://code.claude.com/docs/en/setup#authenticate). See [Availability](#availability) for the full set of requirements.

12 12 

13An [artifact](https://claude.com/features/artifacts) is a live, interactive web page that Claude Code publishes from your session to a private URL on claude.ai. You open it in a browser, and it updates in place as the session continues. Share it from the page header when you want someone else to see it too.13An [artifact](https://claude.com/features/artifacts) is a live, interactive web page that Claude Code publishes from your session to a private URL on claude.ai. You open it in a browser, and it updates in place as the session continues. Share it from the page header when you want someone else to see it too.

14 14 

197 197 

198## Pull live data with MCP connectors198## Pull live data with MCP connectors

199 199 

200An artifact can call [MCP connectors](https://code.claude.com/docs/en/mcp.md#use-mcp-servers-from-claude-ai) each time someone views it, so the page shows current data rather than a snapshot from the session that built it. Connector calls from artifacts are available on Pro, Max, Team, and Enterprise plans and require Claude Code v2.1.209 or later. On earlier versions, Claude publishes the page with whatever data the session gathered while building it.200An artifact can call [MCP connectors](https://code.claude.com/docs/en/mcp.md#use-mcp-servers-from-claude-ai) each time someone views it, so the page shows current data rather than a snapshot from the session that built it. Connector calls from artifacts are available on Pro, Max, Ultra, Team, and Enterprise plans and require Claude Code v2.1.209 or later. On earlier versions, Claude publishes the page with whatever data the session gathered while building it.

201 201 

202To create a connector-backed page, name the connector and the data you want in your prompt:202To create a connector-backed page, name the connector and the data you want in your prompt:

203 203 

314 314 

315> [!NOTE]315> [!NOTE]

316>316>

317> Templates are in beta. They're on by default on Pro, Max, and Team plans. On Enterprise plans, an Owner [turns each template on](https://support.claude.com/en/articles/16994751-artifacts-admin-guide-for-team-and-enterprise-plans) under **Organization settings > Artifacts**. If your organization has the Slides template turned off, `/slides` doesn't appear; if it has the Design template turned off, `/design` doesn't draft designs. Both commands require Claude Code v2.1.265 or later and a session where [artifacts are available](#availability).317> Templates are in beta. They're on by default on Pro, Max, Ultra, and Team plans. On Enterprise plans, an Owner [turns each template on](https://support.claude.com/en/articles/16994751-artifacts-admin-guide-for-team-and-enterprise-plans) under **Organization settings > Artifacts**. If your organization has the Slides template turned off, `/slides` doesn't appear; if it has the Design template turned off, `/design` doesn't draft designs. Both commands require Claude Code v2.1.265 or later and a session where [artifacts are available](#availability).

318 318 

319### Make a slide deck319### Make a slide deck

320 320 

368 368 

369| Requirement | Available when |369| Requirement | Available when |

370| :- | :- |370| :- | :- |

371| Plan | Pro, Max, Team, or Enterprise. On Pro and Max plans, artifacts are private to you until you share them, and no admin management applies. On Team and Enterprise plans, artifacts are on by default, and an Owner can [turn them off for the organization](#manage-artifacts-for-your-organization) in claude.ai admin settings. |371| Plan | Pro, Max, Ultra, Team, or Enterprise. On Pro, Max, and Ultra plans, artifacts are private to you until you share them, and no admin management applies. On Team and Enterprise plans, artifacts are on by default, and an Owner can [turn them off for the organization](#manage-artifacts-for-your-organization) in claude.ai admin settings. |

372| Authentication | The session is backed by a claude.ai account: sign in with `/login` in the CLI or desktop app. Claude Tag sessions need no sign-in step. Sessions using an API key, [gateway token](https://code.claude.com/docs/en/llm-gateway), or cloud-provider credential cannot publish. |372| Authentication | The session is backed by a claude.ai account: sign in with `/login` in the CLI or desktop app. Claude Tag sessions need no sign-in step. Sessions using an API key, [gateway token](https://code.claude.com/docs/en/llm-gateway), or cloud-provider credential cannot publish. |

373| Model provider | Anthropic API. Not available on [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md), [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md), or [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md). |373| Model provider | Anthropic API. Not available on [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md), [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md), or [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md). |

374| Organization policy | Customer-managed encryption keys (CMEK), HIPAA, and [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md) are not enabled for the organization. |374| Organization policy | Customer-managed encryption keys (CMEK), HIPAA, and [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md) are not enabled for the organization. |

23 23 

24You can authenticate with any of these account types:24You can authenticate with any of these account types:

25 25 

26* **Claude Pro or Max subscription**: log in with your claude.ai account. Subscribe at [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_pro_max).26* **Claude Pro, Max, or Ultra subscription**: log in with your claude.ai account. Subscribe at [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_pro_max).

27* **Claude for Teams or Enterprise**: log in with the claude.ai account your team admin invited you to.27* **Claude for Teams or Enterprise**: log in with the claude.ai account your team admin invited you to.

28* **Claude Console**: log in with your Console credentials. Your admin must have [invited you](#claude-console-authentication) first. You can sign in with or without [creating an API key](#sign-in-without-an-api-key).28* **Claude Console**: log in with your Console credentials. Your admin must have [invited you](#claude-console-authentication) first. You can sign in with or without [creating an API key](#sign-in-without-an-api-key).

29* **Cloud providers**: if your organization uses [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md), [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md), or [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md), set the required environment variables before running `claude`, or select **3rd-party platform** at the login prompt, which launches an interactive setup wizard for Bedrock and Vertex AI. No browser login is needed.29* **Cloud providers**: if your organization uses [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock.md), [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai.md), or [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md), set the required environment variables before running `claude`, or select **3rd-party platform** at the login prompt, which launches an interactive setup wizard for Bedrock and Vertex AI. No browser login is needed.

2534. [`apiKeyHelper`](https://code.claude.com/docs/en/settings-reference#apikeyhelper) script output. Use this for dynamic or rotating credentials, such as short-lived tokens fetched from a vault.2534. [`apiKeyHelper`](https://code.claude.com/docs/en/settings-reference#apikeyhelper) script output. Use this for dynamic or rotating credentials, such as short-lived tokens fetched from a vault.

2545. `CLAUDE_CODE_OAUTH_TOKEN` environment variable. A long-lived OAuth token generated by [`claude setup-token`](#generate-a-long-lived-token). Use this for CI pipelines and scripts where browser login isn't available. If you run `/login` while the variable is set, Claude Code switches the current session to the new login, but reads the variable again in every new session until you remove it from your shell profile or the `env` block of a [settings file](https://code.claude.com/docs/en/settings.md).2545. `CLAUDE_CODE_OAUTH_TOKEN` environment variable. A long-lived OAuth token generated by [`claude setup-token`](#generate-a-long-lived-token). Use this for CI pipelines and scripts where browser login isn't available. If you run `/login` while the variable is set, Claude Code switches the current session to the new login, but reads the variable again in every new session until you remove it from your shell profile or the `env` block of a [settings file](https://code.claude.com/docs/en/settings.md).

2556. Anthropic profile and federation credentials, the credentials that the `ant` CLI and Workload Identity Federation use. A profile that `ant auth login` wrote ranks here only when you name it in `ANTHROPIC_PROFILE`; otherwise it ranks below `/login`. See [Anthropic profiles and federation credentials](#anthropic-profiles-and-federation-credentials).2556. Anthropic profile and federation credentials, the credentials that the `ant` CLI and Workload Identity Federation use. A profile that `ant auth login` wrote ranks here only when you name it in `ANTHROPIC_PROFILE`; otherwise it ranks below `/login`. See [Anthropic profiles and federation credentials](#anthropic-profiles-and-federation-credentials).

2567. Subscription OAuth credentials from `/login`. This is the default for Claude Pro, Max, Team, and Enterprise users.2567. Subscription OAuth credentials from `/login`. This is the default for Claude Pro, Max, Ultra, Team, and Enterprise users.

257 257 

258A signed-in [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway) session sits outside this list: it is a provider selection like Amazon Bedrock or Google Cloud's Agent Platform, and it outranks them. When a gateway session exists, the CLI authenticates with the gateway token even if `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, or `CLAUDE_CODE_USE_FOUNDRY` is set, and credential sources above such as the bearer token, API key, `apiKeyHelper`, and profiles are not used.258A signed-in [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway) session sits outside this list: it is a provider selection like Amazon Bedrock or Google Cloud's Agent Platform, and it outranks them. When a gateway session exists, the CLI authenticates with the gateway token even if `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, or `CLAUDE_CODE_USE_FOUNDRY` is set, and credential sources above such as the bearer token, API key, `apiKeyHelper`, and profiles are not used.

259 259 

300 300 

301The command opens the same browser authorization flow as `/login`, and the token prints to the terminal after you approve access in the browser. It does not save the token anywhere; copy it and set it as the `CLAUDE_CODE_OAUTH_TOKEN` environment variable wherever you want to authenticate:301The command opens the same browser authorization flow as `/login`, and the token prints to the terminal after you approve access in the browser. It does not save the token anywhere; copy it and set it as the `CLAUDE_CODE_OAUTH_TOKEN` environment variable wherever you want to authenticate:

302 302 

303**macOS, Linux, WSL**303> [tab] macOS, Linux, WSL

304 304>

305```bash theme={null}305> ```bash theme={null}

306export CLAUDE_CODE_OAUTH_TOKEN=your-token306> export CLAUDE_CODE_OAUTH_TOKEN=your-token

307```307> ```

308 308 

309**Windows PowerShell**309> [tab] Windows PowerShell

310 310>

311```powershell theme={null}311> ```powershell theme={null}

312$env:CLAUDE_CODE_OAUTH_TOKEN = "your-token"312> $env:CLAUDE_CODE_OAUTH_TOKEN = "your-token"

313```313> ```

314 314 

315**Windows CMD**315> [tab] Windows CMD

316 316>

317```batch theme={null}317> ```batch theme={null}

318set CLAUDE_CODE_OAUTH_TOKEN=your-token318> set CLAUDE_CODE_OAUTH_TOKEN=your-token

319```319> ```

320 320 

321This token authenticates with your Claude subscription and requires a Pro, Max, Team, or Enterprise plan. It can only make model requests, so it can't establish [Remote Control](https://code.claude.com/docs/en/remote-control.md) sessions or fetch [claude.ai connectors](https://code.claude.com/docs/en/mcp.md#use-mcp-servers-from-claude-ai). MCP servers you configure locally still work.321This token authenticates with your Claude subscription and requires a Pro, Max, Ultra, Team, or Enterprise plan. It can only make model requests, so it can't establish [Remote Control](https://code.claude.com/docs/en/remote-control.md) sessions or fetch [claude.ai connectors](https://code.claude.com/docs/en/mcp.md#use-mcp-servers-from-claude-ai). MCP servers you configure locally still work.

322 322 

323[Bare mode](https://code.claude.com/docs/en/headless.md#start-faster-with-bare-mode) does not read `CLAUDE_CODE_OAUTH_TOKEN`. If your script passes `--bare`, authenticate with `ANTHROPIC_API_KEY` or an `apiKeyHelper` instead.323[Bare mode](https://code.claude.com/docs/en/headless.md#start-faster-with-bare-mode) does not read `CLAUDE_CODE_OAUTH_TOKEN`. If your script passes `--bare`, authenticate with `ANTHROPIC_API_KEY` or an `apiKeyHelper` instead.

43 43 

44## Why the notice appears44## Why the notice appears

45 45 

46[Server-side classifier review](https://code.claude.com/docs/en/permission-modes.md#server-side-classifier-review) lists which sessions ask the server for the classifier checks. Pro, Max, and Team plans never show the notice. When it appears, the usual causes are:46On a Pro, Max, Ultra, or Team plan, you never see the notice. To find out which sessions ask the server for the classifier checks, see [Server-side classifier review](https://code.claude.com/docs/en/permission-modes.md#server-side-classifier-review). If you see the notice, check for these usual causes:

47 47 

48* **An LLM gateway or proxy is in the path**: one that strips or rewrites request headers, drops request fields it doesn't recognize, or edits responses. The server then never receives the request for checks, or Claude Code never receives the results. When your configuration or the responses identify the gateway, the notice names it.48* **An LLM gateway or proxy is in the path**: one that strips or rewrites request headers, drops request fields it doesn't recognize, or edits responses. The server then never receives the request for checks, or Claude Code never receives the results. When your configuration or the responses identify the gateway, the notice names it.

49* **Server-side checks haven't reached your platform, region, or credential yet**: whether a platform or region performs them depends on that platform's rollout. If you see the notice with no gateway or proxy in the path and it keeps appearing, this is the likely cause. To confirm, contact support or your company's admin, or report it with `/feedback`.49* **Server-side checks haven't reached your platform, region, or credential yet**: whether a platform or region performs them depends on that platform's rollout. If you see the notice with no gateway or proxy in the path and it keeps appearing, this is the likely cause. To confirm, contact support or your company's admin, or report it with `/feedback`.

161 161 

162> [!NOTE]162> [!NOTE]

163>163>

164> `/auto-mode-setup` is available on Pro, Max, Team, and Enterprise plans and with a Claude Console API key. On a Pro, Max, or Team plan, you need v2.1.228 or later, or v2.1.233 or later on native Windows. On an Enterprise plan or with a Claude Console API key, you need v2.1.283 or later. If the command is missing from your session, see [`/auto-mode-setup` returns "Unknown command"](#auto-mode-setup-returns-unknown-command).164> `/auto-mode-setup` is available on Pro, Max, Ultra, Team, and Enterprise plans and with a Claude Console API key. On a Pro, Max, Ultra, or Team plan, you need v2.1.228 or later, or v2.1.233 or later on native Windows. On an Enterprise plan or with a Claude Console API key, you need v2.1.283 or later. If the command is missing from your session, see [`/auto-mode-setup` returns "Unknown command"](#auto-mode-setup-returns-unknown-command).

165 165 

166### What `/auto-mode-setup` reads166### What `/auto-mode-setup` reads

167 167 

489 489 

490With a 1M-token window on most current models and compaction near the top of it, you'll rarely run out of context. You can still *pay* for context you don't need, though. Every request sends the whole conversation, so a session that's collected three unrelated tasks re-reads all three on every turn of the fourth. That's [discounted while the cache is warm](https://code.claude.com/docs/en/costs.md#why-usage-climbs-in-a-long-session) and full price once it expires.490With a 1M-token window on most current models and compaction near the top of it, you'll rarely run out of context. You can still *pay* for context you don't need, though. Every request sends the whole conversation, so a session that's collected three unrelated tasks re-reads all three on every turn of the fourth. That's [discounted while the cache is warm](https://code.claude.com/docs/en/costs.md#why-usage-climbs-in-a-long-session) and full price once it expires.

491 491 

492[`/usage`](https://code.claude.com/docs/en/costs) is the first place to look. On Pro, Max, Team, and Enterprise it breaks your usage down by skill, subagent, plugin, and MCP server. It also flags patterns like long context or frequent cache misses once one of them passes 10% of your usage. From there, the usual fixes:492[`/usage`](https://code.claude.com/docs/en/costs) is the first place to look. On Pro, Max, Ultra, Team, and Enterprise it breaks your usage down by skill, subagent, plugin, and MCP server. It also flags patterns like long context or frequent cache misses once one of them passes 10% of your usage. From there, the usual fixes:

493 493 

494* `/clear` between unrelated tasks. It costs nothing, and it means the next task doesn't keep paying for the previous one's history. `/clear oauth-migration` names the session you're leaving, so you can come back to it later.494* `/clear` between unrelated tasks. It costs nothing, and it means the next task doesn't keep paying for the previous one's history. `/clear oauth-migration` names the session you're leaving, so you can come back to it later.

495* `/compact` with a focus, like `/compact keep the API changes and the test commands`. On a long session `/compact` is itself a big request, since it reads the whole conversation to summarize it, and even more so once the cache has expired.495* `/compact` with a focus, like `/compact keep the API changes and the test commands`. On a long session `/compact` is itself a big request, since it reads the whole conversation to summarize it, and even more so once the cache has expired.

24 24 

25Each supported channel is a plugin that requires [Bun](https://bun.sh). For a hands-on demo of the plugin flow before connecting a real platform, try the [fakechat quickstart](#quickstart).25Each supported channel is a plugin that requires [Bun](https://bun.sh). For a hands-on demo of the plugin flow before connecting a real platform, try the [fakechat quickstart](#quickstart).

26 26 

27**Telegram**27> [tab] Telegram

28 

29View the full [Telegram plugin source](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram).

30 

31**1. Create a Telegram bot**

32 

33Open [BotFather](https://t.me/BotFather) in Telegram and send `/newbot`. Give it a display name and a unique username ending in `bot`. Copy the token BotFather returns.

34 

35**2. Install the plugin**

36 

37Start Claude Code by running `claude` in your terminal, then enter this at its prompt:

38 

39```

40/plugin install telegram@claude-plugins-official

41```

42 

43If the install fails, match the message Claude Code reports:

44 

45* `Marketplace "claude-plugins-official" not found`: add the marketplace with `/plugin marketplace add anthropics/claude-plugins-official`, then retry the install.

46* `Plugin "<name>" not found in marketplace "claude-plugins-official"`: your local copy of the marketplace catalog may be out of date. Refresh it with `/plugin marketplace update claude-plugins-official`, then retry the install. If the retry prints the same message, see [Plugin not found in marketplace](https://code.claude.com/docs/en/plugins/troubleshooting.md#plugin-not-found-in-marketplace).

47 

48When the install asks for an installation scope, choose the user scope option so the plugin is available across all your projects. Check the install summary: if it reports `Run /reload-plugins to apply.`, see [Apply plugin changes without restarting](https://code.claude.com/docs/en/plugins/cli-reference.md#reload-plugins) to make the plugin's configure command available.

49 

50**3. Configure your token**

51 

52Run the configure command with the token from BotFather:

53 

54```

55/telegram:configure <token>

56```

57 

58This saves it to `~/.claude/channels/telegram/.env`. You can also set `TELEGRAM_BOT_TOKEN` in your shell environment before launching Claude Code.

59 

60**4. Restart with channels enabled**

61 

62Exit Claude Code and restart with the channel flag. This starts the Telegram plugin, which begins polling for messages from your bot:

63 

64```bash theme={null}

65claude --channels plugin:telegram@claude-plugins-official

66```

67 

68**5. Pair your account**

69 

70Open Telegram and send any message to your bot. The bot replies with a pairing code.

71 

72> [!NOTE]

73>28>

74> If your bot doesn't respond, make sure Claude Code is running with `--channels` from the previous step. The bot can only reply while the channel is active.29> View the full [Telegram plugin source](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram).

75 

76Back in Claude Code, run:

77 

78```

79/telegram:access pair <code>

80```

81 

82Then lock down access so only your account can send messages:

83 

84```

85/telegram:access policy allowlist

86```

87 

88**Discord**

89 

90View the full [Discord plugin source](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord).

91 

92**1. Create a Discord bot**

93 

94Go to the [Discord Developer Portal](https://discord.com/developers/applications), click **New Application**, and name it. In the **Bot** section, create a username, then click **Reset Token** and copy the token.

95 

96**2. Enable Message Content Intent**

97 

98In your bot's settings, scroll to **Privileged Gateway Intents** and enable **Message Content Intent**.

99 

100**3. Invite the bot to your server**

101 

102Go to **OAuth2 > URL Generator**. Select the `bot` scope and enable these permissions:

103 

104* View Channels

105* Send Messages

106* Send Messages in Threads

107* Read Message History

108* Attach Files

109* Add Reactions

110 

111Open the generated URL to add the bot to your server.

112 

113**4. Install the plugin**

114 

115Start Claude Code by running `claude` in your terminal, then enter this at its prompt:

116 

117```

118/plugin install discord@claude-plugins-official

119```

120 

121If the install fails, match the message Claude Code reports:

122 

123* `Marketplace "claude-plugins-official" not found`: add the marketplace with `/plugin marketplace add anthropics/claude-plugins-official`, then retry the install.

124* `Plugin "<name>" not found in marketplace "claude-plugins-official"`: your local copy of the marketplace catalog may be out of date. Refresh it with `/plugin marketplace update claude-plugins-official`, then retry the install. If the retry prints the same message, see [Plugin not found in marketplace](https://code.claude.com/docs/en/plugins/troubleshooting.md#plugin-not-found-in-marketplace).

125 

126When the install asks for an installation scope, choose the user scope option so the plugin is available across all your projects. Check the install summary: if it reports `Run /reload-plugins to apply.`, see [Apply plugin changes without restarting](https://code.claude.com/docs/en/plugins/cli-reference.md#reload-plugins) to make the plugin's configure command available.

127 

128**5. Configure your token**

129 

130Run the configure command with the bot token you copied:

131 

132```

133/discord:configure <token>

134```

135 

136This saves it to `~/.claude/channels/discord/.env`. You can also set `DISCORD_BOT_TOKEN` in your shell environment before launching Claude Code.

137 

138**6. Restart with channels enabled**

139 

140Exit Claude Code and restart with the channel flag. This connects the Discord plugin so your bot can receive and respond to messages:

141 

142```bash theme={null}

143claude --channels plugin:discord@claude-plugins-official

144```

145 

146**7. Pair your account**

147 

148DM your bot on Discord. The bot replies with a pairing code.

149 

150> [!NOTE]

151>30>

152> If your bot doesn't respond, make sure Claude Code is running with `--channels` from the previous step. The bot can only reply while the channel is active.31> **1. Create a Telegram bot**

153 

154Back in Claude Code, run:

155 

156```

157/discord:access pair <code>

158```

159 

160Then lock down access so only your account can send messages:

161 

162```

163/discord:access policy allowlist

164```

165 

166**iMessage**

167 

168View the full [iMessage plugin source](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/imessage).

169 

170The iMessage channel reads your Messages database directly and sends replies through AppleScript. It requires macOS and needs no bot token or external service.

171 

172**1. Grant Full Disk Access**

173 

174The Messages database at `~/Library/Messages/chat.db` is protected by macOS. The first time the server reads it, macOS prompts for access: click **Allow**. The prompt names whichever app launched Bun, such as Terminal, iTerm, or your IDE.

175 

176If the prompt doesn't appear or you clicked Don't Allow, grant access manually under **System Settings > Privacy & Security > Full Disk Access** and add your terminal. Without this, the server exits immediately with `authorization denied`.

177 

178**2. Install the plugin**

179 

180Start Claude Code by running `claude` in your terminal, then enter this at its prompt:

181 

182```

183/plugin install imessage@claude-plugins-official

184```

185 

186If the install fails, match the message Claude Code reports:

187 

188* `Marketplace "claude-plugins-official" not found`: add the marketplace with `/plugin marketplace add anthropics/claude-plugins-official`, then retry the install.

189* `Plugin "<name>" not found in marketplace "claude-plugins-official"`: your local copy of the marketplace catalog may be out of date. Refresh it with `/plugin marketplace update claude-plugins-official`, then retry the install. If the retry prints the same message, see [Plugin not found in marketplace](https://code.claude.com/docs/en/plugins/troubleshooting.md#plugin-not-found-in-marketplace).

190 

191When the install asks for an installation scope, choose the user scope option so the plugin is available across all your projects.

192 

193If the install summary reports `Run /reload-plugins to apply.`, you don't need to act on it here, because restarting in the next step picks up the plugin.

194 

195**3. Restart with channels enabled**

196 

197Exit Claude Code and restart with the channel flag:

198 

199```bash theme={null}

200claude --channels plugin:imessage@claude-plugins-official

201```

202 

203**4. Text yourself**

204 

205Open Messages on any device signed into your Apple ID and send a message to yourself. It reaches Claude immediately: self-chat bypasses access control with no setup.

206 

207> [!NOTE]

208>32>

209> The first reply Claude sends triggers a macOS Automation prompt asking if your terminal can control Messages. Click **OK**.33> Open [BotFather](https://t.me/BotFather) in Telegram and send `/newbot`. Give it a display name and a unique username ending in `bot`. Copy the token BotFather returns.

210 34>

211**5. Allow other senders**35> **2. Install the plugin**

212 36>

213By default, only your own messages pass through. To let another contact reach Claude, add their handle:37> Start Claude Code by running `claude` in your terminal, then enter this at its prompt:

38>

39> ```

40> /plugin install telegram@claude-plugins-official

41> ```

42>

43> If the install fails, match the message Claude Code reports:

44>

45> * `Marketplace "claude-plugins-official" not found`: add the marketplace with `/plugin marketplace add anthropics/claude-plugins-official`, then retry the install.

46> * `Plugin "<name>" not found in marketplace "claude-plugins-official"`: your local copy of the marketplace catalog may be out of date. Refresh it with `/plugin marketplace update claude-plugins-official`, then retry the install. If the retry prints the same message, see [Plugin not found in marketplace](https://code.claude.com/docs/en/plugins/troubleshooting.md#plugin-not-found-in-marketplace).

47>

48> When the install asks for an installation scope, choose the user scope option so the plugin is available across all your projects. Check the install summary: if it reports `Run /reload-plugins to apply.`, see [Apply plugin changes without restarting](https://code.claude.com/docs/en/plugins/cli-reference.md#reload-plugins) to make the plugin's configure command available.

49>

50> **3. Configure your token**

51>

52> Run the configure command with the token from BotFather:

53>

54> ```

55> /telegram:configure <token>

56> ```

57>

58> This saves it to `~/.claude/channels/telegram/.env`. You can also set `TELEGRAM_BOT_TOKEN` in your shell environment before launching Claude Code.

59>

60> **4. Restart with channels enabled**

61>

62> Exit Claude Code and restart with the channel flag. This starts the Telegram plugin, which begins polling for messages from your bot:

63>

64> ```bash theme={null}

65> claude --channels plugin:telegram@claude-plugins-official

66> ```

67>

68> **5. Pair your account**

69>

70> Open Telegram and send any message to your bot. The bot replies with a pairing code.

71>

72> > [!NOTE]

73> >

74> > If your bot doesn't respond, make sure Claude Code is running with `--channels` from the previous step. The bot can only reply while the channel is active.

75>

76> Back in Claude Code, run:

77>

78> ```

79> /telegram:access pair <code>

80> ```

81>

82> Then lock down access so only your account can send messages:

83>

84> ```

85> /telegram:access policy allowlist

86> ```

214 87 

215```88> [tab] Discord

216/imessage:access allow +1555123456789>

217```90> View the full [Discord plugin source](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord).

91>

92> **1. Create a Discord bot**

93>

94> Go to the [Discord Developer Portal](https://discord.com/developers/applications), click **New Application**, and name it. In the **Bot** section, create a username, then click **Reset Token** and copy the token.

95>

96> **2. Enable Message Content Intent**

97>

98> In your bot's settings, scroll to **Privileged Gateway Intents** and enable **Message Content Intent**.

99>

100> **3. Invite the bot to your server**

101>

102> Go to **OAuth2 > URL Generator**. Select the `bot` scope and enable these permissions:

103>

104> * View Channels

105> * Send Messages

106> * Send Messages in Threads

107> * Read Message History

108> * Attach Files

109> * Add Reactions

110>

111> Open the generated URL to add the bot to your server.

112>

113> **4. Install the plugin**

114>

115> Start Claude Code by running `claude` in your terminal, then enter this at its prompt:

116>

117> ```

118> /plugin install discord@claude-plugins-official

119> ```

120>

121> If the install fails, match the message Claude Code reports:

122>

123> * `Marketplace "claude-plugins-official" not found`: add the marketplace with `/plugin marketplace add anthropics/claude-plugins-official`, then retry the install.

124> * `Plugin "<name>" not found in marketplace "claude-plugins-official"`: your local copy of the marketplace catalog may be out of date. Refresh it with `/plugin marketplace update claude-plugins-official`, then retry the install. If the retry prints the same message, see [Plugin not found in marketplace](https://code.claude.com/docs/en/plugins/troubleshooting.md#plugin-not-found-in-marketplace).

125>

126> When the install asks for an installation scope, choose the user scope option so the plugin is available across all your projects. Check the install summary: if it reports `Run /reload-plugins to apply.`, see [Apply plugin changes without restarting](https://code.claude.com/docs/en/plugins/cli-reference.md#reload-plugins) to make the plugin's configure command available.

127>

128> **5. Configure your token**

129>

130> Run the configure command with the bot token you copied:

131>

132> ```

133> /discord:configure <token>

134> ```

135>

136> This saves it to `~/.claude/channels/discord/.env`. You can also set `DISCORD_BOT_TOKEN` in your shell environment before launching Claude Code.

137>

138> **6. Restart with channels enabled**

139>

140> Exit Claude Code and restart with the channel flag. This connects the Discord plugin so your bot can receive and respond to messages:

141>

142> ```bash theme={null}

143> claude --channels plugin:discord@claude-plugins-official

144> ```

145>

146> **7. Pair your account**

147>

148> DM your bot on Discord. The bot replies with a pairing code.

149>

150> > [!NOTE]

151> >

152> > If your bot doesn't respond, make sure Claude Code is running with `--channels` from the previous step. The bot can only reply while the channel is active.

153>

154> Back in Claude Code, run:

155>

156> ```

157> /discord:access pair <code>

158> ```

159>

160> Then lock down access so only your account can send messages:

161>

162> ```

163> /discord:access policy allowlist

164> ```

218 165 

219Handles are phone numbers in `+country` format or Apple ID emails like `user@example.com`.166> [tab] iMessage

167>

168> View the full [iMessage plugin source](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/imessage).

169>

170> The iMessage channel reads your Messages database directly and sends replies through AppleScript. It requires macOS and needs no bot token or external service.

171>

172> **1. Grant Full Disk Access**

173>

174> The Messages database at `~/Library/Messages/chat.db` is protected by macOS. The first time the server reads it, macOS prompts for access: click **Allow**. The prompt names whichever app launched Bun, such as Terminal, iTerm, or your IDE.

175>

176> If the prompt doesn't appear or you clicked Don't Allow, grant access manually under **System Settings > Privacy & Security > Full Disk Access** and add your terminal. Without this, the server exits immediately with `authorization denied`.

177>

178> **2. Install the plugin**

179>

180> Start Claude Code by running `claude` in your terminal, then enter this at its prompt:

181>

182> ```

183> /plugin install imessage@claude-plugins-official

184> ```

185>

186> If the install fails, match the message Claude Code reports:

187>

188> * `Marketplace "claude-plugins-official" not found`: add the marketplace with `/plugin marketplace add anthropics/claude-plugins-official`, then retry the install.

189> * `Plugin "<name>" not found in marketplace "claude-plugins-official"`: your local copy of the marketplace catalog may be out of date. Refresh it with `/plugin marketplace update claude-plugins-official`, then retry the install. If the retry prints the same message, see [Plugin not found in marketplace](https://code.claude.com/docs/en/plugins/troubleshooting.md#plugin-not-found-in-marketplace).

190>

191> When the install asks for an installation scope, choose the user scope option so the plugin is available across all your projects.

192>

193> If the install summary reports `Run /reload-plugins to apply.`, you don't need to act on it here, because restarting in the next step picks up the plugin.

194>

195> **3. Restart with channels enabled**

196>

197> Exit Claude Code and restart with the channel flag:

198>

199> ```bash theme={null}

200> claude --channels plugin:imessage@claude-plugins-official

201> ```

202>

203> **4. Text yourself**

204>

205> Open Messages on any device signed into your Apple ID and send a message to yourself. It reaches Claude immediately: self-chat bypasses access control with no setup.

206>

207> > [!NOTE]

208> >

209> > The first reply Claude sends triggers a macOS Automation prompt asking if your terminal can control Messages. Click **OK**.

210>

211> **5. Allow other senders**

212>

213> By default, only your own messages pass through. To let another contact reach Claude, add their handle:

214>

215> ```

216> /imessage:access allow +15551234567

217> ```

218>

219> Handles are phone numbers in `+country` format or Apple ID emails like `user@example.com`.

220 220 

221## Quickstart221## Quickstart

222 222 

308| `channelsEnabled` | Master switch. Must be `true` for any channel to deliver messages. Blocks all channels including the development flag when off. See [Enable channels for your organization](#enable-channels-for-your-organization). | claude.ai Team and Enterprise: channels blocked. Console: channels allowed unless your organization deploys managed settings, in which case channels are blocked until this key is set |308| `channelsEnabled` | Master switch. Must be `true` for any channel to deliver messages. Blocks all channels including the development flag when off. See [Enable channels for your organization](#enable-channels-for-your-organization). | claude.ai Team and Enterprise: channels blocked. Console: channels allowed unless your organization deploys managed settings, in which case channels are blocked until this key is set |

309| `allowedChannelPlugins` | Which plugins can register once channels are enabled. Replaces the Anthropic-maintained list when set. | Anthropic default list applies |309| `allowedChannelPlugins` | Which plugins can register once channels are enabled. Replaces the Anthropic-maintained list when set. | Anthropic default list applies |

310 310 

311Pro and Max users without an organization skip these checks entirely: channels are available and users opt in per session with `--channels`.311Pro, Max, and Ultra users without an organization skip these checks entirely: channels are available and users opt in per session with `--channels`.

312 312 

313### Enable channels for your organization313### Enable channels for your organization

314 314 

39* [Google Chrome](https://www.google.com/chrome/), [Microsoft Edge](https://www.microsoft.com/edge), or another Chromium-based browser such as Brave, Arc, Vivaldi, or Opera39* [Google Chrome](https://www.google.com/chrome/), [Microsoft Edge](https://www.microsoft.com/edge), or another Chromium-based browser such as Brave, Arc, Vivaldi, or Opera

40* [Claude in Chrome extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) version 1.0.36 or later, available in the Chrome Web Store40* [Claude in Chrome extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) version 1.0.36 or later, available in the Chrome Web Store

41* [Claude Code](https://code.claude.com/docs/en/quickstart.md#step-1-install-claude-code)41* [Claude Code](https://code.claude.com/docs/en/quickstart.md#step-1-install-claude-code)

42* A direct Anthropic plan (Pro, Max, Team, or Enterprise)42* A direct Anthropic plan (Pro, Max, Ultra, Team, or Enterprise)

43 43 

44In Enterprise organizations that have HIPAA enabled, Claude in Chrome is off by default, and an [Owner](https://code.claude.com/docs/en/server-managed-settings.md#access-control) can turn it on in [**Organization settings > Claude in Chrome**](https://claude.ai/admin-settings/browser-extension). Your Business Associate Agreement (BAA) with Anthropic doesn't cover data sent to third-party sites through Claude in Chrome. See the [Implementation Guide](https://trust.anthropic.com/resources?s=l1wrssd9hsbi4gak0tp5a6\&name=%5Banthropic%5D-hipaa-ready-offering-implementation-guide) for a list of Eligible Services.44In Enterprise organizations that have HIPAA enabled, Claude in Chrome is off by default, and an [Owner](https://code.claude.com/docs/en/server-managed-settings.md#access-control) can turn it on in [**Organization settings > Claude in Chrome**](https://claude.ai/admin-settings/browser-extension). Your Business Associate Agreement (BAA) with Anthropic doesn't cover data sent to third-party sites through Claude in Chrome. See the [Implementation Guide](https://trust.anthropic.com/resources?s=l1wrssd9hsbi4gak0tp5a6\&name=%5Banthropic%5D-hipaa-ready-offering-implementation-guide) for a list of Eligible Services.

45 45 

325 325 

326**7. Deploy**326**7. Deploy**

327 327 

328**ECS Fargate**328> [tab] ECS Fargate

329 329>

330Create the cluster and a log group for the gateway's stderr, which carries both its audit events and operational logs. Retention is a separate call, and without one CloudWatch keeps the logs forever; align the 90 days with your audit retention policy:330> Create the cluster and a log group for the gateway's stderr, which carries both its audit events and operational logs. Retention is a separate call, and without one CloudWatch keeps the logs forever; align the 90 days with your audit retention policy:

331 331>

332```bash theme={null}332> ```bash theme={null}

333aws ecs create-cluster --cluster-name claude-gateway333> aws ecs create-cluster --cluster-name claude-gateway

334aws logs create-log-group --log-group-name /ecs/claude-gateway334> aws logs create-log-group --log-group-name /ecs/claude-gateway

335aws logs put-retention-policy --log-group-name /ecs/claude-gateway \335> aws logs put-retention-policy --log-group-name /ecs/claude-gateway \

336 --retention-in-days 90336> --retention-in-days 90

337```337> ```

338 338>

339Write the task definition. The task role carries the Bedrock permission and the execution role injects the secrets; use the secret ARNs from the Secrets Manager step:339> Write the task definition. The task role carries the Bedrock permission and the execution role injects the secrets; use the secret ARNs from the Secrets Manager step:

340 340>

341```json claude-gateway-task.json theme={null}341> ```json claude-gateway-task.json theme={null}

342{342> {

343 "family": "claude-gateway",343> "family": "claude-gateway",

344 "networkMode": "awsvpc",344> "networkMode": "awsvpc",

345 "requiresCompatibilities": ["FARGATE"],345> "requiresCompatibilities": ["FARGATE"],

346 "cpu": "1024",346> "cpu": "1024",

347 "memory": "2048",347> "memory": "2048",

348 "runtimePlatform": { "cpuArchitecture": "X86_64", "operatingSystemFamily": "LINUX" },348> "runtimePlatform": { "cpuArchitecture": "X86_64", "operatingSystemFamily": "LINUX" },

349 "executionRoleArn": "arn:aws:iam::<account-id>:role/claude-gateway-execution",349> "executionRoleArn": "arn:aws:iam::<account-id>:role/claude-gateway-execution",

350 "taskRoleArn": "arn:aws:iam::<account-id>:role/claude-gateway-task",350> "taskRoleArn": "arn:aws:iam::<account-id>:role/claude-gateway-task",

351 "containerDefinitions": [351> "containerDefinitions": [

352 {352> {

353 "name": "gateway",353> "name": "gateway",

354 "image": "<account-id>.dkr.ecr.<region>.amazonaws.com/claude-gateway:<version>",354> "image": "<account-id>.dkr.ecr.<region>.amazonaws.com/claude-gateway:<version>",

355 "portMappings": [{ "containerPort": 8080 }],355> "portMappings": [{ "containerPort": 8080 }],

356 "secrets": [356> "secrets": [

357 { "name": "GATEWAY_JWT_SECRET", "valueFrom": "<gateway-jwt-secret ARN>" },357> { "name": "GATEWAY_JWT_SECRET", "valueFrom": "<gateway-jwt-secret ARN>" },

358 { "name": "OIDC_CLIENT_SECRET", "valueFrom": "<gateway-oidc-client-secret ARN>" },358> { "name": "OIDC_CLIENT_SECRET", "valueFrom": "<gateway-oidc-client-secret ARN>" },

359 { "name": "GATEWAY_POSTGRES_URL", "valueFrom": "<gateway-postgres-url ARN>" }359> { "name": "GATEWAY_POSTGRES_URL", "valueFrom": "<gateway-postgres-url ARN>" }

360 ],360> ],

361 "logConfiguration": {361> "logConfiguration": {

362 "logDriver": "awslogs",362> "logDriver": "awslogs",

363 "options": {363> "options": {

364 "awslogs-group": "/ecs/claude-gateway",364> "awslogs-group": "/ecs/claude-gateway",

365 "awslogs-region": "<region>",365> "awslogs-region": "<region>",

366 "awslogs-stream-prefix": "gateway"366> "awslogs-stream-prefix": "gateway"

367 }367> }

368 }368> }

369 }369> }

370 ]370> ]

371}371> }

372```372> ```

373 373>