One read of Claude Code CLIclaude-code-20261023T023701Z
10 pages moved out of 228 read.
Pages moved
10
significant first
Pages read
228
in this capture
Captured
02:37 UTC
Corpus hash
961f7402a63f
corpus-hash
What this read moved
1-10 of 10errors Changed · +22 / -0 lines
### Skipping connection (recent failure cached; retries automatically in 15 min, or edit the plugin config to retry now)
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 310
310310| `"<plugin>" was not uninstalled: <file> is there and could not be read` | [Plugin errors](#plugin-was-not-uninstalled) |
311311| `Plugin "<plugin>" was not uninstalled: installed_plugins.json` | [Plugin troubleshooting](/docs/en/plugins/troubleshooting.md#installed-plugins-json-holds-a-record-this-version-cannot-read) |
312312| `Plugin directory does not exist: <path>` | [Plugin troubleshooting](/docs/en/plugins/troubleshooting.md#plugin-directory-does-not-exist) |
313| `Skipping connection (recent failure cached; retries automatically in 15 min, or edit the plugin config to retry now)` | [Plugin errors](#skipping-connection-recent-failure-cached) |
313314| `Error: No such tool available: <tool name>` | [Tool errors](#no-such-tool-available) |
314315| `MCP server "<name>" connection closed before the tool call was answered` | [Tool errors](#connection-closed-before-the-tool-call-was-answered) |
315316| `would be spawned with zero tools — refusing` | [Tool errors](#agent-would-be-spawned-with-zero-tools) |
from line 2621
26202621| A Claude Code you installed | Run `claude update` |
26212622| The Claude desktop app | Update the app |
26222623| The binary the [VS Code extension](/docs/en/vs-code.md) bundles | Update the extension |
2623| The binary an Agent SDK package bundles | [Upgrade the SDK package](/docs/en/agent-sdk/hosting.md#runtime-dependencies), then restart your application. In a [compiled single-file executable](/docs/en/agent-sdk/typescript.md#compile-to-a-single-executable), rebuild it |
2624
2625* If you run
2624| The binary an Agent SDK package bundles | [Upgrade the SDK package](/docs/en/agent-sdk/hosting.md#
mcp Changed · +15 / -4 lines
#### Stdio servers that exit or fail to start
from line 362
362362
363363### Automatic reconnection
364364
365Claude Code reconnects a remote server that drops mid-session and retries an HTTP or SSE server's first connection after a transient error. Stdio servers are local processes, and Claude Code doesn't reconnect them automatically.
365Claude Code reconnects a remote server that drops mid-session and retries an HTTP or SSE server's first connection after a transient error. For a stdio server, see [Stdio servers that exit or fail to start](#stdio-servers-that-exit-or-fail-to-start).
366366
367367#### Mid-session drops of a remote server
368368
from line 377
377377
378378When an HTTP or SSE server's first connection fails with a transient error, such as a 5xx response, a connection refused, or a timeout, Claude Code retries up to three times. If the connection still fails, Claude Code marks the server as failed.
379379
380Claude Code doesn't retry in these cases:
380Those retries don't apply in these cases:
381381
382* A stdio server's first connection. To try it again, see [Stdio servers that exit or fail to start](#stdio-servers-that-exit-or-fail-to-start)
382383* A WebSocket server's first connection
383384* An authentication or not-found error, because it requires a configuration change to resolve. When a [`headersHelper`](#use-dynamic-headers-for-custom-authentication) is the server's only source of the `Authorization` header, Claude Code retries an authentication error anyway, because it re-runs the helper on each attempt and can pick up a fresh credential
384385
386#### Stdio servers that exit or fail to start
387
388To start a stdio server again, read the column that matches what happened to it. Find your row by how you run Claude Code: an interactive session, a `claude -p` run, or an Agent SDK session.
389
390| How you run Claude Code | The server's process exits mid-session | The server's first connection fails |
391| - | - | - |
392| Interactive session | Claude Code marks the server as failed. To start it again, select **Reconnect** from the server's menu in `/mcp` | Claude Code marks the server as failed. To start it again, select **Reconnect** from the server's menu in `/mcp` |
393| `claude -p` run | Claude Code starts the server again the next time Claude calls one of the server's tools, and the call runs once the server connects | The run continues without the server's tools. To have Claude Code try the connection again, start the run again. When a plugin provides the server, new runs skip the connection for 15 minutes after a failure, so wait that long first or [retry sooner](/docs/en/errors.md#skipping-connection-recent-failure-cached) |
394| Agent SDK session | Claude Code starts the server again the next time Claude calls one of the server's tools, and the call runs once the server connects | The session continues without the server's tools. Your code can [reconnect the server](/docs/en/agent-sdk/mcp.md#error-handling) |
395
385396#### Failed discovery requests
386397
387398After a server connects, Claude Code sends it capability discovery requests such as `tools/list`, `prompts/list`, and `resources/list`. Claude Code retries those requests up to three times with short backoff after a transient network or server error. It doesn't retry authentication errors, 4xx responses, or request timeouts.
from line 505
494505**Plugin MCP features**:
495506
496507* **Automatic lifecycle**: servers connect and disconnect at these points:
497 * At session startup, Claude Code connects the servers for enabled plugins automatically. In `/mcp`, a remote (HTTP or SSE) plugin server you've used before can show the [`cached` status](#server-status-detail) instead; Claude Code connects it when Claude first calls one of its tools
508 * At session startup, Claude Code connects the servers for enabled plugins automatically. In `/mcp`, a remote (HTTP or SSE) plugin server you've used before can show the [`cached` status](#server-status-detail) instead; Claude Code connects it when Claude first calls one of its tools. When a stdio plugin server's connection failed less than 15 minutes earlier, Claude Code [skips the connection](/docs/en/errors.md#skipping-connection-recent-failure-cached)
498509 * If you enable or disable a plugin during a session, Claude Code connects or disconnects its MCP servers when the change applies. [Apply plugin changes without restarting](/docs/en/plugins/cli-reference.md#reload-plugins) describes when that is. In a session without an interactive terminal, `/reload-plugins` doesn't connect or disconnect plugin MCP servers; those changes take effect in your next session
499510 * When you reload, Claude Code keeps the live connections of plugin servers whose configuration is unchanged, and does the same when you [replace the session's MCP server list](/docs/en/agent-sdk/typescript.md#mcpsetserversresult) from the Agent SDK without naming them
500511 * When you [move the session with `/cd`](/docs/en/permissions#move-the-session-to-another-directory) on v2.1.246 or later, Claude Code connects the servers of plugins the new directory's settings enable and disconnects the servers of plugins that are no longer enabled, so you don't need to run `/reload-plugins` after the move
sessions Changed · +9 / -0 lines
### The "Resume this conversation?" dialog
from line 87
8787* The run isn't started through [channels](/docs/en/channels.md)
8888* No [deny rule](/docs/en/permissions.md#manage-permissions) removes the `ExitPlanMode` tool
8989
90### The "Resume this conversation?" dialog
91
92If you see the "Resume this conversation?" dialog when resuming a session, its estimate is the share of your 5-hour usage limit that the saved conversation alone would use. The estimate doesn't count what you've already used.
93
94On Pro and Max plans, the dialog can appear when you resume a long conversation [after a long break](/docs/en/prompt-caching.md#resuming-a-session) or on a different model. The estimated use comes when you send your first message after **Resume**, not when you select it. Choose by whether your next task still needs the saved conversation:
95
96* **Resume**: keep working in the saved conversation.
97* **Start a new conversation**: switch to work that doesn't need the saved conversation. To reopen it later, run [`/resume`](#use-the-session-picker) at the prompt. The estimate doesn't apply to your first message in the new conversation. If the option says that Claude can look up this conversation, you can still refer to earlier work in the new conversation.
98
9099### Where the session picker looks
91100
92101Claude Code stores sessions per project directory. By default the session picker shows:
tools-reference Changed · +5 / -2 lines
### Task-tracking tools in subagents and agent teams
from line 596
596596
597597In [background sessions](/docs/en/agent-view.md) and in [cloud sessions](/docs/en/claude-code-on-the-web.md), Claude Code provides the same tools on every model, listed or not.
598598
599The default set described here applies in Claude Code v2.1.268 and later.
600
601### Task-tracking tools in subagents and agent teams
602
599603A subagent has the task-tracking tools only when your session has them, whatever model the subagent runs. An in-process [agent team](/docs/en/agent-teams.md) teammate has the task-tracking tools when your session does. A [split-pane](/docs/en/agent-teams.md#choose-a-display-mode) teammate is a separate Claude Code process that [inherits](/docs/en/agent-teams.md#permissions) your `--tools` list and deny rules, not `--allowedTools`, so check what you set:
600604
601605* **No `--tools` list or deny rule, and `CLAUDE_CODE_ENABLE_TODO_TOOLS` unset for the teammate**: the teammate has the task-tracking tools its own model has by default.
606* **`CLAUDE_CODE_ENABLE_TODO_TOOLS` exported in your shell**: Claude Code passes the teammate a fixed set of environment variables that doesn't include the one you exported. To set it for the teammate too, start your session by running `claude --settings '{"env":{"CLAUDE_CODE_ENABLE_TODO_TOOLS":"1"}}'` in your shell. The teammate also gets your [`--settings`](/docs/en/settings#change-a-setting-for-one-session) value.
602607* **`--tools` naming the task-tracking tools**: the teammate has them on any model.
603608* **A task-tracking tool missing from `--tools` or named in a deny rule**: the teammate lacks that tool.
604609
605610Without the Task tools, an agent coordinates with its team through messages instead of the [shared task list](/docs/en/agent-teams.md#assign-and-claim-tasks).
606
607The default set described here applies in Claude Code v2.1.268 and later.
608611
609612## WebFetch tool behavior
610613
agent-sdk/typescript Changed · +2 / -0 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
Nothing in the body moved in this read. What changed is above.
claude-tag Changed · +1 / -1 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
Nothing in the body moved in this read. What changed is above.
costs Changed · +3 / -1 lines
from line 54
5454On a Pro, Max, Team, or Enterprise plan, `/usage` also shows a breakdown of what counts against your plan limits, with recommendations:
5555
5656* **Attribution**: recent usage attributed to skills, subagents, plugins, and individual MCP servers, each shown as a percentage of the total. An MCP server's share counts only the requests that consumed one of its tool results. Before v2.1.222, after one call to an MCP server, Claude Code attributed every subsequent request to that server, overstating its share.
57* **Recommendations**: changes that lower your usage, one per row. Each row starts with the share of recent usage it addresses, at least 10%, as in `25% Trim ~/code/api/CLAUDE.md · 49k tokens per request`. To have Claude Code apply the ones it can, see [Apply recommendations with the fix shortcut](#apply-recommendations-with-the-fix-shortcut).
57* **Recommendations**: suggested changes, one per row. Each row starts with a share of your recent usage, at least 10%, as in `25% Trim ~/code/api/CLAUDE.md · 49k tokens per request`.
58 * **How to read the share**: it tells you how much of your usage the row applies to, not how much the change saves. One request can count toward several rows, so the shares can add up to more than 100%.
59 * **How to apply recommendations**: to have Claude Code apply the ones it can, see [Apply recommendations with the fix shortcut](#apply-recommendations-with-the-fix-shortcut)
5860* **Loops**: a row for each of the heaviest [`/loop` or other session-scoped scheduled tasks](/docs/en/scheduled-tasks) that ran recently, ordered by total tokens, with a count of the rest. Requires Claude Code v2.1.242 or later.
5961 * **What each row reports**: how often the task fires, how many times it ran, its total and per-run tokens, and when it last ran
6062 * **Stopped and re-created loops**: Claude Code keys a row by the task's prompt, so a loop you stop and re-create stays one row
plugins/troubleshooting Changed · +4 / -0 lines
from line 898
898898
899899To read the error the server printed while starting, run `claude --debug` and open the log at `~/.claude/debug/<session-id>.txt`. The `--debug` flag doesn't print to the terminal.
900900
901> [!NOTE]
902>
903> When a connection to a [plugin's stdio server](/docs/en/mcp.md#plugin-provided-mcp-servers) failed less than 15 minutes before you ran `claude --debug`, Claude Code [doesn't start the server](/docs/en/errors.md#skipping-connection-recent-failure-cached). In the new session, select **Reconnect** from the server's menu in `/mcp` to start it, then open the log.
904
901905A server entry in `.mcp.json` that fails the schema doesn't appear in the **Errors** tab. Claude Code drops that server and records `Invalid MCP server config for <server> in <path>` only in that debug log. To find the entry without loading the plugin, run `claude plugin validate` in your shell on the plugin directory, which reports it as an error.
902906
903907Before v2.1.281, `claude plugin validate` didn't check `.mcp.json`.
prompt-caching Changed · +1 / -1 lines
from line 114
114114| Mid-session change | Cache | Tool definitions in the next request |
115115| - | - | - |
116116| A server connects, or a [dynamic tool update](/docs/en/mcp.md#dynamic-tool-updates) adds tools | Invalidated | The new definitions are added |
117| A server drops out with no action on your part, such as a stdio server's process exiting | Kept | The server's definitions stay unchanged. A call to one of its tools returns an error instead of running |
117| A server drops out with no action on your part, such as a stdio server's process exiting | Kept | The server's definitions stay unchanged. A call to one of its tools returns an error instead of running, unless Claude Code [starts the server again](/docs/en/mcp.md#stdio-servers-that-exit-or-fail-to-start) for that call |
118118| A remote server [reconnects automatically](/docs/en/mcp.md#automatic-reconnection) after its connection drops | Kept, unless a request sent while the server reconnects adds the `WaitForMcpServers` tool, which invalidates the cache once | The server's definitions stay unchanged. A request sent while the server reconnects can add `WaitForMcpServers` when the conversation hasn't listed it yet, and the tool then stays listed for the rest of the conversation |
119119| You remove a tool on purpose, such as with a [deny rule](#denying-an-entire-tool) or by disabling its server in `/mcp` | Invalidated | The definition is removed |
120120
vs-code Changed · +1 / -1 lines
from line 316
316316
317317 The dialog also breaks down what is contributing to your plan limits:
318318
319 * **Recommendations**: changes that lower your usage, one per row with the share of recent usage it addresses, such as `Trim ~/code/api/CLAUDE.md · 49k tokens per request`
319 * **Recommendations**: suggested changes, one per row, such as `Trim ~/code/api/CLAUDE.md · 49k tokens per request`
320320 * **Fix button**: to have Claude Code apply the recommendations it can, click the button under them, such as **Fix both**. To learn which rows the button acts on and what then happens in your session, see [Apply recommendations with the fix shortcut](/docs/en/costs.md#apply-recommendations-with-the-fix-shortcut). Requires Claude Code v2.1.305 or later.
321321
322322 The button isn't shown while [Remote Control](/docs/en/remote-control.md) is connected. If a warning reads `The usage fix wasn’t fully sent. Open usage and try again.` after Remote Control connected, [disconnect Remote Control](/docs/en/remote-control.md#check-connection-status) before you try again.