Anthropic - Claude Code Docs Changes 2026-02-11 00:11 UTC → 2026-04-04 03:46 UTC

14 14 

15Unlike [subagents](/en/sub-agents), which run within a single session and can only report back to the main agent, you can also interact with individual teammates directly without going through the lead.15Unlike [subagents](/en/sub-agents), which run within a single session and can only report back to the main agent, you can also interact with individual teammates directly without going through the lead.

16 16 

17<Note>

18 Agent teams require Claude Code v2.1.32 or later. Check your version with `claude --version`.

19</Note>

20 

17This page covers:21This page covers:

18 22 

19* [When to use agent teams](#when-to-use-agent-teams), including best use cases and how they compare with subagents23* [When to use agent teams](#when-to-use-agent-teams), including best use cases and how they compare with subagents

36 40 

37Both agent teams and [subagents](/en/sub-agents) let you parallelize work, but they operate differently. Choose based on whether your workers need to communicate with each other:41Both agent teams and [subagents](/en/sub-agents) let you parallelize work, but they operate differently. Choose based on whether your workers need to communicate with each other:

38 42 

43<Frame caption="Subagents only report results back to the main agent and never talk to each other. In agent teams, teammates share a task list, claim work, and communicate directly with each other.">

44 <img src="https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-light.png?fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=2f8db9b4f3705dd3ab931fbe2d96e42a" className="dark:hidden" alt="Diagram comparing subagent and agent team architectures. Subagents are spawned by the main agent, do work, and report results back. Agent teams coordinate through a shared task list, with teammates communicating directly with each other." width="4245" height="1615" data-path="images/subagents-vs-agent-teams-light.png" />

45 

46 <img src="https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-dark.png?fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=d573a037540f2ada6a9ae7d8285b46fd" className="hidden dark:block" alt="Diagram comparing subagent and agent team architectures. Subagents are spawned by the main agent, do work, and report results back. Agent teams coordinate through a shared task list, with teammates communicating directly with each other." width="4245" height="1615" data-path="images/subagents-vs-agent-teams-dark.png" />

47</Frame>

48 

39| | Subagents | Agent teams |49| | Subagents | Agent teams |

40| :---------------- | :----------------------------------------------- | :-------------------------------------------------- |50| :---------------- | :----------------------------------------------- | :-------------------------------------------------- |

41| **Context** | Own context window; results return to the caller | Own context window; fully independent |51| **Context** | Own context window; results return to the caller | Own context window; fully independent |

64 74 

65This example works well because the three roles are independent and can explore the problem without waiting on each other:75This example works well because the three roles are independent and can explore the problem without waiting on each other:

66 76 

67```77```text theme={null}

68I'm designing a CLI tool that helps developers track TODO comments across78I'm designing a CLI tool that helps developers track TODO comments across

69their codebase. Create an agent team to explore this from different angles: one79their codebase. Create an agent team to explore this from different angles: one

70teammate on UX, one on technical architecture, one playing devil's advocate.80teammate on UX, one on technical architecture, one playing devil's advocate.

72 82 

73From there, Claude creates a team with a [shared task list](/en/interactive-mode#task-list), spawns teammates for each perspective, has them explore the problem, synthesizes findings, and attempts to [clean up the team](#clean-up-the-team) when finished.83From there, Claude creates a team with a [shared task list](/en/interactive-mode#task-list), spawns teammates for each perspective, has them explore the problem, synthesizes findings, and attempts to [clean up the team](#clean-up-the-team) when finished.

74 84 

75The lead's terminal lists all teammates and what they're working on. Use Shift+Up/Down to select a teammate and message them directly.85The lead's terminal lists all teammates and what they're working on. Use Shift+Down to cycle through teammates and message them directly. After the last teammate, Shift+Down wraps back to the lead.

76 86 

77If you want each teammate in its own split pane, see [Choose a display mode](#choose-a-display-mode).87If you want each teammate in its own split pane, see [Choose a display mode](#choose-a-display-mode).

78 88 

84 94 

85Agent teams support two display modes:95Agent teams support two display modes:

86 96 

87* **In-process**: all teammates run inside your main terminal. Use Shift+Up/Down to select a teammate and type to message them directly. Works in any terminal, no extra setup required.97* **In-process**: all teammates run inside your main terminal. Use Shift+Down to cycle through teammates and type to message them directly. Works in any terminal, no extra setup required.

88* **Split panes**: each teammate gets its own pane. You can see everyone's output at once and click into a pane to interact directly. Requires tmux, or iTerm2.98* **Split panes**: each teammate gets its own pane. You can see everyone's output at once and click into a pane to interact directly. Requires tmux, or iTerm2.

89 99 

90<Note>100<Note>

91 `tmux` has known limitations on certain operating systems and traditionally works best on macOS. Using `tmux -CC` in iTerm2 is the suggested entrypoint into `tmux`.101 `tmux` has known limitations on certain operating systems and traditionally works best on macOS. Using `tmux -CC` in iTerm2 is the suggested entrypoint into `tmux`.

92</Note>102</Note>

93 103 

94The default is `"auto"`, which uses split panes if you're already running inside a tmux session, and in-process otherwise. The `"tmux"` setting enables split-pane mode and auto-detects whether to use tmux or iTerm2 based on your terminal. To override, set `teammateMode` in your [settings.json](/en/settings):104The default is `"auto"`, which uses split panes if you're already running inside a tmux session, and in-process otherwise. The `"tmux"` setting enables split-pane mode and auto-detects whether to use tmux or iTerm2 based on your terminal. To override, set `teammateMode` in your [global config](/en/settings#global-config-settings) at `~/.claude.json`:

95 105 

96```json theme={null}106```json theme={null}

97{107{

114 124 

115Claude decides the number of teammates to spawn based on your task, or you can specify exactly what you want:125Claude decides the number of teammates to spawn based on your task, or you can specify exactly what you want:

116 126 

117```127```text theme={null}

118Create a team with 4 teammates to refactor these modules in parallel.128Create a team with 4 teammates to refactor these modules in parallel.

119Use Sonnet for each teammate.129Use Sonnet for each teammate.

120```130```

123 133 

124For complex or risky tasks, you can require teammates to plan before implementing. The teammate works in read-only plan mode until the lead approves their approach:134For complex or risky tasks, you can require teammates to plan before implementing. The teammate works in read-only plan mode until the lead approves their approach:

125 135 

126```136```text theme={null}

127Spawn an architect teammate to refactor the authentication module.137Spawn an architect teammate to refactor the authentication module.

128Require plan approval before they make any changes.138Require plan approval before they make any changes.

129```139```

132 142 

133The lead makes approval decisions autonomously. To influence the lead's judgment, give it criteria in your prompt, such as "only approve plans that include test coverage" or "reject plans that modify the database schema."143The lead makes approval decisions autonomously. To influence the lead's judgment, give it criteria in your prompt, such as "only approve plans that include test coverage" or "reject plans that modify the database schema."

134 144 

135### Use delegate mode

136 

137Without delegate mode, the lead sometimes starts implementing tasks itself instead of waiting for teammates. Delegate mode prevents this by restricting the lead to coordination-only tools: spawning, messaging, shutting down teammates, and managing tasks.

138 

139This is useful when you want the lead to focus entirely on orchestration, such as breaking down work, assigning tasks, and synthesizing results, without touching code directly.

140 

141To enable it, start a team first, then press Shift+Tab to cycle into delegate mode.

142 

143### Talk to teammates directly145### Talk to teammates directly

144 146 

145Each teammate is a full, independent Claude Code session. You can message any teammate directly to give additional instructions, ask follow-up questions, or redirect their approach.147Each teammate is a full, independent Claude Code session. You can message any teammate directly to give additional instructions, ask follow-up questions, or redirect their approach.

146 148 

147* **In-process mode**: use Shift+Up/Down to select a teammate, then type to send them a message. Press Enter to view a teammate's session, then Escape to interrupt their current turn. Press Ctrl+T to toggle the task list.149* **In-process mode**: use Shift+Down to cycle through teammates, then type to send them a message. Press Enter to view a teammate's session, then Escape to interrupt their current turn. Press Ctrl+T to toggle the task list.

148* **Split-pane mode**: click into a teammate's pane to interact with their session directly. Each teammate has a full view of their own terminal.150* **Split-pane mode**: click into a teammate's pane to interact with their session directly. Each teammate has a full view of their own terminal.

149 151 

150### Assign and claim tasks152### Assign and claim tasks

162 164 

163To gracefully end a teammate's session:165To gracefully end a teammate's session:

164 166 

165```167```text theme={null}

166Ask the researcher teammate to shut down168Ask the researcher teammate to shut down

167```169```

168 170 

172 174 

173When you're done, ask the lead to clean up:175When you're done, ask the lead to clean up:

174 176 

175```177```text theme={null}

176Clean up the team178Clean up the team

177```179```

178 180 

184 186 

185### Enforce quality gates with hooks187### Enforce quality gates with hooks

186 188 

187Use [hooks](/en/hooks) to enforce rules when teammates finish work or tasks complete:189Use [hooks](/en/hooks) to enforce rules when teammates finish work or tasks are created or completed:

188 190 

189* [`TeammateIdle`](/en/hooks#teammateidle): runs when a teammate is about to go idle. Exit with code 2 to send feedback and keep the teammate working.191* [`TeammateIdle`](/en/hooks#teammateidle): runs when a teammate is about to go idle. Exit with code 2 to send feedback and keep the teammate working.

192* [`TaskCreated`](/en/hooks#taskcreated): runs when a task is being created. Exit with code 2 to prevent creation and send feedback.

190* [`TaskCompleted`](/en/hooks#taskcompleted): runs when a task is being marked complete. Exit with code 2 to prevent completion and send feedback.193* [`TaskCompleted`](/en/hooks#taskcompleted): runs when a task is being marked complete. Exit with code 2 to prevent completion and send feedback.

191 194 

192## How agent teams work195## How agent teams work

222* **Team config**: `~/.claude/teams/{team-name}/config.json`225* **Team config**: `~/.claude/teams/{team-name}/config.json`

223* **Task list**: `~/.claude/tasks/{team-name}/`226* **Task list**: `~/.claude/tasks/{team-name}/`

224 227 

228Claude Code generates both of these automatically when you create a team and updates them as teammates join, go idle, or leave. The team config holds runtime state such as session IDs and tmux pane IDs, so don't edit it by hand or pre-author it: your changes are overwritten on the next state update.

229 

230To define reusable teammate roles, use [subagent definitions](#use-subagent-definitions-for-teammates) instead.

231 

225The team config contains a `members` array with each teammate's name, agent ID, and agent type. Teammates can read this file to discover other team members.232The team config contains a `members` array with each teammate's name, agent ID, and agent type. Teammates can read this file to discover other team members.

226 233 

234There is no project-level equivalent of the team config. A file like `.claude/teams/teams.json` in your project directory is not recognized as configuration; Claude treats it as an ordinary file.

235 

236### Use subagent definitions for teammates

237 

238When spawning a teammate, you can reference a [subagent](/en/sub-agents) type from any [subagent scope](/en/sub-agents#choose-the-subagent-scope): project, user, plugin, or CLI-defined. This lets you define a role once, such as a security-reviewer or test-runner, and reuse it both as a delegated subagent and as an agent team teammate.

239 

240To use a subagent definition, mention it by name when asking Claude to spawn the teammate:

241 

242```text theme={null}

243Spawn a teammate using the security-reviewer agent type to audit the auth module.

244```

245 

246The teammate honors that definition's `tools` allowlist and `model`, and the definition's body is appended to the teammate's system prompt as additional instructions rather than replacing it. Team coordination tools such as `SendMessage` and the task management tools are always available to a teammate even when `tools` restricts other tools.

247 

248<Note>

249 The `skills` and `mcpServers` frontmatter fields in a subagent definition are not applied when that definition runs as a teammate. Teammates load skills and MCP servers from your project and user settings, the same as a regular session.

250</Note>

251 

227### Permissions252### Permissions

228 253 

229Teammates start with the lead's permission settings. If the lead runs with `--dangerously-skip-permissions`, all teammates do too. After spawning, you can change individual teammate modes, but you can't set per-teammate modes at spawn time.254Teammates start with the lead's permission settings. If the lead runs with `--dangerously-skip-permissions`, all teammates do too. After spawning, you can change individual teammate modes, but you can't set per-teammate modes at spawn time.

243* **message**: send a message to one specific teammate268* **message**: send a message to one specific teammate

244* **broadcast**: send to all teammates simultaneously. Use sparingly, as costs scale with team size.269* **broadcast**: send to all teammates simultaneously. Use sparingly, as costs scale with team size.

245 270 

271The lead assigns every teammate a name when it spawns them, and any teammate can message any other by that name. To get predictable names you can reference in later prompts, tell the lead what to call each teammate in your spawn instruction.

272 

246### Token usage273### Token usage

247 274 

248Agent teams use significantly more tokens than a single session. Each teammate has its own context window, and token usage scales with the number of active teammates. For research, review, and new feature work, the extra tokens are usually worthwhile. For routine tasks, a single session is more cost-effective. See [agent team token costs](/en/costs#agent-team-token-costs) for usage guidance.275Agent teams use significantly more tokens than a single session. Each teammate has its own context window, and token usage scales with the number of active teammates. For research, review, and new feature work, the extra tokens are usually worthwhile. For routine tasks, a single session is more cost-effective. See [agent team token costs](/en/costs#agent-team-token-costs) for usage guidance.

255 282 

256A single reviewer tends to gravitate toward one type of issue at a time. Splitting review criteria into independent domains means security, performance, and test coverage all get thorough attention simultaneously. The prompt assigns each teammate a distinct lens so they don't overlap:283A single reviewer tends to gravitate toward one type of issue at a time. Splitting review criteria into independent domains means security, performance, and test coverage all get thorough attention simultaneously. The prompt assigns each teammate a distinct lens so they don't overlap:

257 284 

258```285```text theme={null}

259Create an agent team to review PR #142. Spawn three reviewers:286Create an agent team to review PR #142. Spawn three reviewers:

260- One focused on security implications287- One focused on security implications

261- One checking performance impact288- One checking performance impact

269 296 

270When the root cause is unclear, a single agent tends to find one plausible explanation and stop looking. The prompt fights this by making teammates explicitly adversarial: each one's job is not only to investigate its own theory but to challenge the others'.297When the root cause is unclear, a single agent tends to find one plausible explanation and stop looking. The prompt fights this by making teammates explicitly adversarial: each one's job is not only to investigate its own theory but to challenge the others'.

271 298 

272```299```text theme={null}

273Users report the app exits after one message instead of staying connected.300Users report the app exits after one message instead of staying connected.

274Spawn 5 agent teammates to investigate different hypotheses. Have them talk to301Spawn 5 agent teammates to investigate different hypotheses. Have them talk to

275each other to try to disprove each other's theories, like a scientific302each other to try to disprove each other's theories, like a scientific

286 313 

287Teammates load project context automatically, including CLAUDE.md, MCP servers, and skills, but they don't inherit the lead's conversation history. See [Context and communication](#context-and-communication) for details. Include task-specific details in the spawn prompt:314Teammates load project context automatically, including CLAUDE.md, MCP servers, and skills, but they don't inherit the lead's conversation history. See [Context and communication](#context-and-communication) for details. Include task-specific details in the spawn prompt:

288 315 

289```316```text theme={null}

290Spawn a security reviewer teammate with the prompt: "Review the authentication module317Spawn a security reviewer teammate with the prompt: "Review the authentication module

291at src/auth/ for security vulnerabilities. Focus on token handling, session318at src/auth/ for security vulnerabilities. Focus on token handling, session

292management, and input validation. The app uses JWT tokens stored in319management, and input validation. The app uses JWT tokens stored in

293httpOnly cookies. Report any issues with severity ratings."320httpOnly cookies. Report any issues with severity ratings."

294```321```

295 322 

323### Choose an appropriate team size

324 

325There's no hard limit on the number of teammates, but practical constraints apply:

326 

327* **Token costs scale linearly**: each teammate has its own context window and consumes tokens independently. See [agent team token costs](/en/costs#agent-team-token-costs) for details.

328* **Coordination overhead increases**: more teammates means more communication, task coordination, and potential for conflicts

329* **Diminishing returns**: beyond a certain point, additional teammates don't speed up work proportionally

330 

331Start with 3-5 teammates for most workflows. This balances parallel work with manageable coordination. The examples in this guide use 3-5 teammates because that range works well across different task types.

332 

333Having 5-6 [tasks](/en/agent-teams#architecture) per teammate keeps everyone productive without excessive context switching. If you have 15 independent tasks, 3 teammates is a good starting point.

334 

335Scale up only when the work genuinely benefits from having teammates work simultaneously. Three focused teammates often outperform five scattered ones.

336 

296### Size tasks appropriately337### Size tasks appropriately

297 338 

298* **Too small**: coordination overhead exceeds the benefit339* **Too small**: coordination overhead exceeds the benefit

307 348 

308Sometimes the lead starts implementing tasks itself instead of waiting for teammates. If you notice this:349Sometimes the lead starts implementing tasks itself instead of waiting for teammates. If you notice this:

309 350 

310```351```text theme={null}

311Wait for your teammates to complete their tasks before proceeding352Wait for your teammates to complete their tasks before proceeding

312```353```

313 354 

343 384 

344### Teammates stopping on errors385### Teammates stopping on errors

345 386 

346Teammates may stop after encountering errors instead of recovering. Check their output using Shift+Up/Down in in-process mode or by clicking the pane in split mode, then either:387Teammates may stop after encountering errors instead of recovering. Check their output using Shift+Down in in-process mode or by clicking the pane in split mode, then either:

347 388 

348* Give them additional instructions directly389* Give them additional instructions directly

349* Spawn a replacement teammate to continue the work390* Spawn a replacement teammate to continue the work

11Before configuring Claude Code with Bedrock, ensure you have:11Before configuring Claude Code with Bedrock, ensure you have:

12 12 

13* An AWS account with Bedrock access enabled13* An AWS account with Bedrock access enabled

14* Access to desired Claude models (for example, Claude Sonnet 4.5) in Bedrock14* Access to desired Claude models (for example, Claude Sonnet 4.6) in Bedrock

15* AWS CLI installed and configured (optional - only needed if you don't have another mechanism for getting credentials)15* AWS CLI installed and configured (optional - only needed if you don't have another mechanism for getting credentials)

16* Appropriate IAM permissions16* Appropriate IAM permissions

17 17 

18<Note>

19 If you are deploying Claude Code to multiple users, [pin your model versions](#4-pin-model-versions) to prevent breakage when Anthropic releases new models.

20</Note>

21 

18## Setup22## Setup

19 23 

20### 1. Submit use case details24### 1. Submit use case details

21 25 

22First-time users of Anthropic models are required to submit use case details before invoking a model. This is done once per account.26First-time users of Anthropic models are required to submit use case details before invoking a model. This is done once per AWS account.

23 27 

241. Ensure you have the right IAM permissions (see more on that below)281. Ensure you have the right IAM permissions described below

252. Navigate to the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/)292. Navigate to the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/)

263. Select **Chat/Text playground**303. Select an Anthropic model from the **Model catalog**

274. Choose any Anthropic model and you will be prompted to fill out the use case form314. Complete the use case form. Access is granted immediately after submission.

32 

33If you use AWS Organizations, you can submit the form once from the management account using the [`PutUseCaseForModelAccess` API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_PutUseCaseForModelAccess.html). This call requires the `bedrock:PutUseCaseForModelAccess` IAM permission. Approval extends to child accounts automatically.

28 34 

29### 2. Configure AWS credentials35### 2. Configure AWS credentials

30 36 

112 118 

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

114export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2120export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2

121 

122# Optional: Override the Bedrock endpoint URL for custom endpoints or gateways

123# export ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com

115```124```

116 125 

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

120* When using Bedrock, the `/login` and `/logout` commands are disabled since authentication is handled through AWS credentials.129* When using Bedrock, the `/login` and `/logout` commands are disabled since authentication is handled through AWS credentials.

121* You can use settings files for environment variables like `AWS_PROFILE` that you don't want to leak to other processes. See [Settings](/en/settings) for more information.130* You can use settings files for environment variables like `AWS_PROFILE` that you don't want to leak to other processes. See [Settings](/en/settings) for more information.

122 131 

123### 4. Model configuration132### 4. Pin model versions

133 

134<Warning>

135 Pin specific model versions for every deployment. If you use model aliases (`sonnet`, `opus`, `haiku`) without pinning, Claude Code may attempt to use a newer model version that isn't available in your Bedrock account, breaking existing users when Anthropic releases updates.

136</Warning>

137 

138Set these environment variables to specific Bedrock model IDs:

139 

140```bash theme={null}

141export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-6-v1'

142export ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'

143export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

144```

124 145 

125Claude Code uses these default models for Bedrock:146These variables use cross-region inference profile IDs (with the `us.` prefix). If you use a different region prefix or application inference profiles, adjust accordingly. For current and legacy model IDs, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). See [Model configuration](/en/model-config#pin-models-for-third-party-deployments) for the full list of environment variables.

147 

148Claude Code uses these default models when no pinning variables are set:

126 149 

127| Model type | Default value |150| Model type | Default value |

128| :--------------- | :------------------------------------------------- |151| :--------------- | :--------------------------------------------- |

129| Primary model | `global.anthropic.claude-sonnet-4-5-20250929-v1:0` |152| Primary model | `us.anthropic.claude-sonnet-4-5-20250929-v1:0` |

130| Small/fast model | `us.anthropic.claude-haiku-4-5-20251001-v1:0` |153| Small/fast model | `us.anthropic.claude-haiku-4-5-20251001-v1:0` |

131 154 

132<Note>155To customize models further, use one of these methods:

133 For Bedrock users, Claude Code won't automatically upgrade from Haiku 3.5 to Haiku 4.5. To manually switch to a newer Haiku model, set the `ANTHROPIC_DEFAULT_HAIKU_MODEL` environment variable to the full model name (for example, `us.anthropic.claude-haiku-4-5-20251001-v1:0`).

134</Note>

135 

136To customize models, use one of these methods:

137 156 

138```bash theme={null}157```bash theme={null}

139# Using inference profile ID158# Using inference profile ID

140export ANTHROPIC_MODEL='global.anthropic.claude-sonnet-4-5-20250929-v1:0'159export ANTHROPIC_MODEL='global.anthropic.claude-sonnet-4-6'

141export ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'160export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

142 161 

143# Using application inference profile ARN162# Using application inference profile ARN

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

149 168 

150<Note>[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) may not be available in all regions.</Note>169<Note>[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) may not be available in all regions.</Note>

151 170 

171#### Map each model version to an inference profile

172 

173The `ANTHROPIC_DEFAULT_*_MODEL` environment variables configure one inference profile per model family. If your organization needs to expose several versions of the same family in the `/model` picker, each routed to its own application inference profile ARN, use the `modelOverrides` setting in your [settings file](/en/settings#settings-files) instead.

174 

175This example maps three Opus versions to distinct ARNs so users can switch between them without bypassing your organization's inference profiles:

176 

177```json theme={null}

178{

179 "modelOverrides": {

180 "claude-opus-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-46-prod",

181 "claude-opus-4-5-20251101": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-45-prod",

182 "claude-opus-4-1-20250805": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-41-prod"

183 }

184}

185```

186 

187When a user selects one of these versions in `/model`, Claude Code calls Bedrock with the mapped ARN. Versions without an override fall back to the built-in Bedrock model ID or any matching inference profile discovered at startup. See [Override model IDs per version](/en/model-config#override-model-ids-per-version) for details on how overrides interact with `availableModels` and other model settings.

188 

152## IAM configuration189## IAM configuration

153 190 

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

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

195 232 

196<Note>233<Note>

197 We recommend creating a dedicated AWS account for Claude Code to simplify cost tracking and access control.234 Create a dedicated AWS account for Claude Code to simplify cost tracking and access control.

198</Note>235</Note>

199 236 

237## 1M token context window

238 

239Claude Opus 4.6 and Sonnet 4.6 support the [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) on Amazon Bedrock. Claude Code automatically enables the extended context window when you select a 1M model variant.

240 

241To enable the 1M context window for your pinned model, append `[1m]` to the model ID. See [Pin models for third-party deployments](/en/model-config#pin-models-for-third-party-deployments) for details.

242 

200## AWS Guardrails243## AWS Guardrails

201 244 

202[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) let you implement content filtering for Claude Code. Create a Guardrail in the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/), publish a version, then add the Guardrail headers to your [settings file](/en/settings). Enable Cross-Region inference on your Guardrail if you're using cross-region inference profiles.245[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) let you implement content filtering for Claude Code. Create a Guardrail in the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/), publish a version, then add the Guardrail headers to your [settings file](/en/settings). Enable Cross-Region inference on your Guardrail if you're using cross-region inference profiles.

213 256 

214## Troubleshooting257## Troubleshooting

215 258 

259### Authentication loop with SSO and corporate proxies

260 

261If browser tabs spawn repeatedly when using AWS SSO, remove the `awsAuthRefresh` setting from your [settings file](/en/settings). This can occur when corporate VPNs or TLS inspection proxies interrupt the SSO browser flow. Claude Code treats the interrupted connection as an authentication failure, re-runs `awsAuthRefresh`, and loops indefinitely.

262 

263If your network environment interferes with automatic browser-based SSO flows, use `aws sso login` manually before starting Claude Code instead of relying on `awsAuthRefresh`.

264 

265### Region issues

266 

216If you encounter region issues:267If you encounter region issues:

217 268 

218* Check model availability: `aws bedrock list-inference-profiles --region your-region`269* Check model availability: `aws bedrock list-inference-profiles --region your-region`

230* [Bedrock documentation](https://docs.aws.amazon.com/bedrock/)281* [Bedrock documentation](https://docs.aws.amazon.com/bedrock/)

231* [Bedrock pricing](https://aws.amazon.com/bedrock/pricing/)282* [Bedrock pricing](https://aws.amazon.com/bedrock/pricing/)

232* [Bedrock inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html)283* [Bedrock inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html)

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

285* [Claude Code on Amazon Bedrock: Quick Setup Guide](https://community.aws/content/2tXkZKrZzlrlu0KfH8gST5Dkppq/claude-code-on-amazon-bedrock-quick-setup-guide)

286* [Claude Code Monitoring Implementation (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)

9Claude Code provides analytics dashboards to help organizations understand developer usage patterns, track contribution metrics, and measure how Claude Code impacts engineering velocity. Access the dashboard for your plan:9Claude Code provides analytics dashboards to help organizations understand developer usage patterns, track contribution metrics, and measure how Claude Code impacts engineering velocity. Access the dashboard for your plan:

10 10 

11| Plan | Dashboard URL | Includes | Read more |11| Plan | Dashboard URL | Includes | Read more |

12| ----------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------- |12| ----------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------- |

13| Claude for Teams / Enterprise | [claude.ai/analytics/claude-code](https://claude.ai/analytics/claude-code) | Usage metrics, contribution metrics with GitHub integration, leaderboard, data export | [Details](#access-analytics-for-teams-and-enterprise) |13| Claude for Teams / Enterprise | [claude.ai/analytics/claude-code](https://claude.ai/analytics/claude-code) | Usage metrics, contribution metrics with GitHub integration, leaderboard, data export | [Details](#access-analytics-for-team-and-enterprise) |

14| API (Claude Console) | [platform.claude.com/claude-code](https://platform.claude.com/claude-code) | Usage metrics, spend tracking, team insights | [Details](#access-analytics-for-api-customers) |14| API (Claude Console) | [platform.claude.com/claude-code](https://platform.claude.com/claude-code) | Usage metrics, spend tracking, team insights | [Details](#access-analytics-for-api-customers) |

15 15 

16## Access analytics for Teams and Enterprise16## Access analytics for Team and Enterprise

17 17 

18Navigate to [claude.ai/analytics/claude-code](https://claude.ai/analytics/claude-code). Admins and Owners can view the dashboard.18Navigate to [claude.ai/analytics/claude-code](https://claude.ai/analytics/claude-code). Admins and Owners can view the dashboard.

19 19 

20The Teams and Enterprise dashboard includes:20The Team and Enterprise dashboard includes:

21 21 

22* **Usage metrics**: lines of code accepted, suggestion accept rate, daily active users and sessions22* **Usage metrics**: lines of code accepted, suggestion accept rate, daily active users and sessions

23* **Contribution metrics**: PRs and lines of code shipped with Claude Code assistance, with [GitHub integration](#enable-contribution-metrics)23* **Contribution metrics**: PRs and lines of code shipped with Claude Code assistance, with [GitHub integration](#enable-contribution-metrics)

35You need the Owner role to configure analytics settings. A GitHub admin must install the GitHub app.35You need the Owner role to configure analytics settings. A GitHub admin must install the GitHub app.

36 36 

37<Warning>37<Warning>

38 Contribution metrics are not available for organizations with [Zero Data Retention](/en/data-usage#data-retention) enabled. The analytics dashboard will show usage metrics only.38 Contribution metrics are not available for organizations with [Zero Data Retention](/en/zero-data-retention) enabled. The analytics dashboard will show usage metrics only.

39</Warning>39</Warning>

40 40 

41<Steps>41<Steps>

4 4 

5# Authentication5# Authentication

6 6 

7> Learn how to configure user authentication and credential management for Claude Code in your organization.7> Log in to Claude Code and configure authentication for individuals, teams, and organizations.

8 8 

9## Authentication methods9Claude Code supports multiple authentication methods depending on your setup. Individual users can log in with a Claude.ai account, while teams can use Claude for Teams or Enterprise, the Claude Console, or a cloud provider like Amazon Bedrock, Google Vertex AI, or Microsoft Foundry.

10 10 

11Setting up Claude Code requires access to Anthropic models. For teams, you can set up Claude Code access in one of these ways:11## Log in to Claude Code

12 12 

13* [Claude for Teams or Enterprise](#claude-for-teams-or-enterprise) (recommended)13After [installing Claude Code](/en/setup#install-claude-code), run `claude` in your terminal. On first launch, Claude Code opens a browser window for you to log in.

14 

15If the browser doesn't open automatically, press `c` to copy the login URL to your clipboard, then paste it into your browser.

16 

17You can authenticate with any of these account types:

18 

19* **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).

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

21* **Claude Console**: log in with your Console credentials. Your admin must have [invited you](#claude-console-authentication) first.

22* **Cloud providers**: if your organization uses [Amazon Bedrock](/en/amazon-bedrock), [Google Vertex AI](/en/google-vertex-ai), or [Microsoft Foundry](/en/microsoft-foundry), set the required environment variables before running `claude`. No browser login is needed.

23 

24To log out and re-authenticate, type `/logout` at the Claude Code prompt.

25 

26If you're having trouble logging in, see [authentication troubleshooting](/en/troubleshooting#authentication-issues).

27 

28## Set up team authentication

29 

30For teams and organizations, you can configure Claude Code access in one of these ways:

31 

32* [Claude for Teams or Enterprise](#claude-for-teams-or-enterprise), recommended for most teams

14* [Claude Console](#claude-console-authentication)33* [Claude Console](#claude-console-authentication)

15* [Amazon Bedrock](/en/amazon-bedrock)34* [Amazon Bedrock](/en/amazon-bedrock)

16* [Google Vertex AI](/en/google-vertex-ai)35* [Google Vertex AI](/en/google-vertex-ai)

18 37 

19### Claude for Teams or Enterprise38### Claude for Teams or Enterprise

20 39 

21[Claude for Teams](https://claude.com/pricing#team-&-enterprise) and [Claude for Enterprise](https://anthropic.com/contact-sales) provide the best experience for organizations using Claude Code. Team members get access to both Claude Code and Claude on the web with centralized billing and team management.40[Claude for Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_teams#team-&-enterprise) and [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_enterprise) provide the best experience for organizations using Claude Code. Team members get access to both Claude Code and Claude on the web with centralized billing and team management.

22 41 

23* **Claude for Teams**: self-service plan with collaboration features, admin tools, and billing management. Best for smaller teams.42* **Claude for Teams**: self-service plan with collaboration features, admin tools, and billing management. Best for smaller teams.

24* **Claude for Enterprise**: adds SSO, domain capture, role-based permissions, compliance API, and managed policy settings for organization-wide Claude Code configurations. Best for larger organizations with security and compliance requirements.43* **Claude for Enterprise**: adds SSO, domain capture, role-based permissions, compliance API, and managed policy settings for organization-wide Claude Code configurations. Best for larger organizations with security and compliance requirements.

25 44 

26<Steps>45<Steps>

27 <Step title="Subscribe">46 <Step title="Subscribe">

28 Subscribe to [Claude for Teams](https://claude.com/pricing#team-&-enterprise) or contact sales for [Claude for Enterprise](https://anthropic.com/contact-sales).47 Subscribe to [Claude for Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_teams_step#team-&-enterprise) or contact sales for [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_enterprise_step).

29 </Step>48 </Step>

30 49 

31 <Step title="Invite team members">50 <Step title="Invite team members">

49 <Step title="Add users">68 <Step title="Add users">

50 You can add users through either method:69 You can add users through either method:

51 70 

52 * Bulk invite users from within the Console (Console -> Settings -> Members -> Invite)71 * Bulk invite users from within the Console: Settings -> Members -> Invite

53 * [Set up SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso)72 * [Set up SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso)

54 </Step>73 </Step>

55 74 

65 84 

66 * Accept the Console invite85 * Accept the Console invite

67 * [Check system requirements](/en/setup#system-requirements)86 * [Check system requirements](/en/setup#system-requirements)

68 * [Install Claude Code](/en/setup#installation)87 * [Install Claude Code](/en/setup#install-claude-code)

69 * Log in with Console account credentials88 * Log in with Console account credentials

70 </Step>89 </Step>

71</Steps>90</Steps>

72 91 

73### Cloud provider authentication92### Cloud provider authentication

74 93 

75For teams using Amazon Bedrock, Google Vertex AI, or Microsoft Azure:94For teams using Amazon Bedrock, Google Vertex AI, or Microsoft Foundry:

76 95 

77<Steps>96<Steps>

78 <Step title="Follow provider setup">97 <Step title="Follow provider setup">

84 </Step>103 </Step>

85 104 

86 <Step title="Install Claude Code">105 <Step title="Install Claude Code">

87 Users can [install Claude Code](/en/setup#installation).106 Users can [install Claude Code](/en/setup#install-claude-code).

88 </Step>107 </Step>

89</Steps>108</Steps>

90 109 

92 111 

93Claude Code securely manages your authentication credentials:112Claude Code securely manages your authentication credentials:

94 113 

95* **Storage location**: on macOS, API keys, OAuth tokens, and other credentials are stored in the encrypted macOS Keychain.114* **Storage location**: on macOS, credentials are stored in the encrypted macOS Keychain. On Linux and Windows, credentials are stored in `~/.claude/.credentials.json`, or under `$CLAUDE_CONFIG_DIR` if that variable is set. On Linux, the file is written with mode `0600`; on Windows, it inherits the access controls of your user profile directory.

96* **Supported authentication types**: Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth.115* **Supported authentication types**: Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth.

97* **Custom credential scripts**: the [`apiKeyHelper`](/en/settings#available-settings) setting can be configured to run a shell script that returns an API key.116* **Custom credential scripts**: the [`apiKeyHelper`](/en/settings#available-settings) setting can be configured to run a shell script that returns an API key.

98* **Refresh intervals**: by default, `apiKeyHelper` is called after 5 minutes or on HTTP 401 response. Set `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` environment variable for custom refresh intervals.117* **Refresh intervals**: by default, `apiKeyHelper` is called after 5 minutes or on HTTP 401 response. Set `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` environment variable for custom refresh intervals.

118* **Slow helper notice**: if `apiKeyHelper` takes longer than 10 seconds to return a key, Claude Code displays a warning notice in the prompt bar showing the elapsed time. If you see this notice regularly, check whether your credential script can be optimized.

119 

120`apiKeyHelper`, `ANTHROPIC_API_KEY`, and `ANTHROPIC_AUTH_TOKEN` apply to terminal CLI sessions only. Claude Desktop and remote sessions use OAuth exclusively and do not call `apiKeyHelper` or read API key environment variables.

121 

122### Authentication precedence

123 

124When multiple credentials are present, Claude Code chooses one in this order:

125 

1261. Cloud provider credentials, when `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, or `CLAUDE_CODE_USE_FOUNDRY` is set. See [third-party integrations](/en/third-party-integrations) for setup.

1272. `ANTHROPIC_AUTH_TOKEN` environment variable. Sent as the `Authorization: Bearer` header. Use this when routing through an [LLM gateway or proxy](/en/llm-gateway) that authenticates with bearer tokens rather than Anthropic API keys.

1283. `ANTHROPIC_API_KEY` environment variable. Sent as the `X-Api-Key` header. Use this for direct Anthropic API access with a key from the [Claude Console](https://platform.claude.com). In interactive mode, you are prompted once to approve or decline the key, and your choice is remembered. To change it later, use the "Use custom API key" toggle in `/config`. In non-interactive mode (`-p`), the key is always used when present.

1294. [`apiKeyHelper`](/en/settings#available-settings) script output. Use this for dynamic or rotating credentials, such as short-lived tokens fetched from a vault.

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

99 131 

100## See also132If you have an active Claude subscription but also have `ANTHROPIC_API_KEY` set in your environment, the API key takes precedence once approved. This can cause authentication failures if the key belongs to a disabled or expired organization. Run `unset ANTHROPIC_API_KEY` to fall back to your subscription, and check `/status` to confirm which method is active.

101 133 

102* [Permissions](/en/permissions): configure what Claude Code can access and do134[Claude Code on the Web](/en/claude-code-on-the-web) always uses your subscription credentials. `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` in the sandbox environment do not override them.

103* [Settings](/en/settings): complete configuration reference

104* [Security](/en/security): security safeguards and best practices

20 20 

21Claude's context window holds your entire conversation, including every message, every file Claude reads, and every command output. However, this can fill up fast. A single debugging session or codebase exploration might generate and consume tens of thousands of tokens.21Claude's context window holds your entire conversation, including every message, every file Claude reads, and every command output. However, this can fill up fast. A single debugging session or codebase exploration might generate and consume tens of thousands of tokens.

22 22 

23This matters since LLM performance degrades as context fills. When the context window is getting full, Claude may start "forgetting" earlier instructions or making more mistakes. The context window is the most important resource to manage. Track context usage continuously with a [custom status line](/en/statusline), and see [Reduce token usage](/en/costs#reduce-token-usage) for strategies on reducing token usage.23This matters since LLM performance degrades as context fills. When the context window is getting full, Claude may start "forgetting" earlier instructions or making more mistakes. The context window is the most important resource to manage. To see how a session fills up in practice, [watch an interactive walkthrough](/en/context-window) of what loads at startup and what each file read costs. Track context usage continuously with a [custom status line](/en/statusline), and see [Reduce token usage](/en/costs#reduce-token-usage) for strategies on reducing token usage.

24 24 

25***25***

26 26 

148 Run `/init` to generate a starter CLAUDE.md file based on your current project structure, then refine over time.148 Run `/init` to generate a starter CLAUDE.md file based on your current project structure, then refine over time.

149</Tip>149</Tip>

150 150 

151CLAUDE.md is a special file that Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules. This gives Claude persistent context **it can't infer from code alone**.151CLAUDE.md is a special file that Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules. This gives Claude persistent context it can't infer from code alone.

152 152 

153The `/init` command analyzes your codebase to detect build systems, test frameworks, and code patterns, giving you a solid foundation to refine.153The `/init` command analyzes your codebase to detect build systems, test frameworks, and code patterns, giving you a solid foundation to refine.

154 154 

194 194 

195You can place CLAUDE.md files in several locations:195You can place CLAUDE.md files in several locations:

196 196 

197* **Home folder (`~/.claude/CLAUDE.md`)**: Applies to all Claude sessions197* **Home folder (`~/.claude/CLAUDE.md`)**: applies to all Claude sessions

198* **Project root (`./CLAUDE.md`)**: Check into git to share with your team, or name it `CLAUDE.local.md` and `.gitignore` it198* **Project root (`./CLAUDE.md`)**: check into git to share with your team

199* **Parent directories**: Useful for monorepos where both `root/CLAUDE.md` and `root/foo/CLAUDE.md` are pulled in automatically199* **Project root (`./CLAUDE.local.md`)**: personal project-specific notes; add this file to your `.gitignore` so it isn't shared with your team

200* **Parent directories**: useful for monorepos where both `root/CLAUDE.md` and `root/foo/CLAUDE.md` are pulled in automatically

200* **Child directories**: Claude pulls in child CLAUDE.md files on demand when working with files in those directories201* **Child directories**: Claude pulls in child CLAUDE.md files on demand when working with files in those directories

201 202 

202### Configure permissions203### Configure permissions

203 204 

204<Tip>205<Tip>

205 Use `/permissions` to allowlist safe commands or `/sandbox` for OS-level isolation. This reduces interruptions while keeping you in control.206 Use [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) to let a classifier handle approvals, `/permissions` to allowlist specific commands, or `/sandbox` for OS-level isolation. Each reduces interruptions while keeping you in control.

206</Tip>207</Tip>

207 208 

208By default, Claude Code requests permission for actions that might modify your system: file writes, Bash commands, MCP tools, etc. This is safe but tedious. After the tenth approval you're not really reviewing anymore, you're just clicking through. There are two ways to reduce these interruptions:209By default, Claude Code requests permission for actions that might modify your system: file writes, Bash commands, MCP tools, etc. This is safe but tedious. After the tenth approval you're not really reviewing anymore, you're just clicking through. There are three ways to reduce these interruptions:

209 210 

210* **Permission allowlists**: Permit specific tools you know are safe (like `npm run lint` or `git commit`)211* **Auto mode**: a separate classifier model reviews commands and blocks only what looks risky: scope escalation, unknown infrastructure, or hostile-content-driven actions. Best when you trust the general direction of a task but don't want to click through every step

211* **Sandboxing**: Enable OS-level isolation that restricts filesystem and network access, allowing Claude to work more freely within defined boundaries212* **Permission allowlists**: permit specific tools you know are safe, like `npm run lint` or `git commit`

213* **Sandboxing**: enable OS-level isolation that restricts filesystem and network access, allowing Claude to work more freely within defined boundaries

212 214 

213Alternatively, use `--dangerously-skip-permissions` to bypass all permission checks for contained workflows like fixing lint errors or generating boilerplate.215Read more about [permission modes](/en/permission-modes), [permission rules](/en/permissions), and [sandboxing](/en/sandboxing).

214 

215<Warning>

216 Letting Claude run arbitrary commands can result in data loss, system corruption, or data exfiltration via prompt injection. Only use `--dangerously-skip-permissions` in a sandbox without internet access.

217</Warning>

218 

219Read more about [configuring permissions](/en/settings) and [enabling sandboxing](/en/sandboxing#sandboxing).

220 216 

221### Use CLI tools217### Use CLI tools

222 218 

244 240 

245[Hooks](/en/hooks-guide) run scripts automatically at specific points in Claude's workflow. Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens.241[Hooks](/en/hooks-guide) run scripts automatically at specific points in Claude's workflow. Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens.

246 242 

247Claude can write hooks for you. Try prompts like *"Write a hook that runs eslint after every file edit"* or *"Write a hook that blocks writes to the migrations folder."* Run `/hooks` for interactive configuration, or edit `.claude/settings.json` directly.243Claude can write hooks for you. Try prompts like *"Write a hook that runs eslint after every file edit"* or *"Write a hook that blocks writes to the migrations folder."* Edit `.claude/settings.json` directly to configure hooks by hand, and run `/hooks` to browse what's configured.

248 244 

249### Create skills245### Create skills

250 246 

356 352 

357Claude asks about things you might not have considered yet, including technical implementation, UI/UX, edge cases, and tradeoffs.353Claude asks about things you might not have considered yet, including technical implementation, UI/UX, edge cases, and tradeoffs.

358 354 

359```355```text theme={null}

360I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.356I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

361 357 

362Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.358Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

380 376 

381The best results come from tight feedback loops. Though Claude occasionally solves problems perfectly on the first attempt, correcting it quickly generally produces better solutions faster.377The best results come from tight feedback loops. Though Claude occasionally solves problems perfectly on the first attempt, correcting it quickly generally produces better solutions faster.

382 378 

383* **`Esc`**: Stop Claude mid-action with the `Esc` key. Context is preserved, so you can redirect.379* **`Esc`**: stop Claude mid-action with the `Esc` key. Context is preserved, so you can redirect.

384* **`Esc + Esc` or `/rewind`**: Press `Esc` twice or run `/rewind` to open the rewind menu and restore previous conversation and code state, or summarize from a selected message.380* **`Esc + Esc` or `/rewind`**: press `Esc` twice or run `/rewind` to open the rewind menu and restore previous conversation and code state, or summarize from a selected message.

385* **`"Undo that"`**: Have Claude revert its changes.381* **`"Undo that"`**: have Claude revert its changes.

386* **`/clear`**: Reset context between unrelated tasks. Long sessions with irrelevant context can reduce performance.382* **`/clear`**: reset context between unrelated tasks. Long sessions with irrelevant context can reduce performance.

387 383 

388If you've corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. Run `/clear` and start fresh with a more specific prompt that incorporates what you learned. A clean session with a better prompt almost always outperforms a long session with accumulated corrections.384If you've corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. Run `/clear` and start fresh with a more specific prompt that incorporates what you learned. A clean session with a better prompt almost always outperforms a long session with accumulated corrections.

389 385 

402* For more control, run `/compact <instructions>`, like `/compact Focus on the API changes`398* For more control, run `/compact <instructions>`, like `/compact Focus on the API changes`

403* To compact only part of the conversation, use `Esc + Esc` or `/rewind`, select a message checkpoint, and choose **Summarize from here**. This condenses messages from that point forward while keeping earlier context intact.399* To compact only part of the conversation, use `Esc + Esc` or `/rewind`, select a message checkpoint, and choose **Summarize from here**. This condenses messages from that point forward while keeping earlier context intact.

404* Customize compaction behavior in CLAUDE.md with instructions like `"When compacting, always preserve the full list of modified files and any test commands"` to ensure critical context survives summarization400* Customize compaction behavior in CLAUDE.md with instructions like `"When compacting, always preserve the full list of modified files and any test commands"` to ensure critical context survives summarization

401* For quick questions that don't need to stay in context, use [`/btw`](/en/interactive-mode#side-questions-with-btw). The answer appears in a dismissible overlay and never enters conversation history, so you can check a detail without growing context.

405 402 

406### Use subagents for investigation403### Use subagents for investigation

407 404 

411 408 

412Since context is your fundamental constraint, subagents are one of the most powerful tools available. When Claude researches a codebase it reads lots of files, all of which consume your context. Subagents run in separate context windows and report back summaries:409Since context is your fundamental constraint, subagents are one of the most powerful tools available. When Claude researches a codebase it reads lots of files, all of which consume your context. Subagents run in separate context windows and report back summaries:

413 410 

414```411```text theme={null}

415Use subagents to investigate how our authentication system handles token412Use subagents to investigate how our authentication system handles token

416refresh, and whether we have any existing OAuth utilities I should reuse.413refresh, and whether we have any existing OAuth utilities I should reuse.

417```414```

420 417 

421You can also use subagents for verification after Claude implements something:418You can also use subagents for verification after Claude implements something:

422 419 

423```420```text theme={null}

424use a subagent to review this code for edge cases421use a subagent to review this code for edge cases

425```422```

426 423 

444 Run `claude --continue` to pick up where you left off, or `--resume` to choose from recent sessions.441 Run `claude --continue` to pick up where you left off, or `--resume` to choose from recent sessions.

445</Tip>442</Tip>

446 443 

447Claude Code saves conversations locally. When a task spans multiple sessions (you start a feature, get interrupted, come back the next day) you don't have to re-explain the context:444Claude Code saves conversations locally. When a task spans multiple sessions, you don't have to re-explain the context:

448 445 

449```bash theme={null}446```bash theme={null}

450claude --continue # Resume the most recent conversation447claude --continue # Resume the most recent conversation

451claude --resume # Select from recent conversations448claude --resume # Select from recent conversations

452```449```

453 450 

454Use `/rename` to give sessions descriptive names (`"oauth-migration"`, `"debugging-memory-leak"`) so you can find them later. Treat sessions like branches. Different workstreams can have separate, persistent contexts.451Use `/rename` to give sessions descriptive names like `"oauth-migration"` or `"debugging-memory-leak"` so you can find them later. Treat sessions like branches: different workstreams can have separate, persistent contexts.

455 452 

456***453***

457 454 

458## Automate and scale455## Automate and scale

459 456 

460Once you're effective with one Claude, multiply your output with parallel sessions, headless mode, and fan-out patterns.457Once you're effective with one Claude, multiply your output with parallel sessions, non-interactive mode, and fan-out patterns.

461 458 

462Everything so far assumes one human, one Claude, and one conversation. But Claude Code scales horizontally. The techniques in this section show how you can get more done.459Everything so far assumes one human, one Claude, and one conversation. But Claude Code scales horizontally. The techniques in this section show how you can get more done.

463 460 

464### Run headless mode461### Run non-interactive mode

465 462 

466<Tip>463<Tip>

467 Use `claude -p "prompt"` in CI, pre-commit hooks, or scripts. Add `--output-format stream-json` for streaming JSON output.464 Use `claude -p "prompt"` in CI, pre-commit hooks, or scripts. Add `--output-format stream-json` for streaming JSON output.

468</Tip>465</Tip>

469 466 

470With `claude -p "your prompt"`, you can run Claude headlessly, without an interactive session. Headless mode is how you integrate Claude into CI pipelines, pre-commit hooks, or any automated workflow. The output formats (plain text, JSON, streaming JSON) let you parse results programmatically.467With `claude -p "your prompt"`, you can run Claude non-interactively, without a session. Non-interactive mode is how you integrate Claude into CI pipelines, pre-commit hooks, or any automated workflow. The output formats let you parse results programmatically: plain text, JSON, or streaming JSON.

471 468 

472```bash theme={null}469```bash theme={null}

473# One-off queries470# One-off queries

488 485 

489There are three main ways to run parallel sessions:486There are three main ways to run parallel sessions:

490 487 

491* [Claude Desktop](/en/desktop): Manage multiple local sessions visually. Each session gets its own isolated worktree.488* [Claude Code desktop app](/en/desktop#work-in-parallel-with-sessions): Manage multiple local sessions visually. Each session gets its own isolated worktree.

492* [Claude Code on the web](/en/claude-code-on-the-web): Run on Anthropic's secure cloud infrastructure in isolated VMs.489* [Claude Code on the web](/en/claude-code-on-the-web): Run on Anthropic's secure cloud infrastructure in isolated VMs.

493* [Agent teams](/en/agent-teams): Automated coordination of multiple sessions with shared tasks, messaging, and a team lead.490* [Agent teams](/en/agent-teams): Automated coordination of multiple sessions with shared tasks, messaging, and a team lead.

494 491 

539 536 

540Use `--verbose` for debugging during development, and turn it off in production.537Use `--verbose` for debugging during development, and turn it off in production.

541 538 

542### Safe Autonomous Mode539### Run autonomously with auto mode

543 540 

544Use `claude --dangerously-skip-permissions` to bypass all permission checks and let Claude work uninterrupted. This works well for workflows like fixing lint errors or generating boilerplate code.541For uninterrupted execution with background safety checks, use [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode). A classifier model reviews commands before they run, blocking scope escalation, unknown infrastructure, and hostile-content-driven actions while letting routine work proceed without prompts.

545 542 

546<Warning>543```bash theme={null}

547 Letting Claude run arbitrary commands is risky and can result in data loss, system corruption, or data exfiltration (e.g., via prompt injection attacks). To minimize these risks, use `--dangerously-skip-permissions` in a container without internet access.544claude --permission-mode auto -p "fix all lint errors"

545```

548 546 

549 With sandboxing enabled (`/sandbox`), you get similar autonomy with better security. Sandbox defines upfront boundaries rather than bypassing all checks.547For non-interactive runs with the `-p` flag, auto mode aborts if the classifier repeatedly blocks actions, since there is no user to fall back to. See [when auto mode falls back](/en/permission-modes#when-auto-mode-falls-back) for thresholds.

550</Warning>

551 548 

552***549***

553 550 

580 577 

581## Related resources578## Related resources

582 579 

583<CardGroup cols={2}>580* [How Claude Code works](/en/how-claude-code-works): the agentic loop, tools, and context management

584 <Card title="How Claude Code works" icon="gear" href="/en/how-claude-code-works">581* [Extend Claude Code](/en/features-overview): skills, hooks, MCP, subagents, and plugins

585 Understand the agentic loop, tools, and context management582* [Common workflows](/en/common-workflows): step-by-step recipes for debugging, testing, PRs, and more

586 </Card>583* [CLAUDE.md](/en/memory): store project conventions and persistent context

587 

588 <Card title="Extend Claude Code" icon="puzzle-piece" href="/en/features-overview">

589 Choose between skills, hooks, MCP, subagents, and plugins

590 </Card>

591 

592 <Card title="Common workflows" icon="list-check" href="/en/common-workflows">

593 Step-by-step recipes for debugging, testing, PRs, and more

594 </Card>

595 

596 <Card title="CLAUDE.md" icon="file-lines" href="/en/memory">

597 Store project conventions and persistent context

598 </Card>

599</CardGroup>

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Push events into a running session with channels

6 

7> Use channels to push messages, alerts, and webhooks into your Claude Code session from an MCP server. Forward CI results, chat messages, and monitoring events so Claude can react while you're away.

8 

9<Note>

10 Channels are in [research preview](#research-preview) and require Claude Code v2.1.80 or later. They require claude.ai login. Console and API key authentication is not supported. Team and Enterprise organizations must [explicitly enable them](#enterprise-controls).

11</Note>

12 

13A channel is an MCP server that pushes events into your running Claude Code session, so Claude can react to things that happen while you're not at the terminal. Channels can be two-way: Claude reads the event and replies back through the same channel, like a chat bridge. Events only arrive while the session is open, so for an always-on setup you run Claude in a background process or persistent terminal.

14 

15Unlike integrations that spawn a fresh cloud session or wait to be polled, the event arrives in the session you already have open: see [how channels compare](#how-channels-compare).

16 

17You install a channel as a plugin and configure it with your own credentials. Telegram, Discord, and iMessage are included in the research preview.

18 

19When Claude replies through a channel, you see the inbound message in your terminal but not the reply text. The terminal shows the tool call and a confirmation (like "sent"), and the actual reply appears on the other platform.

20 

21This page covers:

22 

23* [Supported channels](#supported-channels): Telegram, Discord, and iMessage setup

24* [Install and run a channel](#quickstart) with fakechat, a localhost demo

25* [Who can push messages](#security): sender allowlists and how you pair

26* [Enable channels for your organization](#enterprise-controls) on Team and Enterprise

27* [How channels compare](#how-channels-compare) to web sessions, Slack, MCP, and Remote Control

28 

29To build your own channel, see the [Channels reference](/en/channels-reference).

30 

31## Supported channels

32 

33Each 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).

34 

35<Tabs>

36 <Tab title="Telegram">

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

38 

39 <Steps>

40 <Step title="Create a Telegram bot">

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

42 </Step>

43 

44 <Step title="Install the plugin">

45 In Claude Code, run:

46 

47 ```

48 /plugin install telegram@claude-plugins-official

49 ```

50 

51 If Claude Code reports that the plugin is not found in any marketplace, your marketplace is either missing or outdated. Run `/plugin marketplace update claude-plugins-official` to refresh it, or `/plugin marketplace add anthropics/claude-plugins-official` if you haven't added it before. Then retry the install.

52 

53 After installing, run `/reload-plugins` to activate the plugin's configure command.

54 </Step>

55 

56 <Step title="Configure your token">

57 Run the configure command with the token from BotFather:

58 

59 ```

60 /telegram:configure <token>

61 ```

62 

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

64 </Step>

65 

66 <Step title="Restart with channels enabled">

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

68 

69 ```bash theme={null}

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

71 ```

72 </Step>

73 

74 <Step title="Pair your account">

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

76 

77 <Note>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.</Note>

78 

79 Back in Claude Code, run:

80 

81 ```

82 /telegram:access pair <code>

83 ```

84 

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

86 

87 ```

88 /telegram:access policy allowlist

89 ```

90 </Step>

91 </Steps>

92 </Tab>

93 

94 <Tab title="Discord">

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

96 

97 <Steps>

98 <Step title="Create a Discord bot">

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

100 </Step>

101 

102 <Step title="Enable Message Content Intent">

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

104 </Step>

105 

106 <Step title="Invite the bot to your server">

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

108 

109 * View Channels

110 * Send Messages

111 * Send Messages in Threads

112 * Read Message History

113 * Attach Files

114 * Add Reactions

115 

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

117 </Step>

118 

119 <Step title="Install the plugin">

120 In Claude Code, run:

121 

122 ```

123 /plugin install discord@claude-plugins-official

124 ```

125 

126 If Claude Code reports that the plugin is not found in any marketplace, your marketplace is either missing or outdated. Run `/plugin marketplace update claude-plugins-official` to refresh it, or `/plugin marketplace add anthropics/claude-plugins-official` if you haven't added it before. Then retry the install.

127 

128 After installing, run `/reload-plugins` to activate the plugin's configure command.

129 </Step>

130 

131 <Step title="Configure your token">

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

133 

134 ```

135 /discord:configure <token>

136 ```

137 

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

139 </Step>

140 

141 <Step title="Restart with channels enabled">

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

143 

144 ```bash theme={null}

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

146 ```

147 </Step>

148 

149 <Step title="Pair your account">

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

151 

152 <Note>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.</Note>

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 ```

165 </Step>

166 </Steps>

167 </Tab>

168 

169 <Tab title="iMessage">

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

171 

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

173 

174 <Steps>

175 <Step title="Grant Full Disk Access">

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

177 

178 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`.

179 </Step>

180 

181 <Step title="Install the plugin">

182 In Claude Code, run:

183 

184 ```

185 /plugin install imessage@claude-plugins-official

186 ```

187 

188 If Claude Code reports that the plugin is not found in any marketplace, your marketplace is either missing or outdated. Run `/plugin marketplace update claude-plugins-official` to refresh it, or `/plugin marketplace add anthropics/claude-plugins-official` if you haven't added it before. Then retry the install.

189 </Step>

190 

191 <Step title="Restart with channels enabled">

192 Exit Claude Code and restart with the channel flag:

193 

194 ```bash theme={null}

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

196 ```

197 </Step>

198 

199 <Step title="Text yourself">

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

201 

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

203 </Step>

204 

205 <Step title="Allow other senders">

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

207 

208 ```

209 /imessage:access allow +15551234567

210 ```

211 

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

213 </Step>

214 </Steps>

215 </Tab>

216</Tabs>

217 

218You can also [build your own channel](/en/channels-reference) for systems that don't have a plugin yet.

219 

220## Quickstart

221 

222Fakechat is an officially supported demo channel that runs a chat UI on localhost, with nothing to authenticate and no external service to configure.

223 

224Once you install and enable fakechat, you can type in the browser and the message arrives in your Claude Code session. Claude replies, and the reply shows up back in the browser. After you've tested the fakechat interface, try out [Telegram](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram), [Discord](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord), or [iMessage](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/imessage).

225 

226To try the fakechat demo, you'll need:

227 

228* Claude Code [installed and authenticated](/en/quickstart#step-1-install-claude-code) with a claude.ai account

229* [Bun](https://bun.sh) installed. The pre-built channel plugins are Bun scripts. Check with `bun --version`; if that fails, [install Bun](https://bun.sh/docs/installation).

230* **Team/Enterprise users**: your organization admin must [enable channels](#enterprise-controls) in managed settings

231 

232<Steps>

233 <Step title="Install the fakechat channel plugin">

234 Start a Claude Code session and run the install command:

235 

236 ```text theme={null}

237 /plugin install fakechat@claude-plugins-official

238 ```

239 

240 If Claude Code reports that the plugin is not found in any marketplace, your marketplace is either missing or outdated. Run `/plugin marketplace update claude-plugins-official` to refresh it, or `/plugin marketplace add anthropics/claude-plugins-official` if you haven't added it before. Then retry the install.

241 </Step>

242 

243 <Step title="Restart with the channel enabled">

244 Exit Claude Code, then restart with `--channels` and pass the fakechat plugin you installed:

245 

246 ```bash theme={null}

247 claude --channels plugin:fakechat@claude-plugins-official

248 ```

249 

250 The fakechat server starts automatically.

251 

252 <Tip>

253 You can pass several plugins to `--channels`, space-separated.

254 </Tip>

255 </Step>

256 

257 <Step title="Push a message in">

258 Open the fakechat UI at [http://localhost:8787](http://localhost:8787) and type a message:

259 

260 ```text theme={null}

261 hey, what's in my working directory?

262 ```

263 

264 The message arrives in your Claude Code session as a `<channel source="fakechat">` event. Claude reads it, does the work, and calls fakechat's `reply` tool. The answer shows up in the chat UI.

265 </Step>

266</Steps>

267 

268If Claude hits a permission prompt while you're away from the terminal, the session pauses until you respond. Channel servers that declare the [permission relay capability](/en/channels-reference#relay-permission-prompts) can forward these prompts to you so you can approve or deny remotely. For unattended use, [`--dangerously-skip-permissions`](/en/permission-modes#skip-all-checks-with-bypasspermissions-mode) bypasses prompts entirely, but only use it in environments you trust.

269 

270## Security

271 

272Every approved channel plugin maintains a sender allowlist: only IDs you've added can push messages, and everyone else is silently dropped.

273 

274Telegram and Discord bootstrap the list by pairing:

275 

2761. Find your bot in Telegram or Discord and send it any message

2772. The bot replies with a pairing code

2783. In your Claude Code session, approve the code when prompted

2794. Your sender ID is added to the allowlist

280 

281iMessage works differently: texting yourself bypasses the gate automatically, and you add other contacts by handle with `/imessage:access allow`.

282 

283On top of that, you control which servers are enabled each session with `--channels`, and on Team and Enterprise plans your organization controls availability with [`channelsEnabled`](#enterprise-controls).

284 

285Being in `.mcp.json` isn't enough to push messages: a server also has to be named in `--channels`.

286 

287The allowlist also gates [permission relay](/en/channels-reference#relay-permission-prompts) if the channel declares it. Anyone who can reply through the channel can approve or deny tool use in your session, so only allowlist senders you trust with that authority.

288 

289## Enterprise controls

290 

291On Team and Enterprise plans, channels are off by default. Admins control availability through two [managed settings](/en/settings) that users cannot override:

292 

293| Setting | Purpose | When not configured |

294| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------- |

295| `channelsEnabled` | Master switch. Must be `true` for any channel to deliver messages. Set via the [claude.ai Admin console](https://claude.ai/admin-settings/claude-code) toggle or directly in managed settings. Blocks all channels including the development flag when off. | Channels blocked |

296| `allowedChannelPlugins` | Which plugins can register once channels are enabled. Replaces the Anthropic-maintained list when set. Only applies when `channelsEnabled` is `true`. | Anthropic default list applies |

297 

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

299 

300### Enable channels for your organization

301 

302Admins can enable channels from [**claude.ai → Admin settings → Claude Code → Channels**](https://claude.ai/admin-settings/claude-code), or by setting `channelsEnabled` to `true` in managed settings.

303 

304Once enabled, users in your organization can use `--channels` to opt channel servers into individual sessions. If the setting is disabled or unset, the MCP server still connects and its tools work, but channel messages won't arrive. A startup warning tells the user to have an admin enable the setting.

305 

306### Restrict which channel plugins can run

307 

308By default, any plugin on the Anthropic-maintained allowlist can register as a channel. Admins on Team and Enterprise plans can replace that allowlist with their own by setting `allowedChannelPlugins` in managed settings. Use this to restrict which official plugins are allowed, approve channels from your own internal marketplace, or both. Each entry names a plugin and the marketplace it comes from:

309 

310```json theme={null}

311{

312 "channelsEnabled": true,

313 "allowedChannelPlugins": [

314 { "marketplace": "claude-plugins-official", "plugin": "telegram" },

315 { "marketplace": "claude-plugins-official", "plugin": "discord" },

316 { "marketplace": "acme-corp-plugins", "plugin": "internal-alerts" }

317 ]

318}

319```

320 

321When `allowedChannelPlugins` is set, it replaces the Anthropic allowlist entirely: only the listed plugins can register. Leave it unset to fall back to the default Anthropic allowlist. An empty array blocks all channel plugins from the allowlist, but `--dangerously-load-development-channels` can still bypass it for local testing. To block channels entirely including the development flag, leave `channelsEnabled` unset instead.

322 

323This setting requires `channelsEnabled: true`. If a user passes a plugin to `--channels` that isn't on your list, Claude Code starts normally but the channel doesn't register, and the startup notice explains that the plugin isn't on the organization's approved list.

324 

325## Research preview

326 

327Channels are a research preview feature. Availability is rolling out gradually, and the `--channels` flag syntax and protocol contract may change based on feedback.

328 

329During the preview, `--channels` only accepts plugins from an Anthropic-maintained allowlist, or from your organization's allowlist if an admin has set [`allowedChannelPlugins`](#restrict-which-channel-plugins-can-run). The channel plugins in [claude-plugins-official](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins) are the default approved set. If you pass something that isn't on the effective allowlist, Claude Code starts normally but the channel doesn't register, and the startup notice tells you why.

330 

331To test a channel you're building, use `--dangerously-load-development-channels`. See [Test during the research preview](/en/channels-reference#test-during-the-research-preview) for information about testing custom channels that you build.

332 

333Report issues or feedback on the [Claude Code GitHub repository](https://github.com/anthropics/claude-code/issues).

334 

335## How channels compare

336 

337Several Claude Code features connect to systems outside the terminal, each suited to a different kind of work:

338 

339| Feature | What it does | Good for |

340| ---------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- |

341| [Claude Code on the web](/en/claude-code-on-the-web) | Runs tasks in a fresh cloud sandbox, cloned from GitHub | Delegating self-contained async work you check on later |

342| [Claude in Slack](/en/slack) | Spawns a web session from an `@Claude` mention in a channel or thread | Starting tasks directly from team conversation context |

343| Standard [MCP server](/en/mcp) | Claude queries it during a task; nothing is pushed to the session | Giving Claude on-demand access to read or query a system |

344| [Remote Control](/en/remote-control) | You drive your local session from claude.ai or the Claude mobile app | Steering an in-progress session while away from your desk |

345 

346Channels fill the gap in that list by pushing events from non-Claude sources into your already-running local session.

347 

348* **Chat bridge**: ask Claude something from your phone via Telegram, Discord, or iMessage, and the answer comes back in the same chat while the work runs on your machine against your real files.

349* **[Webhook receiver](/en/channels-reference#example-build-a-webhook-receiver)**: a webhook from CI, your error tracker, a deploy pipeline, or other external service arrives where Claude already has your files open and remembers what you were debugging.

350 

351## Next steps

352 

353Once you have a channel running, explore these related features:

354 

355* [Build your own channel](/en/channels-reference) for systems that don't have plugins yet

356* [Remote Control](/en/remote-control) to drive a local session from your phone instead of forwarding events into it

357* [Scheduled tasks](/en/scheduled-tasks) to poll on a timer instead of reacting to pushed events

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Channels reference

6 

7> Build an MCP server that pushes webhooks, alerts, and chat messages into a Claude Code session. Reference for the channel contract: capability declaration, notification events, reply tools, sender gating, and permission relay.

8 

9<Note>

10 Channels are in [research preview](/en/channels#research-preview) and require Claude Code v2.1.80 or later. They require claude.ai login. Console and API key authentication is not supported. Team and Enterprise organizations must [explicitly enable them](/en/channels#enterprise-controls).

11</Note>

12 

13A channel is an MCP server that pushes events into a Claude Code session so Claude can react to things happening outside the terminal.

14 

15You can build a one-way or two-way channel. One-way channels forward alerts, webhooks, or monitoring events for Claude to act on. Two-way channels like chat bridges also [expose a reply tool](#expose-a-reply-tool) so Claude can send messages back. A channel with a trusted sender path can also opt in to [relay permission prompts](#relay-permission-prompts) so you can approve or deny tool use remotely.

16 

17This page covers:

18 

19* [Overview](#overview): how channels work

20* [What you need](#what-you-need): requirements and general steps

21* [Example: build a webhook receiver](#example-build-a-webhook-receiver): a minimal one-way walkthrough

22* [Server options](#server-options): the constructor fields

23* [Notification format](#notification-format): the event payload

24* [Expose a reply tool](#expose-a-reply-tool): let Claude send messages back

25* [Gate inbound messages](#gate-inbound-messages): sender checks to prevent prompt injection

26* [Relay permission prompts](#relay-permission-prompts): forward tool approval prompts to remote channels

27 

28To use an existing channel instead of building one, see [Channels](/en/channels). Telegram, Discord, iMessage, and fakechat are included in the research preview.

29 

30## Overview

31 

32A channel is an [MCP](https://modelcontextprotocol.io) server that runs on the same machine as Claude Code. Claude Code spawns it as a subprocess and communicates over stdio. Your channel server is the bridge between external systems and the Claude Code session:

33 

34* **Chat platforms** (Telegram, Discord): your plugin runs locally and polls the platform's API for new messages. When someone DMs your bot, the plugin receives the message and forwards it to Claude. No URL to expose.

35* **Webhooks** (CI, monitoring): your server listens on a local HTTP port. External systems POST to that port, and your server pushes the payload to Claude.

36 

37<img src="https://mintcdn.com/claude-code/zbUxPYi8065L3Y_P/en/images/channel-architecture.svg?fit=max&auto=format&n=zbUxPYi8065L3Y_P&q=85&s=fd6b6b949eab38264043d2a96285a57c" alt="Architecture diagram showing external systems connecting to your local channel server, which communicates with Claude Code over stdio" width="600" height="220" data-path="en/images/channel-architecture.svg" />

38 

39## What you need

40 

41The only hard requirement is the [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) package and a Node.js-compatible runtime. [Bun](https://bun.sh), [Node](https://nodejs.org), and [Deno](https://deno.com) all work. The pre-built plugins in the research preview use Bun, but your channel doesn't have to.

42 

43Your server needs to:

44 

451. Declare the `claude/channel` capability so Claude Code registers a notification listener

462. Emit `notifications/claude/channel` events when something happens

473. Connect over [stdio transport](https://modelcontextprotocol.io/docs/concepts/transports#standard-io) (Claude Code spawns your server as a subprocess)

48 

49The [Server options](#server-options) and [Notification format](#notification-format) sections cover each of these in detail. See [Example: build a webhook receiver](#example-build-a-webhook-receiver) for a full walkthrough.

50 

51During the research preview, custom channels aren't on the [approved allowlist](/en/channels#supported-channels). Use `--dangerously-load-development-channels` to test locally. See [Test during the research preview](#test-during-the-research-preview) for details.

52 

53## Example: build a webhook receiver

54 

55This walkthrough builds a single-file server that listens for HTTP requests and forwards them into your Claude Code session. By the end, anything that can send an HTTP POST, like a CI pipeline, a monitoring alert, or a `curl` command, can push events to Claude.

56 

57This example uses [Bun](https://bun.sh) as the runtime for its built-in HTTP server and TypeScript support. You can use [Node](https://nodejs.org) or [Deno](https://deno.com) instead; the only requirement is the [MCP SDK](https://www.npmjs.com/package/@modelcontextprotocol/sdk).

58 

59<Steps>

60 <Step title="Create the project">

61 Create a new directory and install the MCP SDK:

62 

63 ```bash theme={null}

64 mkdir webhook-channel && cd webhook-channel

65 bun add @modelcontextprotocol/sdk

66 ```

67 </Step>

68 

69 <Step title="Write the channel server">

70 Create a file called `webhook.ts`. This is your entire channel server: it connects to Claude Code over stdio, and it listens for HTTP POSTs on port 8788. When a request arrives, it pushes the body to Claude as a channel event.

71 

72 ```ts title="webhook.ts" theme={null}

73 #!/usr/bin/env bun

74 import { Server } from '@modelcontextprotocol/sdk/server/index.js'

75 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

76 

77 // Create the MCP server and declare it as a channel

78 const mcp = new Server(

79 { name: 'webhook', version: '0.0.1' },

80 {

81 // this key is what makes it a channel — Claude Code registers a listener for it

82 capabilities: { experimental: { 'claude/channel': {} } },

83 // added to Claude's system prompt so it knows how to handle these events

84 instructions: 'Events from the webhook channel arrive as <channel source="webhook" ...>. They are one-way: read them and act, no reply expected.',

85 },

86 )

87 

88 // Connect to Claude Code over stdio (Claude Code spawns this process)

89 await mcp.connect(new StdioServerTransport())

90 

91 // Start an HTTP server that forwards every POST to Claude

92 Bun.serve({

93 port: 8788, // any open port works

94 // localhost-only: nothing outside this machine can POST

95 hostname: '127.0.0.1',

96 async fetch(req) {

97 const body = await req.text()

98 await mcp.notification({

99 method: 'notifications/claude/channel',

100 params: {

101 content: body, // becomes the body of the <channel> tag

102 // each key becomes a tag attribute, e.g. <channel path="/" method="POST">

103 meta: { path: new URL(req.url).pathname, method: req.method },

104 },

105 })

106 return new Response('ok')

107 },

108 })

109 ```

110 

111 The file does three things in order:

112 

113 * **Server configuration**: creates the MCP server with `claude/channel` in its capabilities, which is what tells Claude Code this is a channel. The [`instructions`](#server-options) string goes into Claude's system prompt: tell Claude what events to expect, whether to reply, and how to route replies if it should.

114 * **Stdio connection**: connects to Claude Code over stdin/stdout. This is standard for any [MCP server](https://modelcontextprotocol.io/docs/concepts/transports#standard-io): Claude Code spawns it as a subprocess.

115 * **HTTP listener**: starts a local web server on port 8788. Every POST body gets forwarded to Claude as a channel event via `mcp.notification()`. The `content` becomes the event body, and each `meta` entry becomes an attribute on the `<channel>` tag. The listener needs access to the `mcp` instance, so it runs in the same process. You could split it into separate modules for a larger project.

116 </Step>

117 

118 <Step title="Register your server with Claude Code">

119 Add the server to your MCP config so Claude Code knows how to start it. For a project-level `.mcp.json` in the same directory, use a relative path. For user-level config in `~/.claude.json`, use the full absolute path so the server can be found from any project:

120 

121 ```json title=".mcp.json" theme={null}

122 {

123 "mcpServers": {

124 "webhook": { "command": "bun", "args": ["./webhook.ts"] }

125 }

126 }

127 ```

128 

129 Claude Code reads your MCP config at startup and spawns each server as a subprocess.

130 </Step>

131 

132 <Step title="Test it">

133 During the research preview, custom channels aren't on the allowlist, so start Claude Code with the development flag:

134 

135 ```bash theme={null}

136 claude --dangerously-load-development-channels server:webhook

137 ```

138 

139 When Claude Code starts, it reads your MCP config, spawns your `webhook.ts` as a subprocess, and the HTTP listener starts automatically on the port you configured (8788 in this example). You don't need to run the server yourself.

140 

141 If you see "blocked by org policy," your Team or Enterprise admin needs to [enable channels](/en/channels#enterprise-controls) first.

142 

143 In a separate terminal, simulate a webhook by sending an HTTP POST with a message to your server. This example sends a CI failure alert to port 8788 (or whichever port you configured):

144 

145 ```bash theme={null}

146 curl -X POST localhost:8788 -d "build failed on main: https://ci.example.com/run/1234"

147 ```

148 

149 The payload arrives in your Claude Code session as a `<channel>` tag:

150 

151 ```text theme={null}

152 <channel source="webhook" path="/" method="POST">build failed on main: https://ci.example.com/run/1234</channel>

153 ```

154 

155 In your Claude Code terminal, you'll see Claude receive the message and start responding: reading files, running commands, or whatever the message calls for. This is a one-way channel, so Claude acts in your session but doesn't send anything back through the webhook. To add replies, see [Expose a reply tool](#expose-a-reply-tool).

156 

157 If the event doesn't arrive, the diagnosis depends on what `curl` returned:

158 

159 * **`curl` succeeds but nothing reaches Claude**: run `/mcp` in your session to check the server's status. "Failed to connect" usually means a dependency or import error in your server file; check the debug log at `~/.claude/debug/<session-id>.txt` for the stderr trace.

160 * **`curl` fails with "connection refused"**: the port is either not bound yet or a stale process from an earlier run is holding it. `lsof -i :<port>` shows what's listening; `kill` the stale process before restarting your session.

161 </Step>

162</Steps>

163 

164The [fakechat server](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/fakechat) extends this pattern with a web UI, file attachments, and a reply tool for two-way chat.

165 

166## Test during the research preview

167 

168During the research preview, every channel must be on the [approved allowlist](/en/channels#research-preview) to register. The development flag bypasses the allowlist for specific entries after a confirmation prompt. This example shows both entry types:

169 

170```bash theme={null}

171# Testing a plugin you're developing

172claude --dangerously-load-development-channels plugin:yourplugin@yourmarketplace

173 

174# Testing a bare .mcp.json server (no plugin wrapper yet)

175claude --dangerously-load-development-channels server:webhook

176```

177 

178The bypass is per-entry. Combining this flag with `--channels` doesn't extend the bypass to the `--channels` entries. During the research preview, the approved allowlist is Anthropic-curated, so your channel stays on the development flag while you build and test.

179 

180<Note>

181 This flag skips the allowlist only. The `channelsEnabled` organization policy still applies. Don't use it to run channels from untrusted sources.

182</Note>

183 

184## Server options

185 

186A channel sets these options in the [`Server`](https://modelcontextprotocol.io/docs/concepts/servers) constructor. The `instructions` and `capabilities.tools` fields are [standard MCP](https://modelcontextprotocol.io/docs/concepts/servers); `capabilities.experimental['claude/channel']` and `capabilities.experimental['claude/channel/permission']` are the channel-specific additions:

187 

188| Field | Type | Description |

189| :------------------------------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

190| `capabilities.experimental['claude/channel']` | `object` | Required. Always `{}`. Presence registers the notification listener. |

191| `capabilities.experimental['claude/channel/permission']` | `object` | Optional. Always `{}`. Declares that this channel can receive permission relay requests. When declared, Claude Code forwards tool approval prompts to your channel so you can approve or deny them remotely. See [Relay permission prompts](#relay-permission-prompts). |

192| `capabilities.tools` | `object` | Two-way only. Always `{}`. Standard MCP tool capability. See [Expose a reply tool](#expose-a-reply-tool). |

193| `instructions` | `string` | Recommended. Added to Claude's system prompt. Tell Claude what events to expect, what the `<channel>` tag attributes mean, whether to reply, and if so which tool to use and which attribute to pass back (like `chat_id`). |

194 

195To create a one-way channel, omit `capabilities.tools`. This example shows a two-way setup with the channel capability, tools, and instructions set:

196 

197```ts theme={null}

198import { Server } from '@modelcontextprotocol/sdk/server/index.js'

199 

200const mcp = new Server(

201 { name: 'your-channel', version: '0.0.1' },

202 {

203 capabilities: {

204 experimental: { 'claude/channel': {} }, // registers the channel listener

205 tools: {}, // omit for one-way channels

206 },

207 // added to Claude's system prompt so it knows how to handle your events

208 instructions: 'Messages arrive as <channel source="your-channel" ...>. Reply with the reply tool.',

209 },

210)

211```

212 

213To push an event, call `mcp.notification()` with method `notifications/claude/channel`. The params are in the next section.

214 

215## Notification format

216 

217Your server emits `notifications/claude/channel` with two params:

218 

219| Field | Type | Description |

220| :-------- | :----------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

221| `content` | `string` | The event body. Delivered as the body of the `<channel>` tag. |

222| `meta` | `Record<string, string>` | Optional. Each entry becomes an attribute on the `<channel>` tag for routing context like chat ID, sender name, or alert severity. Keys must be identifiers: letters, digits, and underscores only. Keys containing hyphens or other characters are silently dropped. |

223 

224Your server pushes events by calling `mcp.notification()` on the `Server` instance. This example pushes a CI failure alert with two meta keys:

225 

226```ts theme={null}

227await mcp.notification({

228 method: 'notifications/claude/channel',

229 params: {

230 content: 'build failed on main: https://ci.example.com/run/1234',

231 meta: { severity: 'high', run_id: '1234' },

232 },

233})

234```

235 

236The event arrives in Claude's context wrapped in a `<channel>` tag. The `source` attribute is set automatically from your server's configured name:

237 

238```text theme={null}

239<channel source="your-channel" severity="high" run_id="1234">

240build failed on main: https://ci.example.com/run/1234

241</channel>

242```

243 

244## Expose a reply tool

245 

246If your channel is two-way, like a chat bridge rather than an alert forwarder, expose a standard [MCP tool](https://modelcontextprotocol.io/docs/concepts/tools) that Claude can call to send messages back. Nothing about the tool registration is channel-specific. A reply tool has three components:

247 

2481. A `tools: {}` entry in your `Server` constructor capabilities so Claude Code discovers the tool

2492. Tool handlers that define the tool's schema and implement the send logic

2503. An `instructions` string in your `Server` constructor that tells Claude when and how to call the tool

251 

252To add these to the [webhook receiver above](#example-build-a-webhook-receiver):

253 

254<Steps>

255 <Step title="Enable tool discovery">

256 In your `Server` constructor in `webhook.ts`, add `tools: {}` to the capabilities so Claude Code knows your server offers tools:

257 

258 ```ts theme={null}

259 capabilities: {

260 experimental: { 'claude/channel': {} },

261 tools: {}, // enables tool discovery

262 },

263 ```

264 </Step>

265 

266 <Step title="Register the reply tool">

267 Add the following to `webhook.ts`. The `import` goes at the top of the file with your other imports; the two handlers go between the `Server` constructor and `mcp.connect()`. This registers a `reply` tool that Claude can call with a `chat_id` and `text`:

268 

269 ```ts theme={null}

270 // Add this import at the top of webhook.ts

271 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'

272 

273 // Claude queries this at startup to discover what tools your server offers

274 mcp.setRequestHandler(ListToolsRequestSchema, async () => ({

275 tools: [{

276 name: 'reply',

277 description: 'Send a message back over this channel',

278 // inputSchema tells Claude what arguments to pass

279 inputSchema: {

280 type: 'object',

281 properties: {

282 chat_id: { type: 'string', description: 'The conversation to reply in' },

283 text: { type: 'string', description: 'The message to send' },

284 },

285 required: ['chat_id', 'text'],

286 },

287 }],

288 }))

289 

290 // Claude calls this when it wants to invoke a tool

291 mcp.setRequestHandler(CallToolRequestSchema, async req => {

292 if (req.params.name === 'reply') {

293 const { chat_id, text } = req.params.arguments as { chat_id: string; text: string }

294 // send() is your outbound: POST to your chat platform, or for local

295 // testing the SSE broadcast shown in the full example below.

296 send(`Reply to ${chat_id}: ${text}`)

297 return { content: [{ type: 'text', text: 'sent' }] }

298 }

299 throw new Error(`unknown tool: ${req.params.name}`)

300 })

301 ```

302 </Step>

303 

304 <Step title="Update the instructions">

305 Update the `instructions` string in your `Server` constructor so Claude knows to route replies back through the tool. This example tells Claude to pass `chat_id` from the inbound tag:

306 

307 ```ts theme={null}

308 instructions: 'Messages arrive as <channel source="webhook" chat_id="...">. Reply with the reply tool, passing the chat_id from the tag.'

309 ```

310 </Step>

311</Steps>

312 

313Here's the complete `webhook.ts` with two-way support. Outbound replies stream over `GET /events` using [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) (SSE), so `curl -N localhost:8788/events` can watch them live; inbound chat arrives on `POST /`:

314 

315```ts title="Full webhook.ts with reply tool" expandable theme={null}

316#!/usr/bin/env bun

317import { Server } from '@modelcontextprotocol/sdk/server/index.js'

318import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

319import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'

320 

321// --- Outbound: write to any curl -N listeners on /events --------------------

322// A real bridge would POST to your chat platform instead.

323const listeners = new Set<(chunk: string) => void>()

324function send(text: string) {

325 const chunk = text.split('\n').map(l => `data: ${l}\n`).join('') + '\n'

326 for (const emit of listeners) emit(chunk)

327}

328 

329const mcp = new Server(

330 { name: 'webhook', version: '0.0.1' },

331 {

332 capabilities: {

333 experimental: { 'claude/channel': {} },

334 tools: {},

335 },

336 instructions: 'Messages arrive as <channel source="webhook" chat_id="...">. Reply with the reply tool, passing the chat_id from the tag.',

337 },

338)

339 

340mcp.setRequestHandler(ListToolsRequestSchema, async () => ({

341 tools: [{

342 name: 'reply',

343 description: 'Send a message back over this channel',

344 inputSchema: {

345 type: 'object',

346 properties: {

347 chat_id: { type: 'string', description: 'The conversation to reply in' },

348 text: { type: 'string', description: 'The message to send' },

349 },

350 required: ['chat_id', 'text'],

351 },

352 }],

353}))

354 

355mcp.setRequestHandler(CallToolRequestSchema, async req => {

356 if (req.params.name === 'reply') {

357 const { chat_id, text } = req.params.arguments as { chat_id: string; text: string }

358 send(`Reply to ${chat_id}: ${text}`)

359 return { content: [{ type: 'text', text: 'sent' }] }

360 }

361 throw new Error(`unknown tool: ${req.params.name}`)

362})

363 

364await mcp.connect(new StdioServerTransport())

365 

366let nextId = 1

367Bun.serve({

368 port: 8788,

369 hostname: '127.0.0.1',

370 idleTimeout: 0, // don't close idle SSE streams

371 async fetch(req) {

372 const url = new URL(req.url)

373 

374 // GET /events: SSE stream so curl -N can watch Claude's replies live

375 if (req.method === 'GET' && url.pathname === '/events') {

376 const stream = new ReadableStream({

377 start(ctrl) {

378 ctrl.enqueue(': connected\n\n') // so curl shows something immediately

379 const emit = (chunk: string) => ctrl.enqueue(chunk)

380 listeners.add(emit)

381 req.signal.addEventListener('abort', () => listeners.delete(emit))

382 },

383 })

384 return new Response(stream, {

385 headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' },

386 })

387 }

388 

389 // POST: forward to Claude as a channel event

390 const body = await req.text()

391 const chat_id = String(nextId++)

392 await mcp.notification({

393 method: 'notifications/claude/channel',

394 params: {

395 content: body,

396 meta: { chat_id, path: url.pathname, method: req.method },

397 },

398 })

399 return new Response('ok')

400 },

401})

402```

403 

404The [fakechat server](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/fakechat) shows a more complete example with file attachments and message editing.

405 

406## Gate inbound messages

407 

408An ungated channel is a prompt injection vector. Anyone who can reach your endpoint can put text in front of Claude. A channel listening to a chat platform or a public endpoint needs a real sender check before it emits anything.

409 

410Check the sender against an allowlist before calling `mcp.notification()`. This example drops any message from a sender not in the set:

411 

412```ts theme={null}

413const allowed = new Set(loadAllowlist()) // from your access.json or equivalent

414 

415// inside your message handler, before emitting:

416if (!allowed.has(message.from.id)) { // sender, not room

417 return // drop silently

418}

419await mcp.notification({ ... })

420```

421 

422Gate on the sender's identity, not the chat or room identity: `message.from.id` in the example, not `message.chat.id`. In group chats, these differ, and gating on the room would let anyone in an allowlisted group inject messages into the session.

423 

424The [Telegram](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram) and [Discord](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord) channels gate on a sender allowlist the same way. They bootstrap the list by pairing: the user DMs the bot, the bot replies with a pairing code, the user approves it in their Claude Code session, and their platform ID is added. See either implementation for the full pairing flow. The [iMessage](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/imessage) channel takes a different approach: it detects the user's own addresses from the Messages database at startup and lets them through automatically, with other senders added by handle.

425 

426## Relay permission prompts

427 

428<Note>

429 Permission relay requires Claude Code v2.1.81 or later. Earlier versions ignore the `claude/channel/permission` capability.

430</Note>

431 

432When Claude calls a tool that needs approval, the local terminal dialog opens and the session waits. A two-way channel can opt in to receive the same prompt in parallel and relay it to you on another device. Both stay live: you can answer in the terminal or on your phone, and Claude Code applies whichever answer arrives first and closes the other.

433 

434Relay covers tool-use approvals like `Bash`, `Write`, and `Edit`. Project trust and MCP server consent dialogs don't relay; those only appear in the local terminal.

435 

436### How relay works

437 

438When a permission prompt opens, the relay loop has four steps:

439 

4401. Claude Code generates a short request ID and notifies your server

4412. Your server forwards the prompt and ID to your chat app

4423. The remote user replies with a yes or no and that ID

4434. Your inbound handler parses the reply into a verdict, and Claude Code applies it only if the ID matches an open request

444 

445The local terminal dialog stays open through all of this. If someone at the terminal answers before the remote verdict arrives, that answer is applied instead and the pending remote request is dropped.

446 

447<img src="https://mintcdn.com/claude-code/DsZvsJII1OmzIjIs/en/images/channel-permission-relay.svg?fit=max&auto=format&n=DsZvsJII1OmzIjIs&q=85&s=c1d75f6ee34c2757983e2cca899b90d1" alt="Sequence diagram: Claude Code sends a permission_request notification to the channel server, the server formats and sends the prompt to the chat app, the human replies with a verdict, and the server parses that reply into a permission notification back to Claude Code" width="600" height="230" data-path="en/images/channel-permission-relay.svg" />

448 

449### Permission request fields

450 

451The outbound notification from Claude Code is `notifications/claude/channel/permission_request`. Like the [channel notification](#notification-format), the transport is standard MCP but the method and schema are Claude Code extensions. The `params` object has four string fields your server formats into the outgoing prompt:

452 

453| Field | Description |

454| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

455| `request_id` | Five lowercase letters drawn from `a`-`z` without `l`, so it never reads as a `1` or `I` when typed on a phone. Include it in your outgoing prompt so it can be echoed in the reply. Claude Code only accepts a verdict that carries an ID it issued. The local terminal dialog doesn't display this ID, so your outbound handler is the only way to learn it. |

456| `tool_name` | Name of the tool Claude wants to use, for example `Bash` or `Write`. |

457| `description` | Human-readable summary of what this specific tool call does, the same text the local terminal dialog shows. For a Bash call this is Claude's description of the command, or the command itself if none was given. |

458| `input_preview` | The tool's arguments as a JSON string, truncated to 200 characters. For Bash this is the command; for Write it's the file path and a prefix of the content. Omit it from your prompt if you only have room for a one-line message. Your server decides what to show. |

459 

460The verdict your server sends back is `notifications/claude/channel/permission` with two fields: `request_id` echoing the ID above, and `behavior` set to `'allow'` or `'deny'`. Allow lets the tool call proceed; deny rejects it, the same as answering No in the local dialog. Neither verdict affects future calls.

461 

462### Add relay to a chat bridge

463 

464Adding permission relay to a two-way channel takes three components:

465 

4661. A `claude/channel/permission: {}` entry under `experimental` capabilities in your `Server` constructor so Claude Code knows to forward prompts

4672. A notification handler for `notifications/claude/channel/permission_request` that formats the prompt and sends it out through your platform API

4683. A check in your inbound message handler that recognizes `yes <id>` or `no <id>` and emits a `notifications/claude/channel/permission` verdict instead of forwarding the text to Claude

469 

470Only declare the capability if your channel [authenticates the sender](#gate-inbound-messages), because anyone who can reply through your channel can approve or deny tool use in your session.

471 

472To add these to a two-way chat bridge like the one assembled in [Expose a reply tool](#expose-a-reply-tool):

473 

474<Steps>

475 <Step title="Declare the permission capability">

476 In your `Server` constructor, add `claude/channel/permission: {}` alongside `claude/channel` under `experimental`:

477 

478 ```ts theme={null}

479 capabilities: {

480 experimental: {

481 'claude/channel': {},

482 'claude/channel/permission': {}, // opt in to permission relay

483 },

484 tools: {},

485 },

486 ```

487 </Step>

488 

489 <Step title="Handle the incoming request">

490 Register a notification handler between your `Server` constructor and `mcp.connect()`. Claude Code calls it with the [four request fields](#permission-request-fields) when a permission dialog opens. Your handler formats the prompt for your platform and includes instructions for replying with the ID:

491 

492 ```ts theme={null}

493 import { z } from 'zod'

494 

495 // setNotificationHandler routes by z.literal on the method field,

496 // so this schema is both the validator and the dispatch key

497 const PermissionRequestSchema = z.object({

498 method: z.literal('notifications/claude/channel/permission_request'),

499 params: z.object({

500 request_id: z.string(), // five lowercase letters, include verbatim in your prompt

501 tool_name: z.string(), // e.g. "Bash", "Write"

502 description: z.string(), // human-readable summary of this call

503 input_preview: z.string(), // tool args as JSON, truncated to ~200 chars

504 }),

505 })

506 

507 mcp.setNotificationHandler(PermissionRequestSchema, async ({ params }) => {

508 // send() is your outbound: POST to your chat platform, or for local

509 // testing the SSE broadcast shown in the full example below.

510 send(

511 `Claude wants to run ${params.tool_name}: ${params.description}\n\n` +

512 // the ID in the instruction is what your inbound handler parses in Step 3

513 `Reply "yes ${params.request_id}" or "no ${params.request_id}"`,

514 )

515 })

516 ```

517 </Step>

518