claude-code-20260929T003702Z / documentation capture

authentication Changed · +8 / -0 lines

from line 26

2626

2727To log out and re-authenticate, type `/logout` at the Claude Code prompt. Logging out also resets your first-launch setup state, so the next time you run `claude` it walks you through login and setup again.

2828

29To stay signed in to multiple accounts at once, such as work and personal accounts, give each account its own configuration directory. When you start `claude`, set the [`CLAUDE_CONFIG_DIR`](/docs/en/env-vars#variables) environment variable to the directory for the account you want to use. Each directory has its own settings, session history, and claude.ai login or API key. For example, in Bash or Zsh, add this alias to `~/.bashrc` or `~/.zshrc` so that `claude-work` uses your work account while `claude` keeps your personal one:

30

31```bash theme={null}

32alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

33```

34

35After you open a new terminal and run `claude-work` for the first time, Claude Code walks you through login and setup for the new directory. Separate directories don't keep two Claude Console sign-ins [without an API key](#sign-in-without-an-api-key) apart, because Claude Code stores that kind of sign-in outside the configuration directory.

36

2937If you're having trouble logging in, see [authentication troubleshooting](/docs/en/troubleshoot-install#login-and-authentication).

3038

3139## Set up team authentication

hooks Changed · +6 / -6 lines

from line 590

590590| Field | Required | Description |

591591| :- | :- | :- |

592592| `prompt` | yes | Prompt text to send to the model. Use `$ARGUMENTS` as a placeholder for the hook input JSON. Escape with a backslash to include literal text: `\$1.00` renders as `$1.00` |

593| `model` | no | Model to use for evaluation. Defaults to a fast model |

593| `model` | no | Model to use for evaluation. Defaults to the model Claude Code uses for [background functionality](/docs/en/costs#background-token-usage) |

594594

595595### Reference scripts by path

596596

from line 1790

17901790| Field | Description |

17911791| :- | :- |

17921792| `permissionDecision` | `"allow"` skips the permission prompt, except for the [actions no mode auto-approves](/docs/en/permission-modes#actions-no-mode-auto-approves) and for `AskUserQuestion` and `ExitPlanMode`, which need [`updatedInput` paired with it](#allow-with-updatedinput). `"deny"` prevents the tool call. `"ask"` prompts the user to confirm. `"defer"` exits gracefully so the tool can be resumed later. [Deny and ask rules](/docs/en/permissions#manage-permissions) are still evaluated regardless of what the hook returns |

1793| `permissionDecisionReason` | For `"allow"` and `"ask"`, shown to the user but not Claude. For `"deny"`, shown to Claude. For `"defer"`, ignored |

1793| `permissionDecisionReason` | For `"ask"`, shown to the user but not Claude. For `"deny"`, shown to Claude. For `"allow"` and `"defer"`, written to the [debug log](#debug-hooks) only |

17941794| `updatedInput` | Modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones. Claude Code evaluates permission rules and a Bash command's [auto-background eligibility](/docs/en/tools-reference#background-commands) against the input your hook returns, not the input Claude sent. Combine with `"allow"` to auto-approve, or `"ask"` to show the modified input to the user. For `"defer"`, ignored |

17951795| `additionalContext` | String added to Claude's context alongside the tool result. Ignored when `permissionDecision` is `"defer"`. See [Add context for Claude](#add-context-for-claude) |

17961796

from line 2155

21552155 "tool_name": "Read",

21562156 "tool_input": {"file_path": "/.../ledger/accounts.py"},

21572157 "tool_use_id": "toolu_01...",

2158 "tool_response": " 1\tfrom __future__ import annotations\n 2\t..."

2158 "tool_response": "1\tfrom __future__ import annotations\n2\t..."

21592159 },

21602160 {

21612161 "tool_name": "Read",

21622162 "tool_input": {"file_path": "/.../ledger/transactions.py"},

21632163 "tool_use_id": "toolu_02...",

2164 "tool_response": " 1\tfrom __future__ import annotations\n 2\t..."

2164 "tool_response": "1\tfrom __future__ import annotations\n2\t..."

21652165 }

21662166 ]

21672167}

from line 3511

35113511

35123512Instead of executing a Bash command, prompt-based hooks:

35133513

35141. Send the hook input and your prompt to a Claude model, Haiku by default

35141. Send the hook input and your prompt to a Claude model, by default the one Claude Code uses for [background functionality](/docs/en/costs#background-token-usage)

351535152. The LLM responds with structured JSON containing a decision

351635163. Claude Code processes the decision automatically

35173517

from line 3542

35423542| :- | :- | :- |

35433543| `type` | yes | Must be `"prompt"` |

35443544| `prompt` | yes | The prompt text to send to the LLM. Use `$ARGUMENTS` as a placeholder for the hook input JSON. If `$ARGUMENTS` is not present, input JSON is appended to the prompt |

3545| `model` | no | Model to use for evaluation. Defaults to a fast model |

3545| `model` | no | Model to use for evaluation. Defaults to the model Claude Code uses for [background functionality](/docs/en/costs#background-token-usage) |

35463546| `timeout` | no | Timeout in seconds. Default: 30 |

35473547| `continueOnBlock` | no | On the events it applies to, `true` feeds an `ok: false` reason back to Claude and continues instead of ending the turn. Default: `false`. See [Response schema](#response-schema) for per-event behavior |

35483548

mcp Changed · +5 / -10 lines

from line 265

265265

266266The discovery cache is off by default unless a gradual rollout has enabled it for your account. Set [`MCP_DISCOVERY_CACHE=1`](/docs/en/env-vars) to turn it on, or `0` to keep it off even when the rollout has enabled it. Before v2.1.238, the cache was on by default.

267267

268Two actions in a server's menu in `/mcp` also affect that server's cache entry:

268When you select **Disable** or **Clear authentication** from a server's menu in `/mcp`, Claude Code also discards that server's cache entry. **Reconnect** discards it too on a connected or failed server; on a `cached` server, **Reconnect** connects the server now and keeps the entry. The next time Claude Code connects to the server after discarding the entry, it fetches the tool list from the server instead of from the cache.

269269

270* **Reconnect**: on a `cached` server, Claude Code connects it now rather than on its first tool call and keeps the entry. On a connected or failed server, Claude Code reconnects it and also discards the entry.

271* **Clear authentication**: Claude Code revokes the server's authentication and also discards the entry.

272

273After discarding the entry, Claude Code fetches the server's tool list from the server instead of from the cache.

274

275270When a server's status is `✘ Failed to connect`, `claude mcp list` appends the failure detail to that status line, and `claude mcp get <name>` shows it on an `Issue:` line: the HTTP status or error code, plus any error text the server returned. The server's detail view in `/mcp` includes the same server-reported text in its `Issue:` row. Claude Code redacts credential-like text from this detail and never includes the expanded server URL, which can carry secrets. Claude Code appends no detail to a `✘ Connection error` status, because the exception text it would print there can embed that URL. Before v2.1.219, both commands showed only the bare failure status, without the status code or the server's error text.

276271

277272When you complete authentication from `/mcp` and the connection still fails with an HTTP status or a transport error code, Claude Code adds that code and the origin of the server's URL to the message it prints after the attempt. The origin is the scheme and host, plus the port when the URL names one, such as `https://mcp.example.com`.

from line 594

5995944. [Plugin-provided servers](/docs/en/plugins/components#mcp-servers)

6005955. [claude.ai connectors](#use-mcp-servers-from-claude-ai)

601596

602Claude Code matches duplicates across the three scopes by name. It matches plugins and connectors by endpoint, so one that points at the same URL or command as a server above counts as a duplicate.

597Claude Code matches duplicates across the three scopes by name. It matches plugins and connectors by endpoint, so one that points at the same URL or command as an enabled server above counts as a duplicate.

603598

604599Two URL spellings count as the same endpoint when they differ only in the letter case of the scheme or host, the scheme's default port, such as `:443` on `https`, or a trailing slash. A different path, query string, userinfo, or non-default port makes two servers.

605600

from line 814

819814 <Step title="Register an OAuth app with the server">

820815 Create an app through the server's developer portal and note your client ID and client secret.

821816

822 Many servers also require a redirect URI. If so, choose a port and register a redirect URI in the format `http://localhost:PORT/callback`. Use that same port with `--callback-port` in the next step.

817 If the registration form asks for a redirect URI, pick any available port and enter `http://localhost:PORT/callback` with that port. You'll use the same port in the next step.

823818

824819 In v2.1.229, Claude Code sent `http://127.0.0.1:PORT/callback` instead, and servers that exact-match the registered redirect URI rejected the sign-in with a redirect URI mismatch. Claude Code v2.1.231 restored the `localhost` form. To recover on v2.1.229, upgrade Claude Code, or temporarily add the `http://127.0.0.1:PORT/callback` form to the server's registered redirect URIs.

825820 </Step>

826821

827822 <Step title="Add the server with your credentials">

828 Choose one of the following methods. The port used for `--callback-port` can be any available port. It needs to match the redirect URI you registered in the previous step.

823 The tabs cover both commands: `claude mcp add` takes your client ID and callback port as flags, and `claude mcp add-json` takes them in an `oauth` object. If you registered a redirect URI, set the callback port to the port in that URI.

829824

830825 <Tabs>

831826 <Tab title="claude mcp add">

from line 844

849844 </Tab>

850845

851846 <Tab title="claude mcp add-json (callback port only)">

852 Use `--callback-port` without a client ID to fix the port while using dynamic client registration:

847 To fix only the callback port and let Claude Code register the client automatically, set `callbackPort` on its own:

853848

854849 ```bash theme={null}

855850 claude mcp add-json my-server \

settings-reference Changed · +97 / -1 lines

### `claudeInChromeDefaultEnabled` ### `copyFullResponse` ### `defaultToAgentsView` ### `leftArrowOpensAgents` ### `prStatusFooterEnabled`

This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.

from line 624

627| [`claudeInChromeDefaultEnabled`](#claudeinchromedefaultenabled) | Turn on [Chrome integration](/docs/en/chrome) in every interactive CLI session without passing `--chrome` | Global config settings | Global config |

631633| [`copyOnSelect`](#copyonselect) | Turn off automatic copying of text you select with the mouse in [fullscreen rendering](/docs/en/fullscreen#use-the-mouse) and agent view | Global config settings | Global config |

632634| [`crossSessionInbound`](#crosssessioninbound) | Choose whether Claude Code delivers [messages from your other sessions](/docs/en/cross-session-messaging#control-inbound-messages), shows a notice without delivering them, or refuses them | Agents, sessions, and worktrees | Any file |

633635| [`defaultShell`](#defaultshell) | Choose whether Bash or PowerShell runs the shell commands you type with the [`!` prefix](/docs/en/interactive-mode#shell-mode-with-prefix) | Interface and terminal | Any file |

636639| [`desktopSessionCleanupPeriodDays`](#desktopsessioncleanupperioddays) | Set an age limit in days for [Claude Desktop and Cowork transcripts](/docs/en/claude-directory#cleaned-up-automatically) | Privacy and telemetry | User or managed |

from line 689

686689| [`isolatePeerMachines`](#isolatepeermachines) | Ask you before Claude [messages one of your sessions on another machine](/docs/en/cross-session-messaging#require-approval-for-cross-machine-messages) | Agents, sessions, and worktrees | Any file |

687690| [`keybindingFlavor`](#keybindingflavor) | Deprecated and has no effect; the word-editing shortcuts always [follow readline conventions](/docs/en/interactive-mode#make-ctrl-w-delete-back-to-whitespace) | Interface and terminal | Any file |

692| [`leftArrowOpensAgents`](#leftarrowopensagents) | Turn off the `←` shortcut that [backgrounds the session and opens agent view](/docs/en/agent-view#switch-sessions-without-leaving-the-terminal) | Global config settings | Global config |

690694| [`managedSourcesBehavior`](#managedsourcesbehavior) | Compose every [managed source](/docs/en/managed-settings#how-claude-code-combines-managed-sources) you deploy instead of using the highest-priority one alone | Enterprise and managed settings | Managed |

from line 725

728| [`prStatusFooterEnabled`](#prstatusfooterenabled) | Turn off the prompt footer's [PR review status](/docs/en/interactive-mode#pr-review-status) badge and the pull request check behind it | Global config settings | Global config |

725730| [`remote.defaultEnvironmentId`](#remote-defaultenvironmentid) | Pick the default [cloud environment](/docs/en/cloud-environments) for `claude --cloud`; a self-hosted `ccpool_` ID is read only from user and managed settings and `--settings` | Remote, desktop, and notifications | Any file |

726731| [`remoteControlAtStartup`](#remotecontrolatstartup) | Connect [Remote Control](/docs/en/remote-control#enable-remote-control-for-all-sessions) automatically when a session starts | Remote, desktop, and notifications | Any file |

from line 4191

41864191

41874192* **Scope**: [`User, local, or managed`](#scopes), and files passed with `--settings`. A repository can't turn it off for you.

41884193* **Type**: Boolean

4189 * `false`: Claude Code stops downloading synced skills and stops loading the ones already in `~/.claude/skills/synced/`. In user or managed settings, it also moves them to `~/.claude/skills/.trash/`

4190 * `true`: the same as unset

4191* **Default**: unset, so sessions signed in with your claude.ai account sync your skills

4192

4193This example keeps a machine from downloading the account's skills in any session:

4194

4195```json settings.json theme={null}

4196{

4197 "syncClaudeAiSkills": false

4198}

4199```

4200

4201### `syncClaudeAiPlugins`

4202

4203Turn off the download of the [plugins enabled for your claude.ai account](/docs/en/plugins/loading#synced-plugins). Claude Code downloads them into `~/.claude/plugins/synced/` at the start of terminal sessions where you sign in with your claude.ai account and in Cowork sessions, and loads each one as `<name>@synced`. Set `false` to stop that download and stop loading the plugins it already synced. Claude Code honors only `false`: `true` is the same as unset and doesn't turn syncing on where it's otherwise off. Requires Claude Code v2.1.273 or later.

4204

4205* **Scope**: [`User, local, or managed`](#scopes), and files passed with `--settings`. A repository can't turn it off for you.

4206* **Type**: Boolean

4207 * `false`: Claude Code st

4194 * `false`: Claude Code stops downloading synced skills and stops loading the ones already in `~/.claude/skills/synced/`. In user or managed settings, it also mov

vs-code Changed · +10 / -1 lines

### Filter the sessions list

from line 255

255255

256256## Customize your workflow

257257

258You can reposition the Claude panel, run multiple conversations, organize the sessions list into groups, or switch to terminal mode.

258You can reposition the Claude panel, run multiple conversations, group or filter the sessions list, or switch to terminal mode.

259259

260260### Choose where Claude lives

261261

from line 298

298298* **Rename or delete a group**: right-click a group header. Deleting a group removes only the group, and its sessions return to the ungrouped list.

299299

300300The extension saves groups per workspace folder, so they survive window reloads and appear in every window where you open the same folder. When you search the list, the extension shows matches in one flat list across all groups.

301

302### Filter the sessions list

303

304To narrow a long sessions list in the Activity Bar, use the two filter controls at the top of the list. Requires Claude Code v2.1.271 or later. Archived sessions don't appear while either filter is on.

305

306* **Active**: turn on this toggle to show only sessions that need your input, are working, or are unread, plus the session in the Claude tab you last focused.

307* **Filter by status**: click the funnel icon, then check **Needs input**, **Working**, or **Completed** to show sessions in any of those states. Check **Open** or **Closed** to narrow by whether a session is open. A session counts as open when it has a tab in this window or is running in another Claude Code process on this machine, such as in a terminal.

308

309When **Active** is on and you check a status, **Open**, or **Closed**, the list also shows every session that matches your checks. The filters you set persist across window reloads.

301310

302311### Switch to terminal mode

303312

agent-view Changed · +1 / -1 lines

from line 240

240240

241241Pressing `←` creates the session's row even when the conversation has no messages yet, so `→` still returns to it.

242242

243You can turn this shortcut off with the `leftArrowOpensAgents` setting in `/config`.

243You can turn this shortcut off for foreground sessions with the [`leftArrowOpensAgents`](/docs/en/settings-reference#leftarrowopensagents) setting in `/config`.

244244

245245### Organize the list

246246

hooks-guide Changed · +1 / -1 lines

from line 838

838838

839839## Prompt-based hooks

840840

841For decisions that require judgment rather than deterministic rules, use `type: "prompt"` hooks. Instead of running a shell command, Claude Code sends your prompt and the hook's input data to a Claude model, Haiku by default, to make the decision. You can specify a different model with the `model` field if you need more capability.

841For decisions that require judgment rather than deterministic rules, use `type: "prompt"` hooks. Instead of running a shell command, Claude Code sends your prompt and the hook's input data to a Claude model to make the decision. You can specify a different model with the `model` field if you need more capability.

842842

843843The model's only job is to return its decision as JSON:

844844

One read of Claude Code CLIclaude-code-20260929T003702Z

What this read moved