From 6c72eba12eef971a9d81aa65efc32ba3e447ef4d Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Mon, 31 Aug 2026 06:23:20 +0000 Subject: [PATCH] docs: Claude Code v2.1.251 - per-model effort storage, CLAUDE_CODE_SUBAGENT_MODEL demoted, project settings security hardening Co-Authored-By: claude-yolo[bot] --- content/.metadata.json | 425 +++++++++--------- .../en/docs/claude-code/agent-sdk/hosting.md | 34 +- content/en/docs/claude-code/agent-sdk/mcp.md | 10 +- .../agent-sdk/modifying-system-prompts.md | 39 +- .../claude-code/agent-sdk/observability.md | 2 +- .../en/docs/claude-code/agent-sdk/python.md | 30 +- .../docs/claude-code/agent-sdk/subagents.md | 30 +- .../docs/claude-code/agent-sdk/typescript.md | 192 ++++---- content/en/docs/claude-code/agent-teams.md | 14 +- content/en/docs/claude-code/agent-view.md | 4 +- content/en/docs/claude-code/artifacts.md | 34 +- content/en/docs/claude-code/authentication.md | 43 +- .../claude-code/claude-apps-gateway-deploy.md | 4 +- .../docs/claude-code/claude-apps-gateway.md | 18 +- .../en/docs/claude-code/claude-security.md | 6 +- content/en/docs/claude-code/cli-reference.md | 2 +- .../en/docs/claude-code/cloud-environments.md | 5 +- content/en/docs/claude-code/commands.md | 1 + .../en/docs/claude-code/debug-your-config.md | 3 +- content/en/docs/claude-code/env-vars.md | 18 +- content/en/docs/claude-code/errors.md | 19 +- content/en/docs/claude-code/fast-mode.md | 4 +- .../docs/claude-code/feature-availability.md | 2 +- .../en/docs/claude-code/features-overview.md | 2 +- content/en/docs/claude-code/gateways.md | 4 +- content/en/docs/claude-code/headless.md | 2 +- content/en/docs/claude-code/hooks.md | 2 +- content/en/docs/claude-code/iam.md | 43 +- .../docs/claude-code/llm-gateway-connect.md | 4 +- .../en/docs/claude-code/managed-settings.md | 4 +- content/en/docs/claude-code/mcp.md | 8 +- content/en/docs/claude-code/memory.md | 2 + content/en/docs/claude-code/model-config.md | 48 +- .../en/docs/claude-code/monitoring-usage.md | 18 +- .../en/docs/claude-code/plugins-reference.md | 2 +- .../self-hosted-environments-testing.md | 6 +- .../en/docs/claude-code/settings-example.md | 2 +- .../en/docs/claude-code/settings-reference.md | 89 +++- content/en/docs/claude-code/settings.md | 11 +- content/en/docs/claude-code/skills.md | 2 +- content/en/docs/claude-code/slash-commands.md | 2 +- content/en/docs/claude-code/sub-agents.md | 34 +- .../en/docs/claude-code/terminal-config.md | 2 +- .../claude-code/third-party-integrations.md | 2 +- .../en/docs/claude-code/tools-reference.md | 2 +- .../docs/claude-code/troubleshoot-install.md | 26 +- .../en/docs/claude-code/whats-new/2026-w34.md | 2 +- content/en/docs/claude-code/workflows.md | 6 +- .../community/interest-groups/enterprise.md | 112 +++++ content/mcp/registry/package-types.md | 51 +++ ...how-do-i-log-out-of-all-active-sessions.md | 2 +- ...-can-i-delete-my-claude-console-account.md | 4 +- ...k-settings-on-team-and-enterprise-plans.md | 2 +- ...ser-feedback-settings-on-claude-console.md | 2 +- .../10593882-share-and-unshare-chats.md | 6 +- ...ith-local-mcp-servers-on-claude-desktop.md | 2 +- content/support/11101966-use-voice-mode.md | 8 +- ...the-claude-lti-in-canvas-by-instructure.md | 2 +- ...and-memory-to-build-on-previous-context.md | 10 +- ...being-asked-to-verify-my-payment-method.md | 2 +- .../11869629-use-claude-with-android-apps.md | 2 +- ...or-team-and-seat-based-enterprise-plans.md | 10 +- ...12173-get-started-with-claude-in-chrome.md | 2 +- ...eam-plan-from-monthly-to-annual-billing.md | 4 +- ...11783-create-and-edit-files-with-claude.md | 6 +- .../12157520-claude-code-usage-analytics.md | 2 +- .../support/12260368-use-incognito-chats.md | 2 +- .../support/12293051-use-claude-in-xcode.md | 2 +- ...age-usage-credits-for-paid-claude-plans.md | 2 +- ...6728-troubleshoot-claude-error-messages.md | 2 +- .../support/12512180-use-skills-in-claude.md | 2 +- ...d-using-the-desktop-extension-allowlist.md | 8 +- .../12618689-claude-code-on-the-web.md | 6 +- ...-quick-entry-with-claude-desktop-on-mac.md | 2 +- ...analytics-for-team-and-enterprise-plans.md | 24 +- ...2446-claude-in-chrome-permissions-guide.md | 4 +- .../12997503-team-plan-billing-faqs.md | 2 +- .../13132885-set-up-single-sign-on-sso.md | 8 +- ...3133195-set-up-jit-or-scim-provisioning.md | 6 +- ...1-configuring-session-security-settings.md | 6 +- .../13189465-log-in-to-your-claude-account.md | 2 +- .../13325567-account-management-faqs.md | 2 +- ...13345190-get-started-with-claude-cowork.md | 2 +- ...mizing-your-console-appearance-settings.md | 2 +- ...13371040-log-in-to-your-console-account.md | 2 +- ...13641943-visual-and-interactive-content.md | 6 +- .../support/13756069-public-sector-faqs.md | 2 +- ...33-manage-plugins-for-your-organization.md | 2 +- .../support/13837440-use-plugins-in-claude.md | 4 +- ...hedule-recurring-tasks-in-claude-cowork.md | 2 +- ...gn-tasks-from-anywhere-in-claude-cowork.md | 4 +- ...ur-tasks-with-projects-in-claude-cowork.md | 12 +- ...-let-claude-use-your-computer-in-cowork.md | 4 +- ...sync-works-for-enterprise-organizations.md | 4 +- content/support/14503613-sso-login.md | 6 +- ...43-set-up-scim-in-claude-for-government.md | 6 +- content/support/14503775-mcp-web-search.md | 2 +- ...-up-your-design-system-in-claude-design.md | 2 +- ...min-guide-for-team-and-enterprise-plans.md | 2 +- ...14604416-get-started-with-claude-design.md | 2 +- ...t-a-default-model-for-your-organization.md | 2 +- ...nage-model-access-for-your-organization.md | 8 +- ...1-get-started-with-1password-for-claude.md | 2 +- ...rstanding-your-pro-or-max-plan-invoices.md | 2 +- .../8114491-get-started-with-claude.md | 2 +- ...8230524-delete-or-rename-a-conversation.md | 16 +- .../support/8325618-paid-plan-billing-faqs.md | 2 +- ...27-customizing-your-appearance-settings.md | 6 +- ...nt-to-a-team-or-enterprise-organization.md | 2 +- ...77-how-can-i-create-and-manage-projects.md | 8 +- ...9-manage-project-visibility-and-sharing.md | 10 +- ...d-usage-reporting-in-the-claude-console.md | 8 +- .../9547008-publish-and-share-artifacts.md | 8 +- ...e-public-projects-for-your-organization.md | 2 +- discovery.json | 2 +- tombstones.json | 2 +- 116 files changed, 1085 insertions(+), 636 deletions(-) create mode 100644 content/mcp/community/interest-groups/enterprise.md diff --git a/content/.metadata.json b/content/.metadata.json index 916e3e98c2..351925ae55 100644 --- a/content/.metadata.json +++ b/content/.metadata.json @@ -1,7 +1,7 @@ { "metadata": { "version": "2.0", - "fetch_date": "2026-08-30T18:54:02.672238Z", + "fetch_date": "2026-08-31T06:21:27.710737Z", "section": "all" }, "items": [ @@ -4853,8 +4853,8 @@ "url": "https://code.claude.com/docs/en/features-overview", "status": "success", "path": "en/docs/claude-code/features-overview.md", - "sha256": "ad88831830057e06f4c3ea5c39e47818abb0efc2df9469e34bee06caa472a62c", - "size": 32357 + "sha256": "f02145dc806e3f2160c243a75f32c04243a2a1ef85237a2e6fe6a9ed4fc4e6a8", + "size": 32352 }, { "url": "https://code.claude.com/docs/en/claude-directory", @@ -4881,8 +4881,8 @@ "url": "https://code.claude.com/docs/en/memory", "status": "success", "path": "en/docs/claude-code/memory.md", - "sha256": "8499a90d02435f460c729f3dc789072dc9224d3efac7cffdd507dafe76f20303", - "size": 36982 + "sha256": "3651ab935d3ba8a0cc3eb9e3343ad52928375410271f697bae6b7d3ca1db1323", + "size": 37361 }, { "url": "https://code.claude.com/docs/en/sessions", @@ -5056,8 +5056,8 @@ "url": "https://code.claude.com/docs/en/claude-security", "status": "success", "path": "en/docs/claude-code/claude-security.md", - "sha256": "fa35ea2bc3e0ac2b2ba5f9e183c9cc71526017850ceeed48cfcd0136a18565ab", - "size": 13687 + "sha256": "917f742b5535c77b4a1bda0599a0540a334b1f19ef44dbc51634cdee280ab690", + "size": 13830 }, { "url": "https://code.claude.com/docs/en/code-review", @@ -5105,22 +5105,22 @@ "url": "https://code.claude.com/docs/en/sub-agents", "status": "success", "path": "en/docs/claude-code/sub-agents.md", - "sha256": "6c469d1f8cd67757942444b5c8ab54fb7f74ebfd7cbf2cfb07e187fbb37067e5", - "size": 106993 + "sha256": "dffcb87abbc3a5fd58360d708e42400e0eb162247e366f2c006cf5e43fef9677", + "size": 108096 }, { "url": "https://code.claude.com/docs/en/agent-view", "status": "success", "path": "en/docs/claude-code/agent-view.md", - "sha256": "e01a04261f03d6177cb48cf12bd5eabea22385cee0fdc02d08d9fdcdf7d8230c", - "size": 226668 + "sha256": "3b8b645bbe8e489ba3e1eb9b9af599a8b1d700bcaceef212088cd21f17ff8baf", + "size": 226778 }, { "url": "https://code.claude.com/docs/en/agent-teams", "status": "success", "path": "en/docs/claude-code/agent-teams.md", - "sha256": "cdd15b1b8a8ea37ca2903b29078965192053bc232012adf8d71b403db621ab23", - "size": 40606 + "sha256": "0eff171758ad7003344f6a6ca4dc13600599004bd41bc7a0da68ebde915dee3d", + "size": 40659 }, { "url": "https://code.claude.com/docs/en/cross-session-messaging", @@ -5133,8 +5133,8 @@ "url": "https://code.claude.com/docs/en/workflows", "status": "success", "path": "en/docs/claude-code/workflows.md", - "sha256": "ba36960244015e6f104653edd3b6a790075b39f0234bcf30a4586e857c5211a4", - "size": 37438 + "sha256": "f95bdda81473d9289e7f3784c741b7b28a9fb9a119810c4f53878db15c12f2c8", + "size": 37708 }, { "url": "https://code.claude.com/docs/en/worktrees", @@ -5154,15 +5154,15 @@ "url": "https://code.claude.com/docs/en/mcp", "status": "success", "path": "en/docs/claude-code/mcp.md", - "sha256": "be0624af48b735a4bd2085cbd2d6e227aca3a8c5b3ebf7a40d201c796dad3590", - "size": 111039 + "sha256": "c4d6746c8ae51e0fdaf10443ae115d692833ede95db6047dbc2dd67eb6f1244d", + "size": 111153 }, { "url": "https://code.claude.com/docs/en/skills", "status": "success", "path": "en/docs/claude-code/skills.md", - "sha256": "79fcd0c50f8fff8319754b57b379183ef60512ac06c383ff354f4241e6210bbd", - "size": 99321 + "sha256": "b7a030ad40a8e613349dbc56b7f951d54b720c8b6616b96c97d6b116178e1d89", + "size": 99094 }, { "url": "https://code.claude.com/docs/en/discover-plugins", @@ -5182,8 +5182,8 @@ "url": "https://code.claude.com/docs/en/artifacts", "status": "success", "path": "en/docs/claude-code/artifacts.md", - "sha256": "6e476eb059c935bdf41081558de98417563eb6fe5658062898a54a54e96c5720", - "size": 36160 + "sha256": "687ce645f96b959e44a3873b58d87a4a119b049e9936a32397ed6ed35aec484e", + "size": 37244 }, { "url": "https://code.claude.com/docs/en/hooks-guide", @@ -5217,8 +5217,8 @@ "url": "https://code.claude.com/docs/en/headless", "status": "success", "path": "en/docs/claude-code/headless.md", - "sha256": "8c0bd278afb8f8d93f445fa0ba450cbf57d63ac908526624f284f829e615d174", - "size": 30337 + "sha256": "999f122f6d227c14a25223e2d02d4044c1201f01d9a0621ca9646ebb8347fb47", + "size": 30635 }, { "url": "https://code.claude.com/docs/en/deep-links", @@ -5238,8 +5238,8 @@ "url": "https://code.claude.com/docs/en/troubleshoot-install", "status": "success", "path": "en/docs/claude-code/troubleshoot-install.md", - "sha256": "1776718e5d4c21654278ba638d5457e3f0da238b338f3ba4276fb36cd4b068cc", - "size": 61795 + "sha256": "c83d61a9b307685768a93997521188fc5ff121e43600061575eada47bfd2e639", + "size": 63280 }, { "url": "https://code.claude.com/docs/en/troubleshooting", @@ -5252,15 +5252,15 @@ "url": "https://code.claude.com/docs/en/debug-your-config", "status": "success", "path": "en/docs/claude-code/debug-your-config.md", - "sha256": "440b0d006a880c05f6862330f05881638e73fe590fdb5606e3538bc5b1e48b7a", - "size": 23631 + "sha256": "6fa9b2c2e17d27ad6665b5ecdd6c5de93e9d05d3f81ad84c5760dd8b4707b69f", + "size": 23464 }, { "url": "https://code.claude.com/docs/en/errors", "status": "success", "path": "en/docs/claude-code/errors.md", - "sha256": "391e61f8d0681ed04615412743c18fa230d3ead8dcf9c6c6cdc2e2324aec8f07", - "size": 344214 + "sha256": "bed8af66fd566e787004edac5b6867b93c5890b11abb06ee596f288ab57eea55", + "size": 345384 }, { "url": "https://code.claude.com/docs/en/admin-setup", @@ -5280,15 +5280,15 @@ "url": "https://code.claude.com/docs/en/authentication", "status": "success", "path": "en/docs/claude-code/authentication.md", - "sha256": "9bebf8122c2084254be0b88bbd0d19d13964f17f43685e5a006a7c67730de24f", - "size": 24231 + "sha256": "4d9b27ab1577205a1e1aabaa0c9960a09acfc021f32f8d27b825facb579f2284", + "size": 28422 }, { "url": "https://code.claude.com/docs/en/managed-settings", "status": "success", "path": "en/docs/claude-code/managed-settings.md", - "sha256": "a0efee2271228ce4aa2bb12f781dae8a70b97c20a1afd1b59d55ed92b7dfffd4", - "size": 58010 + "sha256": "2ad7c3bf984151aebc7a16397340db224d506dae35112121ee4da8fd55a0cd1b", + "size": 58185 }, { "url": "https://code.claude.com/docs/en/server-managed-settings", @@ -5315,15 +5315,15 @@ "url": "https://code.claude.com/docs/en/third-party-integrations", "status": "success", "path": "en/docs/claude-code/third-party-integrations.md", - "sha256": "a1f1fe72368dbceb42f655d043334968806a012ba9c294b990b2c427dad7d4f2", - "size": 13841 + "sha256": "32bbffbc078f85a6c9a1c72d76f93e1babf5bbd466dcd988c162dade74ecf19b", + "size": 13928 }, { "url": "https://code.claude.com/docs/en/feature-availability", "status": "success", "path": "en/docs/claude-code/feature-availability.md", - "sha256": "0712f7d6cdf5d516d35d284dd75dc26575bb5fff3b5343d25f2fd102eef73e48", - "size": 22935 + "sha256": "1f09c7e60871a8f3d23948fd7df431640e8b3e94140a4d6ef6a72aa5c2f1380b", + "size": 23039 }, { "url": "https://code.claude.com/docs/en/amazon-bedrock", @@ -5378,15 +5378,15 @@ "url": "https://code.claude.com/docs/en/gateways", "status": "success", "path": "en/docs/claude-code/gateways.md", - "sha256": "1cc6872a4a08f92b062fdd346c34a091b789801cb68985c035e0d25ffd5ca201", - "size": 8964 + "sha256": "283234918cf222b4f80607d9d695bba2a42e879de5e85de950d41cc45724d940", + "size": 9184 }, { "url": "https://code.claude.com/docs/en/claude-apps-gateway", "status": "success", "path": "en/docs/claude-code/claude-apps-gateway.md", - "sha256": "53f3e0e21e2a77f0c284e87450fcc9bcd25b107e75c763a256cb02004ffe10e6", - "size": 56521 + "sha256": "a0d87dcb769827faa22cdec912eeb99bf8ee6acd2d6e9cb8784707c8c6cb21fa", + "size": 57236 }, { "url": "https://code.claude.com/docs/en/claude-apps-gateway-config", @@ -5406,8 +5406,8 @@ "url": "https://code.claude.com/docs/en/claude-apps-gateway-deploy", "status": "success", "path": "en/docs/claude-code/claude-apps-gateway-deploy.md", - "sha256": "f21526b7e01bcdc6e6ea7d27093aed3e56f7f6a5f4c3a5b478140a9942a9b7df", - "size": 54580 + "sha256": "af962cd1acd4c2102d969a1213c9e00e2fb69d688e289e96a5fdebcc80ba8778", + "size": 54600 }, { "url": "https://code.claude.com/docs/en/claude-apps-gateway-on-aws", @@ -5434,8 +5434,8 @@ "url": "https://code.claude.com/docs/en/llm-gateway-connect", "status": "success", "path": "en/docs/claude-code/llm-gateway-connect.md", - "sha256": "bebeb983bc979812fc6bf99a866fe6826dce4cdc1e96ebae1c1c444314aa387a", - "size": 53576 + "sha256": "27c26e909f54bb952efcfe6b19f97e40d321bfc2dd050fb6f565ae6a6ace0be3", + "size": 53704 }, { "url": "https://code.claude.com/docs/en/llm-gateway-rollout", @@ -5455,8 +5455,8 @@ "url": "https://code.claude.com/docs/en/monitoring-usage", "status": "success", "path": "en/docs/claude-code/monitoring-usage.md", - "sha256": "778577645d6a294b3d96e242b677444a8e73c82d04c619baad391f245661d360", - "size": 137695 + "sha256": "2d6b621661b34c63e9604e16e7afa18a1fc10dc2720bef4794d28fedd317b42f", + "size": 139411 }, { "url": "https://code.claude.com/docs/en/costs", @@ -5539,22 +5539,22 @@ "url": "https://code.claude.com/docs/en/settings", "status": "success", "path": "en/docs/claude-code/settings.md", - "sha256": "a6f10afd9d41fffa2b14e1f113ef641ea6fbe9b319c114bb986efc3e186de009", - "size": 57166 + "sha256": "3f1b27a915fd3ebe6345af6ccc4d63ac64b36fb613d76e887a18c66c92ad2959", + "size": 57650 }, { "url": "https://code.claude.com/docs/en/settings-reference", "status": "success", "path": "en/docs/claude-code/settings-reference.md", - "sha256": "68df655c381eafa98f4671f601999065ee99851ad9942a01747803f8113eca7c", - "size": 410249 + "sha256": "f776bf5a6d4eb4dacb005da6f701acd4c1e2709f2dd4cc49f0a5f06db31dfb83", + "size": 415109 }, { "url": "https://code.claude.com/docs/en/settings-example", "status": "success", "path": "en/docs/claude-code/settings-example.md", - "sha256": "ffa1249c2fdab2f432dd80d4f996f22bc5337a496fc6227a342795693f9c640c", - "size": 14784 + "sha256": "c04b742b421dcb2591a55cba80ba2b5692346ffd0631d7438e4058059109ac31", + "size": 14823 }, { "url": "https://code.claude.com/docs/en/permissions", @@ -5588,8 +5588,8 @@ "url": "https://code.claude.com/docs/en/cloud-environments", "status": "success", "path": "en/docs/claude-code/cloud-environments.md", - "sha256": "4f60cae2896e2963b1c978b62050965fd592743b731b42c585415393db50e7b8", - "size": 64278 + "sha256": "a7caed2fb6658fb7f2638f1c759c9a28a9e1dd41a5ede3f902d304d9d8a60445", + "size": 64299 }, { "url": "https://code.claude.com/docs/en/self-hosted-environments", @@ -5623,8 +5623,8 @@ "url": "https://code.claude.com/docs/en/self-hosted-environments-testing", "status": "success", "path": "en/docs/claude-code/self-hosted-environments-testing.md", - "sha256": "c05fe79fbcf9e2325e3a16bdb8518a7b082f2f823c7b3741487aeab5ca72d36c", - "size": 15369 + "sha256": "1c0cf02a5024078b7cd182a0b4e62226b28c7e47299da19d1e9441b631b62523", + "size": 15651 }, { "url": "https://code.claude.com/docs/en/self-hosted-environments-reference", @@ -5644,15 +5644,15 @@ "url": "https://code.claude.com/docs/en/model-config", "status": "success", "path": "en/docs/claude-code/model-config.md", - "sha256": "11331c888dbbd07acb345a1902c87d896f09e1bdf4dc70fe2d73ed6db7c35dbd", - "size": 100264 + "sha256": "a88487693ce942f52876e91ba05644d11070b61f2aaa1b5843ba77b8057155ba", + "size": 101609 }, { "url": "https://code.claude.com/docs/en/fast-mode", "status": "success", "path": "en/docs/claude-code/fast-mode.md", - "sha256": "a30584e70457c10a77ef5cc026e831f4a8efa6ac67e3bdb3499441ac1fe1c460", - "size": 18833 + "sha256": "9c7b13a89a9bda9f1697f84bf21acd27c60cfcebff78640a57c2e09eb626a397", + "size": 18884 }, { "url": "https://code.claude.com/docs/en/advisor", @@ -5672,8 +5672,8 @@ "url": "https://code.claude.com/docs/en/terminal-config", "status": "success", "path": "en/docs/claude-code/terminal-config.md", - "sha256": "2881cd463d2b152ff23c638b576d2614c87ec8819604a1780e4b6c4af7c181b3", - "size": 26365 + "sha256": "c92b71c5f9d2b12f3c2d6f0182784f61b9540774c7c624668da2f6c4015df246", + "size": 26532 }, { "url": "https://code.claude.com/docs/en/fullscreen", @@ -5714,29 +5714,29 @@ "url": "https://code.claude.com/docs/en/cli-reference", "status": "success", "path": "en/docs/claude-code/cli-reference.md", - "sha256": "b5b4585ce917230d12e0d9f95600868e0b182e09ce659e7d2848638e06dc4a9d", - "size": 107565 + "sha256": "9d1b73785c1baa6277fcf53f7a9b874e74014cabd6c3e97cb10a12c65cd655b1", + "size": 107570 }, { "url": "https://code.claude.com/docs/en/commands", "status": "success", "path": "en/docs/claude-code/commands.md", - "sha256": "6bbc0ba8e5183e113a018fa896b182fcdb04f96dce8d3d792439821a43b1c6e9", - "size": 161593 + "sha256": "850bd5572b8019f846bcd80688643f773e06788001a5b1d4cca7081c24795c7c", + "size": 162979 }, { "url": "https://code.claude.com/docs/en/env-vars", "status": "success", "path": "en/docs/claude-code/env-vars.md", - "sha256": "3f2ff571e2084fbceef263718aa38189f87f9aa78b091b49d59390247d42d58d", - "size": 472385 + "sha256": "db06824f9545d550719b412b53abca5a728711b9f56d7a2915b842f201c4a3ba", + "size": 476696 }, { "url": "https://code.claude.com/docs/en/tools-reference", "status": "success", "path": "en/docs/claude-code/tools-reference.md", - "sha256": "21045fa1ae08db958afa473a2664bc36ed0fff116c917a66de2456b937e5a48a", - "size": 105643 + "sha256": "fb7a88af3f3ce67d5d1017d55617e6921d3eb272b0956540e1cc72b5ad36f4bf", + "size": 105838 }, { "url": "https://code.claude.com/docs/en/interactive-mode", @@ -5756,15 +5756,15 @@ "url": "https://code.claude.com/docs/en/hooks", "status": "success", "path": "en/docs/claude-code/hooks.md", - "sha256": "70e0b0e2e1cb2b2866580e8417467cc74c732dd3b21f1a519464ba190489578e", - "size": 316860 + "sha256": "eda66d26982ca7af5574852ba74ad60833baf429f0d25355a38cbadcbee5cc2c", + "size": 316865 }, { "url": "https://code.claude.com/docs/en/plugins-reference", "status": "success", "path": "en/docs/claude-code/plugins-reference.md", - "sha256": "a0bc8cc75ce7b6a02446f7c1abb805a63fb72b0386471a44c476957bebdb5253", - "size": 115309 + "sha256": "165d8eeace1f0d91bac134e3111ea56cb6dfe92b2f3efd78a7a2b9fbfe98e432", + "size": 115419 }, { "url": "https://code.claude.com/docs/en/channels-reference", @@ -5875,8 +5875,8 @@ "url": "https://code.claude.com/docs/en/agent-sdk/mcp", "status": "success", "path": "en/docs/claude-code/agent-sdk/mcp.md", - "sha256": "59462afa71fd93c7bfafe8aeea59e2109f0bb552be3a4c8082f40297a4b31c81", - "size": 35132 + "sha256": "38d3bf3173e53b1f8a4bdf8e574a561ca1f1ad28600c9e91b20ea508bf3d7d09", + "size": 35875 }, { "url": "https://code.claude.com/docs/en/agent-sdk/tool-search", @@ -5889,15 +5889,15 @@ "url": "https://code.claude.com/docs/en/agent-sdk/subagents", "status": "success", "path": "en/docs/claude-code/agent-sdk/subagents.md", - "sha256": "ceaa3641cabe8e5542e172bdcd091dc35a42c6834c3c64ddc3403852ed1ac217", - "size": 46339 + "sha256": "8439017889d40c6c18e4f9ad3add4c4953d79b922a78b2cb4f07b4ba6650ba65", + "size": 47544 }, { "url": "https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts", "status": "success", "path": "en/docs/claude-code/agent-sdk/modifying-system-prompts.md", - "sha256": "634ca134a49ec7eef589d525e4ea57198f06b735d9d2ec7f5c12d88689047d17", - "size": 22719 + "sha256": "8f6d7fc8148988538521ff74ffecb748e2344c358bcd497a5b2363a8a3208adc", + "size": 25833 }, { "url": "https://code.claude.com/docs/en/agent-sdk/skills", @@ -5945,8 +5945,8 @@ "url": "https://code.claude.com/docs/en/agent-sdk/observability", "status": "success", "path": "en/docs/claude-code/agent-sdk/observability.md", - "sha256": "5b93d939d6bc6534560d0f61e8a57553a1dbdf08023a64a006d8e406d39337ed", - "size": 19922 + "sha256": "2b25862396915d6c444bca6e50c731214b47160d01df9ac930c4ff95fb6bc83c", + "size": 19887 }, { "url": "https://code.claude.com/docs/en/agent-sdk/todo-tracking", @@ -5959,8 +5959,8 @@ "url": "https://code.claude.com/docs/en/agent-sdk/hosting", "status": "success", "path": "en/docs/claude-code/agent-sdk/hosting.md", - "sha256": "949abada98d5a7023187a991c6fb49367ca62d493aa67ad18532e233171a1564", - "size": 24649 + "sha256": "56a8022cd9328be5c322b294080629a7efa5d993f1773abade12e021cd4c241d", + "size": 25630 }, { "url": "https://code.claude.com/docs/en/agent-sdk/secure-deployment", @@ -5973,8 +5973,8 @@ "url": "https://code.claude.com/docs/en/agent-sdk/typescript", "status": "success", "path": "en/docs/claude-code/agent-sdk/typescript.md", - "sha256": "b6b180ad1ba5f671f41b9ebb278313556223b749316eff468bd0ce8ba0f3465d", - "size": 322312 + "sha256": "66bca40f031f3445400be2faab6313f502edf9fb7762a0cc30153c295399483d", + "size": 325814 }, { "url": "https://code.claude.com/docs/en/agent-sdk/typescript-v2-preview", @@ -5987,8 +5987,8 @@ "url": "https://code.claude.com/docs/en/agent-sdk/python", "status": "success", "path": "en/docs/claude-code/agent-sdk/python.md", - "sha256": "fbc9a83ccde7bae3ea32201cdcad9cdffa3feb6197b49fc3ad1cab5e02abcd07", - "size": 193905 + "sha256": "b3c775585619522627701db50fd454df09bc282c573e443f47e948ca50dbbd2e", + "size": 194015 }, { "url": "https://code.claude.com/docs/en/agent-sdk/migration-guide", @@ -6008,7 +6008,7 @@ "url": "https://code.claude.com/docs/en/whats-new/2026-w34", "status": "success", "path": "en/docs/claude-code/whats-new/2026-w34.md", - "sha256": "1d892495d63b14a857c8aaaefa7d67568a43bd91f09009761e525c3083fa3a03", + "sha256": "260e257510e9eb8e36fc524aed44ef7d61ed6add074376d4eb143f2b0f83a68a", "size": 8507 }, { @@ -6221,6 +6221,13 @@ "sha256": "554f724f9086d18152244c99b67c4c1db9f8ca85236bc41afdd8d21466ef74f5", "size": 13402 }, + { + "url": "https://modelcontextprotocol.io/community/interest-groups/enterprise", + "status": "success", + "path": "mcp/community/interest-groups/enterprise.md", + "sha256": "336e1b4f529797dab12530eece98c754c78ee2ee25a62d8b00ab0411e97ebe66", + "size": 11863 + }, { "url": "https://modelcontextprotocol.io/community/interest-groups/enterprise-managed-authorization", "status": "success", @@ -7233,8 +7240,8 @@ "url": "https://modelcontextprotocol.io/registry/package-types", "status": "success", "path": "mcp/registry/package-types.md", - "sha256": "a57f08e32bfc27d05d277ac2c078fd80c1fc51d014ebfca9dd34e3e2a5352f2c", - "size": 7167 + "sha256": "3bef3313bdff89048ff305cb728051017fd8f0e429741fa9fcff0560149f6ef5", + "size": 9971 }, { "url": "https://modelcontextprotocol.io/registry/quickstart", @@ -8640,8 +8647,8 @@ "url": "https://support.claude.com/en/articles/8114491-get-started-with-claude", "status": "success", "path": "support/8114491-get-started-with-claude.md", - "sha256": "a4433557d210325664eacfaddac2c18f799caa576d6797b3ae984e3a73fcf28f", - "size": 5300 + "sha256": "634805a13d877dde2aa570db394c1ed5b46e9be6d1093be2b28f3046b6b3a448", + "size": 5302 }, { "url": "https://support.claude.com/en/articles/8114494-how-up-to-date-is-claude-s-training-data", @@ -8717,8 +8724,8 @@ "url": "https://support.claude.com/en/articles/8230524-delete-or-rename-a-conversation", "status": "success", "path": "support/8230524-delete-or-rename-a-conversation.md", - "sha256": "cc71d82d090985c5bfd9ceb0a114db79d955f2a434fe711f98f6645de98227ab", - "size": 5877 + "sha256": "26b16f63542712e1dac7163eb314dc8fdbb2989062bb0f1a1203cab947f26985", + "size": 5881 }, { "url": "https://support.claude.com/en/articles/8241126-upload-files-to-claude", @@ -8787,8 +8794,8 @@ "url": "https://support.claude.com/en/articles/8325618-paid-plan-billing-faqs", "status": "success", "path": "support/8325618-paid-plan-billing-faqs.md", - "sha256": "505d6539afde68373bb04d083a1ca04ed0bfbe35d3341d2b9b6bccfbf02eb819", - "size": 4555 + "sha256": "00c9a4b90ec2d9bc621d852a087035c11577619437e0615eed6e0666146fb3e1", + "size": 4551 }, { "url": "https://support.claude.com/en/articles/8325621-i-would-like-to-input-sensitive-data-into-my-chats-with-claude-who-can-view-my-conversations", @@ -8850,8 +8857,8 @@ "url": "https://support.claude.com/en/articles/8887527-customizing-your-appearance-settings", "status": "success", "path": "support/8887527-customizing-your-appearance-settings.md", - "sha256": "6eb154cbfb30a7a50ea8e1d859c75cd26ac80e44cff85bb1ff3c8944a0b4da5b", - "size": 1876 + "sha256": "d61ee9c88b8f228a2e052eb4a156bc1d6a5cba6b00b9e88f3b6029657139b7ee", + "size": 1868 }, { "url": "https://support.claude.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler", @@ -9025,8 +9032,8 @@ "url": "https://support.claude.com/en/articles/9267400-move-your-personal-claude-account-to-a-team-or-enterprise-organization", "status": "success", "path": "support/9267400-move-your-personal-claude-account-to-a-team-or-enterprise-organization.md", - "sha256": "772f9be02e1ed2d2993cfa6c4a3dcff2ec0693a2694037505e76bf44fef25970", - "size": 9384 + "sha256": "ad386563a2961d237dbab43dfb3d2beffc238572d270f78f0182d7570d5ab8ed", + "size": 9376 }, { "url": "https://support.claude.com/en/articles/9301722-updates-to-our-acceptable-use-policy-now-usage-policy-consumer-terms-of-service-and-privacy-policy", @@ -9074,15 +9081,15 @@ "url": "https://support.claude.com/en/articles/9519177-how-can-i-create-and-manage-projects", "status": "success", "path": "support/9519177-how-can-i-create-and-manage-projects.md", - "sha256": "ca3e95dad42ea8efbff338c6367b67e7cdb2419a4de0093cc41e4dae743e626b", - "size": 9323 + "sha256": "6f87b7e0cb91d677673a3238649c8c30cc0c2f05140bb42cbedad46641055474", + "size": 9321 }, { "url": "https://support.claude.com/en/articles/9519189-manage-project-visibility-and-sharing", "status": "success", "path": "support/9519189-manage-project-visibility-and-sharing.md", - "sha256": "4843ecf87c8fdc48a1366e43a73c62756969e9ee7a72e7c885b2873ba1e0ffd0", - "size": 8567 + "sha256": "68629e7002a3f3876182c4e221fed21599a7a95e1f992e0ef512e3f1f408517f", + "size": 8561 }, { "url": "https://support.claude.com/en/articles/9519291-what-is-anthropic-s-policy-for-handling-governmental-requests-for-user-information", @@ -9102,14 +9109,14 @@ "url": "https://support.claude.com/en/articles/9534590-cost-and-usage-reporting-in-the-claude-console", "status": "success", "path": "support/9534590-cost-and-usage-reporting-in-the-claude-console.md", - "sha256": "4b8be1a8913d40e6bd15ce3be36b7aa85b5a9b8875e6da9078502f7e8e766baf", - "size": 5100 + "sha256": "f7de27b8acc3da086db224b4c0116367a08510f3ef0d26f14e8a1573f20dadab", + "size": 5096 }, { "url": "https://support.claude.com/en/articles/9547008-publish-and-share-artifacts", "status": "success", "path": "support/9547008-publish-and-share-artifacts.md", - "sha256": "9e6203643a4db5066751a4c535f641bd033512c11c90db387f0af86b4d4a8f85", + "sha256": "c9f88e0e39ea2dc33d5e793afb1a15942be3764b1169f1bbb7eeacc6c099b1b2", "size": 7332 }, { @@ -9186,7 +9193,7 @@ "url": "https://support.claude.com/en/articles/9927533-disable-public-projects-for-your-organization", "status": "success", "path": "support/9927533-disable-public-projects-for-your-organization.md", - "sha256": "e39b0cd59c03bf7329a018ffbdca57083027cee121275baf8b29818a61e598cd", + "sha256": "fb7cd1403fba470ede6eb63e5e742c0628e342d1dccdd86f19b7fd217b920a92", "size": 2584 }, { @@ -9326,14 +9333,14 @@ "url": "https://support.claude.com/en/articles/10310342-how-do-i-log-out-of-all-active-sessions", "status": "success", "path": "support/10310342-how-do-i-log-out-of-all-active-sessions.md", - "sha256": "6c240306c481df7b0ef71d702745cc38891a1d402a7b3f9d451121dd00175714", - "size": 2492 + "sha256": "d30fa3ffae65e20409a6cd70c27ba1a8dea75e629bd3e06996641962cc50905d", + "size": 2498 }, { "url": "https://support.claude.com/en/articles/10366376-how-can-i-delete-my-claude-console-account", "status": "success", "path": "support/10366376-how-can-i-delete-my-claude-console-account.md", - "sha256": "224dd8bc7eac3c4cd9fb206ef08ccfc9abb4d7b00a31679f92db53b040fc443b", + "sha256": "c20cd4a68099785c4a21804c480e241ce6fcccbfe9523fc8ac783088bc5f5edf", "size": 3165 }, { @@ -9375,15 +9382,15 @@ "url": "https://support.claude.com/en/articles/10504844-manage-user-feedback-settings-on-team-and-enterprise-plans", "status": "success", "path": "support/10504844-manage-user-feedback-settings-on-team-and-enterprise-plans.md", - "sha256": "be207b3080ebeed700cd2b9a6e5c4648dd87d008b4a6a46e041ea135e7d7c444", + "sha256": "4daca4adcc111ab10e9a3369ccd0a589a96f6435f4161ca9502ba3001a6b35f4", "size": 1036 }, { "url": "https://support.claude.com/en/articles/10504853-manage-user-feedback-settings-on-claude-console", "status": "success", "path": "support/10504853-manage-user-feedback-settings-on-claude-console.md", - "sha256": "3857575122c8798518036d45fdb42902eb679d947530fa1327dc86999ef419a8", - "size": 999 + "sha256": "36434c11cf3923f7404e967d02fb45967df373ec36f6e40a4816bec0050f6076", + "size": 1001 }, { "url": "https://support.claude.com/en/articles/10534883-use-the-claude-widget-on-android", @@ -9396,8 +9403,8 @@ "url": "https://support.claude.com/en/articles/10593882-share-and-unshare-chats", "status": "success", "path": "support/10593882-share-and-unshare-chats.md", - "sha256": "b777888a703d1d555717228f812408a2b99bc3c5aa6b9c6d79f3c1d8c7cf0752", - "size": 4014 + "sha256": "eb4ff14577ae502b1063d7a78ec4a0c3c00bff6933bb5d8e92f65f3d489b65b0", + "size": 4012 }, { "url": "https://support.claude.com/en/articles/10684626-enable-and-use-web-search", @@ -9424,8 +9431,8 @@ "url": "https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop", "status": "success", "path": "support/10949351-getting-started-with-local-mcp-servers-on-claude-desktop.md", - "sha256": "498b115ffc01c558cab8924b3d987fa52d25d4d0332cfd1210872c9827771150", - "size": 8267 + "sha256": "140306cb598b8d8becb2e53d8a72f447083e70fb9b493a4da906d2a1ded7a590", + "size": 8273 }, { "url": "https://support.claude.com/en/articles/11049741-what-is-the-max-plan", @@ -9466,8 +9473,8 @@ "url": "https://support.claude.com/en/articles/11101966-use-voice-mode", "status": "success", "path": "support/11101966-use-voice-mode.md", - "sha256": "8abce95e75a0d95d8fb2fe347e9d99adfc0927de2fd599971f597565044cf7a6", - "size": 10556 + "sha256": "2d460a4444a6e564f3a7cee9510bfa51018f90e8a1860097302c6073912bbee5", + "size": 10560 }, { "url": "https://support.claude.com/en/articles/11107691-why-is-a-coupon-or-promotion-not-available-for-my-account", @@ -9599,7 +9606,7 @@ "url": "https://support.claude.com/en/articles/11725453-set-up-the-claude-lti-in-canvas-by-instructure", "status": "success", "path": "support/11725453-set-up-the-claude-lti-in-canvas-by-instructure.md", - "sha256": "381d8890d281a569bae05b9b3b42501786aaa87681cfea91a433c3d4d35a9b1e", + "sha256": "f92585036fe9a14a2950751659226771b1333d08bba04a163164b5630858cf6b", "size": 2746 }, { @@ -9613,14 +9620,14 @@ "url": "https://support.claude.com/en/articles/11817273-use-claude-s-chat-search-and-memory-to-build-on-previous-context", "status": "success", "path": "support/11817273-use-claude-s-chat-search-and-memory-to-build-on-previous-context.md", - "sha256": "dffa3cb04f98eae957904cbf9f70b84e4e2cf28fe0c9eacdfa262acb0e8e4585", - "size": 25900 + "sha256": "6973d3ae29d3405a140301f1d3b176d3b56ddb8d784cefc8068ec06533e154bf", + "size": 25908 }, { "url": "https://support.claude.com/en/articles/11818288-why-am-i-being-asked-to-verify-my-payment-method", "status": "success", "path": "support/11818288-why-am-i-being-asked-to-verify-my-payment-method.md", - "sha256": "9bf4dda3f2807b19102085b0653e799fed593a45a140b741ae41dcb2f86b7b85", + "sha256": "12fe68e055d23bc3b77f7c179a2cc2738e1f0ab0d6b82e1e10f3aeff9837c1fb", "size": 814 }, { @@ -9655,8 +9662,8 @@ "url": "https://support.claude.com/en/articles/11869629-use-claude-with-android-apps", "status": "success", "path": "support/11869629-use-claude-with-android-apps.md", - "sha256": "bbb32b2e486e7891843cac556dfcf81664c87ee405730bd180897aaac176495e", - "size": 13991 + "sha256": "531085946c4748ed0a49f5c53112b58f29d22e735f65aa9b73181b4221cfb5e5", + "size": 13993 }, { "url": "https://support.claude.com/en/articles/11932705-automated-security-reviews-in-claude-code", @@ -9690,15 +9697,15 @@ "url": "https://support.claude.com/en/articles/12005970-manage-usage-credits-for-team-and-seat-based-enterprise-plans", "status": "success", "path": "support/12005970-manage-usage-credits-for-team-and-seat-based-enterprise-plans.md", - "sha256": "39fe40b45d888de8871ad25dcb5f5c1d8996aa1734fbb7efccd20f8c32b3e40e", - "size": 9642 + "sha256": "00744b557d771ad42c8f9330b9c2510e05a0f859979c7ed6546ff6395bb1e23b", + "size": 9636 }, { "url": "https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome", "status": "success", "path": "support/12012173-get-started-with-claude-in-chrome.md", - "sha256": "f26c469768922e7251e679b0ba7195bb8d9fed3316402a296190267a0b6a4c57", - "size": 14859 + "sha256": "21de20309bc0bb2c09aa4da38d576092e60ac794cba4e1bce6b0bde68d193504", + "size": 14857 }, { "url": "https://support.claude.com/en/articles/12053672-what-happens-to-a-user-s-data-when-they-are-removed-from-a-team-or-enterprise-organization", @@ -9711,7 +9718,7 @@ "url": "https://support.claude.com/en/articles/12083917-change-your-team-plan-from-monthly-to-annual-billing", "status": "success", "path": "support/12083917-change-your-team-plan-from-monthly-to-annual-billing.md", - "sha256": "96635cd727051fd8a949f127a227364d19923296718b7d91fa5ee7fc7ff800c2", + "sha256": "f51ac652e6ba07fcb006bce897439cc51bcf782a9c73d095fb85da2e09feb38d", "size": 1400 }, { @@ -9725,8 +9732,8 @@ "url": "https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude", "status": "success", "path": "support/12111783-create-and-edit-files-with-claude.md", - "sha256": "8ae0f1a82a6a5890b4cf28eaa1fecab401c2091ca62cd34fad788e7468631352", - "size": 17958 + "sha256": "e6ec5ebaf6396d5cdd3b9b8f1c04acaeb60e5c6a7e3bf0facc05c7d6198d8a24", + "size": 17960 }, { "url": "https://support.claude.com/en/articles/12119250-model-safety-bug-bounty-program", @@ -9753,21 +9760,21 @@ "url": "https://support.claude.com/en/articles/12157520-claude-code-usage-analytics", "status": "success", "path": "support/12157520-claude-code-usage-analytics.md", - "sha256": "5e38e3a087736ccd2c98171c9f9b07d6d1b8b6f2c69970c4d4022fc267014b13", - "size": 6431 + "sha256": "3d8222cda8dff2ca34eb00d6e6a3f67d008b8e68aae7b3ca1001d982f5b2c6ec", + "size": 6425 }, { "url": "https://support.claude.com/en/articles/12260368-use-incognito-chats", "status": "success", "path": "support/12260368-use-incognito-chats.md", - "sha256": "21a8423f7c3fd789a5d609489f781f7252d37634a56631353f2460500b98e690", - "size": 3600 + "sha256": "43f04d8a380510d6402912a3c1a392b903a7b5482ad1cd70cf00c0fb405a986b", + "size": 3598 }, { "url": "https://support.claude.com/en/articles/12293051-use-claude-in-xcode", "status": "success", "path": "support/12293051-use-claude-in-xcode.md", - "sha256": "4c47c79e11164e1495d8fd5a111f8aca4c67cc0a92704a51b9164e9ad510cf22", + "sha256": "41df091a67d33e929b1baad86d09cf28548483fd34050ae3a4b00ab89bc77d02", "size": 1907 }, { @@ -9809,14 +9816,14 @@ "url": "https://support.claude.com/en/articles/12429409-manage-usage-credits-for-paid-claude-plans", "status": "success", "path": "support/12429409-manage-usage-credits-for-paid-claude-plans.md", - "sha256": "26af79e29e8722f298894df353cb71b6844cf45f913fdfb9ac7afc8bc8f5c974", - "size": 6416 + "sha256": "161ed6a8aca6a349d3e64ad436c5cd1e02c98acd232f132f3c1837cd5d5ef481", + "size": 6418 }, { "url": "https://support.claude.com/en/articles/12466728-troubleshoot-claude-error-messages", "status": "success", "path": "support/12466728-troubleshoot-claude-error-messages.md", - "sha256": "6ff98a19fab7b38c2d6d707b2b59414ef8471eeb81529ec4d6bb33917bf1d34e", + "sha256": "386b72a725f57a16a23829bee8196a0ddfe3e10887768be52e51523d045dd38d", "size": 4232 }, { @@ -9837,8 +9844,8 @@ "url": "https://support.claude.com/en/articles/12512180-use-skills-in-claude", "status": "success", "path": "support/12512180-use-skills-in-claude.md", - "sha256": "998d383cdca78c8a93c99122c71fbf7bbf933bd6d9d73c79e8ab4a5a508671e9", - "size": 15546 + "sha256": "c970dbba409546a4be372026942a7fc6ab0a4123e0ba90d8b242e1a66746c726", + "size": 15550 }, { "url": "https://support.claude.com/en/articles/12512198-how-to-create-custom-skills", @@ -9858,8 +9865,8 @@ "url": "https://support.claude.com/en/articles/12592343-enabling-and-using-the-desktop-extension-allowlist", "status": "success", "path": "support/12592343-enabling-and-using-the-desktop-extension-allowlist.md", - "sha256": "3eedf69434e22d9911057161c02ddf0b9c9cc5d0d357625ccf9808943d3ab1c3", - "size": 5716 + "sha256": "036b73a87cf072e7b5f76333fe6a65fe98c5f38b982be93378bb6341224eb91e", + "size": 5720 }, { "url": "https://support.claude.com/en/articles/12611117-deploy-claude-desktop-for-macos", @@ -9872,8 +9879,8 @@ "url": "https://support.claude.com/en/articles/12618689-claude-code-on-the-web", "status": "success", "path": "support/12618689-claude-code-on-the-web.md", - "sha256": "fa2f6f51d4a81b5ab32084de162e8fcd8d7084bf2b97bdb2160ca0bd198d33df", - "size": 10960 + "sha256": "9eda27b9e58cf56a0b9b31beb2777eb1cf5754a46f0004be1eae5ddad644a722", + "size": 10972 }, { "url": "https://support.claude.com/en/articles/12622667-enterprise-configuration-for-claude-desktop", @@ -9893,7 +9900,7 @@ "url": "https://support.claude.com/en/articles/12626668-use-quick-entry-with-claude-desktop-on-mac", "status": "success", "path": "support/12626668-use-quick-entry-with-claude-desktop-on-mac.md", - "sha256": "d24c692078482a614d881eebae98c54950878b6345d5330583e90566d195425d", + "sha256": "2a68cb641cedcf47317686f830560ad991969922977775537f0d5eaab2b2fe74", "size": 5972 }, { @@ -9928,8 +9935,8 @@ "url": "https://support.claude.com/en/articles/12883420-view-usage-analytics-for-team-and-enterprise-plans", "status": "success", "path": "support/12883420-view-usage-analytics-for-team-and-enterprise-plans.md", - "sha256": "aa00efc3a83b0566f8a735d22dd3434dfe7e4ce46da3ae8c0790f09bd6066422", - "size": 13161 + "sha256": "b086011332877eb7d33aa1ec7e7a34173f1f4b3a55dd1c3858a57889ffeeb0bc", + "size": 13173 }, { "url": "https://support.claude.com/en/articles/12902405-claude-in-chrome-troubleshooting", @@ -9949,8 +9956,8 @@ "url": "https://support.claude.com/en/articles/12902446-claude-in-chrome-permissions-guide", "status": "success", "path": "support/12902446-claude-in-chrome-permissions-guide.md", - "sha256": "19c36744a64b7d9afbeeff9ace168aa1280a4ddd15a588252a967395fb00003c", - "size": 9561 + "sha256": "78893fe71c271fba5516810919a2521c7e16209b937ea00538f6aa96174a2f1a", + "size": 9567 }, { "url": "https://support.claude.com/en/articles/12938627-how-to-gift-a-claude-subscription", @@ -9977,8 +9984,8 @@ "url": "https://support.claude.com/en/articles/12997503-team-plan-billing-faqs", "status": "success", "path": "support/12997503-team-plan-billing-faqs.md", - "sha256": "abfc4057c88f2c56b5225297daa4321283d246232f8f90fdb03a6f2eefb07a19", - "size": 4008 + "sha256": "01d61fa22cda63a80593f20f63b57af13171924e49040b347b5a1acd985fab57", + "size": 4004 }, { "url": "https://support.claude.com/en/articles/13015708-access-the-compliance-api", @@ -10026,15 +10033,15 @@ "url": "https://support.claude.com/en/articles/13132885-set-up-single-sign-on-sso", "status": "success", "path": "support/13132885-set-up-single-sign-on-sso.md", - "sha256": "a5a2c57e946af436059f78c5f045d881aa67e459cd9b71ccb7e8a4b25d0fa234", - "size": 12317 + "sha256": "8e67b5b627b7aaea2561ba385539ea1fb39937667cad5bbe54754dc235c6aa4d", + "size": 12319 }, { "url": "https://support.claude.com/en/articles/13133195-set-up-jit-or-scim-provisioning", "status": "success", "path": "support/13133195-set-up-jit-or-scim-provisioning.md", - "sha256": "409010007d87f0da8794bb44f9b205980c244259cf5b1bcd08162ce575ce3825", - "size": 19487 + "sha256": "928c729244ad05a59ccff78efdf80821aada8206b35d5616a8f5e5b729e73222", + "size": 19489 }, { "url": "https://support.claude.com/en/articles/13133750-manage-members-on-team-and-enterprise-plans", @@ -10061,8 +10068,8 @@ "url": "https://support.claude.com/en/articles/13163631-configuring-session-security-settings", "status": "success", "path": "support/13163631-configuring-session-security-settings.md", - "sha256": "06a99d8a7436455eacfeb51b848de287736082542c79ea086c23a3a9ad3679de", - "size": 3704 + "sha256": "fe78ab6732480f150859c3a258d6934dda809f9e5bf692097d7017e0028f6fdd", + "size": 3698 }, { "url": "https://support.claude.com/en/articles/13163666-holiday-2025-usage-promotion", @@ -10082,7 +10089,7 @@ "url": "https://support.claude.com/en/articles/13189465-log-in-to-your-claude-account", "status": "success", "path": "support/13189465-log-in-to-your-claude-account.md", - "sha256": "06d50516281ecf7274362b28d4cff806bfb351f67ba7fc302a1bccb0caecd8b5", + "sha256": "3e32a36336f4e3765c64386eef3a7a7643a2ceac56215cfb8de38a51b2d3b4ed", "size": 7036 }, { @@ -10110,22 +10117,22 @@ "url": "https://support.claude.com/en/articles/13325567-account-management-faqs", "status": "success", "path": "support/13325567-account-management-faqs.md", - "sha256": "207919025ae03d7da227e7e62f58278fad06826be2fa7c9d7807953dee87a5e4", + "sha256": "2948f652ff19bd05a50b8be0db790730b0bca56f5e3766b45424528b05fc027b", "size": 2632 }, { "url": "https://support.claude.com/en/articles/13345190-get-started-with-claude-cowork", "status": "success", "path": "support/13345190-get-started-with-claude-cowork.md", - "sha256": "171347efdb916a1c46663a108ee068a16d4ea6e6ec26bbdbcee246ce9d5eb201", - "size": 21354 + "sha256": "280571ec873f0b9f95c88a6f9e14aa812acee372c039ee081e9fa8b303cc0067", + "size": 21358 }, { "url": "https://support.claude.com/en/articles/13346458-customizing-your-console-appearance-settings", "status": "success", "path": "support/13346458-customizing-your-console-appearance-settings.md", - "sha256": "9ce9bb80268e8575ca32ed3fd3d1bc3f77f333eaf40169a2cba3996ddab706df", - "size": 607 + "sha256": "dbb1cb772a75bd662ce32f22efc882abee268019e27608b51d8d3dbd80c7563c", + "size": 611 }, { "url": "https://support.claude.com/en/articles/13346720-export-your-organization-s-data", @@ -10145,8 +10152,8 @@ "url": "https://support.claude.com/en/articles/13371040-log-in-to-your-console-account", "status": "success", "path": "support/13371040-log-in-to-your-console-account.md", - "sha256": "ed9001d3d25eb665ad6ebd12d2a165b1e91ec9a1fde25ef3358fe1347bb0da05", - "size": 4615 + "sha256": "9773fb76edea830bb03f784f54a1029c85849f7b8c70afee63905d6556b54a54", + "size": 4611 }, { "url": "https://support.claude.com/en/articles/13393991-purchase-and-manage-seats-on-enterprise-plans", @@ -10201,8 +10208,8 @@ "url": "https://support.claude.com/en/articles/13641943-visual-and-interactive-content", "status": "success", "path": "support/13641943-visual-and-interactive-content.md", - "sha256": "15fcf5e95b4d1cc0b0859d080c2c7e1da504b2ba5d6fd16412d0664f99e4ea2f", - "size": 6511 + "sha256": "cd351d2d253605a4a39725058c24aa603e128691910579b88e3454d92bdc49e5", + "size": 6509 }, { "url": "https://support.claude.com/en/articles/13663666-use-visual-and-interactive-content-on-team-and-enterprise-plans", @@ -10229,8 +10236,8 @@ "url": "https://support.claude.com/en/articles/13756069-public-sector-faqs", "status": "success", "path": "support/13756069-public-sector-faqs.md", - "sha256": "d2a3bb64dc70627d64407975a7011d1ec00c062744d37f5e114c04c13eda7d4b", - "size": 8378 + "sha256": "3bb812f79542f3bc7dd1a8bcec6c4417ad6b2c3ed10404d931ff09cb1358a433", + "size": 8376 }, { "url": "https://support.claude.com/en/articles/13776697-join-an-organization-via-invite-link", @@ -10257,22 +10264,22 @@ "url": "https://support.claude.com/en/articles/13837433-manage-plugins-for-your-organization", "status": "success", "path": "support/13837433-manage-plugins-for-your-organization.md", - "sha256": "3267d160a4843756f616c253c2981a420b24f05ff8b770a061c32c6ce7ac7f46", + "sha256": "787cc727803341f973391f06b550f3557f0c082d7f7bed4ef3cb868a685bdfb6", "size": 20823 }, { "url": "https://support.claude.com/en/articles/13837440-use-plugins-in-claude", "status": "success", "path": "support/13837440-use-plugins-in-claude.md", - "sha256": "ade656bc2fb3b192ae3a87d191d03419fdfdeca254c5e01274d4debd2119557e", - "size": 6714 + "sha256": "3465fd7bf50b2a99ab64da596fb26549bfa4cd44b227da7ba1b6a8d867e325f8", + "size": 6716 }, { "url": "https://support.claude.com/en/articles/13854387-schedule-recurring-tasks-in-claude-cowork", "status": "success", "path": "support/13854387-schedule-recurring-tasks-in-claude-cowork.md", - "sha256": "b182970c2b2b5b13cba466812eee11cd0827bd32c37931805d1eacd5e9e9f24d", - "size": 4747 + "sha256": "f0b0882f531f2fea8170f2251a09572207f93a49997205d41630f3c6607f87cc", + "size": 4749 }, { "url": "https://support.claude.com/en/articles/13917817-google-workspace-sso-scim-email-mismatch", @@ -10362,8 +10369,8 @@ "url": "https://support.claude.com/en/articles/13947068-assign-tasks-from-anywhere-in-claude-cowork", "status": "success", "path": "support/13947068-assign-tasks-from-anywhere-in-claude-cowork.md", - "sha256": "d14375278f38918fa32cd5d6a0402685fdcc942ed7321f66eb78bbf88523b413", - "size": 8274 + "sha256": "98991475a7fca3e88613df0ad786216390230b2a115e6bac535c63fb6757d99a", + "size": 8278 }, { "url": "https://support.claude.com/en/articles/13979539-custom-visuals-in-chat-and-cowork", @@ -10383,15 +10390,15 @@ "url": "https://support.claude.com/en/articles/14116274-organize-your-tasks-with-projects-in-claude-cowork", "status": "success", "path": "support/14116274-organize-your-tasks-with-projects-in-claude-cowork.md", - "sha256": "f2e84fedbcbc6ca026f06c580d6c142a0f02b58ea74ca88c1591ce8538594b56", - "size": 5692 + "sha256": "9821083322902dceaa0cda14f74ecca62696f489b4db8f839991db1a18df38f8", + "size": 5710 }, { "url": "https://support.claude.com/en/articles/14128542-let-claude-use-your-computer-in-cowork", "status": "success", "path": "support/14128542-let-claude-use-your-computer-in-cowork.md", - "sha256": "b2a7a6c0661113d4f66bfde942a6948dfbd1cf38e4cba326e97f3e9d43d01603", - "size": 8927 + "sha256": "e7531b95ce642f8dbe2ad0ee8c086b8dd1795e27253ec5cc3805401d9f39cc97", + "size": 8925 }, { "url": "https://support.claude.com/en/articles/14128775-claude-code-on-console-to-enterprise-migration", @@ -10453,7 +10460,7 @@ "url": "https://support.claude.com/en/articles/14499648-how-scim-sync-works-for-enterprise-organizations", "status": "success", "path": "support/14499648-how-scim-sync-works-for-enterprise-organizations.md", - "sha256": "e12bcae00cee9d96ec0a8ee083f68f54466fc98fc867bd933fed4cbbfcdb5bb1", + "sha256": "ed1b63faa5c79f8c807263873de39091e1a803299d7769cf96e9f69bc227c544", "size": 7440 }, { @@ -10474,14 +10481,14 @@ "url": "https://support.claude.com/en/articles/14503613-sso-login", "status": "success", "path": "support/14503613-sso-login.md", - "sha256": "37adf7370eaf2d14861368440c2df7c46ff16c00e3a8582bacac12ae09b84eb0", - "size": 6694 + "sha256": "c98f0adc3126ec251bba5dd6bd6e47a921aa7d41802b351630c4a6198d4fbcf6", + "size": 6692 }, { "url": "https://support.claude.com/en/articles/14503643-set-up-scim-in-claude-for-government", "status": "success", "path": "support/14503643-set-up-scim-in-claude-for-government.md", - "sha256": "70fea1d0bc977397ed77e21625792f36cc416b50cac716467f2d3c7e2d2502b6", + "sha256": "815edd7cc7a8f81aa7be971f3ffa095c0e4208f761bcac39bda01c65fac66ab2", "size": 6421 }, { @@ -10509,8 +10516,8 @@ "url": "https://support.claude.com/en/articles/14503775-mcp-web-search", "status": "success", "path": "support/14503775-mcp-web-search.md", - "sha256": "abd705873508cdcf64b261d1009eecd94916185d83edbc294a0ee29344345d65", - "size": 4679 + "sha256": "98fbbc5d7e29c12a30db2623770da6adaf71c9451fbf77552d1779d9109f38a8", + "size": 4681 }, { "url": "https://support.claude.com/en/articles/14503794-model-availability-in-claude-for-government", @@ -10607,22 +10614,22 @@ "url": "https://support.claude.com/en/articles/14604397-set-up-your-design-system-in-claude-design", "status": "success", "path": "support/14604397-set-up-your-design-system-in-claude-design.md", - "sha256": "204ccca5916c11d6353e91c9f8b65fd85dd6a699e7621b87708b9041a0fbe906", + "sha256": "f4c617505a13d151aab1f3f95285a46daf583cf313d5fd63c379645f84e1618b", "size": 4400 }, { "url": "https://support.claude.com/en/articles/14604406-claude-design-admin-guide-for-team-and-enterprise-plans", "status": "success", "path": "support/14604406-claude-design-admin-guide-for-team-and-enterprise-plans.md", - "sha256": "54f01523b12ea81536c6957414362f5ff79d78173387f19da4b70ddd7c2fba70", - "size": 12733 + "sha256": "3ee8cb8a945b7d722fb82f816d29ab1969d62fe15c0844ee51ad47c8e0f98759", + "size": 12735 }, { "url": "https://support.claude.com/en/articles/14604416-get-started-with-claude-design", "status": "success", "path": "support/14604416-get-started-with-claude-design.md", - "sha256": "e06c9fe2069f4dc99c0ae53c88bf38ff0248b9dfacbd3d57e380c06264f4d285", - "size": 11132 + "sha256": "d1c9e70488d33c7110dd57042470aa1c44ab84f4191833905931d72b84ddcfea", + "size": 11134 }, { "url": "https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet", @@ -10747,8 +10754,8 @@ "url": "https://support.claude.com/en/articles/15330088-set-a-default-model-for-your-organization", "status": "success", "path": "support/15330088-set-a-default-model-for-your-organization.md", - "sha256": "0f3b492170a5ada21ec8df6c9df634f37ef0fef8bdfd75eb896110aa6c31d36c", - "size": 5744 + "sha256": "cea300367bd87ace550aceee0234cb9ab737bf2147b6bd7818358d85c9115997", + "size": 5746 }, { "url": "https://support.claude.com/en/articles/15330651-claude-enterprise-admin-api-reference-guide", @@ -10859,8 +10866,8 @@ "url": "https://support.claude.com/en/articles/15694740-manage-model-access-for-your-organization", "status": "success", "path": "support/15694740-manage-model-access-for-your-organization.md", - "sha256": "4ae967a94e682b24b991ebc168451946f112afe0e08129b3d87a35821b0f4a24", - "size": 8503 + "sha256": "e747863026cce7ef2327f4fa249b636ceb88b70fc8a5609305a1c65fafed3f64", + "size": 8499 }, { "url": "https://support.claude.com/en/articles/15707726-using-claude-for-legal-work-privilege-confidentiality-and-how-to-think-about-configuration", @@ -10894,7 +10901,7 @@ "url": "https://support.claude.com/en/articles/15936181-get-started-with-1password-for-claude", "status": "success", "path": "support/15936181-get-started-with-1password-for-claude.md", - "sha256": "0e3625362fe45c9c8568e542df0c35cbe0db3f56f7582cbd8eff41e4a8108b89", + "sha256": "1779096af0efaf08798dece7d0c7c6d98d6e852c714091d6e52de6063fb44d5a", "size": 5056 }, { @@ -10943,8 +10950,8 @@ "url": "https://support.claude.com/en/articles/16607638-understanding-your-pro-or-max-plan-invoices", "status": "success", "path": "support/16607638-understanding-your-pro-or-max-plan-invoices.md", - "sha256": "cb6accd6b0c884b7dbe7f4522d5cd2c6a9db3f5c883308b5dc023f1488102abb", - "size": 5439 + "sha256": "990686518ae08aa529b605d240cb7878e0d3a991fb6064ecf95a4f1f31002c61", + "size": 5443 }, { "url": "https://support.claude.com/en/articles/16607668-understanding-your-team-plan-invoices", @@ -21345,8 +21352,8 @@ "url": "https://code.claude.com/docs/en/slash-commands", "status": "success", "path": "en/docs/claude-code/slash-commands.md", - "sha256": "79fcd0c50f8fff8319754b57b379183ef60512ac06c383ff354f4241e6210bbd", - "size": 99321 + "sha256": "b7a030ad40a8e613349dbc56b7f951d54b720c8b6616b96c97d6b116178e1d89", + "size": 99094 }, { "url": "https://code.claude.com/docs/en/desktop-changelog", @@ -21366,8 +21373,8 @@ "url": "https://code.claude.com/docs/en/iam", "status": "success", "path": "en/docs/claude-code/iam.md", - "sha256": "9bebf8122c2084254be0b88bbd0d19d13964f17f43685e5a006a7c67730de24f", - "size": 24231 + "sha256": "4d9b27ab1577205a1e1aabaa0c9960a09acfc021f32f8d27b825facb579f2284", + "size": 28422 }, { "url": "https://code.claude.com/docs/en/agent-sdk/slash-commands", @@ -27677,8 +27684,8 @@ } ], "summary": { - "total": 3991, - "downloaded": 3901, + "total": 3992, + "downloaded": 3902, "skipped": 0, "failed": 0, "dead": 90, diff --git a/content/en/docs/claude-code/agent-sdk/hosting.md b/content/en/docs/claude-code/agent-sdk/hosting.md index 5c6c5dc38a..3ef9e4ebd2 100644 --- a/content/en/docs/claude-code/agent-sdk/hosting.md +++ b/content/en/docs/claude-code/agent-sdk/hosting.md @@ -20,18 +20,40 @@ Every hosting decision on this page follows from how the SDK runs the agent. Whe Request flow: client to your app, which spawns a claude CLI subprocess over stdio inside the container; the subprocess writes to local disk and calls api.anthropic.com over HTTPS -One agent session maps to one subprocess. Running N concurrent sessions means N subprocesses, each with its own process tree and transcript file. By default they all inherit your application's working directory, so pass `cwd` on each `query()` call when sessions need separate filesystems: +One agent session maps to one subprocess. Running N concurrent sessions means N subprocesses, each with its own process tree and transcript file. By default they all inherit your application's working directory. When sessions need separate filesystems, pass a distinct `cwd` in the options of each session's `query()` call: ```typescript TypeScript theme={null} - query({ prompt, options: { cwd: "/work/session-a" } }) + import { query } from "@anthropic-ai/claude-agent-sdk"; + + for await (const message of query({ + prompt: "Summarize the files in this directory", + options: { cwd: "/work/session-a" }, + })) { + console.log(message); + } ``` ```python Python theme={null} - query(prompt=prompt, options=ClaudeAgentOptions(cwd="/work/session-a")) + import asyncio + + from claude_agent_sdk import ClaudeAgentOptions, query + + + async def main(): + async for message in query( + prompt="Summarize the files in this directory", + options=ClaudeAgentOptions(cwd="/work/session-a"), + ): + print(message) + + + asyncio.run(main()) ``` +The TypeScript examples on this page use top-level `await`, so save them as `.mts` files or set `"type": "module"` in `package.json`. + ### State that lives on local disk Three kinds of agent state live on the container's filesystem by default. None of them survive a container restart, a scale-down, or a move to a different node. @@ -56,7 +78,7 @@ Create a container for each user task and destroy it when the task completes. Be Example workloads include bug investigation and fix, invoice and receipt extraction, document translation, and media transformation. -The container runs a one-shot entrypoint that calls the SDK and exits. In TypeScript, save the file as `entrypoint.mts` or set `"type": "module"` in `package.json` so top-level `await` is available. +The container runs a one-shot entrypoint that reads the task from the `TASK_PROMPT` environment variable, calls the SDK, and exits. ```typescript TypeScript theme={null} @@ -87,6 +109,8 @@ The container runs a one-shot entrypoint that calls the SDK and exits. In TypeSc ``` +The script prints each message as it arrives, including a result message whose `subtype` is `success` when the task completes within the turn limit. If the task hits the 20-turn limit instead, the result message's `subtype` is `error_max_turns` and the `query()` call raises an error after yielding it, so wrap the loop in a try block if the container needs to exit cleanly. See [Handle the result](/docs/en/agent-sdk/agent-loop#handle-the-result) for the error subtypes. + ### Long-running sessions Run persistent container instances, often hosting multiple SDK processes per container, to serve ongoing work. Best for agents that take autonomous action, serve content, or handle high-volume message streams. @@ -316,7 +340,7 @@ Plan around these in your deployment design. | Limitation | What to do | | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| No top-level session timeout | A session does not time out on its own. Set `maxTurns` in `Options` to bound how many tool-use round trips the agent takes before stopping. | +| No top-level session timeout | A session does not time out on its own. Set `maxTurns` in TypeScript or `max_turns` in Python to bound how many tool-use round trips the agent takes before stopping. | | Memory growth over long sessions | Cap session length or recycle subprocesses periodically. See [Scaling and concurrency](#scaling-and-concurrency). | | Large parallel-subagent fanouts can hit rate limits | Break work into smaller batches rather than issuing one wide dispatch. | | No per-subagent wall-clock deadline | Cap each [subagent](/docs/en/agent-sdk/subagents) with `maxTurns` in its `AgentDefinition`. For background subagents only, `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` sets a stall watchdog that fires when a `run_in_background` subagent stops producing output; it is not a total-runtime deadline. | diff --git a/content/en/docs/claude-code/agent-sdk/mcp.md b/content/en/docs/claude-code/agent-sdk/mcp.md index 8381558e30..26cffe0b87 100644 --- a/content/en/docs/claude-code/agent-sdk/mcp.md +++ b/content/en/docs/claude-code/agent-sdk/mcp.md @@ -76,7 +76,7 @@ You can configure MCP servers in code when calling `query()`, or in a `.mcp.json ### In code -Pass MCP servers directly in the `mcpServers` option: +Pass MCP servers directly in the `mcpServers` option. This example starts a local filesystem MCP server for `/Users/me/projects`. Replace that path with a directory on your machine: ```typescript TypeScript theme={null} @@ -131,7 +131,7 @@ Pass MCP servers directly in the `mcpServers` option: ### From a config file -Create a `.mcp.json` file at your project root. The file is picked up when the `project` setting source is enabled, which it is for default `query()` options. If you set `settingSources` explicitly, include `"project"` for this file to load: +Create a `.mcp.json` file at your project root. The file is picked up when the `project` setting source is enabled, which it is for default `query()` options. If you set `settingSources` explicitly, include `"project"` for this file to load. Replace `/Users/me/projects` with a directory on your machine: ```json theme={null} { @@ -268,7 +268,7 @@ MCP servers communicate with your agent using different transport protocols. Che ### stdio servers -Local processes that communicate via stdin/stdout. Use this for MCP servers you run on the same machine. For the `.mcp.json` form, use the same fields shown at [From a config file](#from-a-config-file). In code, pass the command and its arguments: +Local processes that communicate via stdin/stdout. Use this for MCP servers you run on the same machine. For the `.mcp.json` form, use the same fields shown at [From a config file](#from-a-config-file). In code, pass the command and its arguments. Replace `/Users/me/projects` with a directory on your machine: ```typescript TypeScript hidelines={1,-1} theme={null} @@ -338,7 +338,7 @@ Use HTTP or SSE for cloud-hosted MCP servers and remote APIs. For the `.mcp.json ``` -For the streamable HTTP transport, use `"type": "http"` instead. In `.mcp.json` and other JSON config files, `"streamable-http"` is accepted as an alias for `"http"`. The programmatic `mcpServers` option accepts only `"http"`. +For the streamable HTTP transport, use `"type": "http"` instead. In `.mcp.json` and other JSON config files, `"streamable-http"` is accepted as an alias for `"http"`. The SDKs' `McpHttpServerConfig` type declares only `"http"`, so use `"http"` for servers you pass in code. ### SDK MCP servers @@ -617,6 +617,8 @@ export GITHUB_TOKEN=YOUR_GITHUB_PAT ``` +In the `MCP servers:` line, a `status` of `connected` for `github` confirms the token works. If Claude Code has a [cached tool list](#connection-timing) for the server, the status can read `pending` instead and the server connects on its first tool call. If the status is `failed` or `needs-auth`, see [Error handling](#error-handling) before trusting the result, since Claude can fall back to built-in tools when the server is unavailable. + ### Query a database This example uses [DBHub](https://github.com/bytebase/dbhub) to query a Postgres database. The agent automatically discovers the database schema, writes the SQL query, and returns the results. diff --git a/content/en/docs/claude-code/agent-sdk/modifying-system-prompts.md b/content/en/docs/claude-code/agent-sdk/modifying-system-prompts.md index 93eea3749b..ffd9659704 100644 --- a/content/en/docs/claude-code/agent-sdk/modifying-system-prompts.md +++ b/content/en/docs/claude-code/agent-sdk/modifying-system-prompts.md @@ -210,7 +210,7 @@ By default, two sessions that use the same `claude_code` preset and `append` tex To make the system prompt identical across sessions, set `excludeDynamicSections: true` in TypeScript or `"exclude_dynamic_sections": True` in Python. The per-session context moves into the first user message, leaving only the static preset and your `append` text in the system prompt so identical configurations share a cache entry across users and machines. - `excludeDynamicSections` requires `@anthropic-ai/claude-agent-sdk` v0.2.98 or later, or `claude-agent-sdk` v0.1.58 or later for Python. It applies only to the preset object form and has no effect when `systemPrompt` is a string. + `excludeDynamicSections` requires `@anthropic-ai/claude-agent-sdk` v0.2.98 or later, or `claude-agent-sdk` v0.1.58 or later for Python. Set it on the preset object form only. The SDK ignores it when you pass a custom prompt instead of the preset; to keep a custom prompt's instructions cached in the TypeScript SDK, see [Cache the static part of a custom prompt](#cache-the-static-part-of-a-custom-prompt). The following example pairs a shared `append` block with `excludeDynamicSections` so a fleet of agents running from different directories can reuse the same cached system prompt: @@ -326,6 +326,43 @@ You can provide a custom string as `systemPrompt` to replace the default entirel In Python, load a large custom prompt from a file with `system_prompt={"type": "file", "path": "..."}` instead of passing it as a string. The Python SDK passes a string prompt as one command-line argument to the CLI subprocess, so a prompt that exceeds the OS argument-length limit fails at process spawn before any API request is sent. On Linux the error is `Argument list too long`. See [`SystemPromptFile`](/docs/en/agent-sdk/python#systempromptfile) for the platform thresholds and the Windows behavior. +#### Cache the static part of a custom prompt + +In the TypeScript SDK, you can pass a custom prompt as an array of strings instead of one string, with the `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` marker between the static part and the rest. Use this when your prompt combines instructions that are the same on every request with context that changes per request, such as the customer or ticket the agent is handling. When you pass both parts as one string, a change to the per-request part changes the whole system prompt, so the static instructions miss the cache too. This form isn't available in the Python SDK, whose `system_prompt` option accepts a string, a preset, or a [file](/docs/en/agent-sdk/python#systempromptfile). + + + The SDK splits the prompt only when it calls the Claude API directly or runs on [Claude Platform on AWS](/docs/en/claude-platform-on-aws). In every other configuration, such as Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or an [LLM gateway](/docs/en/llm-gateway-connect), and whenever you set [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/en/llm-gateway-protocol#disable-pre-release-capabilities), the SDK sends the whole prompt as one block, the same as passing one string. + + +To split the prompt, import `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` from `@anthropic-ai/claude-agent-sdk` and pass it as its own array element between the two parts. The SDK sends the strings before the marker as one text block and the strings after it as a second block, each with its own cache breakpoint. In the example below, a support agent loads its triage instructions from a file and receives details about one ticket on each request, so the instructions stay cached while the ticket details change: + +```typescript TypeScript theme={null} +import { readFile } from "node:fs/promises"; +import { query, SYSTEM_PROMPT_DYNAMIC_BOUNDARY } from "@anthropic-ai/claude-agent-sdk"; + +// Identical on every request +const instructions = await readFile("triage-instructions.md", "utf8"); +// Different on every request +const ticketContext = "Customer plan: Enterprise. Other open tickets from this customer: 3."; + +for await (const message of query({ + prompt: "Triage ticket 4821", + options: { + systemPrompt: [instructions, SYSTEM_PROMPT_DYNAMIC_BOUNDARY, ticketContext] + } +})) { + // ... +} +``` + +[Track cache tokens](/docs/en/agent-sdk/cost-tracking#track-cache-tokens) describes the `cache_creation_input_tokens` and `cache_read_input_tokens` fields on each result message. + +The SDK assembles the blocks from the array as follows: + +* The SDK joins the strings on each side of the marker with a blank line between them and removes the marker itself, so the marker text doesn't reach Claude. +* If you include the marker more than once, the first one is the split and the SDK removes the others. +* If you leave the marker out, the SDK joins all the strings into one block, the same as passing one string. + ## Compare the four approaches The four customization methods differ in where they live, how they're shared, and what they preserve from the `claude_code` preset. diff --git a/content/en/docs/claude-code/agent-sdk/observability.md b/content/en/docs/claude-code/agent-sdk/observability.md index 2f1058bd99..3d3b4df148 100644 --- a/content/en/docs/claude-code/agent-sdk/observability.md +++ b/content/en/docs/claude-code/agent-sdk/observability.md @@ -145,7 +145,7 @@ Traces give you the most detailed view of an agent run. With `CLAUDE_CODE_ENHANC * **`claude_code.interaction`:** wraps a single turn of the agent loop, from receiving a prompt to producing a response. * **`claude_code.llm_request`:** wraps each call to the Claude API, with model name, latency, and token counts as attributes. * **`claude_code.tool`:** wraps each tool invocation, with child spans for the permission wait (`claude_code.tool.blocked_on_user`) and the execution itself (`claude_code.tool.execution`). -* **`claude_code.hook`:** wraps each [hook](/docs/en/agent-sdk/hooks) execution. Requires detailed beta tracing (`ENABLE_BETA_TRACING_DETAILED=1` and `BETA_TRACING_ENDPOINT`) in addition to the variables above. +* **`claude_code.hook`:** wraps each [hook](/docs/en/agent-sdk/hooks) execution. Requires detailed beta tracing (`ENABLE_BETA_TRACING_DETAILED=1` and `BETA_TRACING_ENDPOINT`). The `llm_request`, `tool`, and `hook` spans are children of the enclosing `claude_code.interaction` span. When the agent spawns a subagent through the Agent tool, the subagent's `llm_request` and `tool` spans nest under the parent agent's `claude_code.tool` span, so the full delegation chain appears as one trace. diff --git a/content/en/docs/claude-code/agent-sdk/python.md b/content/en/docs/claude-code/agent-sdk/python.md index 31bdfeb92a..e1ded8dea9 100644 --- a/content/en/docs/claude-code/agent-sdk/python.md +++ b/content/en/docs/claude-code/agent-sdk/python.md @@ -1053,21 +1053,21 @@ class AgentDefinition: permissionMode: PermissionMode | None = None ``` -| Field | Required | Description | -| :---------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `description` | Yes | Natural language description of when to use this agent | -| `prompt` | Yes | The agent's system prompt | -| `tools` | No | Array of allowed tool names. If omitted, inherits every [tool available to subagents](/docs/en/sub-agents#available-tools) | -| `disallowedTools` | No | Array of tool names to remove from the agent's tool set. MCP server-level patterns are also accepted: `mcp__server` or `mcp__server__*` removes every tool from that server, and `mcp__*` removes every MCP tool from any server | -| `model` | No | Model override for this agent. Accepts an alias such as `"sonnet"`, `"opus"`, `"haiku"`, or `"inherit"`, or a full model ID. If omitted, uses the main model | -| `skills` | No | List of skill names to preload into the agent's context at startup. Unlisted skills remain invocable through the Skill tool | -| `memory` | No | Memory source for this agent: `"user"`, `"project"`, or `"local"` | -| `mcpServers` | No | MCP servers available to this agent. Each entry is a server name or an inline `{name: config}` dict | -| `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main thread agent | -| `maxTurns` | No | Maximum number of agentic turns before the agent stops | -| `background` | No | Run this agent as a non-blocking background task when invoked | -| `effort` | No | Reasoning effort level for this agent. Accepts a named level or an integer. See [`EffortLevel`](#effortlevel) | -| `permissionMode` | No | Permission mode for tool execution within this agent. See [`PermissionMode`](#permissionmode) | +| Field | Required | Description | +| :---------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `description` | Yes | Natural language description of when to use this agent | +| `prompt` | Yes | The agent's system prompt | +| `tools` | No | Array of allowed tool names. If omitted, inherits every [tool available to subagents](/docs/en/sub-agents#available-tools) | +| `disallowedTools` | No | Array of tool names to remove from the agent's tool set. MCP server-level patterns are also accepted: `mcp__server` or `mcp__server__*` removes every tool from that server, and `mcp__*` removes every MCP tool from any server | +| `model` | No | Model override for this agent. Accepts an alias such as `"sonnet"`, `"opus"`, `"haiku"`, or `"inherit"`, or a full model ID. When you omit it, Claude Code picks the model in the [subagent model order](/docs/en/sub-agents#choose-a-model) | +| `skills` | No | List of skill names to preload into the agent's context at startup. Unlisted skills remain invocable through the Skill tool | +| `memory` | No | Memory source for this agent: `"user"`, `"project"`, or `"local"` | +| `mcpServers` | No | MCP servers available to this agent. Each entry is a server name or an inline `{name: config}` dict | +| `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main thread agent | +| `maxTurns` | No | Maximum number of agentic turns before the agent stops | +| `background` | No | Run this agent as a non-blocking background task when invoked | +| `effort` | No | Reasoning effort level for this agent. Accepts a named level or an integer. See [`EffortLevel`](#effortlevel) | +| `permissionMode` | No | Permission mode for tool execution within this agent. See [`PermissionMode`](#permissionmode) | `AgentDefinition` field names use camelCase, such as `disallowedTools`, `permissionMode`, and `maxTurns`. These names map directly to the wire format shared with the TypeScript SDK. This differs from `ClaudeAgentOptions`, which uses Python snake\_case for the equivalent top-level fields such as `disallowed_tools` and `permission_mode`. Because `AgentDefinition` is a dataclass, passing a snake\_case keyword raises a `TypeError` at construction time. diff --git a/content/en/docs/claude-code/agent-sdk/subagents.md b/content/en/docs/claude-code/agent-sdk/subagents.md index d48d458fc4..6cefdc926f 100644 --- a/content/en/docs/claude-code/agent-sdk/subagents.md +++ b/content/en/docs/claude-code/agent-sdk/subagents.md @@ -144,21 +144,21 @@ This example creates two subagents: a code reviewer with read-only access and a ### AgentDefinition configuration -| Field | Type | Required | Description | -| :---------------- | :---------------------------------------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `description` | `string` | Yes | Natural language description of when to use this agent | -| `prompt` | `string` | Yes | The agent's system prompt defining its role and behavior | -| `tools` | `string[]` | No | Array of allowed tool names. If omitted, inherits every [tool available to subagents](/docs/en/sub-agents#available-tools) | -| `disallowedTools` | `string[]` | No | Array of tool names to remove from the agent's tool set. MCP server-level patterns are also accepted: `mcp__server` or `mcp__server__*` removes every tool from that server, and `mcp__*` removes every MCP tool from any server | -| `model` | `string` | No | Model override for this agent. Accepts an alias such as `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, or a full model ID. Defaults to main model if omitted | -| `skills` | `string[]` | No | List of skill names to preload into the agent's context at startup. Unlisted skills remain invocable through the Skill tool | -| `memory` | `'user' \| 'project' \| 'local'` | No | Memory source for this agent | -| `mcpServers` | `(string \| object)[]` | No | MCP servers available to this agent, by name or inline config | -| `initialPrompt` | `string` | No | Auto-submitted as the first user turn when this agent runs as the main thread agent. Ignored when the agent is invoked as a subagent | -| `maxTurns` | `number` | No | Maximum number of agentic turns before the agent stops. When the agent reaches the limit, Claude Code returns its output marked as partial, and you can [resume the agent](#resume-subagents) to continue. The partial marking requires Claude Code v2.1.246 or later | -| `background` | `boolean` | No | Run this agent as a non-blocking background task when invoked | -| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' \| number` | No | Reasoning effort level for this agent | -| `permissionMode` | `PermissionMode` | No | Permission mode for tool execution within this agent | +| Field | Type | Required | Description | +| :---------------- | :---------------------------------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `description` | `string` | Yes | Natural language description of when to use this agent | +| `prompt` | `string` | Yes | The agent's system prompt defining its role and behavior | +| `tools` | `string[]` | No | Array of allowed tool names. If omitted, inherits every [tool available to subagents](/docs/en/sub-agents#available-tools) | +| `disallowedTools` | `string[]` | No | Array of tool names to remove from the agent's tool set. MCP server-level patterns are also accepted: `mcp__server` or `mcp__server__*` removes every tool from that server, and `mcp__*` removes every MCP tool from any server | +| `model` | `string` | No | Model override for this agent. Accepts an alias such as `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, or a full model ID. `'inherit'` uses the main model. If omitted, the agent uses the default subagent model ([`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/en/model-config#environment-variables)) when one is configured, otherwise the main model | +| `skills` | `string[]` | No | List of skill names to preload into the agent's context at startup. Unlisted skills remain invocable through the Skill tool | +| `memory` | `'user' \| 'project' \| 'local'` | No | Memory source for this agent | +| `mcpServers` | `(string \| object)[]` | No | MCP servers available to this agent, by name or inline config | +| `initialPrompt` | `string` | No | Auto-submitted as the first user turn when this agent runs as the main thread agent. Ignored when the agent is invoked as a subagent | +| `maxTurns` | `number` | No | Maximum number of agentic turns before the agent stops. When the agent reaches the limit, Claude Code returns its output marked as partial, and you can [resume the agent](#resume-subagents) to continue. The partial marking requires Claude Code v2.1.246 or later | +| `background` | `boolean` | No | Run this agent as a non-blocking background task when invoked | +| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' \| number` | No | Reasoning effort level for this agent | +| `permissionMode` | `PermissionMode` | No | Permission mode for tool execution within this agent | In the Python SDK, multi-word field names such as `disallowedTools` and `mcpServers` keep their camelCase spelling to match the wire format rather than following Python's snake\_case convention. See the [`AgentDefinition` reference](/docs/en/agent-sdk/python#agentdefinition) for details. diff --git a/content/en/docs/claude-code/agent-sdk/typescript.md b/content/en/docs/claude-code/agent-sdk/typescript.md index ac0b7b81a5..9d657b6d42 100644 --- a/content/en/docs/claude-code/agent-sdk/typescript.md +++ b/content/en/docs/claude-code/agent-sdk/typescript.md @@ -352,9 +352,15 @@ function tagSession( Resolves the effective Claude Code settings for a given directory using the same merge engine as the CLI, without spawning the Claude CLI. Use it to inspect what configuration a `query()` call would see before invoking one. - This function is alpha and its API may change before stabilization. It reads MDM sources, including macOS plist and Windows HKLM/HKCU, for parity with CLI startup, but does not execute the admin-configured `policyHelper` subprocess. The `permissions.defaultMode` field is returned as-is from all tiers including project settings. In a live session, the CLI [ignores `defaultMode: 'auto'` from project and local settings](/docs/en/permission-modes#eliminate-prompts-with-auto-mode); `resolveSettings()` skips that check, so an `auto` from those tiers appears here even though a session would ignore it. + This function is alpha and its API may change before stabilization. +The snapshot differs from what a live `query()` session applies: + +* **`policyHelper`**: `resolveSettings()` reads MDM sources, including macOS plist and Windows HKLM/HKCU, but doesn't execute the admin-configured `policyHelper` subprocess. +* **Server-managed settings**: `resolveSettings()` doesn't fetch [server-managed settings](/docs/en/server-managed-settings#fetch-and-caching-behavior). Pass them as `options.serverManagedSettings` to include them. +* **`defaultMode`**: the snapshot returns `permissions.defaultMode` as-is from every tier. A live session [ignores `defaultMode: 'auto'` from project and local settings](/docs/en/permission-modes#eliminate-prompts-with-auto-mode), so an `auto` from those tiers appears in the snapshot even though a session would ignore it. + ```typescript theme={null} function resolveSettings( options?: ResolveSettingsOptions @@ -365,12 +371,12 @@ function resolveSettings( `resolveSettings()` accepts a single options object. All fields are optional. -| Parameter | Type | Default | Description | -| :------------------------------ | :------------------------------------ | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `options.cwd` | `string` | `process.cwd()` | Directory to resolve project and local settings relative to | -| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | All sources | Which filesystem sources to load. Pass `[]` to skip user, project, and local settings. [Endpoint-managed policy](/docs/en/managed-settings#delivery-mechanisms) loads in all cases. Server-managed settings are taken from `serverManagedSettings` when the host passes it, or read from the CLI's on-disk cache otherwise; the snapshot does not fetch them from the network | -| `options.managedSettings` | `Settings` | `undefined` | Policy-tier settings supplied by the embedding host. Follows the same rules as [`managedSettings` in `Options`](#options), except that `resolveSettings()` doesn't execute a configured [`policyHelper`](/docs/en/settings-reference#policyhelper), so the snapshot can include settings that a live session drops | -| `options.serverManagedSettings` | `Settings` | `undefined` | Server-managed settings payload from `/api/claude_code/settings`. Non-restrictive keys pass through unfiltered | +| Parameter | Type | Default | Description | +| :------------------------------ | :------------------------------------ | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `options.cwd` | `string` | `process.cwd()` | Directory to resolve project and local settings relative to | +| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | All sources | Which filesystem sources to load. Pass `[]` to skip user, project, and local settings. [Endpoint-managed policy](/docs/en/managed-settings#delivery-mechanisms) loads in all cases. `resolveSettings()` includes server-managed settings only when you pass `options.serverManagedSettings` | +| `options.managedSettings` | `Settings` | `undefined` | Policy-tier settings supplied by the embedding host. Follows the same rules as [`managedSettings` in `Options`](#options), except that `resolveSettings()` doesn't execute a configured [`policyHelper`](/docs/en/settings-reference#policyhelper), so the snapshot can include settings that a live session drops | +| `options.serverManagedSettings` | `Settings` | `undefined` | Server-managed settings payload from `/api/claude_code/settings`. Non-restrictive keys pass through unfiltered | #### Return type: `ResolvedSettings` @@ -404,71 +410,71 @@ console.log(`Set by: ${provenance.cleanupPeriodDays?.source}`); Configuration object for the `query()` function. -| Property | Type | Default | Description | -| :-------------------------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `abortController` | `AbortController` | `new AbortController()` | Controller for cancelling operations | -| `additionalDirectories` | `string[]` | `[]` | Additional directories Claude can access. The SDK passes each entry to Claude Code as `--add-dir`, so with the `project` setting source Claude Code also [loads the directory's skills, commands, and subagents](/docs/en/permissions#additional-directories-grant-file-access-not-configuration) | -| `agent` | `string` | `undefined` | Agent name for the main thread. The agent must be defined in the `agents` option or in settings | -| `agents` | `Record` | `undefined` | Programmatically define subagents | -| `agentProgressSummaries` | `boolean` | `false` | When `true`, generate one-line progress summaries for subagents and forward them on [`task_progress`](#sdktaskprogressmessage) events via the `summary` field. Applies to foreground and background subagents | -| `allowDangerouslySkipPermissions` | `boolean` | `false` | Enable bypassing permissions. Required when using `permissionMode: 'bypassPermissions'` | -| `allowedTools` | `string[]` | `[]` | Tools to auto-approve without prompting. This does not restrict Claude to only these tools. If you name one of the [task-tracking tools](/docs/en/agent-sdk/todo-tracking#model-availability) here, Claude Code also opts the session in. Other unlisted tools fall through to `permissionMode` and `canUseTool`. Use `disallowedTools` to block tools. See [Permissions](/docs/en/agent-sdk/permissions#allow-and-deny-rules) | -| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | Enable beta features | -| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | Custom permission function, invoked only when the [permission flow](/docs/en/agent-sdk/permissions#how-permissions-are-evaluated) falls through to a prompt. Not invoked for calls auto-approved by `allowedTools`, allow rules, or `permissionMode`. An allow rule doesn't pre-approve the [actions no mode auto-approves](/docs/en/permission-modes#actions-no-mode-auto-approves). See [`CanUseTool`](#canusetool) for details | -| `continue` | `boolean` | `false` | Continue the most recent conversation | -| `cwd` | `string` | `process.cwd()` | Current working directory | -| `debug` | `boolean` | `false` | Enable debug mode for the Claude Code process | -| `debugFile` | `string` | `undefined` | Write debug logs to a specific file path. Implicitly enables debug mode | -| `disallowedTools` | `string[]` | `[]` | Tools to deny. A bare name such as `"Bash"` removes the tool from Claude's context. A scoped rule such as `"Bash(rm *)"` leaves the tool available and denies matching calls in every permission mode, including `bypassPermissions`. See [Permissions](/docs/en/agent-sdk/permissions#allow-and-deny-rules) | -| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | Model default | Controls how much effort Claude puts into its response. Works with adaptive thinking to guide thinking depth. See [adjust the effort level](/docs/en/model-config#adjust-effort-level) | -| `enableFileCheckpointing` | `boolean` | `false` | Enable file change tracking for rewinding. See [File checkpointing](/docs/en/agent-sdk/file-checkpointing) | -| `env` | `Record` | `process.env` | Environment variables. When set, this replaces the subprocess environment instead of merging with `process.env`, so pass `{ ...process.env, YOUR_VAR: 'value' }` to keep inherited variables like `PATH`. See [Handle slow or stalled API responses](#handle-slow-or-stalled-api-responses) for an example of this pattern, and [Environment variables](/docs/en/env-vars) for variables the underlying CLI reads. Set `CLAUDE_AGENT_SDK_CLIENT_APP` to identify your app in the User-Agent header | -| `executable` | `'bun' \| 'deno' \| 'node'` | Auto-detected | JavaScript runtime to use | -| `executableArgs` | `string[]` | `[]` | Arguments to pass to the executable | -| `extraArgs` | `Record` | `{}` | Additional arguments | -| `fallbackModel` | `string` | `undefined` | Model to use if primary fails | -| `forkSession` | `boolean` | `false` | When resuming with `resume`, fork to a new session ID instead of continuing the original session | -| `forwardSubagentText` | `boolean` | `false` | Forward subagent text and thinking blocks as assistant and user messages with `parent_tool_use_id` set, so consumers can render a nested transcript. By default only `tool_use` and `tool_result` blocks from subagents are emitted. Messages from subagents at every nesting depth are forwarded on Claude Code v2.1.219 and later; before v2.1.219, only messages from depth-1 subagents appeared | -| `hooks` | `Partial>` | `{}` | Hook callbacks for events | -| `includeHookEvents` | `boolean` | `false` | Include hook lifecycle events in the message stream as [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage), and [`SDKHookResponseMessage`](#sdkhookresponsemessage). Lifecycle events for `SessionStart` and `Setup` hooks are always included and don't need this option. Some hook events, such as `Notification`, `SessionEnd`, `PreCompact`, and `PostCompact`, never produce an `SDKHookStartedMessage`, even with this option. For those events, Claude Code still emits an `SDKHookProgressMessage` while a command hook that runs for more than a second produces output, and emits an `SDKHookResponseMessage` only when a hook [that runs in the background](/docs/en/hooks#run-hooks-in-the-background) finishes | -| `includePartialMessages` | `boolean` | `false` | Include partial message events | -| `loadTimeoutMs` | `number` | `60000` | *Alpha.* Timeout in milliseconds for each `sessionStore.load()` and `sessionStore.listSubkeys()` call during resume materialization. If the adapter doesn't settle within this window, the query fails instead of hanging. Ignored when `sessionStore` is not set | -| `managedSettings` | `Settings` | `undefined` | Policy-tier settings your host process supplies to the spawned session. On machines with admin-deployed managed settings, Claude Code ignores these unless the admin's highest-priority managed source sets `parentSettingsBehavior: 'merge'`, and never merges them while a [`policyHelper`](/docs/en/settings-reference#policyhelper) supplies managed settings. Merged values pass through a restrictive-only filter; [Restrict parent settings](/docs/en/claude-apps-gateway#restrict-parent-settings) covers what the filter admits and the `allowManaged*Only` locks. A host that sets [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/en/env-vars) has three keys read straight from this payload instead: its [model configuration](/docs/en/model-config#restrict-model-selection) on Claude Code v2.1.222 or later, [`modelPricing`](/docs/en/settings-reference#modelpricing) when no managed source sets it on v2.1.246 or later, and its `ENABLE_TOOL_SEARCH` env entry on v2.1.247 or later | -| `maxBudgetUsd` | `number` | `undefined` | Stop the query when the client-side cost estimate reaches this USD value. Compared against the same estimate as `total_cost_usd`; see [Track cost and usage](/docs/en/agent-sdk/cost-tracking) for accuracy caveats | -| `maxThinkingTokens` | `number` | `undefined` | *Deprecated:* Use `thinking` instead. Maximum tokens for thinking process | -| `maxTurns` | `number` | `undefined` | Maximum agentic turns (tool-use round trips) | -| `mcpServers` | `Record` | `{}` | MCP server configurations | -| `model` | `string` | Default from CLI | Claude model alias or full model name. See [accepted values and provider-specific IDs](/docs/en/model-config#available-models) | -| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise` | `undefined` | Callback for handling MCP elicitation requests. Called when an MCP server requests user input and no hook handles it first. When not provided, unhandled elicitation requests are declined automatically | -| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Define output format for agent results. See [Structured outputs](/docs/en/agent-sdk/structured-outputs) for details | -| `outputStyle` | `string` | `undefined` | Not an `Options` field. Set `outputStyle` in the inline [`settings`](/docs/en/settings) object or a settings file instead. See [Activate an output style](/docs/en/agent-sdk/modifying-system-prompts#activate-an-output-style) | -| `pathToClaudeCodeExecutable` | `string` | Auto-resolved from bundled native binary | Path to Claude Code executable. Only needed if optional dependencies were skipped during install or your platform isn't in the supported set | -| `permissionMode` | [`PermissionMode`](#permissionmode) | `'default'` | Permission mode for the session | -| `permissionPromptToolName` | `string` | `undefined` | MCP tool name for permission prompts | -| `persistSession` | `boolean` | `true` | When `false`, disables session persistence to disk. Sessions cannot be resumed later | -| `planModeInstructions` | `string` | `undefined` | Custom workflow instructions for plan mode. When `permissionMode` is `'plan'`, this string replaces the default plan-mode workflow body. The CLI still wraps it with the read-only enforcement preamble and the ExitPlanMode protocol footer | -| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | Load custom plugins from local paths. See [Plugins](/docs/en/agent-sdk/plugins) for details | -| `promptSuggestions` | `boolean` | `false` | Enable prompt suggestions. After a turn, Claude Code emits a `prompt_suggestion` message carrying a predicted next user prompt. Claude Code generates no suggestion for some turns, such as while your account is close to or at its usage limit. See [When Claude Code skips suggestions](/docs/en/interactive-mode#when-claude-code-skips-suggestions) | -| `resume` | `string` | `undefined` | Session ID to resume | -| `resumeDropsTurn` | `string` | `undefined` | With `resumeSessionAt`: the prompt UUID of the turn the truncating resume intends to discard. Claude Code refuses the resume when the discarded range contains anything not attributable to that turn, such as absorbed queued messages or task notifications, and names the `--resume-drops-turn` flag in the rejection message. Only the Agent SDK and print-mode resumes read the pair. Requires Claude Code v2.1.223 or later | -| `resumeSessionAt` | `string` | `undefined` | Resume session at a specific message UUID | -| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | Configure sandbox behavior programmatically. See [Sandbox settings](#sandboxsettings) for details | -| `sessionId` | `string` | Auto-generated | Use a specific UUID for the session instead of auto-generating one | -| `sessionStore` | [`SessionStore`](/docs/en/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Mirror session transcripts to an external backend so another host can resume them. See [Persist sessions to external storage](/docs/en/agent-sdk/session-storage) | -| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *Alpha.* Flush mode for `sessionStore`. Ignored when `sessionStore` is not set | -| `settings` | `string \| Settings` | `undefined` | Inline [settings](/docs/en/settings) object or path to a settings file. Populates the flag-settings layer in the [precedence order](/docs/en/settings#settings-precedence). Change at runtime with [`applyFlagSettings()`](#applyflagsettings) | -| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI defaults (all sources) | Control which filesystem settings to load. Pass `[]` to disable user, project, and local settings. [Endpoint-managed policy](/docs/en/managed-settings#delivery-mechanisms) loads regardless; server-managed settings are fetched when the session authenticates with an organization credential on an [eligible configuration](/docs/en/server-managed-settings#platform-availability). See [Use Claude Code features](/docs/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) | -| `skills` | `string[] \| 'all'` | `undefined` | Skills available to the session. Pass `'all'` to enable every discovered skill, or a list of skill names. Pass exact names only. On Agent SDK v0.3.221 or later, the SDK rejects malformed and wildcard-form names with an error before starting the Claude Code process. When set, the SDK adds the Skill tool to `allowedTools` automatically. If you also pass `tools`, include `'Skill'` in that list. See [Skills](/docs/en/agent-sdk/skills) | -| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Custom function to spawn the Claude Code process. Use to run Claude Code in VMs, containers, or remote environments | -| `stderr` | `(data: string) => void` | `undefined` | Callback for stderr output | -| `strictMcpConfig` | `boolean` | `false` | Use only the servers passed in `mcpServers` and ignore project `.mcp.json`, user settings, plugin-provided MCP servers, and [claude.ai connectors](/docs/en/mcp#use-mcp-servers-from-claude-ai) | -| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (minimal prompt) | System prompt configuration. Pass a string for custom prompt, or `{ type: 'preset', preset: 'claude_code' }` to use Claude Code's system prompt. When using the preset object form, add `append` to extend it with additional instructions, and set `excludeDynamicSections: true` to move per-session context into the first user message for [better prompt-cache reuse across machines](/docs/en/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) | -| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* API-side task budget in tokens. When set, the model is told its remaining token budget so it can pace tool use and wrap up before the limit | -| `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` for supported models | Controls Claude's thinking/reasoning behavior. See [`ThinkingConfig`](#thinkingconfig) for options | -| `title` | `string` | `undefined` | Display title for the session. When resuming via `resume` or `continue`, the resumed session's persisted title takes precedence; use [`renameSession()`](#renamesession) to retitle an existing session | -| `toolAliases` | `Record` | `undefined` | Map built-in tool names to MCP tool names so Claude calls your MCP implementation in place of the built-in. For example, `{ Bash: 'mcp__workspace__bash' }` | -| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | Configuration for built-in tool behavior. See [`ToolConfig`](#toolconfig) for details | -| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Tool configuration. Pass an array of tool names or use the preset to get Claude Code's default tools | +| Property | Type | Default | Description | +| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `abortController` | `AbortController` | `new AbortController()` | Controller for cancelling operations | +| `additionalDirectories` | `string[]` | `[]` | Additional directories Claude can access. The SDK passes each entry to Claude Code as `--add-dir`, so with the `project` setting source Claude Code also [loads the directory's skills, commands, and subagents](/docs/en/permissions#additional-directories-grant-file-access-not-configuration) | +| `agent` | `string` | `undefined` | Agent name for the main thread. The agent must be defined in the `agents` option or in settings | +| `agents` | `Record` | `undefined` | Programmatically define subagents | +| `agentProgressSummaries` | `boolean` | `false` | When `true`, generate one-line progress summaries for subagents and forward them on [`task_progress`](#sdktaskprogressmessage) events via the `summary` field. Applies to foreground and background subagents | +| `allowDangerouslySkipPermissions` | `boolean` | `false` | Enable bypassing permissions. Required when using `permissionMode: 'bypassPermissions'` | +| `allowedTools` | `string[]` | `[]` | Tools to auto-approve without prompting. This does not restrict Claude to only these tools. If you name one of the [task-tracking tools](/docs/en/agent-sdk/todo-tracking#model-availability) here, Claude Code also opts the session in. Other unlisted tools fall through to `permissionMode` and `canUseTool`. Use `disallowedTools` to block tools. See [Permissions](/docs/en/agent-sdk/permissions#allow-and-deny-rules) | +| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | Enable beta features | +| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | Custom permission function, invoked only when the [permission flow](/docs/en/agent-sdk/permissions#how-permissions-are-evaluated) falls through to a prompt. Not invoked for calls auto-approved by `allowedTools`, allow rules, or `permissionMode`. An allow rule doesn't pre-approve the [actions no mode auto-approves](/docs/en/permission-modes#actions-no-mode-auto-approves). See [`CanUseTool`](#canusetool) for details | +| `continue` | `boolean` | `false` | Continue the most recent conversation | +| `cwd` | `string` | `process.cwd()` | Current working directory | +| `debug` | `boolean` | `false` | Enable debug mode for the Claude Code process | +| `debugFile` | `string` | `undefined` | Write debug logs to a specific file path. Implicitly enables debug mode | +| `disallowedTools` | `string[]` | `[]` | Tools to deny. A bare name such as `"Bash"` removes the tool from Claude's context. A scoped rule such as `"Bash(rm *)"` leaves the tool available and denies matching calls in every permission mode, including `bypassPermissions`. See [Permissions](/docs/en/agent-sdk/permissions#allow-and-deny-rules) | +| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | Model default | Controls how much effort Claude puts into its response. Works with adaptive thinking to guide thinking depth. See [adjust the effort level](/docs/en/model-config#adjust-effort-level) | +| `enableFileCheckpointing` | `boolean` | `false` | Enable file change tracking for rewinding. See [File checkpointing](/docs/en/agent-sdk/file-checkpointing) | +| `env` | `Record` | `process.env` | Environment variables. When set, this replaces the subprocess environment instead of merging with `process.env`, so pass `{ ...process.env, YOUR_VAR: 'value' }` to keep inherited variables like `PATH`. See [Handle slow or stalled API responses](#handle-slow-or-stalled-api-responses) for an example of this pattern, and [Environment variables](/docs/en/env-vars) for variables the underlying CLI reads. Set `CLAUDE_AGENT_SDK_CLIENT_APP` to identify your app in the User-Agent header | +| `executable` | `'bun' \| 'deno' \| 'node'` | Auto-detected | JavaScript runtime to use | +| `executableArgs` | `string[]` | `[]` | Arguments to pass to the executable | +| `extraArgs` | `Record` | `{}` | Additional arguments | +| `fallbackModel` | `string` | `undefined` | Model to use if primary fails | +| `forkSession` | `boolean` | `false` | When resuming with `resume`, fork to a new session ID instead of continuing the original session | +| `forwardSubagentText` | `boolean` | `false` | Forward subagent text and thinking blocks as assistant and user messages with `parent_tool_use_id` set, so consumers can render a nested transcript. By default only `tool_use` and `tool_result` blocks from subagents are emitted. Messages from subagents at every nesting depth are forwarded on Claude Code v2.1.219 and later; before v2.1.219, only messages from depth-1 subagents appeared | +| `hooks` | `Partial>` | `{}` | Hook callbacks for events | +| `includeHookEvents` | `boolean` | `false` | Include hook lifecycle events in the message stream as [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage), and [`SDKHookResponseMessage`](#sdkhookresponsemessage). Lifecycle events for `SessionStart` and `Setup` hooks are always included and don't need this option. Some hook events, such as `Notification`, `SessionEnd`, `PreCompact`, and `PostCompact`, never produce an `SDKHookStartedMessage`, even with this option. For those events, Claude Code still emits an `SDKHookProgressMessage` while a command hook that runs for more than a second produces output, and emits an `SDKHookResponseMessage` only when a hook [that runs in the background](/docs/en/hooks#run-hooks-in-the-background) finishes | +| `includePartialMessages` | `boolean` | `false` | Include partial message events | +| `loadTimeoutMs` | `number` | `60000` | *Alpha.* Timeout in milliseconds for each `sessionStore.load()` and `sessionStore.listSubkeys()` call during resume materialization. If the adapter doesn't settle within this window, the query fails instead of hanging. Ignored when `sessionStore` is not set | +| `managedSettings` | `Settings` | `undefined` | Policy-tier settings your host process supplies to the spawned session. On machines with admin-deployed managed settings, Claude Code ignores these unless the admin's highest-priority managed source sets `parentSettingsBehavior: 'merge'`, and never merges them while a [`policyHelper`](/docs/en/settings-reference#policyhelper) supplies managed settings. Merged values pass through a restrictive-only filter; [Restrict parent settings](/docs/en/claude-apps-gateway#restrict-parent-settings) covers what the filter admits and the `allowManaged*Only` locks. A host that sets [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/en/env-vars) has three keys read straight from this payload instead: its [model configuration](/docs/en/model-config#restrict-model-selection) on Claude Code v2.1.222 or later, [`modelPricing`](/docs/en/settings-reference#modelpricing) when no managed source sets it on v2.1.246 or later, and its `ENABLE_TOOL_SEARCH` env entry on v2.1.247 or later | +| `maxBudgetUsd` | `number` | `undefined` | Stop the query when the client-side cost estimate reaches this USD value. Compared against the same estimate as `total_cost_usd`; see [Track cost and usage](/docs/en/agent-sdk/cost-tracking) for accuracy caveats | +| `maxThinkingTokens` | `number` | `undefined` | *Deprecated:* Use `thinking` instead. Maximum tokens for thinking process | +| `maxTurns` | `number` | `undefined` | Maximum agentic turns (tool-use round trips) | +| `mcpServers` | `Record` | `{}` | MCP server configurations | +| `model` | `string` | Default from CLI | Claude model alias or full model name. See [accepted values and provider-specific IDs](/docs/en/model-config#available-models) | +| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise` | `undefined` | Callback for handling MCP elicitation requests. Called when an MCP server requests user input and no hook handles it first. When not provided, unhandled elicitation requests are declined automatically | +| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Define output format for agent results. See [Structured outputs](/docs/en/agent-sdk/structured-outputs) for details | +| `outputStyle` | `string` | `undefined` | Not an `Options` field. Set `outputStyle` in the inline [`settings`](/docs/en/settings) object or a settings file instead. See [Activate an output style](/docs/en/agent-sdk/modifying-system-prompts#activate-an-output-style) | +| `pathToClaudeCodeExecutable` | `string` | Auto-resolved from bundled native binary | Path to Claude Code executable. Only needed if optional dependencies were skipped during install or your platform isn't in the supported set | +| `permissionMode` | [`PermissionMode`](#permissionmode) | `'default'` | Permission mode for the session | +| `permissionPromptToolName` | `string` | `undefined` | MCP tool name for permission prompts | +| `persistSession` | `boolean` | `true` | When `false`, disables session persistence to disk. Sessions cannot be resumed later | +| `planModeInstructions` | `string` | `undefined` | Custom workflow instructions for plan mode. When `permissionMode` is `'plan'`, this string replaces the default plan-mode workflow body. The CLI still wraps it with the read-only enforcement preamble and the ExitPlanMode protocol footer | +| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | Load custom plugins from local paths. See [Plugins](/docs/en/agent-sdk/plugins) for details | +| `promptSuggestions` | `boolean` | `false` | Enable prompt suggestions. After a turn, Claude Code emits a `prompt_suggestion` message carrying a predicted next user prompt. Claude Code generates no suggestion for some turns, such as while your account is close to or at its usage limit. See [When Claude Code skips suggestions](/docs/en/interactive-mode#when-claude-code-skips-suggestions) | +| `resume` | `string` | `undefined` | Session ID to resume | +| `resumeDropsTurn` | `string` | `undefined` | With `resumeSessionAt`: the prompt UUID of the turn the truncating resume intends to discard. Claude Code refuses the resume when the discarded range contains anything not attributable to that turn, such as absorbed queued messages or task notifications, and names the `--resume-drops-turn` flag in the rejection message. Only the Agent SDK and print-mode resumes read the pair. Requires Claude Code v2.1.223 or later | +| `resumeSessionAt` | `string` | `undefined` | Resume session at a specific message UUID | +| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | Configure sandbox behavior programmatically. See [Sandbox settings](#sandboxsettings) for details | +| `sessionId` | `string` | Auto-generated | Use a specific UUID for the session instead of auto-generating one | +| `sessionStore` | [`SessionStore`](/docs/en/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Mirror session transcripts to an external backend so another host can resume them. See [Persist sessions to external storage](/docs/en/agent-sdk/session-storage) | +| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *Alpha.* Flush mode for `sessionStore`. Ignored when `sessionStore` is not set | +| `settings` | `string \| Settings` | `undefined` | Inline [settings](/docs/en/settings) object or path to a settings file. Populates the flag-settings layer in the [precedence order](/docs/en/settings#settings-precedence). Change at runtime with [`applyFlagSettings()`](#applyflagsettings) | +| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI defaults (all sources) | Control which filesystem settings to load. Pass `[]` to disable user, project, and local settings. [Endpoint-managed policy](/docs/en/managed-settings#delivery-mechanisms) loads regardless; server-managed settings are fetched when the session authenticates with an organization credential on an [eligible configuration](/docs/en/server-managed-settings#platform-availability). See [Use Claude Code features](/docs/en/agent-sdk/claude-code-features#what-settingsources-does-not-control) | +| `skills` | `string[] \| 'all'` | `undefined` | Skills available to the session. Pass `'all'` to enable every discovered skill, or a list of skill names. Pass exact names only. On Agent SDK v0.3.221 or later, the SDK rejects malformed and wildcard-form names with an error before starting the Claude Code process. When set, the SDK adds the Skill tool to `allowedTools` automatically. If you also pass `tools`, include `'Skill'` in that list. See [Skills](/docs/en/agent-sdk/skills) | +| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Custom function to spawn the Claude Code process. Use to run Claude Code in VMs, containers, or remote environments | +| `stderr` | `(data: string) => void` | `undefined` | Callback for stderr output | +| `strictMcpConfig` | `boolean` | `false` | Use only the servers passed in `mcpServers` and ignore project `.mcp.json`, user settings, plugin-provided MCP servers, and [claude.ai connectors](/docs/en/mcp#use-mcp-servers-from-claude-ai) | +| `systemPrompt` | `string \| string[] \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (minimal prompt) | System prompt configuration. Pass a string for a custom prompt, or `{ type: 'preset', preset: 'claude_code' }` to use Claude Code's system prompt. Pass an array of strings with the exported `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` constant between the static and per-request parts to [cache the static part of a custom prompt](/docs/en/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt). When using the preset object form, add `append` to extend it with additional instructions, and set `excludeDynamicSections: true` to move per-session context into the first user message for [better prompt-cache reuse across machines](/docs/en/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) | +| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* API-side task budget in tokens. When set, the model is told its remaining token budget so it can pace tool use and wrap up before the limit | +| `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` for supported models | Controls Claude's thinking/reasoning behavior. See [`ThinkingConfig`](#thinkingconfig) for options | +| `title` | `string` | `undefined` | Display title for the session. When resuming via `resume` or `continue`, the resumed session's persisted title takes precedence; use [`renameSession()`](#renamesession) to retitle an existing session | +| `toolAliases` | `Record` | `undefined` | Map built-in tool names to MCP tool names so Claude calls your MCP implementation in place of the built-in. For example, `{ Bash: 'mcp__workspace__bash' }` | +| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | Configuration for built-in tool behavior. See [`ToolConfig`](#toolconfig) for details | +| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Tool configuration. Pass an array of tool names or use the preset to get Claude Code's default tools | #### Handle slow or stalled API responses @@ -838,22 +844,22 @@ type AgentDefinition = { }; ``` -| Field | Required | Description | -| :------------------------------------ | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `description` | Yes | Natural language description of when to use this agent | -| `tools` | No | Array of allowed tool names. If omitted, inherits every [tool available to subagents](/docs/en/sub-agents#available-tools). To preload Skills into the agent's context, use the `skills` field rather than listing `'Skill'` here | -| `disallowedTools` | No | Array of tool names to explicitly disallow for this agent. MCP server-level patterns are also accepted: `mcp__server` or `mcp__server__*` removes every tool from that server, and `mcp__*` removes every MCP tool from any server | -| `prompt` | Yes | The agent's system prompt | -| `model` | No | Model override for this agent. Accepts an alias such as `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, or a full model ID. If omitted or `'inherit'`, uses the main model | -| `mcpServers` | No | MCP server specifications for this agent | -| `skills` | No | Array of skill names to preload into the agent context | -| `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main thread agent | -| `maxTurns` | No | Maximum number of agentic turns (API round-trips) before stopping | -| `background` | No | Run this agent as a non-blocking background task when invoked | -| `memory` | No | Memory source for this agent: `'user'`, `'project'`, or `'local'` | -| `effort` | No | Reasoning effort level for this agent. Accepts a named level or an integer | -| `permissionMode` | No | Permission mode for tool execution within this agent. See [`PermissionMode`](#permissionmode) | -| `criticalSystemReminder_EXPERIMENTAL` | No | Experimental: Critical reminder added to the system prompt | +| Field | Required | Description | +| :------------------------------------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `description` | Yes | Natural language description of when to use this agent | +| `tools` | No | Array of allowed tool names. If omitted, inherits every [tool available to subagents](/docs/en/sub-agents#available-tools). To preload Skills into the agent's context, use the `skills` field rather than listing `'Skill'` here | +| `disallowedTools` | No | Array of tool names to explicitly disallow for this agent. MCP server-level patterns are also accepted: `mcp__server` or `mcp__server__*` removes every tool from that server, and `mcp__*` removes every MCP tool from any server | +| `prompt` | Yes | The agent's system prompt | +| `model` | No | Model override for this agent. Accepts an alias such as `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, or a full model ID. `'inherit'` uses the main model. If omitted, the agent uses the default subagent model ([`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/en/model-config#environment-variables)) when one is configured, otherwise the main model | +| `mcpServers` | No | MCP server specifications for this agent | +| `skills` | No | Array of skill names to preload into the agent context | +| `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main thread agent | +| `maxTurns` | No | Maximum number of agentic turns (API round-trips) before stopping | +| `background` | No | Run this agent as a non-blocking background task when invoked | +| `memory` | No | Memory source for this agent: `'user'`, `'project'`, or `'local'` | +| `effort` | No | Reasoning effort level for this agent. Accepts a named level or an integer | +| `permissionMode` | No | Permission mode for tool execution within this agent. See [`PermissionMode`](#permissionmode) | +| `criticalSystemReminder_EXPERIMENTAL` | No | Experimental: Critical reminder added to the system prompt | ### `AgentMcpServerSpec` @@ -4340,11 +4346,11 @@ type AgentInfo = { }; ``` -| Field | Type | Description | -| :------------ | :-------------------- | :------------------------------------------------------------------- | -| `name` | `string` | Agent type identifier (e.g., `"Explore"`, `"general-purpose"`) | -| `description` | `string` | Description of when to use this agent | -| `model` | `string \| undefined` | Model alias this agent uses. If omitted, inherits the parent's model | +| Field | Type | Description | +| :------------ | :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | `string` | Agent type identifier (e.g., `"Explore"`, `"general-purpose"`) | +| `description` | `string` | Description of when to use this agent | +| `model` | `string \| undefined` | Model this agent uses: an alias or model ID, or `'inherit'` for the parent's model. If omitted, the agent uses the default subagent model ([`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/en/model-config#environment-variables)) when one is configured, otherwise the parent's model | ### `McpServerStatus` diff --git a/content/en/docs/claude-code/agent-teams.md b/content/en/docs/claude-code/agent-teams.md index 72970a3581..5aab9862f7 100644 --- a/content/en/docs/claude-code/agent-teams.md +++ b/content/en/docs/claude-code/agent-teams.md @@ -144,19 +144,21 @@ each teammate. Claude Code picks each teammate's model from the first of these that applies: -1. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/en/model-config#environment-variables), when it's set to anything other than `inherit`. -2. The model your spawn prompt names for that teammate. -3. For an in-process teammate spawned from a [subagent definition](#use-subagent-definitions-for-teammates), the definition's `model`. +1. The model your spawn prompt names for that teammate. +2. For a teammate spawned from a [subagent definition](#use-subagent-definitions-for-teammates), the definition's `model`, where `inherit` selects the lead's model. +3. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/en/model-config#environment-variables), when it's set to anything other than `inherit`. 4. The lead's current model. +Before v2.1.251, `CLAUDE_CODE_SUBAGENT_MODEL` came first in this order. + `teammateDefaultModel` was removed in v2.1.234; Claude Code ignores a leftover value. Name the model in your prompt or set `CLAUDE_CODE_SUBAGENT_MODEL` instead. -Claude Code checks the model your prompt requests for a teammate, or the one `CLAUDE_CODE_SUBAGENT_MODEL` supplies, against your organization's [`availableModels`](/docs/en/model-config#restrict-model-selection) allowlist. When the allowlist blocks a value, Claude Code substitutes another model: +Claude Code checks the model it selects for a teammate against your organization's [`availableModels`](/docs/en/model-config#restrict-model-selection) allowlist. When the allowlist blocks a value, Claude Code substitutes another model: * **Family alias such as `opus`**: On the Anthropic API and Claude Platform on AWS, Claude Code runs the teammate on the newest version of that family the allowlist permits. On providers with provider-specific model IDs, where the [substitution doesn't operate](/docs/en/model-config#restrict-model-selection), a blocked alias falls back like any other blocked value per the next bullet -* **Any other blocked value, including a family alias on providers where the substitution doesn't operate or whose family has no permitted version**: Claude Code runs the teammate on the lead's model +* **Any other blocked value, including a family alias on providers where the substitution doesn't operate, or one whose family has no permitted version**: Claude Code runs the teammate on the lead's model instead. If you set `CLAUDE_CODE_SUBAGENT_MODEL`, Claude Code tries that model first, under these same rules Teammates inherit the lead's [effort level](/docs/en/model-config#adjust-effort-level). In split-pane mode this applies from v2.1.186; earlier versions did not pass the lead's session effort to split-pane teammates. @@ -269,7 +271,7 @@ Spawn a teammate using the security-reviewer agent type to audit the auth module Claude Code reads the subagent definition you named and applies these parts of it to the teammate. Where a part depends on the teammate's [display mode](#choose-a-display-mode), the entry says so: * **`tools`**: Claude Code limits the teammate to the tools in the definition's `tools` list. For an in-process teammate, Claude Code adds `SendMessage` to that list, and in a [session that has the Task tools](/docs/en/tools-reference#task-tool-availability) it adds `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate` too. -* **`model`**: for an in-process teammate, Claude Code uses the definition's `model` when neither `CLAUDE_CODE_SUBAGENT_MODEL` nor your spawn prompt names a model. A split-pane teammate doesn't use the definition's `model`. See [how Claude Code picks a teammate's model](#specify-teammates-and-models). +* **`model`**: Claude Code uses the definition's `model` in either display mode when your spawn prompt doesn't name one. See [how Claude Code picks a teammate's model](#specify-teammates-and-models). * **Body**: for an in-process teammate, Claude Code appends the definition's body to its default system prompt as additional instructions. For a split-pane teammate, Claude Code uses the body in place of its default system prompt. * **`skills`**: Claude Code doesn't apply the definition's `skills` to a teammate in either display mode. The teammate loads skills from your project and user settings. * **`mcpServers`**: for a split-pane teammate, Claude Code applies the definition's `mcpServers` under the [rules for that field](/docs/en/sub-agents#scope-mcp-servers-to-a-subagent), which cover a session started with `--agent` as well. An in-process teammate ignores the field and loads MCP servers from your project and user settings. diff --git a/content/en/docs/claude-code/agent-view.md b/content/en/docs/claude-code/agent-view.md index 48e13ff4ff..efac499e3a 100644 --- a/content/en/docs/claude-code/agent-view.md +++ b/content/en/docs/claude-code/agent-view.md @@ -320,7 +320,7 @@ The automatic name is a short label written by a [Haiku-class model](/docs/en/mo Paste an image into the prompt to include a screenshot or diagram with the task. -Pasted text longer than 800 characters or more than two lines collapses to a `[Pasted text #N]` placeholder so the input stays on one line; the full text is sent when you dispatch. To review or edit the collapsed text before dispatching, paste the same text again and the placeholder expands back into the input. +Pasted text longer than 800 characters or more than three lines collapses to a `[Pasted text #N]` placeholder so the input stays on one line; the full text is sent when you dispatch. To review or edit the collapsed text before dispatching, paste the same text again and the placeholder expands back into the input. Prefix or mention parts of the prompt to control how the session starts: @@ -596,7 +596,7 @@ Claude Code refuses `claude --bg --permission-mode bypassPermissions` until you' The permission mode, model, and effort you chose for a background session, along with the [configuration flags it carries](#what-carries-over-when-you-background), all persist when the supervisor later [stops and restarts](#the-supervisor-process) its process. A session you launched with `claude --bg --dangerously-skip-permissions` or `claude --bg --permission-mode bypassPermissions` stays in `bypassPermissions` after that restart. A model or effort you changed mid-session with `/model` or `/effort` is kept too. -If the session took its effort from the [`effortLevel` setting](/docs/en/settings-reference#effortlevel) rather than from `--effort` or `/effort`, Claude Code reads the setting again each time it starts a process for the session. So when you edit `effortLevel` in `settings.json`, the change reaches sessions you background with `←` or `/bg`, and their later restarts. +If the session took its effort from your settings rather than from `--effort` or `/effort`, Claude Code reads your settings again each time it starts a process for the session. So when you edit the saved effort in `settings.json`, the change reaches sessions you background with `←` or `/bg`, and their later restarts. The saved effort is the [`effortLevel`](/docs/en/settings-reference#effortlevel) key or a [`modelSettings`](/docs/en/settings-reference#modelsettings) entry. Claude Code also keeps a name you set with [`/rename`](/docs/en/commands) or `Ctrl+R` across that restart, so you can still run [`claude --resume `](/docs/en/sessions#name-your-sessions) to reach the session. diff --git a/content/en/docs/claude-code/artifacts.md b/content/en/docs/claude-code/artifacts.md index 23c29856a4..2bd73df2eb 100644 --- a/content/en/docs/claude-code/artifacts.md +++ b/content/en/docs/claude-code/artifacts.md @@ -105,8 +105,10 @@ An editor publishes new versions the same way you [update the artifact from anot When you share an artifact within your organization, the people you share it with can leave comments on the page, and you can have Claude read those comments and reply to them. You need Claude Code v2.1.221 or later and a Team or Enterprise plan, because only an artifact you [share within your organization](#share-an-artifact) takes comments. Claude reads the comments in two cases: -* **You ask Claude to read them**: give Claude the artifact's URL and ask for the comments. Claude lists each thread and marks the comments a commenter sent to it. -* **A commenter sends a comment to Claude**: in a thread on the page, the commenter mentions `@claude` or uses the thread's Claude control, where the page offers one. Either gesture activates the thread, and Claude can reply only in a thread someone activated. Viewers see each reply attributed to Claude, via you. +* **You ask Claude to read them**: give Claude the artifact's URL and ask for the comments. Claude lists each thread and marks the comments someone who can edit the artifact sent to it. +* **Someone who can edit the artifact sends a comment to Claude**: in a thread on the page, they send a comment with **Send to Claude**, or mention `@claude` in one. Either way, they activate the thread. + +Claude can reply to or resolve only an activated thread. Other threads stay open until a person resolves them on the page. Viewers see each reply attributed to Claude, via you. If you share an artifact publicly, viewers can't comment on it: the page says `Comments aren't available while this Artifact is shared publicly.` To switch an artifact that already has comment threads to a public link, delete the threads first. @@ -124,7 +126,11 @@ If Claude tells you it can't read comments, check three things: ### Let Claude reply to comments on its own -After your session publishes an artifact, Claude Code watches that artifact for comments for as long as the session runs. When a commenter sends a comment to Claude, it reaches your session right away, and Claude can read the thread and reply without you asking. You need Claude Code v2.1.228 or later. If you turned [feature-flag fetching](/docs/en/env-vars#features-that-need-feature-flag-fetching) off, Claude Code doesn't watch for comments. Your [permission mode](/docs/en/permission-modes) decides what Claude does when a sent comment arrives: +After your session publishes an artifact, Claude Code watches that artifact for comments for as long as the session runs. When someone who can edit the artifact sends a comment to Claude, it reaches your session right away, and Claude can read the thread and reply without you asking. + +You need Claude Code v2.1.228 or later. If you turned [feature-flag fetching](/docs/en/env-vars#features-that-need-feature-flag-fetching) off, Claude Code doesn't watch for comments. + +Your [permission mode](/docs/en/permission-modes) decides what Claude does when a sent comment arrives: * **Claude replies on its own**: when your permission mode lets Claude post the reply without asking you, Claude reads the thread and replies, and edits the artifact when the comment asks for a change. You see `Auto-replied to comment thread on Artifact: ` or `Auto-edited Artifact: in response to a comment thread`. * **Claude waits for you**: outside plan mode, when posting the reply would need your approval, you see `Comments are waiting on Artifact: `. Claude then asks you for approval to read the thread, and again to post the reply. @@ -132,11 +138,13 @@ After your session publishes an artifact, Claude Code watches that artifact for Claude also stops replying on its own to an artifact after it handles 60 sent comments or thread activations on that artifact within an hour. You see `Comments are waiting on Artifact: ` once, and Claude picks up again as that hour's comments age out. -Run `/tasks` to see each artifact your session is watching, listed as a live-updates task. You can stop Claude from replying on its own in three ways, and each one lasts a different length of time: +Run `/tasks` to see each artifact your session is watching, listed as a live-updates task. You can stop Claude from replying on its own in any of these ways: -* **Press Ctrl+C once**: Claude stops replying on every artifact your session is watching, and starts again on an artifact when you have your session publish it again. -* **Stop the task in `/tasks`**: Claude stops replying on that artifact for the rest of the session. Publishing it again doesn't start replies again, and if you resume the session later, Claude still doesn't reply there. -* **Press `Ctrl+X Ctrl+K` twice within 3 seconds**: the chord that [stops every running background subagent](/docs/en/interactive-mode#general-controls) also stops Claude from replying on every artifact for the rest of the session. +* **Press Ctrl+C once at an idle prompt**: Claude pauses replying on every artifact your session is watching. Replies start again after you send your next message. +* **Stop the task in `/tasks`**: Claude stops replying on that artifact until you ask it to resume replies there. Publishing the artifact again doesn't start replies again, and the stop still applies when you resume the session later. +* **Press `Ctrl+X Ctrl+K` twice within 3 seconds**: the chord that [stops every running background subagent](/docs/en/interactive-mode#general-controls) also stops Claude from replying on every artifact for the rest of the session. Asking Claude to resume replies doesn't undo this stop. + +If the service that delivers comments becomes unavailable or stops answering, Claude Code keeps trying to reconnect for a while, then stops watching each artifact your session was watching. ## Pull live data with MCP connectors @@ -232,6 +240,18 @@ Claude treats your design system as higher precedence than its own choices, and For typography, Claude can load a typeface from Google Fonts, the one external font source an artifact page can load from. Claude inlines any other typeface as a `@font-face` data URI and gives every typeface a fallback stack, so the page still renders if a font doesn't load. To use a specific typeface, name it in your prompt or your design system. +## Draft a design canvas + +To mock up a UI, a screen flow, a landing page, or a poster rather than build a page, run `/design` with a brief. Claude drafts the design as artboards on one canvas and publishes the canvas as an artifact that runs a research preview of Claude Design's editor. The brief names what you want drawn: + +```text wrap theme={null} +/design a settings screen for a mobile banking app +``` + +Open the published artifact to review the artboards. Where saving is enabled for your account, select an element on an artboard, change it, and save to publish a new version; otherwise you view the draft and export it as PNG or PDF. + +`/design` requires a session where [artifacts are available](#availability) and Claude Code v2.1.234 or later. + ## Page constraints Each artifact is one self-contained page. Claude Code wraps the file you publish in an HTML document shell and serves it under a strict Content Security Policy (CSP), which shapes what the page can do. diff --git a/content/en/docs/claude-code/authentication.md b/content/en/docs/claude-code/authentication.md index 84db6388d5..c75821d4f1 100644 --- a/content/en/docs/claude-code/authentication.md +++ b/content/en/docs/claude-code/authentication.md @@ -22,7 +22,7 @@ You can authenticate with any of these account types: * **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). * **Claude for Teams or Enterprise**: log in with the Claude.ai account your team admin invited you to. -* **Claude Console**: log in with your Console credentials. Your admin must have [invited you](#claude-console-authentication) first. +* **Claude Console**: log in with your Console credentials. Your admin must have [invited you](#claude-console-authentication) first. You can sign in with or without [creating an API key](#sign-in-without-an-api-key). * **Cloud providers**: if your organization uses [Amazon Bedrock](/docs/en/amazon-bedrock), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai), or [Microsoft Foundry](/docs/en/microsoft-foundry), set the required environment variables before running `claude`, or select **3rd-party platform** at the login prompt, which launches an interactive setup wizard for Bedrock and Vertex AI. No browser login is needed. * **Cloud gateway**: if your organization runs a self-hosted [Claude apps gateway](/docs/en/claude-apps-gateway), sign in with corporate SSO through `/login`. The gateway-issued token is the session's only credential. @@ -97,6 +97,31 @@ For organizations that prefer API-based billing, you can set up access through t +#### Sign in without an API key + +You can sign in to your Console account without creating an API key, even when your organization doesn't let developers create them. Choose the Anthropic Console account at the `/login` prompt and Claude Code asks how you want to sign in. Requires Claude Code v2.1.242 or later. Both routes sign you in to Console in the browser and differ in what Claude Code stores afterwards: + +* **Sign in with your Console account**, labeled `(recommended)`: Claude Code keeps the OAuth token from that sign-in and stores it as an [Anthropic profile](#anthropic-profiles-and-federation-credentials). It creates no API key +* **Create an API key**, labeled `(legacy)`: Claude Code creates a Console API key for you and stores it with your other credentials + +In practice, the profile stores an OAuth login while an API key is a static credential: Claude Code refreshes the profile's login automatically, and when refresh fails, requests fail with [Anthropic profile login expired](/docs/en/errors#anthropic-profile-login-expired) until you sign in again. + +You don't get the choice on every machine. Claude Code creates an API key without asking in these cases: + +* You run against a cloud provider, such as [Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry](/docs/en/third-party-integrations) or [Claude Platform on AWS](/docs/en/claude-platform-on-aws) +* Any settings file sets [`forceLoginOrgUUID`](#restrict-login-to-your-organization), or sets `forceLoginMethod` to `"claudeai"` or `"console"` +* A managed settings source on your machine, such as the managed settings file, an MDM profile, or the cached server-managed settings, exists but Claude Code [can't read it](/docs/en/managed-settings#invalid-entries-in-managed-settings) and no other managed source supplies a policy + +Unset `ANTHROPIC_API_KEY` before you sign in without a key. A profile written by Claude Code's own Console sign-in, or by the Claude Platform CLI's `ant auth login`, is the same kind of credential, so signing in again replaces it. + +After you sign in without a key, you have a profile instead of a stored API key: + +* **Which profile it writes**: Claude Code writes the profile named by `ANTHROPIC_PROFILE`, or your active profile, or `default`. If that profile is a federation profile, Claude Code refuses the sign-in instead of overwriting it +* **What it signs you out of**: Claude Code signs you out of any claude.ai login stored on the machine +* **How to undo it**: run `/logout`, which removes and revokes the credential this sign-in wrote + +Everything else about profiles applies to this sign-in, including where it ranks against your other credentials, the `Profile` row you get in `/status`, and the features that need a claude.ai login. See [Anthropic profiles and federation credentials](#anthropic-profiles-and-federation-credentials). + ### Cloud provider authentication For teams using Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry: @@ -119,7 +144,9 @@ For teams using Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foun To require that developers' claude.ai logins belong to a specific Anthropic organization, set [`forceLoginMethod`](/docs/en/settings-reference#forceloginmethod) and [`forceLoginOrgUUID`](/docs/en/settings-reference#forceloginorguuid) in [managed settings](/docs/en/managed-settings). Set `forceLoginOrgUUID` to your organization ID, shown in [claude.ai admin settings](https://claude.ai/admin-settings/organization) for Claude for Teams or Enterprise organizations. Claude Code reports an error for a claude.ai login to any other organization and exits at startup if the claude.ai credential in use belongs to an organization that isn't listed. -For Claude Console logins, Claude Code uses `forceLoginOrgUUID` only to pre-select the organization on the Console sign-in page when you set it to a single Console organization ID, shown at [platform.claude.com/settings/organization](https://platform.claude.com/settings/organization). It doesn't check which organization the resulting Console credential belongs to, at login or at startup, and a developer who logged in with a Console account before you deployed the keys stays logged in. To direct developers to claude.ai sign-in instead, set `forceLoginMethod` to `"claudeai"`. +For Claude Console logins, Claude Code uses `forceLoginOrgUUID` to pre-select the organization on the Console sign-in page when you set it to a single Console organization ID, shown at [platform.claude.com/settings/organization](https://platform.claude.com/settings/organization). It doesn't check which organization the resulting Console credential belongs to, at login or at startup, and a developer who logged in with a Console account before you deployed the keys stays logged in. + +If you set `forceLoginOrgUUID` in any settings file, Claude Code stops offering the [keyless Console sign-in](#sign-in-without-an-api-key) in the sessions that file applies to and creates an API key instead. To direct developers to claude.ai sign-in instead, set `forceLoginMethod` to `"claudeai"`. Developers can log in from several paths: the terminal `/login` flow, the [VS Code extension](/docs/en/vs-code), the Agent SDK, `claude setup-token`, `/install-github-app`, and [gateway](/docs/en/claude-apps-gateway) sign-in for organizations that route through a cloud gateway. On Claude Code v2.1.212 or later, every path applies `forceLoginMethod`; before v2.1.212, only terminal logins applied either key. On the terminal's interactive login screen, reached by `/login` or first-run onboarding, Claude Code pre-selects a `claudeai` or `console` method without enforcing it, so even with `forceLoginMethod` set to `"claudeai"`, a developer can still complete a Console login there. The paths differ on `forceLoginOrgUUID`: @@ -145,14 +172,14 @@ The keys also decide whether a session that doesn't use a login credential can s Claude Code securely manages your authentication credentials: * **Storage location**: - * On macOS, credentials are stored in the encrypted macOS Keychain. + * On macOS, credentials are stored in the encrypted macOS Keychain. When the Keychain rejects the write, such as when it's locked in an SSH session, Claude Code stores your login in `~/.claude/.credentials.json` with file mode `0600` instead, the same storage it uses on Linux. A Console login that creates an API key fails until the Keychain is writable. To move your login back into the Keychain, follow [the recovery steps](/docs/en/troubleshoot-install#not-logged-in-or-token-expired). * On Linux, credentials are stored in `~/.claude/.credentials.json` with file mode `0600`. * On Windows, credentials are stored in `%USERPROFILE%\.claude\.credentials.json` and inherit the access controls of your user profile directory, which restricts the file to your user account by default. - * If you've set the `CLAUDE_CONFIG_DIR` environment variable on Linux or Windows, the `.credentials.json` file lives under that directory instead. + * If you've set the `CLAUDE_CONFIG_DIR` environment variable, Claude Code keeps the `.credentials.json` file under that directory instead, including the file the macOS fallback writes, and keys the macOS Keychain entry to that directory too, so a session with a different `CLAUDE_CONFIG_DIR` reads a different entry. * Claude Code manages `.credentials.json` through `/login` and `/logout`. To route requests through a custom API endpoint, set the [`ANTHROPIC_BASE_URL`](/docs/en/env-vars) environment variable instead. * **Supported authentication types**: Claude.ai credentials, Claude API credentials, Microsoft Foundry Auth, Bedrock Auth, Vertex Auth, Anthropic profile and [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) credentials, and [Claude apps gateway](/docs/en/claude-apps-gateway) session tokens. * **Custom credential scripts**: configure the [`apiKeyHelper`](/docs/en/settings-reference#apikeyhelper) setting to run a shell script that returns an API key. -* **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. +* **Refresh intervals**: Claude Code re-runs `apiKeyHelper` after five minutes by default. Set the `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` environment variable for custom refresh intervals. See [`apiKeyHelper`](/docs/en/settings-reference#apikeyhelper) for the other cases in which Claude Code re-runs the helper. * **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. * **Helper failures**: when the script exits with an error, times out, or prints nothing, requests fail with [`Your apiKeyHelper script is failing`](/docs/en/errors#your-apikeyhelper-script-is-failing) within three attempts. Before v2.1.208, helper failures surfaced as a generic 401 after about ten silent retries. @@ -192,7 +219,9 @@ If you have an active Claude subscription but also have `ANTHROPIC_API_KEY` set #### Anthropic profiles and federation credentials -A profile is a named credential configuration file in your [Anthropic configuration directory](https://platform.claude.com/docs/en/manage-claude/wif-reference#configuration-directory), by default `~/.config/anthropic` on macOS and Linux or `%APPDATA%\Anthropic` on Windows. A profile's auth mode is `oidc_federation` when you set it up for [Workload Identity Federation (WIF)](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) or `user_oauth` when [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) wrote it. Claude Code doesn't read profiles or federation variables in [bare mode](/docs/en/headless#start-faster-with-bare-mode), in Claude Desktop, or in cloud sessions. +A profile is a named credential configuration file in your [Anthropic configuration directory](https://platform.claude.com/docs/en/manage-claude/wif-reference#configuration-directory), by default `~/.config/anthropic` on macOS and Linux or `%APPDATA%\Anthropic` on Windows. A profile's auth mode is `oidc_federation` when you set it up for [Workload Identity Federation (WIF)](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) or `user_oauth` when [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) wrote it or you [signed in to a Console account without an API key](#sign-in-without-an-api-key). + +Claude Code doesn't read profiles or federation variables in [bare mode](/docs/en/headless#start-faster-with-bare-mode), in Claude Desktop, or in cloud sessions. In those sessions, `/status` shows no `Profile` row. Claude Code checks three sources in this order and stops at the first one that is set. The table shows what sets each source and where it ranks against your `/login` credential. @@ -209,7 +238,7 @@ To confirm which source Claude Code chose, run `/status`: a `Profile` row names Features that need your claude.ai login, such as [claude.ai connectors](/docs/en/mcp#use-mcp-servers-from-claude-ai) and [`/schedule`](/docs/en/routines), aren't available while one of these sources is selected. To stop Claude Code from selecting a source: * **Named profile or federation variables**: unset `ANTHROPIC_PROFILE`, or unset either federation variable -* **Active profile**: run `ant auth logout` for a `user_oauth` profile, or delete the profile's file from `configs/` in your configuration directory for either auth mode +* **Active profile**: run `/logout` for a `user_oauth` profile whose current credential you wrote by [signing in to a Console account without an API key](#sign-in-without-an-api-key), run `ant auth logout` for one whose current credential `ant auth login` wrote, or delete the profile's file from `configs/` in your configuration directory for either auth mode ### Generate a long-lived token diff --git a/content/en/docs/claude-code/claude-apps-gateway-deploy.md b/content/en/docs/claude-code/claude-apps-gateway-deploy.md index 7127ef4f8b..eb6589275c 100644 --- a/content/en/docs/claude-code/claude-apps-gateway-deploy.md +++ b/content/en/docs/claude-code/claude-apps-gateway-deploy.md @@ -214,10 +214,10 @@ The gateway applies per-IP rate limits on the device-grant endpoints, configurab * **Data residency**: the gateway's own data plane sends nothing to Anthropic unless the Anthropic API is a configured upstream; when it is, your existing data-handling agreement applies to the inference path. Telemetry, audit, identity, and settings go only to the destinations you configure. * **Host-process traffic**: the host process is the Claude Code CLI. `claude gateway` runs under the same third-party rules as Amazon Bedrock and Google Cloud's Agent Platform deployments and sends nothing to Anthropic. Before v2.1.227, the host process sent startup telemetry such as product version and platform, which setting `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` in the container environment turned off. Those releases also sent one `HEAD` request at boot, with no body or credentials, to `/api/hello` on `https://api.anthropic.com`, or on `ANTHROPIC_BASE_URL` when the environment set it, unless the environment also set a proxy variable such as `HTTPS_PROXY` or an mTLS client certificate. They ignored the response, so blocking that request at the egress firewall didn't affect the gateway. -* **Client analytics**: the CLI disables its own usage analytics and error reporting while signed in to a gateway. Before the sign-in, including on a first run where a [managed settings file, an MDM profile, or a policy helper](/docs/en/claude-apps-gateway-config#client-side-managed-settings) sets `forceLoginMethod: "gateway"`, the CLI sends its startup events and a feature-flag request to Anthropic. +* **Client analytics**: the CLI disables its own usage analytics and error reporting while signed in to a gateway. Before the first sign-in, the CLI still sends startup events to Anthropic, including on machines whose managed settings force gateway sign-in. To keep those off too, deliver `DISABLE_TELEMETRY` through [managed settings](/docs/en/managed-settings#turn-telemetry-off-for-your-organization). * **Error reporting**: the CLI turns error reporting off whenever its model requests go to any endpoint other than Anthropic's first-party API, such as Amazon Bedrock or a custom `ANTHROPIC_BASE_URL`. * **Client machines**: developers' CLIs still send WebFetch hostname checks and version checks to Anthropic unless `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` and `skipWebFetchPreflight: true` are set. See [data usage](/docs/en/data-usage). -* **Survey ratings**: gateway sign-in disables the Anthropic-bound rating sink from the same point as the analytics streams, so ratings aren't sent to Anthropic. +* **Survey ratings**: while signed in to a gateway, the CLI disables the Anthropic-bound rating upload together with the analytics streams, so it doesn't send ratings to Anthropic. * **Transcript sharing**: choosing Yes on a survey's transcript-share prompt writes a local file under `~/.claude/feedback-bundles/` instead of uploading to Anthropic. * **Client updates**: update checks are separate from gateway traffic. Pin versions through your own distribution and set `DISABLE_UPDATES` if laptops must not fetch releases. `DISABLE_AUTOUPDATER` stops only background updates while `claude update` still works. * **TLS**: serve `public_url` over HTTPS in production, either from the gateway's own listener via `listen.tls` or from a TLS-terminating ingress in front of plain-HTTP replicas, with `listen.public_url` set in both cases. The gateway doesn't refuse plain HTTP. The IdP must serve HTTPS in production, and Postgres supports `?sslmode=require`. Set `Strict-Transport-Security` at your ingress. diff --git a/content/en/docs/claude-code/claude-apps-gateway.md b/content/en/docs/claude-code/claude-apps-gateway.md index 522943bfe9..822da27513 100644 --- a/content/en/docs/claude-code/claude-apps-gateway.md +++ b/content/en/docs/claude-code/claude-apps-gateway.md @@ -279,29 +279,31 @@ Claude Desktop runs its Cowork and Code tabs, plus the Chat tab when you enable Other `cli` keys, such as hooks, `env`, and scoped permission rules like `Bash(npm *)`, reach only clients that sign in through `/login`. Claude Desktop reads the gateway URL from its own managed configuration and signs in with its own flow, separate from the `forceLoginMethod` and `forceLoginGatewayUrl` keys in [Set the gateway URL](#set-the-gateway-url). -Settings passed by a launching process are parent settings. Claude Code ignores parent settings on any machine that has an admin-deployed managed source, unless the highest-priority source sets `parentSettingsBehavior: "merge"`. +Settings passed by a launching process are parent settings. Claude Code ignores parent settings on any machine that has an admin-deployed managed source, unless the [source that delivers the policy](/docs/en/managed-settings#which-managed-source-claude-code-uses) sets `parentSettingsBehavior: "merge"`. #### Which machines need the opt-in Machines that only run Claude Desktop need it. Claude Desktop applies the model list and the disabled-tools list to embedded sessions itself, but the egress allowlist reaches them only as parent settings, in the form of `WebFetch` domain rules and sandbox network rules. Without the opt-in, those sessions run without the egress restriction, and nothing warns you. The gateway still rejects inference requests for models the policy doesn't grant. -Machines where developers sign in through `/login` don't need it; every Claude Code invocation fetches its policy from the gateway directly. Fleets whose [`policyHelper`](/docs/en/settings-reference#policyhelper) supplies managed settings can't use it: parent settings are never merged then, because the helper's output replaces the other managed sources. +Machines where developers sign in through `/login` don't need it; each Claude Code session fetches its policy from the gateway. + +Fleets whose [`policyHelper`](/docs/en/settings-reference#policyhelper) supplies managed settings can't use it: Claude Code never merges parent settings on those fleets, because it reads managed settings from the helper's output alone. #### Set the opt-in -Deploy the key, mirror it to the source that wins on each machine, then verify. +Deploy the managed settings snippet from [Set the gateway URL](#set-the-gateway-url), mirror it to any client-side source that outranks the file, then verify. The [snippet above](#set-the-gateway-url) already includes `parentSettingsBehavior: "merge"`, so the file you push to machines carries it. - - Only the highest-priority admin source's value counts. A managed-preferences plist on macOS or an HKLM policy on Windows outranks the `managed-settings.json` file, and the gateway's own remote managed settings outrank both, so on machines that sign in to the gateway, also set the key in the gateway policy's [`cli` block](/docs/en/claude-apps-gateway-config#managed). + + Claude Code reads `parentSettingsBehavior` only from the [selected source](/docs/en/managed-settings#which-managed-source-claude-code-uses). Adding any policy key to a source can make that source the selected one, so in a client-side source, mirror the whole snippet rather than `parentSettingsBehavior` alone. [Client-side managed settings](/docs/en/claude-apps-gateway-config#client-side-managed-settings) covers fleets that deliver policy through Group Policy or configuration profiles. A managed-preferences plist on macOS or an HKLM policy on Windows outranks the `managed-settings.json` file, and the gateway's own remote managed settings outrank both, so on machines that sign in to the gateway, also set `parentSettingsBehavior` in the gateway policy's [`cli` block](/docs/en/claude-apps-gateway-config#managed). - - Call the Agent SDK's [`resolveSettings()`](/docs/en/agent-sdk/typescript#resolvesettings). Its result includes a `sources` list; the managed policy entry there carries a `policyOrigin` field naming the active source. `resolveSettings()` doesn't execute a configured `policyHelper`, so its result doesn't reflect the live session on machines where a helper supplies the managed settings. + + On a machine that only runs Claude Desktop, call the Agent SDK's [`resolveSettings()`](/docs/en/agent-sdk/typescript#resolvesettings) and read `policyOrigin` on the `managed` entry in its `sources` list. The value names the selected client-side source, `plist`, `hklm`, or `file`, which is the source that must carry the snippet. Claude Desktop's embedded sessions don't fetch the gateway policy, so the gateway's `cli` block never counts as the selected source for them. @@ -374,7 +376,7 @@ Once connected, Claude Desktop sends model requests from every enabled tab throu There is no service-token flow for unattended pipelines. Gateway sign-in always runs the browser device flow, so a CI job with no developer to approve the sign-in can't authenticate; configure those against your provider directly. -Once a developer has signed in, every Claude Code invocation on that machine uses the gateway session, including non-interactive `claude -p` runs and sessions started by the Agent SDK, and the [gateway policy applies to all of them](/docs/en/claude-apps-gateway-config#managed). +Once a developer has signed in, each Claude Code session on that machine uses the gateway session, including non-interactive `claude -p` runs and sessions started by the Agent SDK. Claude Code applies the [gateway policy](/docs/en/claude-apps-gateway-config#managed) to each of them. The device flow separates the polling CLI from the approving browser, so a remote development box with no display still works: the developer runs `/login` over SSH on the remote machine and opens the verification link in the browser on their laptop. diff --git a/content/en/docs/claude-code/claude-security.md b/content/en/docs/claude-code/claude-security.md index e23369219f..ec1c2e0d11 100644 --- a/content/en/docs/claude-code/claude-security.md +++ b/content/en/docs/claude-code/claude-security.md @@ -17,7 +17,7 @@ The plugin is also distinct from the review tools already in Claude Code: the [s To run the plugin, you need: * A paid plan, for the [dynamic workflows](/docs/en/workflows) the scan uses to orchestrate its agents. On Pro, turn them on from the Dynamic workflows row in `/config`. -* Python 3.9.6 or later available on your `PATH` as `python3`. Check with `python3 --version`. The plugin's tooling uses only the Python standard library, so nothing is installed. +* Python 3.9 or later available on your `PATH` as `python3`. Check with `python3 --version`. The plugin's tooling uses only the Python standard library, so nothing is installed. * Linux, macOS, or Windows. * Git, for change scans and for turning findings into patches; those jobs don't support other version control systems. A full scan works in any directory, with or without version control. @@ -29,6 +29,8 @@ In a Claude Code session, install from the [official Anthropic marketplace](/doc /plugin install claude-security@claude-plugins-official ``` +The command opens the plugin's details, where you choose an [installation scope](/docs/en/discover-plugins#install-plugins) to start the install. + If the install fails, the fix depends on which message Claude Code reports: * If it reports `Marketplace "claude-plugins-official" not found`, add the marketplace with `/plugin marketplace add anthropics/claude-plugins-official`, then retry the install. @@ -134,7 +136,7 @@ The plugin doesn't replace your existing source-code security tools. Run it alon ## Troubleshooting -**The `/claude-security` menu opens with a Python warning.** The plugin needs `python3` 3.9.6 or later on your `PATH`. When it can't find `python3` at all, the menu warns that Claude Security won't work until one is installed; when the first `python3` on your `PATH` is older, the warning names the version it found. Install Python 3, or put a newer `python3` first on your `PATH`, then start a new session. +**The `/claude-security` menu opens with a Python warning.** The plugin needs `python3` 3.9 or later on your `PATH`. When it can't find `python3` at all, the menu warns that Claude Security won't work until one is installed; when the first `python3` on your `PATH` is older, the warning names the version it found. Install Python 3, or put a newer `python3` first on your `PATH`, then start a new session. **You may see "Fable 5's safeguards flagged this message" when using Fable 5.** Due to Fable 5's cybersecurity safety classifiers, certain model activities will be blocked and automatically downgraded to Opus. This is expected, and the scan should still complete successfully. diff --git a/content/en/docs/claude-code/cli-reference.md b/content/en/docs/claude-code/cli-reference.md index dbbe2ea80a..afababae34 100644 --- a/content/en/docs/claude-code/cli-reference.md +++ b/content/en/docs/claude-code/cli-reference.md @@ -81,7 +81,7 @@ Customize Claude Code's behavior with these command-line flags. `claude --help` | `--debug-file ` | Write debug logs to a specific file path. Implicitly enables debug mode. Takes precedence over `CLAUDE_CODE_DEBUG_LOGS_DIR` | `claude --debug-file /tmp/claude-debug.log` | | `--disable-slash-commands` | Disable all skills and commands for this session | `claude --disable-slash-commands` | | `--disallowedTools`, `--disallowed-tools` | Deny rules. A bare tool name removes the matching tools from Claude's context: `"Edit"` removes Edit, `"*"` removes every tool, and `"mcp__*"` removes every MCP tool. A scoped rule such as `Bash(rm *)` leaves the tool available and denies only matching calls. A rule naming [`EndConversation`](/docs/en/tools-reference#endconversation-tool-behavior) can't remove it while any other tool remains | `"Bash(git log *)" "Bash(git diff *)" "Edit"` | -| `--effort` | Set the [effort level](/docs/en/model-config#adjust-effort-level) for the current session. Options: `low`, `medium`, `high`, `xhigh`, `max`, or `ultracode`. Available levels depend on the model. `ultracode` starts the session at `xhigh` effort with [ultracode](/docs/en/workflows#let-claude-decide-with-ultracode) turned on, and requires Claude Code v2.1.203 or later. Overrides the [`effortLevel`](/docs/en/settings-reference#effortlevel) setting for this session and does not persist | `claude --effort high` | +| `--effort` | Set the [effort level](/docs/en/model-config#adjust-effort-level) for the current session. Options: `low`, `medium`, `high`, `xhigh`, `max`, or `ultracode`. Available levels depend on the model. `ultracode` starts the session at `xhigh` effort with [ultracode](/docs/en/workflows#let-claude-decide-with-ultracode) turned on, and requires Claude Code v2.1.203 or later. Overrides the [`modelSettings`](/docs/en/settings-reference#modelsettings) and [`effortLevel`](/docs/en/settings-reference#effortlevel) settings for this session and does not persist | `claude --effort high` | | `--enable-auto-mode` | Removed in v2.1.111. Auto mode is now in the `Shift+Tab` cycle by default; use `--permission-mode auto` to start in it | `claude --permission-mode auto` | | `--environment ` | Create a new cloud session that runs on the [self-hosted environment](/docs/en/self-hosted-environments) with the given ID. Environment IDs start with `ccpool_`. See [`--environment` dispatch behavior](/docs/en/self-hosted-environments-testing#environment-dispatch-behavior) for dispatch behavior and the flag combinations it rejects. Requires Claude Code v2.1.224 or later | `claude -p "Fix the login bug" --environment ccpool_abc123` | | `--exclude-dynamic-system-prompt-sections` | Move per-machine sections from the system prompt (working directory, environment info, memory paths, git-repo flag) into the first user message. Improves prompt-cache reuse across different users and machines running the same task. Only applies with the default system prompt; ignored when `--system-prompt` or `--system-prompt-file` is set. Use with `-p` for scripted, multi-user workloads | `claude -p --exclude-dynamic-system-prompt-sections "query"` | diff --git a/content/en/docs/claude-code/cloud-environments.md b/content/en/docs/claude-code/cloud-environments.md index 1bf755c31c..5662fc1344 100644 --- a/content/en/docs/claude-code/cloud-environments.md +++ b/content/en/docs/claude-code/cloud-environments.md @@ -86,7 +86,8 @@ An API credential is an API key or token you store on a cloud environment so Cla Two of these decide whether you can add a credential, and two decide whether the agent proxy can use it once added: -* **Role**: an organization admin role in your claude.ai organization, which Admins and Owners hold +* **Role**: an organization admin role in your claude.ai organization + * On Team and Enterprise, Owners hold it and Admins don't * On Pro and Max, you hold it in your own organization * Without it, you see a note instead of the credential list, on your own environments too. Ask an Owner to add the credential to a shared environment and run your sessions there * **Environment type**: an Anthropic-hosted cloud environment that already exists. A [self-hosted environment](/docs/en/self-hosted-environments) doesn't have API credentials @@ -154,7 +155,7 @@ Archiving affects new sessions, not running ones: On Team and Enterprise plans, an Owner can create cloud environments that are shared with every member of the organization. The same role manages everything else on the **Cloud environments** admin page, including [self-hosted environments](/docs/en/self-hosted-environments); the Admin role can't open the page. The full list of roles that can open it is the one for [managing server-managed settings](/docs/en/server-managed-settings#access-control). Shared environments appear in each member's environment selector alongside their personal ones, so a team can standardize on one configuration instead of each member recreating it. -Create, edit, and archive shared environments from the **Cloud environments** page in [admin settings](https://claude.ai/admin-settings). A shared environment also opens from the [environment selector](#configure-your-environment) at [claude.ai/code](https://claude.ai/code): an Admin or Owner can edit it there, and that dialog is where [API credentials](#add-api-credentials) are added. Other members see it read-only. Each shared environment has a name, a [network access level](#access-levels), [environment variables](#set-environment-variables) in `.env` format, and a [setup script](#setup-scripts). Owners choose the organization's [default environment](#the-default-environment) separately, at [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code). +Create, edit, and archive shared environments from the **Cloud environments** page in [admin settings](https://claude.ai/admin-settings). A shared environment also opens from the [environment selector](#configure-your-environment) at [claude.ai/code](https://claude.ai/code): an Owner can edit it there, and that dialog is where [API credentials](#add-api-credentials) are added. Other members see it read-only. Each shared environment has a name, a [network access level](#access-levels), [environment variables](#set-environment-variables) in `.env` format, and a [setup script](#setup-scripts). Owners choose the organization's [default environment](#the-default-environment) separately, at [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code). Every member's sessions in a shared environment read its variables, so don't include secrets in them. To give those sessions a key they can't read, [add an API credential](#add-api-credentials) from that dialog. diff --git a/content/en/docs/claude-code/commands.md b/content/en/docs/claude-code/commands.md index 415f6d3e8a..4de4ab1466 100644 --- a/content/en/docs/claude-code/commands.md +++ b/content/en/docs/claude-code/commands.md @@ -75,6 +75,7 @@ In the table below, `` indicates a required argument and `[arg]` indicates | `/dataviz [request]` | **[Skill](/docs/en/skills#bundled-skills).** Design guidance for charts, graphs, and dashboards. Claude picks the chart form for the data, assigns color by role, validates the palette for colorblind safety and contrast with a bundled script, and applies mark, interaction, and accessibility rules. Uses a brand-neutral placeholder palette that you replace with your own. Requires Claude Code v2.1.198 or later | | `/debug [description]` | **[Skill](/docs/en/skills#bundled-skills).** Enable debug logging for the current session and troubleshoot issues by reading the session debug log. Debug logging is off by default unless you started with `claude --debug`, so running `/debug` mid-session starts capturing logs from that point forward. Optionally describe the issue to focus the analysis | | `/deep-research ` | **[Workflow](/docs/en/workflows#bundled-workflows).** Fan out web searches on a question, fetch and cross-check sources, and synthesize a cited report | +| `/design [brief]` | **[Skill](/docs/en/skills#bundled-skills).** Draft UI mockups, screen flows, landing pages, or posters as artboards on one canvas, published as an [artifact](/docs/en/artifacts#draft-a-design-canvas) that runs a research preview of Claude Design's editor, for example `/design a settings screen for a mobile banking app`. Where saving is enabled for your account, you edit the artboards on the canvas and save to publish a new version; otherwise you view the draft and export it as PNG or PDF. Requires a session where [artifacts are available](/docs/en/artifacts#availability) and Claude Code v2.1.234 or later. Available on the Anthropic API. On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and Claude Platform on AWS, artifacts aren't available, so the command is unavailable there | | `/design-login` | Authorize design-system access for `/design-sync` with your claude.ai account | | `/design-sync [hint]` | **[Skill](/docs/en/skills#bundled-skills).** Convert your repo's React design system and upload it to [Claude Design](https://claude.ai/design), so designs it produces use your real components. Optionally name the design system, for example `/design-sync Acme DS`. A first-time sync verifies every component and can take a few hours on a large repo. Available on the Anthropic API; on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and Claude Platform on AWS the underlying tool can't reach claude.ai, so the command is unavailable | | `/desktop` | Continue the current session in the Claude Code Desktop app. Requires macOS or x64 Windows and a Claude subscription. Alias: `/app` | diff --git a/content/en/docs/claude-code/debug-your-config.md b/content/en/docs/claude-code/debug-your-config.md index 50220ebbe9..12adaaf5b9 100644 --- a/content/en/docs/claude-code/debug-your-config.md +++ b/content/en/docs/claude-code/debug-your-config.md @@ -82,8 +82,7 @@ cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude The clean session has no user or project settings, hooks, MCP servers, plugins, or memory. On the first launch, expect the first-run setup screens, starting with theme selection. If you see them, the clean configuration directory is in effect. Later launches with the same directory skip these screens because Claude Code saves onboarding state there. * Managed settings still apply if your organization deploys them. Claude Code reads MDM profiles, registry policy, and `managed-settings.json` from locations outside the configuration directory, and [fetches server-managed settings](/docs/en/server-managed-settings#fetch-and-caching-behavior) again for the clean session once it has credentials -* On Linux and Windows, you'll be prompted to log in again because credentials are stored under the configuration directory -* On macOS, credentials are in the Keychain and carry over to the clean session +* You'll be prompted to log in again If the problem disappears here, the cause is somewhere in your real `~/.claude` or project `.claude` files. Reintroduce them one at a time, by copying files into the temporary directory or by launching from your project, to find which one. If it persists in the clean session, the cause is outside your user and project configuration. Run `/status` to check whether managed settings are in effect, look for [environment variables](/docs/en/env-vars) that affect Claude Code, then see [Troubleshooting](/docs/en/troubleshooting). diff --git a/content/en/docs/claude-code/env-vars.md b/content/en/docs/claude-code/env-vars.md index 41da01439b..a89fd9ef95 100644 --- a/content/en/docs/claude-code/env-vars.md +++ b/content/en/docs/claude-code/env-vars.md @@ -108,7 +108,7 @@ In a settings file you can set a variable but you can't remove one. To override Between settings files, `env` values follow [settings precedence](/docs/en/settings#settings-precedence), so a managed settings entry overrides the same variable in user or project settings. -How an environment variable interacts with CLI flags and in-session commands varies per feature: `--model` and `/model` override `ANTHROPIC_MODEL`, while `CLAUDE_CODE_EFFORT_LEVEL` overrides `/effort`. When a variable interacts with another configuration source, its row in the [Variables](#variables) list states the precedence or links to the page that documents it. +How an environment variable interacts with CLI flags and in-session commands varies per feature: `--model` and `/model` override `ANTHROPIC_MODEL`, while `CLAUDE_CODE_EFFORT_LEVEL` overrides `--effort` and `/effort`. When a variable interacts with another configuration source, its row in the [Variables](#variables) list states the precedence or links to the page that documents it. Claude Code reads shell environment variables at startup, so changes to them take effect the next time you launch `claude`. Variables set under the `env` key in settings files are reapplied to a running session when the file changes, with the startup-only exception described in [In settings files](#in-settings-files). @@ -173,7 +173,7 @@ Numeric variables such as timeouts, token budgets, and retry counts accept scien | `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry resource name (for example, `my-resource`). Required if `ANTHROPIC_FOUNDRY_BASE_URL` is not set (see [Microsoft Foundry](/docs/en/microsoft-foundry)) | | `ANTHROPIC_MODEL` | Name of the model setting to use (see [Model Configuration](/docs/en/model-config#environment-variables)) | | `ANTHROPIC_ORGANIZATION_ID` | Organization ID for [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation). Set it together with `ANTHROPIC_FEDERATION_RULE_ID`. See [authentication precedence](/docs/en/authentication#authentication-precedence) | -| `ANTHROPIC_PROFILE` | Name of the Anthropic profile to authenticate with, such as one created by [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication). The named profile ranks above your `/login` credential. See [authentication precedence](/docs/en/authentication#authentication-precedence) | +| `ANTHROPIC_PROFILE` | Name of the Anthropic profile to authenticate with, such as one created by [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) or by [signing in to a Console account without an API key](/docs/en/authentication#sign-in-without-an-api-key). The named profile ranks above your `/login` credential. See [authentication precedence](/docs/en/authentication#authentication-precedence) | | `ANTHROPIC_SMALL_FAST_MODEL` | \[DEPRECATED] Name of [Haiku-class model for background tasks](/docs/en/costs) | | `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Override AWS region for the Haiku-class model when using Amazon Bedrock or Amazon Bedrock Mantle. On Amazon Bedrock, this only takes effect when `ANTHROPIC_DEFAULT_HAIKU_MODEL` or the deprecated `ANTHROPIC_SMALL_FAST_MODEL` is also set, since Amazon Bedrock otherwise runs background tasks on the [default Sonnet model or the primary model](/docs/en/amazon-bedrock#4-pin-model-versions) in the session region | | `ANTHROPIC_VERTEX_BASE_URL` | Override Google Cloud's Agent Platform endpoint URL. Use for custom Google Cloud's Agent Platform endpoints or when routing through an [LLM gateway](/docs/en/llm-gateway). See [Google Cloud's Agent Platform](/docs/en/google-vertex-ai) | @@ -185,6 +185,7 @@ Numeric variables such as timeouts, token budgets, and retry counts accept scien | `BASH_DEFAULT_TIMEOUT_MS` | Default timeout for long-running bash commands (default: 120000, or 2 minutes) | | `BASH_MAX_OUTPUT_LENGTH` | Maximum number of characters of bash output that Claude Code reads back into a command's result (default: 30000; maximum: 150000). See [Output limits](/docs/en/tools-reference#output-limits) | | `BASH_MAX_TIMEOUT_MS` | Maximum timeout the model can set for long-running bash commands (default: 600000, or 10 minutes). The effective ceiling is the larger of this and `BASH_DEFAULT_TIMEOUT_MS` | +| `BETA_TRACING_ENDPOINT` | OTLP endpoint for [detailed beta tracing](/docs/en/monitoring-usage#traces-beta): with `ENABLE_BETA_TRACING_DETAILED=1`, logs and traces go there instead of to the configured exporters. Set it in your shell, user settings, or managed settings. Ignored in [project and local settings](/docs/en/settings-reference#variables-claude-code-ignores-in-env) | | `CCR_FORCE_BUNDLE` | Set to `1` to force [`claude --cloud`](/docs/en/claude-code-on-the-web#send-local-repositories-without-github) to bundle and upload your local repository even when GitHub access is available | | `CLAUDECODE` | Set to `1` in subprocesses Claude Code spawns (Bash and PowerShell tools, tmux sessions, [hook](/docs/en/hooks) commands, [status line](/docs/en/statusline) commands, stdio [MCP server](/docs/en/mcp) subprocesses). IDE extensions also set this in their integrated terminals. Use to detect when a script is running inside a subprocess spawned by Claude Code. To check whether the current process was spawned directly by a tool call or hook, rather than inside a stdio MCP server that Claude Code started, use `CLAUDE_CODE_CHILD_SESSION` instead | | `CLAUDE_AFK_COUNTDOWN_MS` | How many milliseconds before auto-continue the on-screen countdown appears on an unanswered [`AskUserQuestion`](/docs/en/tools-reference) dialog. Default `20000` (20 seconds), capped at the auto-continue timeout. Has no effect unless auto-continue is on; see the [`askUserQuestionTimeout`](/docs/en/settings-reference#askuserquestiontimeout) setting and `CLAUDE_AFK_TIMEOUT_MS`. Requires Claude Code v2.1.198 or later | @@ -209,6 +210,7 @@ Numeric variables such as timeouts, token budgets, and retry counts accept scien | `CLAUDE_CODE_ARTIFACT_COMMENTS` | Set to `0` to stop Claude reading and replying to [comments on an artifact](/docs/en/artifacts#collect-comments-on-an-artifact). Has no effect when `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` has [turned artifacts off](/docs/en/artifacts#availability). Requires Claude Code v2.1.221 or later | | `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | Set to `0` to stop Claude [replying on its own to comments sent to it](/docs/en/artifacts#let-claude-reply-to-comments-on-its-own). Requires Claude Code v2.1.228 or later | | `CLAUDE_CODE_ATTRIBUTION_HEADER` | Set to `0` to omit the [attribution block](/docs/en/llm-gateway-protocol#system-prompt-attribution-block), which carries the client version and a prompt fingerprint, from the start of the system prompt. Caching on a direct connection to the Anthropic API is unaffected either way. In some direct-connection setups, Claude Code keeps the block on [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) classifier requests even when you set `0`. In [System prompt attribution block](/docs/en/llm-gateway-protocol#system-prompt-attribution-block), check which connections and credentials this covers. Before v2.1.181 the block included a per-request token on custom base URLs and Microsoft Foundry connections, so on those versions set it to `0` when your LLM gateway caches on the request body or forwards requests to a third-party provider, or when you connect to Microsoft Foundry directly | +| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | When `CLAUDE_AUTO_BACKGROUND_TASKS` is enabled, seconds between reminders to Claude to check on [background subagents](/docs/en/sub-agents#run-subagents-in-foreground-or-background) that are still running. Accepts a plain integer from `1` to `86400` only; any other value or spelling reads as unset. When unset, there are no check-in reminders. Requires Claude Code v2.1.248 or later | | `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Set the [auto-compact window](/docs/en/model-config#set-the-auto-compact-window) in tokens, from `100000` to `1000000`. Accepts a plain integer such as `500000` only: a value like `500k` reads as `500` and clamps to the 100K minimum. Takes precedence over the `/autocompact` command, the `--autocompact` flag, and the `autoCompactWindow` setting. The status line's `used_percentage` always measures against the model's full context window, so once this variable is set, that percentage no longer indicates when compaction will run | | `CLAUDE_CODE_AUTO_CONNECT_IDE` | Override automatic [IDE connection](/docs/en/vs-code). By default, Claude Code connects automatically when launched inside a supported IDE's integrated terminal. Set to `false` to prevent this. Set to `true` to force a connection attempt when auto-detection fails, such as when tmux obscures the parent terminal. Takes precedence over the [`autoConnectIde`](/docs/en/settings-reference#autoconnectide) global config setting | | `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Time in milliseconds Claude Code waits for the AWS default credential provider chain to produce credentials before the request fails with [`AWS default-chain credential resolve timed out`](/docs/en/errors#aws-default-chain-credential-resolve-timed-out) (default: `60000`). Raise it when a step in your chain legitimately needs longer, such as a browser-based SSO sign-in with MFA through a wrapper like `aws-vault`. Applies wherever Claude Code signs with the default chain: [Amazon Bedrock](/docs/en/amazon-bedrock#credential-caching-and-resolution-timeout), [Claude Platform on AWS](/docs/en/claude-platform-on-aws), and the [Mantle endpoint](/docs/en/amazon-bedrock#use-the-mantle-endpoint). Requires Claude Code v2.1.207 or later | @@ -260,7 +262,7 @@ Numeric variables such as timeouts, token budgets, and retry counts accept scien | `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | Set to `1` to skip proactive [auto-compaction](/docs/en/costs#reduce-token-usage) when Claude Code doesn't recognize the model ID, such as an [LLM gateway](/docs/en/llm-gateway) alias. Without this variable, Claude Code compacts at the context window it assumes for the ID. `CLAUDE_CODE_MAX_CONTEXT_TOKENS` can correct the assumed window instead; see [Correct the window for a gateway or custom model ID](/docs/en/model-config#correct-the-window-for-a-gateway-or-custom-model-id) for when each variable applies. Requires Claude Code v2.1.223 or later | | `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | Set to `1` to disable virtual scrolling in [fullscreen rendering](/docs/en/fullscreen) and render every message in the transcript. Use this if scrolling in fullscreen mode shows blank regions where messages should appear | | `CLAUDE_CODE_DISABLE_WORKFLOWS` | Set to `1` to disable [workflows](/docs/en/workflows#turn-workflows-off). Equivalent to the [`disableWorkflows`](/docs/en/settings-reference#disableworkflows) setting | -| `CLAUDE_CODE_EFFORT_LEVEL` | Set the effort level for supported models. Values: `low`, `medium`, `high`, `xhigh`, `max`, or `auto` to use the model default. Available levels depend on the model. Takes precedence over `/effort` and the `effortLevel` setting. See [Adjust effort level](/docs/en/model-config#adjust-effort-level) | +| `CLAUDE_CODE_EFFORT_LEVEL` | Set the effort level for supported models. Values: `low`, `medium`, `high`, `xhigh`, `max`, or `auto` to use the model default. Available levels depend on the model. Takes precedence over `--effort`, `/effort`, and the `modelSettings` and `effortLevel` settings. See [Adjust effort level](/docs/en/model-config#adjust-effort-level) | | `CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT` | Set to `1` to enable appending extra text to the end of the system prompt of every [subagent](/docs/en/sub-agents) other than a [forked subagent](/docs/en/sub-agents#fork-the-current-conversation). The [`--append-subagent-system-prompt`](/docs/en/cli-reference#cli-flags) flag supplies the appended text and sets this variable automatically, so you don't need to set it yourself. Requires Claude Code v2.1.205 or later | | `CLAUDE_CODE_ENABLE_AUTO_MODE` | Accepted for compatibility with older releases and has no effect. Auto mode is available by default on every provider, including Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and signed-in [Claude apps gateway](/docs/en/claude-apps-gateway) sessions. In v2.1.158 through v2.1.206, setting this to `1` was required to make [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) available on those providers | | `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | Override [session recap](/docs/en/interactive-mode#session-recap) availability. Set to `0` to force recaps off regardless of the `/config` toggle. Set to `1` to force recaps on when [`awaySummaryEnabled`](/docs/en/settings-reference#awaysummaryenabled) is `false`. Takes precedence over the setting and `/config` toggle | @@ -359,7 +361,7 @@ Numeric variables such as timeouts, token budgets, and retry counts accept scien | `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | Set to `1` to skip writing prompt history and session transcripts to disk. Sessions started with this variable set do not appear in `--resume`, `--continue`, or up-arrow history. Useful for ephemeral scripted sessions | | `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Google Cloud's Agent Platform (for example, when using an LLM gateway) | | `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | Maximum number of consecutive times a [Stop](/docs/en/hooks#stop) or [SubagentStop](/docs/en/hooks#subagentstop) hook may block the turn from ending before Claude Code overrides it and ends the turn anyway (default: 8). Set to `0` to disable the cap. Raise this if your hook legitimately needs more iterations to resolve | -| `CLAUDE_CODE_SUBAGENT_MODEL` | The model Claude Code uses for all [subagents](/docs/en/sub-agents#choose-a-model), [agent teams](/docs/en/agent-teams), and agents in a [workflow](/docs/en/workflows). Accepts an alias such as `haiku` or a full model name, and takes precedence over the per-invocation `model` parameter and the subagent definition's `model` frontmatter. See [Model configuration](/docs/en/model-config#environment-variables). Setting it to `inherit` is the same as leaving it unset; before v2.1.196, `inherit` was an override that forced every subagent onto the main conversation's model | +| `CLAUDE_CODE_SUBAGENT_MODEL` | The default model for [subagents](/docs/en/sub-agents#choose-a-model), [agent team](/docs/en/agent-teams#specify-teammates-and-models) teammates, and local [workflow](/docs/en/workflows) agents that aren't assigned a model another way. Accepts an alias such as `haiku` or a full model name. Two sources take precedence over it: a model Claude passes when it spawns the agent, and a `model` field in the agent's definition, including `inherit`. See [Choose a model](/docs/en/sub-agents#choose-a-model) for the full order. Setting it to `inherit` is the same as leaving it unset. Before v2.1.251, this variable overrode both the per-invocation model and the definition's `model` field | | `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | Set `5m` or `1h`, the only values Claude Code accepts, to choose the [prompt cache TTL](/docs/en/prompt-caching#cache-lifetime) for requests outside the main conversation, such as [subagents](/docs/en/sub-agents), workflows, and background work. Takes precedence over the `subagentPromptCacheTtl` setting and over `ENABLE_PROMPT_CACHING_1H`, and `FORCE_PROMPT_CACHING_5M` overrides it. The API bills 1-hour cache writes at a higher rate. Requires Claude Code v2.1.242 or later | | `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Set to `1` to strip Anthropic and cloud provider credentials from subprocess environments (Bash tool, hooks, MCP stdio servers). The parent Claude process keeps these credentials for API calls, but child processes cannot read them, reducing exposure to prompt injection attacks that attempt to exfiltrate secrets via shell expansion. On Linux, this also runs Bash subprocesses in an isolated PID namespace so they cannot read host process environments via `/proc`; as a side effect, `ps`, `pgrep`, and `kill` cannot see or signal host processes. `claude-code-action` sets this automatically when `allowed_non_write_users` is configured | | `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | Set to `1` in non-interactive mode (the `-p` flag) to wait for plugin installation to complete before the first query. Without this, plugins install in the background and may not be available on the first turn. Combine with `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` to bound the wait | @@ -370,7 +372,7 @@ Numeric variables such as timeouts, token budgets, and retry counts accept scien | `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | Set to `false` to disable syntax highlighting in diff output. Useful when colors interfere with your terminal setup. To also disable highlighting in code blocks and file previews, use the [`syntaxHighlightingDisabled`](/docs/en/settings-reference#syntaxhighlightingdisabled) setting | | `CLAUDE_CODE_TASK_LIST_ID` | Share a task list across sessions. Set the same ID in multiple Claude Code instances to coordinate on a shared task list, in [sessions that have the Task tools](/docs/en/tools-reference#task-tool-availability). See [Task list](/docs/en/interactive-mode#task-list) | | `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | Override, in milliseconds, how long a non-interactive session waits at exit for its [agent team](/docs/en/agent-teams) to finish tearing down. Accepts 1000 to 60000; an out-of-range value is ignored and the default of 10000 applies. Requires Claude Code v2.1.206 or later | -| `CLAUDE_CODE_TMPDIR` | Override the temp directory used for internal temp files. Claude Code appends `/claude-{uid}/` on Unix or `/claude/` on Windows to this path. Default: `/tmp` on macOS, `os.tmpdir()` on Linux and Windows. As of v2.1.161, on macOS and Linux, [sandboxed](/docs/en/sandboxing) Bash subprocesses receive a short fallback `$TMPDIR` under the system default when your override is a long path, since some tools fail when temp paths get too long. Unsandboxed Bash commands inherit your shell's `$TMPDIR` unchanged. Claude Code's own temp files always use your override | +| `CLAUDE_CODE_TMPDIR` | Override the temp directory used for internal temp files. Claude Code appends `/claude-{uid}/` on Unix or `/claude/` on Windows to this path. Default: `/tmp` on macOS, `os.tmpdir()` on Linux and Windows. As of v2.1.161, on macOS and Linux, [sandboxed](/docs/en/sandboxing) Bash subprocesses receive a short fallback `$TMPDIR` under the system default when your override is a long path, since some tools fail when temp paths get too long. Unsandboxed Bash commands inherit your shell's `$TMPDIR` unchanged. Claude Code's own temp files always use your override. Set it in your shell, user settings, or managed settings. Ignored in [project and local settings](/docs/en/settings-reference#variables-claude-code-ignores-in-env) | | `CLAUDE_CODE_TMUX_TRUECOLOR` | Set to any non-empty value, such as `1`, to allow 24-bit truecolor output inside tmux. **Setting it to `0` or `false` still allows truecolor**, unlike most on/off variables; unset the variable to restore the 256-color clamp. By default, Claude Code clamps to 256 colors when `$TMUX` is set because tmux does not pass through truecolor escape sequences unless configured to. Set this after adding `set -ga terminal-overrides ',*:Tc'` to your `~/.tmux.conf`. See [Terminal configuration](/docs/en/terminal-config) for other tmux settings | | `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | On Linux and WSL, set to a comma-separated list of the kinds of processes Claude Code [excludes from the tool memory cap](/docs/en/tools-reference#memory-limit-on-linux-and-wsl), such as `mcp` or `lsp`. Set `none` to cap every kind, or `all-new` to cap only Bash, PowerShell, and Monitor tool commands. Claude Code keeps Bash, PowerShell, and Monitor tool commands under the cap whatever you list. Requires Claude Code v2.1.246 or later | | `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | On Linux and WSL, set to a size such as `4G` to [cap the memory that Bash and PowerShell tool commands can use](/docs/en/tools-reference#memory-limit-on-linux-and-wsl), and Monitor tool commands on v2.1.246 or later. Write the size in plain digits, alone for a number of bytes or with a `K`, `M`, `G`, or `T` suffix. Set `0` or `off` to turn the cap off. Once the first process Claude Code starts has turned the cap on or off, a changed value takes effect the next time you launch `claude`. Requires Claude Code v2.1.233 or later | @@ -384,7 +386,7 @@ Numeric variables such as timeouts, token budgets, and retry counts accept scien | `CLAUDE_CODE_USE_VERTEX` | Use [Google Cloud's Agent Platform](/docs/en/google-vertex-ai) | | `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | Set to the number of milliseconds [WebFetch](/docs/en/tools-reference#webfetch-tool-behavior) keeps each fetched URL's response cached. The default is `900000`, which is 15 minutes. Takes plain digits only; `0`, a decimal, or any other spelling keeps the default. Claude Code reads the value once per launch, so a change in a settings `env` block applies when you next launch `claude`. Requires Claude Code v2.1.233 or later | | `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | Upper bound in milliseconds on how long a [workflow](/docs/en/workflows) agent waits for a same-prefix sibling's first response to begin before sending its own first request. When a fan-out starts several agents that share a [prompt-cache prefix](/docs/en/workflows#prompt-caching-in-a-fan-out), Claude Code holds all but the first agent for up to this long so the rest read the cached prefix instead of each processing it uncached. Default `5000`. Set to `0` to disable the wait. When `DISABLE_PROMPT_CACHING` is set, agents never wait. Requires Claude Code v2.1.229 or later | -| `CLAUDE_CONFIG_DIR` | Override the configuration directory (default: `~/.claude`). All settings, session history, and plugins are stored under this path, as are credentials on Linux and Windows; on macOS, credentials are in the system Keychain. Useful for running multiple accounts side by side: for example, `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` | +| `CLAUDE_CONFIG_DIR` | Override the configuration directory (default: `~/.claude`). All settings, session history, and plugins are stored under this path. For credentials, see [where Claude Code stores credentials](/docs/en/authentication#credential-management). Useful for running multiple accounts side by side: for example, `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`. Set it in your shell, user settings, or managed settings. Ignored in [project and local settings](/docs/en/settings-reference#variables-claude-code-ignores-in-env) | | `CLAUDE_DISABLE_ADOPT` | Set to `1` to stop in-flight background work instead of carrying it over when you background a session by pressing `←` or with [`/background`](/docs/en/agent-view#from-inside-a-session). Claude Code asks you to confirm before backgrounding, then stops the tasks that would otherwise carry over. Requires Claude Code v2.1.195 or later | | `CLAUDE_EFFORT` | Set automatically in Bash tool subprocesses and hook commands to the [effort level](/docs/en/model-config#adjust-effort-level) in effect when the subprocess starts: `low`, `medium`, `high`, `xhigh`, or `max`. Ultracode is not a distinct level and reports as `xhigh`. Matches the `effort.level` field passed to [hooks](/docs/en/hooks). Only set when the current model supports the effort parameter | | `CLAUDE_ENABLE_BYTE_WATCHDOG` | Set to `1` to force-enable the byte-level streaming idle watchdog, or set to `0` to force-disable it. `0` also turns off the [first-byte deadline](/docs/en/network-config#streaming-idle-watchdogs) on the connections where that deadline runs. When unset, the watchdog is enabled by default for direct Anthropic API and [Claude Platform on AWS](/docs/en/claude-platform-on-aws) connections, and for streaming responses on [gateway](/docs/en/gateways) connections reached through `ANTHROPIC_BASE_URL` or `ANTHROPIC_AWS_BASE_URL`; before v2.1.222 it didn't run on those gateway connections, so the event-level watchdog could report a stall there even while keep-alive pings were arriving. For timeouts and how the timers interact, see [Streaming idle watchdogs](/docs/en/network-config#streaming-idle-watchdogs) | @@ -420,6 +422,7 @@ Numeric variables such as timeouts, token budgets, and retry counts accept scien | `DISABLE_UPDATES` | Set to `1` to block all updates including manual `claude update` and `claude install`. Stricter than `DISABLE_AUTOUPDATER`. Use when distributing Claude Code through your own channels and users should not self-update | | `DISABLE_UPGRADE_COMMAND` | Set to `1` to hide the `/upgrade` command | | `DO_NOT_TRACK` | Set to `1` to opt out of telemetry, with the same effect as `DISABLE_TELEMETRY`, including making [Remote Control](/docs/en/remote-control#requirements) and the other [features that need feature-flag fetching](#features-that-need-feature-flag-fetching) unavailable. Claude Code reads this variable as a standard boolean, so `0` leaves telemetry on, and honors it as the cross-tool convention recognized by many developer CLIs | +| `ENABLE_BETA_TRACING_DETAILED` | Set to `1`, together with `BETA_TRACING_ENDPOINT`, to turn on [detailed beta tracing](/docs/en/monitoring-usage#traces-beta), which adds content-bearing span attributes and the `claude_code.hook` span. Interactive CLI sessions also require your organization to be allowlisted for the beta. Both variables are ignored in [project and local settings](/docs/en/settings-reference#variables-claude-code-ignores-in-env) | | `ENABLE_CLAUDEAI_MCP_SERVERS` | Set to `false` to stop Claude Code from fetching [claude.ai MCP servers](/docs/en/mcp#use-mcp-servers-from-claude-ai). Enabled by default for logged-in users. To disable per-project or per-org, set [`disableClaudeAiConnectors`](/docs/en/settings-reference#disableclaudeaiconnectors) in settings instead | | `ENABLE_PROMPT_CACHING_1H` | Set to `1` to request a 1-hour [prompt cache TTL](/docs/en/prompt-caching#cache-lifetime) instead of the default 5 minutes. Intended for API key, [Amazon Bedrock](/docs/en/amazon-bedrock), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai), [Microsoft Foundry](/docs/en/microsoft-foundry), and [Claude Platform on AWS](/docs/en/claude-platform-on-aws) users. Subscription users within included usage receive the 1-hour TTL automatically on the [main conversation](/docs/en/prompt-caching#which-ttl-each-request-gets). Subscription users drawing on [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) can set it to keep the 1-hour TTL. 1-hour cache writes are billed at a higher rate. To choose the TTL per request bucket instead, use `CLAUDE_CODE_PROMPT_CACHE_TTL` and `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`, which take precedence over this variable | | `ENABLE_PROMPT_CACHING_1H_BEDROCK` | Deprecated. Use `ENABLE_PROMPT_CACHING_1H` instead | @@ -451,7 +454,7 @@ Numeric variables such as timeouts, token budgets, and retry counts accept scien | `NO_PROXY` | List of domains and IPs to which requests will be directly issued, bypassing proxy | | `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | Standard OpenTelemetry SDK limit on attribute value length. Claude Code caps content-bearing telemetry attributes at the smaller of this and `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH`, so the truncation marker stays within the SDK limit. Claude Code reads the `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` and `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` variants the same way, and the smallest set value applies to all signals. Requires Claude Code v2.1.214 or later. See [Monitoring](/docs/en/monitoring-usage#common-configuration-variables) | | `OTEL_LOG_ASSISTANT_RESPONSES` | Set to `1` to include the model's response text on `assistant_response` OpenTelemetry log events. When unset, the value of `OTEL_LOG_USER_PROMPTS` is used instead. Set to `0` to keep responses redacted even when `OTEL_LOG_USER_PROMPTS` is set. Requires Claude Code v2.1.193 or later. See [Monitoring](/docs/en/monitoring-usage#assistant-response-event) | -| `OTEL_LOG_RAW_API_BODIES` | Emit Anthropic Messages API request and response JSON as `api_request_body` / `api_response_body` log events. Set to `1` for inline bodies truncated at the content limit, or `file:` to write untruncated bodies to disk and emit a `body_ref` path instead. `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` configures the content limit, 60 KB by default. Disabled by default; bodies include the entire conversation history. See [Monitoring](/docs/en/monitoring-usage#api-request-body-event) | +| `OTEL_LOG_RAW_API_BODIES` | Emit Anthropic Messages API request and response JSON as `api_request_body` / `api_response_body` log events. Set to `1` for inline bodies truncated at the content limit, or `file:` to write untruncated bodies to disk and emit a `body_ref` path instead. `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` configures the content limit, 60 KB by default. Disabled by default; bodies include the entire conversation history. Set it in your shell, user settings, or managed settings. Ignored in [project and local settings](/docs/en/settings-reference#variables-claude-code-ignores-in-env). See [Monitoring](/docs/en/monitoring-usage#api-request-body-event) | | `OTEL_LOG_TOOL_CONTENT` | Set to `1` to include tool input and output content in OpenTelemetry span events. Disabled by default to protect sensitive data. See [Monitoring](/docs/en/monitoring-usage) | | `OTEL_LOG_TOOL_DETAILS` | Set to `1` to include tool input arguments, MCP server names, user-authored workflow names, raw error strings on tool failures, the refusal `category` on `api_refusal` events, and other tool details in OpenTelemetry traces and logs. Disabled by default to protect PII. See [Monitoring](/docs/en/monitoring-usage) | | `OTEL_LOG_USER_PROMPTS` | Set to `1` to include user prompt text in OpenTelemetry traces and logs. Disabled by default (prompts are redacted). See [Monitoring](/docs/en/monitoring-usage) | @@ -504,6 +507,7 @@ With fetching off, you can't: * Get the [v2 MCP client runtime](/docs/en/mcp#mcp-client-runtimes) and its protocol probe without setting `MCP_SDK_GENERATION` and `MCP_PROTOCOL_NEGOTIATION`; Claude Code uses the v1 runtime unless you set `MCP_SDK_GENERATION=v2`, and skips the probe unless you set `MCP_PROTOCOL_NEGOTIATION=auto` * Get the [PowerShell tool](/docs/en/tools-reference#powershell-tool) by default for claude.ai and Console accounts on Windows with Git Bash installed; Claude Code routes shell commands through Git Bash unless you set `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. On Windows without Git Bash, the tool stays on * Get [Claude-drafted feedback](/docs/en/tools-reference#sendfeedback-tool-behavior), which Claude Code turns on through a fetched flag +* Have Claude Code [exclude MCP tools whose input schema the API would reject](/docs/en/mcp#tools-with-invalid-input-schemas); it sends the schema anyway, and a request that includes it fails with [a 400 error naming the tool by its position](/docs/en/errors#tool-input-schema-is-invalid) ### First session after an install or upgrade diff --git a/content/en/docs/claude-code/errors.md b/content/en/docs/claude-code/errors.md index d6b898370e..7723ebec70 100644 --- a/content/en/docs/claude-code/errors.md +++ b/content/en/docs/claude-code/errors.md @@ -241,6 +241,7 @@ Claude Code retries these failures: * When no reduction can fit, for example when the conversation itself nearly fills the context window. * When a retry can't shrink `max_tokens` any further. Before v2.1.218, Claude Code could re-send a reduced request that still didn't fit, such as when the extended thinking budget exceeded the remaining context, until the retry budget ran out. * An expired or missing Google Cloud credential on [Google Cloud's Agent Platform](/docs/en/google-vertex-ai), which surfaces as an error such as `Could not load the default credentials`. Claude Code discards its cached credentials and retries up to two times, running your [`gcpAuthRefresh`](/docs/en/google-vertex-ai#advanced-credential-configuration) command if you configured one, then reports the error so you can re-authenticate right away. [Google Cloud's Agent Platform troubleshooting](/docs/en/google-vertex-ai#troubleshooting) covers re-authenticating. Before v2.1.228, Claude Code retried a failing credential through the full retry budget before showing the error. +* A `401` or `403` from the Anthropic API, directly or through an [LLM gateway](/docs/en/llm-gateway), while an [`apiKeyHelper`](/docs/en/settings-reference#apikeyhelper) script supplies the credential. Claude Code re-runs the script and retries with its fresh output, within the full retry budget. When the script itself fails on the re-run, Claude Code shows [Your apiKeyHelper script is failing](#your-apikeyhelper-script-is-failing) instead. Before v2.1.227, `Connection lost before a response was produced` read `Connection closed while thinking, before producing a response` and `The response stalled before a response was produced` read `Response stalled while thinking, before producing a response`. @@ -652,7 +653,7 @@ Not logged in · Please run /login * For CI or automation where interactive login is not possible, configure an [`apiKeyHelper`](/docs/en/settings-reference#apikeyhelper) script that fetches a key at startup * See [Authentication precedence](/docs/en/authentication#authentication-precedence) to understand which credential Claude Code uses when several are present -If you are prompted to log in repeatedly, see [Not logged in or token expired](/docs/en/troubleshoot-install#not-logged-in-or-token-expired) for system clock and macOS Keychain fixes. +If you are prompted to log in repeatedly, see [Not logged in or token expired](/docs/en/troubleshoot-install#not-logged-in-or-token-expired) for system clock checks and macOS credential-storage recovery steps. ### Could not resolve authentication method @@ -938,7 +939,7 @@ API Error: 401 ... authentication_error * Run `/login` to sign in again * If the error returns within the same session after re-authenticating, run `/logout` first to fully clear the stored token, then `/login` * If you authenticate with the `CLAUDE_CODE_OAUTH_TOKEN` environment variable, Claude Code keeps sending the value you set after a request fails with a 401, rather than switching to a stored login's token. [`/status`](/docs/en/commands) shows this credential as an `Auth token` row reading `CLAUDE_CODE_OAUTH_TOKEN`. Generate a fresh token with [`claude setup-token`](/docs/en/authentication#generate-a-long-lived-token) and restart with it, or unset the variable and run `/login`. Before v2.1.225, Claude Code could replace the variable's value mid-session with the short-lived access token from a stored login, and the session failed with 401 errors again once that token expired. -* For repeated prompts to log in across launches, see the system clock and macOS Keychain checks in [Troubleshooting](/docs/en/troubleshoot-install#not-logged-in-or-token-expired) +* For repeated prompts to log in across launches, see the system clock checks and macOS credential-storage recovery steps in [Troubleshooting](/docs/en/troubleshoot-install#not-logged-in-or-token-expired) * For other failures including `403 Forbidden` and OAuth browser issues, see [Login and authentication](/docs/en/troubleshoot-install#login-and-authentication) ### API Error: 401 Invalid authentication credentials @@ -991,16 +992,16 @@ Anthropic profile login expired · Re-authenticate your Anthropic profile Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile ``` -This appears only when the active credential comes from an Anthropic credential profile, one you select with the `ANTHROPIC_PROFILE` environment variable or that Claude Code discovers as the active profile in your Anthropic configuration directory. Sessions that authenticate with `/login`, an API key, a bearer token such as `ANTHROPIC_AUTH_TOKEN`, or a third-party provider never see this message. +This appears only when the active credential comes from an Anthropic credential profile, one you select with the `ANTHROPIC_PROFILE` environment variable, that Claude Code discovers as the active profile in your Anthropic configuration directory, or that Claude Code wrote when you [signed in without an API key](/docs/en/authentication#sign-in-without-an-api-key). Sessions that authenticate with `/login`'s claude.ai option, an API key, a bearer token such as `ANTHROPIC_AUTH_TOKEN`, or a third-party provider never see this message. -Running `/login` doesn't renew the profile credential. Which form you see depends on whether you selected the profile or Claude Code discovered it, and tells you whether a working login can take over instead: +On a machine that [offers the keyless sign-in](/docs/en/authentication#sign-in-without-an-api-key), run `/login`, choose the Anthropic Console account, and sign in again to renew a profile that the keyless Console sign-in or the Claude Platform CLI's `ant auth login` wrote. Claude Code replaces the expired credential in that profile. For a federation profile or one another tool created, `/login` doesn't renew the credential. Which form you see depends on whether you selected the profile or Claude Code discovered it: -* When you set `ANTHROPIC_PROFILE` explicitly, the message ends with `Re-authenticate your Anthropic profile`. Claude Code gives the profile precedence over a saved login, so signing in doesn't stop the error. +* When you set `ANTHROPIC_PROFILE` explicitly, the message ends with `Re-authenticate your Anthropic profile`. * When Claude Code discovered the profile from your configuration directory, the message offers `/login`, because Claude Code gives a working `/login` precedence over the discovered profile and then authenticates with your claude.ai or Console account instead. Before v2.1.234, Claude Code showed the `Re-authenticate your Anthropic profile` form in this case too. **What to do:** -* Sign in to the profile again with the tool that created it, then retry +* Sign in to the profile again, then retry: on a machine that [offers the keyless sign-in](/docs/en/authentication#sign-in-without-an-api-key), run `/login` and choose the Anthropic Console account for a profile the keyless Console sign-in or the Claude Platform CLI's `ant auth login` wrote; for other profiles, use the tool that created them * If an administrator provisioned the profile's credential, ask them to issue a new one * Run `/status` to confirm the active credential source and profile name * To stop using the profile, unset `ANTHROPIC_PROFILE` if you set it, then authenticate another way, such as `/login` or `ANTHROPIC_API_KEY` @@ -1579,7 +1580,11 @@ A tool in the request declared an `input_schema` that fails the API's JSON Schem API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid ``` -Claude Code [excludes MCP tools whose input schema would fail this validation](/docs/en/mcp#tools-with-invalid-input-schemas) when it loads a server's tools, so requests normally never include one. On a deployment that doesn't receive the remote configuration that enables the exclusion, Claude Code records in the server's log which tool would be rejected but sends it anyway, so this error can still occur. The error can also occur for a tool whose schema declares a JSON Schema dialect other than draft 2020-12 in `$schema`: Claude Code doesn't check those schemas against the JSON Schema meta-schema, though it still excludes one with an invalid top-level property name. +Claude Code [excludes MCP tools whose input schema would fail this validation](/docs/en/mcp#tools-with-invalid-input-schemas) when it loads a server's tools, so requests normally never include one. + +On a [deployment where flag fetching is off](/docs/en/env-vars#features-that-need-feature-flag-fetching), or on a machine whose flags have never arrived, Claude Code records in the server's log which tool would be rejected but sends it anyway, so this error can still occur. + +The error can also occur for a tool whose schema declares a JSON Schema dialect other than draft 2020-12 in `$schema`. Claude Code doesn't check those schemas against the JSON Schema meta-schema, though the top-level property-name check still applies. Before v2.1.216, no deployment ran the exclusion checks. diff --git a/content/en/docs/claude-code/fast-mode.md b/content/en/docs/claude-code/fast-mode.md index 166424fcdd..36be7511f1 100644 --- a/content/en/docs/claude-code/fast-mode.md +++ b/content/en/docs/claude-code/fast-mode.md @@ -109,7 +109,9 @@ You can combine both: use fast mode with a lower [effort level](/docs/en/model-c Fast mode requires all of the following: * **Anthropic API or subscription only**: fast mode is available through the Anthropic Console API and for Claude subscription plans using usage credits. It is not available on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or Claude Platform on AWS. Console organizations must also have [fast mode access provisioned](#enable-fast-mode-for-your-organization). -* **Usage credits turned on for subscription plans**: on a Pro, Max, Team, or Enterprise plan, your account must have [usage credits](/docs/en/costs#add-usage-credits-to-your-subscription) turned on, which allows billing beyond your plan's included usage. Until they're on, `/fast` shows "Fast mode requires usage credits · /usage-credits to turn them on". On Pro and Max, turn them on in the **Usage credits** section of [**Settings > Usage**](https://claude.ai/settings/usage) on claude.ai, or run `/usage-credits` to open that page. On Team and Enterprise, a member with billing access turns them on for the organization at [**Admin settings > Usage**](https://claude.ai/admin-settings/usage), and a member without it runs `/usage-credits` to send the organization's admins a request. +* **Usage credits turned on for subscription plans**: on a Pro, Max, Team, or Enterprise plan, your account must have [usage credits](/docs/en/costs#add-usage-credits-to-your-subscription) turned on, which allows billing beyond your plan's included usage. Until they're on, `/fast` shows "Fast mode requires usage credits · /usage-credits to turn them on". How you turn them on depends on your plan: + * On Pro and Max, turn them on in the **Usage credits** section of [**Settings > Usage**](https://claude.ai/settings/usage) on claude.ai, or run `/usage-credits` to open that page. + * On Team and Enterprise, a member with billing access turns them on for the organization at [**Admin settings > Usage**](https://claude.ai/admin-settings/usage), and a member without it runs `/usage-credits` to send the organization's admins a request. Fast mode usage draws directly from usage credits, even if you have remaining usage on your plan. diff --git a/content/en/docs/claude-code/feature-availability.md b/content/en/docs/claude-code/feature-availability.md index 59b078d5c4..ebad3872a9 100644 --- a/content/en/docs/claude-code/feature-availability.md +++ b/content/en/docs/claude-code/feature-availability.md @@ -15,7 +15,7 @@ In the tables below, ✓ means available, ✗ means not available, and "See note How you authenticate determines which features Claude Code can reach. For a single list of what is missing on your provider, see the [summary by provider](#summary-by-provider) tabs. To find your column in the tables: * **Claude subscription**: you sign in with a claude.ai account on the Pro, Max, Team, or Enterprise plan -* **Anthropic Console**: you authenticate with an Anthropic API key +* **Anthropic Console**: you authenticate with an Anthropic API key or by [signing in to a Console account without one](/docs/en/authentication#sign-in-without-an-api-key) * **Amazon Bedrock**: you use Claude models from the Amazon Bedrock model catalog and set `CLAUDE_CODE_USE_BEDROCK`. The [Mantle endpoint](/docs/en/amazon-bedrock#use-the-mantle-endpoint) (`CLAUDE_CODE_USE_MANTLE`) is covered by this column * **Claude Platform on AWS**: you bought Claude through AWS Marketplace but call the Anthropic API, and set `CLAUDE_CODE_USE_ANTHROPIC_AWS` * **Google Cloud's Agent Platform**: Google-operated; you set `CLAUDE_CODE_USE_VERTEX` diff --git a/content/en/docs/claude-code/features-overview.md b/content/en/docs/claude-code/features-overview.md index c5e7e8a3a6..b71acda7d7 100644 --- a/content/en/docs/claude-code/features-overview.md +++ b/content/en/docs/claude-code/features-overview.md @@ -274,7 +274,7 @@ Each feature loads at different points in your session. The tabs below explain w **What loads:** Fresh, isolated context containing: - * The agent's own system prompt, not the full Claude Code system prompt + * The agent's own system prompt, not the Claude Code system prompt * Full content of skills listed in the agent's `skills:` field * CLAUDE.md and git status, except the built-in Explore and Plan agents [omit both](/docs/en/sub-agents#what-loads-at-startup) * Whatever context the lead agent passes in the prompt diff --git a/content/en/docs/claude-code/gateways.md b/content/en/docs/claude-code/gateways.md index af0e1d41ef..d0f15c512c 100644 --- a/content/en/docs/claude-code/gateways.md +++ b/content/en/docs/claude-code/gateways.md @@ -62,7 +62,9 @@ A gateway routes model API requests. A few things you might expect it to handle * **Which model answers**: pick the model with the `/model` command or [model environment variables](/docs/en/model-config#setting-your-model). The gateway decides where requests go, not which model the developer selects. Claude apps gateway can bound the choice with a per-group `availableModels` allowlist, but the developer still picks within it. * **Other network traffic**: Claude Code itself sends version checks and downloads directly to Anthropic, separate from the gateway path. Your network still needs egress to the [required domains](/docs/en/network-config), or set [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/en/env-vars) to turn off the optional streams. -* **Client telemetry**: on a Claude apps gateway session, Claude Code sends no client analytics to Anthropic. It disables the Anthropic-bound analytics when the session signs in. For other gateways, whether the optional client telemetry stream is on depends on your provider, and the [telemetry defaults table](/docs/en/data-usage#telemetry-services) covers each case. Where a gateway session's telemetry goes depends on how the session signed in, and [What's enforced on developers](/docs/en/claude-apps-gateway#whats-enforced-on-developers) says where each kind of session's exports go. +* **Client telemetry**: Claude Code disables its Anthropic-bound client analytics when a session signs in to a Claude apps gateway. To keep pre-sign-in startup analytics off as well, deliver [`DISABLE_TELEMETRY` through managed settings](/docs/en/managed-settings#turn-telemetry-off-for-your-organization). +* **Client telemetry on other gateways**: whether Claude Code sends the optional client telemetry stream depends on your provider, and the [telemetry defaults table](/docs/en/data-usage#default-behaviors-by-api-provider) covers each case. +* **Telemetry destinations**: where Claude Code sends a gateway session's telemetry depends on how the session signed in, and [What's enforced on developers](/docs/en/claude-apps-gateway#whats-enforced-on-developers) says where each kind of session's exports go. * **Corporate HTTP proxies**: an `HTTPS_PROXY` sits between Claude Code and every server it talks to, including the gateway. If your network requires one, [configure the proxy](/docs/en/network-config) in addition to the gateway. For a Claude apps gateway you host, [sign-in checks that the proxy host is also on a private network](/docs/en/claude-apps-gateway#prerequisites); if it isn't, add the gateway host to `NO_PROXY` so the CLI connects to it directly. ## Next steps diff --git a/content/en/docs/claude-code/headless.md b/content/en/docs/claude-code/headless.md index f0b90a50ae..941637e87d 100644 --- a/content/en/docs/claude-code/headless.md +++ b/content/en/docs/claude-code/headless.md @@ -189,7 +189,7 @@ When you enable either option, Claude Code forwards messages from [subagents at #### Handle API retries -When an API request fails with a retryable error, Claude Code emits a `system/api_retry` event before retrying. You can use this to surface retry progress or implement custom backoff logic. +When an API request fails with a retryable error, Claude Code emits a `system/api_retry` event before retrying. On v2.1.246 or later, when a `401` or `403` rejects an [`apiKeyHelper`](/docs/en/settings-reference#apikeyhelper) credential, Claude Code makes the first two retries quietly with no event, then emits the event as usual from the third consecutive retry onward. The quiet retries still count toward `attempt`. You can use the event to show retry progress in your own interface. | Field | Type | Description | | ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | diff --git a/content/en/docs/claude-code/hooks.md b/content/en/docs/claude-code/hooks.md index 0961689324..fddb222553 100644 --- a/content/en/docs/claude-code/hooks.md +++ b/content/en/docs/claude-code/hooks.md @@ -1743,7 +1743,7 @@ In `PostToolUse`, `tool_response` is an object with `plan` and `filePath` fields | :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 | | `permissionDecisionReason` | For `"allow"` and `"ask"`, shown to the user but not Claude. For `"deny"`, shown to Claude. For `"defer"`, ignored | -| `updatedInput` | Modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones. Combine with `"allow"` to auto-approve, or `"ask"` to show the modified input to the user. For `"defer"`, ignored | +| `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 | | `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) | When multiple PreToolUse hooks return different decisions, precedence is `deny` > `defer` > `ask` > `allow`. diff --git a/content/en/docs/claude-code/iam.md b/content/en/docs/claude-code/iam.md index 84db6388d5..c75821d4f1 100644 --- a/content/en/docs/claude-code/iam.md +++ b/content/en/docs/claude-code/iam.md @@ -22,7 +22,7 @@ You can authenticate with any of these account types: * **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). * **Claude for Teams or Enterprise**: log in with the Claude.ai account your team admin invited you to. -* **Claude Console**: log in with your Console credentials. Your admin must have [invited you](#claude-console-authentication) first. +* **Claude Console**: log in with your Console credentials. Your admin must have [invited you](#claude-console-authentication) first. You can sign in with or without [creating an API key](#sign-in-without-an-api-key). * **Cloud providers**: if your organization uses [Amazon Bedrock](/docs/en/amazon-bedrock), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai), or [Microsoft Foundry](/docs/en/microsoft-foundry), set the required environment variables before running `claude`, or select **3rd-party platform** at the login prompt, which launches an interactive setup wizard for Bedrock and Vertex AI. No browser login is needed. * **Cloud gateway**: if your organization runs a self-hosted [Claude apps gateway](/docs/en/claude-apps-gateway), sign in with corporate SSO through `/login`. The gateway-issued token is the session's only credential. @@ -97,6 +97,31 @@ For organizations that prefer API-based billing, you can set up access through t +#### Sign in without an API key + +You can sign in to your Console account without creating an API key, even when your organization doesn't let developers create them. Choose the Anthropic Console account at the `/login` prompt and Claude Code asks how you want to sign in. Requires Claude Code v2.1.242 or later. Both routes sign you in to Console in the browser and differ in what Claude Code stores afterwards: + +* **Sign in with your Console account**, labeled `(recommended)`: Claude Code keeps the OAuth token from that sign-in and stores it as an [Anthropic profile](#anthropic-profiles-and-federation-credentials). It creates no API key +* **Create an API key**, labeled `(legacy)`: Claude Code creates a Console API key for you and stores it with your other credentials + +In practice, the profile stores an OAuth login while an API key is a static credential: Claude Code refreshes the profile's login automatically, and when refresh fails, requests fail with [Anthropic profile login expired](/docs/en/errors#anthropic-profile-login-expired) until you sign in again. + +You don't get the choice on every machine. Claude Code creates an API key without asking in these cases: + +* You run against a cloud provider, such as [Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry](/docs/en/third-party-integrations) or [Claude Platform on AWS](/docs/en/claude-platform-on-aws) +* Any settings file sets [`forceLoginOrgUUID`](#restrict-login-to-your-organization), or sets `forceLoginMethod` to `"claudeai"` or `"console"` +* A managed settings source on your machine, such as the managed settings file, an MDM profile, or the cached server-managed settings, exists but Claude Code [can't read it](/docs/en/managed-settings#invalid-entries-in-managed-settings) and no other managed source supplies a policy + +Unset `ANTHROPIC_API_KEY` before you sign in without a key. A profile written by Claude Code's own Console sign-in, or by the Claude Platform CLI's `ant auth login`, is the same kind of credential, so signing in again replaces it. + +After you sign in without a key, you have a profile instead of a stored API key: + +* **Which profile it writes**: Claude Code writes the profile named by `ANTHROPIC_PROFILE`, or your active profile, or `default`. If that profile is a federation profile, Claude Code refuses the sign-in instead of overwriting it +* **What it signs you out of**: Claude Code signs you out of any claude.ai login stored on the machine +* **How to undo it**: run `/logout`, which removes and revokes the credential this sign-in wrote + +Everything else about profiles applies to this sign-in, including where it ranks against your other credentials, the `Profile` row you get in `/status`, and the features that need a claude.ai login. See [Anthropic profiles and federation credentials](#anthropic-profiles-and-federation-credentials). + ### Cloud provider authentication For teams using Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry: @@ -119,7 +144,9 @@ For teams using Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foun To require that developers' claude.ai logins belong to a specific Anthropic organization, set [`forceLoginMethod`](/docs/en/settings-reference#forceloginmethod) and [`forceLoginOrgUUID`](/docs/en/settings-reference#forceloginorguuid) in [managed settings](/docs/en/managed-settings). Set `forceLoginOrgUUID` to your organization ID, shown in [claude.ai admin settings](https://claude.ai/admin-settings/organization) for Claude for Teams or Enterprise organizations. Claude Code reports an error for a claude.ai login to any other organization and exits at startup if the claude.ai credential in use belongs to an organization that isn't listed. -For Claude Console logins, Claude Code uses `forceLoginOrgUUID` only to pre-select the organization on the Console sign-in page when you set it to a single Console organization ID, shown at [platform.claude.com/settings/organization](https://platform.claude.com/settings/organization). It doesn't check which organization the resulting Console credential belongs to, at login or at startup, and a developer who logged in with a Console account before you deployed the keys stays logged in. To direct developers to claude.ai sign-in instead, set `forceLoginMethod` to `"claudeai"`. +For Claude Console logins, Claude Code uses `forceLoginOrgUUID` to pre-select the organization on the Console sign-in page when you set it to a single Console organization ID, shown at [platform.claude.com/settings/organization](https://platform.claude.com/settings/organization). It doesn't check which organization the resulting Console credential belongs to, at login or at startup, and a developer who logged in with a Console account before you deployed the keys stays logged in. + +If you set `forceLoginOrgUUID` in any settings file, Claude Code stops offering the [keyless Console sign-in](#sign-in-without-an-api-key) in the sessions that file applies to and creates an API key instead. To direct developers to claude.ai sign-in instead, set `forceLoginMethod` to `"claudeai"`. Developers can log in from several paths: the terminal `/login` flow, the [VS Code extension](/docs/en/vs-code), the Agent SDK, `claude setup-token`, `/install-github-app`, and [gateway](/docs/en/claude-apps-gateway) sign-in for organizations that route through a cloud gateway. On Claude Code v2.1.212 or later, every path applies `forceLoginMethod`; before v2.1.212, only terminal logins applied either key. On the terminal's interactive login screen, reached by `/login` or first-run onboarding, Claude Code pre-selects a `claudeai` or `console` method without enforcing it, so even with `forceLoginMethod` set to `"claudeai"`, a developer can still complete a Console login there. The paths differ on `forceLoginOrgUUID`: @@ -145,14 +172,14 @@ The keys also decide whether a session that doesn't use a login credential can s Claude Code securely manages your authentication credentials: * **Storage location**: - * On macOS, credentials are stored in the encrypted macOS Keychain. + * On macOS, credentials are stored in the encrypted macOS Keychain. When the Keychain rejects the write, such as when it's locked in an SSH session, Claude Code stores your login in `~/.claude/.credentials.json` with file mode `0600` instead, the same storage it uses on Linux. A Console login that creates an API key fails until the Keychain is writable. To move your login back into the Keychain, follow [the recovery steps](/docs/en/troubleshoot-install#not-logged-in-or-token-expired). * On Linux, credentials are stored in `~/.claude/.credentials.json` with file mode `0600`. * On Windows, credentials are stored in `%USERPROFILE%\.claude\.credentials.json` and inherit the access controls of your user profile directory, which restricts the file to your user account by default. - * If you've set the `CLAUDE_CONFIG_DIR` environment variable on Linux or Windows, the `.credentials.json` file lives under that directory instead. + * If you've set the `CLAUDE_CONFIG_DIR` environment variable, Claude Code keeps the `.credentials.json` file under that directory instead, including the file the macOS fallback writes, and keys the macOS Keychain entry to that directory too, so a session with a different `CLAUDE_CONFIG_DIR` reads a different entry. * Claude Code manages `.credentials.json` through `/login` and `/logout`. To route requests through a custom API endpoint, set the [`ANTHROPIC_BASE_URL`](/docs/en/env-vars) environment variable instead. * **Supported authentication types**: Claude.ai credentials, Claude API credentials, Microsoft Foundry Auth, Bedrock Auth, Vertex Auth, Anthropic profile and [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) credentials, and [Claude apps gateway](/docs/en/claude-apps-gateway) session tokens. * **Custom credential scripts**: configure the [`apiKeyHelper`](/docs/en/settings-reference#apikeyhelper) setting to run a shell script that returns an API key. -* **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. +* **Refresh intervals**: Claude Code re-runs `apiKeyHelper` after five minutes by default. Set the `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` environment variable for custom refresh intervals. See [`apiKeyHelper`](/docs/en/settings-reference#apikeyhelper) for the other cases in which Claude Code re-runs the helper. * **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. * **Helper failures**: when the script exits with an error, times out, or prints nothing, requests fail with [`Your apiKeyHelper script is failing`](/docs/en/errors#your-apikeyhelper-script-is-failing) within three attempts. Before v2.1.208, helper failures surfaced as a generic 401 after about ten silent retries. @@ -192,7 +219,9 @@ If you have an active Claude subscription but also have `ANTHROPIC_API_KEY` set #### Anthropic profiles and federation credentials -A profile is a named credential configuration file in your [Anthropic configuration directory](https://platform.claude.com/docs/en/manage-claude/wif-reference#configuration-directory), by default `~/.config/anthropic` on macOS and Linux or `%APPDATA%\Anthropic` on Windows. A profile's auth mode is `oidc_federation` when you set it up for [Workload Identity Federation (WIF)](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) or `user_oauth` when [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) wrote it. Claude Code doesn't read profiles or federation variables in [bare mode](/docs/en/headless#start-faster-with-bare-mode), in Claude Desktop, or in cloud sessions. +A profile is a named credential configuration file in your [Anthropic configuration directory](https://platform.claude.com/docs/en/manage-claude/wif-reference#configuration-directory), by default `~/.config/anthropic` on macOS and Linux or `%APPDATA%\Anthropic` on Windows. A profile's auth mode is `oidc_federation` when you set it up for [Workload Identity Federation (WIF)](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) or `user_oauth` when [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) wrote it or you [signed in to a Console account without an API key](#sign-in-without-an-api-key). + +Claude Code doesn't read profiles or federation variables in [bare mode](/docs/en/headless#start-faster-with-bare-mode), in Claude Desktop, or in cloud sessions. In those sessions, `/status` shows no `Profile` row. Claude Code checks three sources in this order and stops at the first one that is set. The table shows what sets each source and where it ranks against your `/login` credential. @@ -209,7 +238,7 @@ To confirm which source Claude Code chose, run `/status`: a `Profile` row names Features that need your claude.ai login, such as [claude.ai connectors](/docs/en/mcp#use-mcp-servers-from-claude-ai) and [`/schedule`](/docs/en/routines), aren't available while one of these sources is selected. To stop Claude Code from selecting a source: * **Named profile or federation variables**: unset `ANTHROPIC_PROFILE`, or unset either federation variable -* **Active profile**: run `ant auth logout` for a `user_oauth` profile, or delete the profile's file from `configs/` in your configuration directory for either auth mode +* **Active profile**: run `/logout` for a `user_oauth` profile whose current credential you wrote by [signing in to a Console account without an API key](#sign-in-without-an-api-key), run `ant auth logout` for one whose current credential `ant auth login` wrote, or delete the profile's file from `configs/` in your configuration directory for either auth mode ### Generate a long-lived token diff --git a/content/en/docs/claude-code/llm-gateway-connect.md b/content/en/docs/claude-code/llm-gateway-connect.md index 2fadc66472..0af4e3157d 100644 --- a/content/en/docs/claude-code/llm-gateway-connect.md +++ b/content/en/docs/claude-code/llm-gateway-connect.md @@ -352,7 +352,9 @@ The helper is any shell command that prints the current credential to stdout. Cl -Claude Code caches the helper's output for five minutes by default and re-runs it when a request returns HTTP 401. To change the cache lifetime, set `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` in milliseconds, for example `CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000` for 15 minutes. +Claude Code caches the helper's output for five minutes by default and re-runs the helper after the cache lifetime elapses. To change the lifetime, set `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` in milliseconds, for example `CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000` for 15 minutes. + +See [`apiKeyHelper`](/docs/en/settings-reference#apikeyhelper) for the other cases in which Claude Code re-runs the helper. The helper's value is sent in both the `Authorization` and `x-api-key` headers, so it works whichever header your gateway reads. diff --git a/content/en/docs/claude-code/managed-settings.md b/content/en/docs/claude-code/managed-settings.md index f9aa75235c..502de9aa61 100644 --- a/content/en/docs/claude-code/managed-settings.md +++ b/content/en/docs/claude-code/managed-settings.md @@ -283,6 +283,8 @@ When the policy isn't applying, the `Setting sources` line tells you which of tw When a managed settings file, MDM profile, registry value, or server-managed payload fails schema validation, Claude Code first skips the individual entries it can repair, such as one invalid permission rule, with a warning for each, then drops any top-level key whose value still fails and keeps enforcing every remaining valid key. Claude Code is stricter with the `managedSettings` a [`policyHelper`](/docs/en/settings-reference#policyhelper) emits: it makes the same entry repairs, but any schema violation that survives fails the whole helper run, and at startup Claude Code refuses to start, the same as for a helper that exits non-zero. A managed settings file or drop-in file that isn't valid JSON contributes no settings at all; Claude Code reports it with the other validation errors and reads the remaining sources as usual. +If a managed settings file or drop-in file can't be read or parsed and no other admin source supplies a policy, sessions signed in with claude.ai or Claude Console credentials exit at startup with a message to contact an administrator. + To find a dropped entry, look in one of three places: * Interactive sessions show a dialog at startup listing the invalid entries. @@ -306,7 +308,7 @@ A few enforcement keys aren't dropped when invalid. Claude Code enforces a stric | `deniedMcpServers` | An individual invalid entry is stripped and the valid subset is enforced. A wholly invalid value is dropped with a warning, since denying every server would block servers the policy never named. | | `sandbox.credentials` | A recoverable invalid entry is degraded to `mode: "deny"` with a warning; an unrecoverable one is stripped; valid entries stay enforced. See [invalid credential entries](/docs/en/settings-reference#invalid-credential-entries-in-managed-settings) | -`requiredMinimumVersion` and `requiredMaximumVersion` fail open by design: an invalid value is dropped rather than enforced, so a bad policy push can't prevent Claude Code from starting. +`requiredMinimumVersion` and `requiredMaximumVersion` fail open by design: an invalid value is dropped rather than enforced. This tolerance applies only to managed settings. User, project, and local settings files remain strict: a file whose JSON or top-level shape fails validation is rejected as a whole and reported, and an individual entry that fails, such as a malformed permission rule, is skipped with a warning while the rest of the file applies. diff --git a/content/en/docs/claude-code/mcp.md b/content/en/docs/claude-code/mcp.md index 61e6e57898..37d7387f4c 100644 --- a/content/en/docs/claude-code/mcp.md +++ b/content/en/docs/claude-code/mcp.md @@ -1250,11 +1250,11 @@ Tools with a root-level combinator stay available. Before sending the tool to th Your server receives whichever arguments Claude chose, so keep validating the combination server-side. -When Claude Code can't produce a schema the API accepts, or on a deployment that doesn't receive the remote configuration that enables the rewrite, such as an offline machine, it skips that one tool, records the reason in the server's log, and leaves the server's other tools available. Versions earlier than v2.1.195 skip every tool whose input schema has a root-level `anyOf`, `oneOf`, or `allOf`. +When Claude Code can't produce a schema the API accepts, or on a deployment that doesn't receive the remote configuration that enables the rewrite, it skips that one tool, records the reason in the server's log, and leaves the server's other tools available. Versions earlier than v2.1.195 skip every tool whose input schema has a root-level `anyOf`, `oneOf`, or `allOf`. ## Tools with invalid input schemas -The Claude API checks every tool's input schema in a request and rejects the whole request when any one schema fails, so a single MCP tool with a malformed schema would make every request that includes it fail with a 400 error. Claude Code runs two of the API's checks itself when it loads a server's tools and, on a deployment that receives the remote configuration that enables the exclusion, excludes each tool that would fail them, so the server's other tools keep working: +The Claude API checks every tool's input schema in a request and rejects the whole request when any one schema fails, so a single MCP tool with a malformed schema would make every request that includes it fail with a 400 error. Claude Code runs two of the API's checks itself when it loads a server's tools and excludes each tool that would fail them, so the server's other tools keep working: * Top-level property names must be 1 to 64 characters long and use only ASCII letters and digits, `_`, `.`, and `-` * The schema must be valid against the JSON Schema draft 2020-12 meta-schema. Claude Code applies this check to schemas that declare no `$schema` and schemas that declare draft 2020-12. A schema that declares any other dialect skips this check, though the property-name check above still applies @@ -1263,7 +1263,9 @@ Claude Code runs the checks after the [root-level combinator rewrite](#tool-inpu When Claude Code excludes a tool, it records the reason in the server's log and tells Claude which tools it excluded and why, so you can ask Claude why a tool is missing. If you fix the schema on the server, the tool comes back the next time Claude Code loads the server's tools. -On a deployment that doesn't receive the remote configuration that enables the exclusion, Claude Code still runs the checks and records in the server's log which tool would be rejected, but sends the tool anyway: the schema goes to the API, and a request that includes it fails with [a 400 error naming the tool by its position](/docs/en/errors#tool-input-schema-is-invalid). The [root-level combinator handling](#tool-input-schemas-with-a-root-level-combinator) is separate and keeps its own behavior on such deployments. Before v2.1.216, no deployment ran these checks. +Claude Code turns the exclusion on through a feature flag it fetches from Anthropic. On a [deployment where flag fetching is off](/docs/en/env-vars#features-that-need-feature-flag-fetching), or on a machine whose flags have never arrived, such as an air-gapped machine, Claude Code still runs the checks and records in the server's log which tool would be rejected, but sends the tool's schema to the API anyway. The API rejects a request that includes that schema with [a 400 error naming the tool by its position](/docs/en/errors#tool-input-schema-is-invalid). Before v2.1.216, no deployment ran these checks. + +The [root-level combinator handling](#tool-input-schemas-with-a-root-level-combinator) is separate and keeps its own behavior when flag fetching is off or the flags have never arrived. ## Require approval for a specific tool diff --git a/content/en/docs/claude-code/memory.md b/content/en/docs/claude-code/memory.md index f242ba0006..cd1e5794ff 100644 --- a/content/en/docs/claude-code/memory.md +++ b/content/en/docs/claude-code/memory.md @@ -335,6 +335,8 @@ This example excludes a top-level CLAUDE.md and a rules directory from a parent Patterns are matched against absolute file paths using glob syntax. You can configure `claudeMdExcludes` at any [settings layer](/docs/en/settings#where-settings-live): user, project, local, or managed policy. Arrays merge across layers. +To exclude a rules file you reach through a [symlink](#share-rules-across-projects-with-symlinks), whether the file or its directory is the link, write the pattern against either path: the file's path under `.claude/rules/` or its link target. A pattern that matches either path excludes the file. Before v2.1.239, only a pattern that matched the link target excluded the file. + Managed policy CLAUDE.md files cannot be excluded. This ensures organization-wide instructions always apply regardless of individual settings. ## Auto memory diff --git a/content/en/docs/claude-code/model-config.md b/content/en/docs/claude-code/model-config.md index 50b496b657..2c6402c1e0 100644 --- a/content/en/docs/claude-code/model-config.md +++ b/content/en/docs/claude-code/model-config.md @@ -212,7 +212,11 @@ Claude Code handles any other blocked selection according to where the model was * **`/model`**: Claude Code rejects the switch with an error * **`--model` flag, `ANTHROPIC_MODEL`, or the `model` setting**: Claude Code replaces the value at startup with a warning naming both the requested and substituted models, and the session starts on the default model * **[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)**: Claude Code ignores the variable -* **Subagent or teammate override**: Claude Code falls back to the [subagent's inherited model](/docs/en/sub-agents#choose-a-model) or the [lead's model for a teammate](/docs/en/agent-teams#specify-teammates-and-models) rather than failing the request. In interactive sessions, Claude Code warns you when it substitutes a subagent's model, by this fallback or by the newest-permitted-version substitution above, naming the requested and substituted models; it doesn't report a teammate's fallback. Where the newest-permitted-version substitution above operates, a blocked family alias follows it instead; before v2.1.222, an alias fell back like any other blocked value on every provider +* **Subagent or teammate override**: Claude Code runs the subagent or teammate on a fallback model rather than failing the request. See [Choose a model](/docs/en/sub-agents#choose-a-model) for the subagent fallback and [Specify teammates and models](/docs/en/agent-teams#specify-teammates-and-models) for the teammate fallback. + + In interactive sessions, Claude Code warns you when it substitutes a subagent's model, by this fallback or by the newest-permitted-version substitution above, naming the requested and substituted models; it doesn't report a teammate's fallback. + + Where the newest-permitted-version substitution above operates, a blocked family alias follows it instead. Before v2.1.222, an alias fell back like any other blocked value on every provider * **Skill or command override**: Claude Code ignores the override, including a blocked family alias, and the skill or command runs on the session model. A skill or command that [runs in a subagent](/docs/en/skills#run-skills-in-a-subagent) follows the subagent behavior above instead * **`advisorModel` setting**: the advisor is disabled for the session * **`--advisor` flag**: Claude Code exits with an error at launch. In a [background session](/docs/en/agent-view), it starts the session without the advisor instead of exiting @@ -371,13 +375,11 @@ Effort limits are delivered together with [organization model restrictions](#org The behavior of `default` depends on your account type: -* **Max, Team Premium, Enterprise pay-as-you-go, and Anthropic API**: defaults to Opus 5 +* **Max, Team Premium, Enterprise, and Anthropic API**: defaults to Opus 5 * **Claude Platform on AWS, Amazon Bedrock, and Google Cloud's Agent Platform**: defaults to Opus 5 -* **Pro, Team Standard, and Enterprise subscription seats**: defaults to Sonnet 5 +* **Pro and Team Standard**: defaults to Sonnet 5 * **Microsoft Foundry**: defaults to Sonnet 4.5 -Enterprise pay-as-you-go means an Enterprise organization billed by usage rather than by subscription seat. - Before v2.1.219, `default` resolved to Opus 4.8 on the Anthropic API, Max, Team Premium, and Enterprise pay-as-you-go from v2.1.154, and on Claude Platform on AWS, Amazon Bedrock, and Google Cloud's Agent Platform from v2.1.207. Before v2.1.207, `default` resolved to Opus 4.7 on Claude Platform on AWS and to Sonnet 4.5 on Amazon Bedrock and Google Cloud's Agent Platform. When an admin has set an [organization default model](#organization-default-model), `default` resolves to that model instead of the account-type default above. Requires Claude Code v2.1.196 or later. `default` can also resolve to the model you set with [`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions), under the conditions listed in its section. @@ -498,17 +500,24 @@ The available effort levels depend on the model. Models not listed here do not s If you set a level the active model does not support, Claude Code falls back to the highest supported level at or below the one you set. For example, `xhigh` runs as `high` on Opus 4.6. Your organization can also cap which levels are available for a model; see [Organization effort limits](#organization-effort-limits). -The default effort is `high` on every model that supports effort, except Opus 4.7, which defaults to `xhigh`. +With the [`ultracode`](/docs/en/settings-reference#ultracode) setting off, Claude Code resolves the session's effort level in this order, taking the first that applies: -When you first run Fable 5, Opus 4.8, or Opus 4.7, Claude Code applies that model's default effort even if you previously set a different level for another model, and holds it across sessions until you make an explicit effort choice, such as running `/effort` in an interactive session or launching with `--effort`. Opus 5 has no such hold: a level you previously set carries over. +1. An explicit choice: the [`CLAUDE_CODE_EFFORT_LEVEL`](/docs/en/env-vars#variables) environment variable, launching with `--effort`, or `/effort` in the session ([a non-interactive `/effort` has narrower effect](#non-interactive-effort)) +2. The model's default effort, on Fable 5, Opus 4.8, or Opus 4.7: from the first time you run one of these models, Claude Code holds that model's default effort across sessions, even when your settings resolve a different level, until you change effort once, for example with an interactive `/effort`, the `/model` picker's effort slider, or `--effort` at launch. Opus 5 has no such hold +3. Your settings: the level you saved for the model or an [`effortLevel`](/docs/en/settings-reference#effortlevel) key, with the precedence between them and across settings files stated at [`modelSettings`](/docs/en/settings-reference#modelsettings) +4. The model's default effort: `high` on every model that supports effort, except that Opus 4.7 defaults to `xhigh` and, when your organization sets a default effort level for its [organization default model](#organization-default-model), that level is the default when you run that model -`low`, `medium`, `high`, and `xhigh` persist across sessions when you set them in an interactive session. `max` provides the deepest reasoning. Unless you set it through the `CLAUDE_CODE_EFFORT_LEVEL` environment variable, `max` applies to the current session only. +When you set `low`, `medium`, `high`, or `xhigh` in an interactive session on your machine, Claude Code saves the level and applies it in later sessions. It saves the level per model, under the [`modelSettings`](/docs/en/settings-reference#modelsettings) key in your user settings, so each model keeps its own saved level. + +`max` is the deepest reasoning level. Unless you set it through the `CLAUDE_CODE_EFFORT_LEVEL` environment variable, Claude Code applies `max` to the current session only. A level you pick from the effort control on a phone or browser connected through [Remote Control](/docs/en/remote-control#what-connected-devices-see) applies to that session only. -A level set with `/effort` in [non-interactive mode](/docs/en/headless), with the `-p` flag, applies to the current session only and isn't saved as your default. It also can't release the model-default hold: while the hold is in force, a non-interactive `/effort` reports `Not applied`, so pass `--effort` at launch instead. + + +A level set with `/effort` in [non-interactive mode](/docs/en/headless), with the `-p` flag, applies to the current session only and isn't saved as your default. It also doesn't count as the one change that ends the model-default step above on Fable 5, Opus 4.8, or Opus 4.7: while that step is in effect, a non-interactive `/effort` reports `Not applied`, so pass `--effort` at launch instead. The `/effort` menu also offers `ultracode`. Ultracode is a Claude Code setting rather than a model effort level: it sends `xhigh` to the model and additionally has Claude orchestrate [dynamic workflows](/docs/en/workflows) for substantive tasks. For where it can be set persistently, see the [`ultracode`](/docs/en/settings-reference#ultracode) setting. @@ -517,6 +526,7 @@ You can turn on ultracode through any of the following: * **`/effort`**: run `/effort ultracode`, or select it from the menu * **`--effort` flag**: launch with `claude --effort ultracode`, which starts the session at `xhigh` effort with ultracode on * **`ultracode` setting**: set [`"ultracode": true`](/docs/en/settings-reference#ultracode) in a settings file, with `--settings`, or in an Agent SDK control request. An [`applyFlagSettings()`](/docs/en/agent-sdk/typescript#applyflagsettings) request also accepts `effortLevel: "ultracode"` +* **`/model` picker**: move the effort slider to `ultracode` with the arrow keys while you choose a model. Claude Code turns it on for the current session, even when you save that model as your default Passing `ultracode` to the `--effort` flag or the Agent SDK `effortLevel` value requires Claude Code v2.1.203 or later. Before v2.1.203, `--effort ultracode` printed `Unknown --effort value 'ultracode'` and the session started at the default effort. @@ -547,15 +557,15 @@ Include `ultrathink` anywhere in your prompt to request deeper reasoning on that You can change effort through any of the following: -* **`/effort`**: run `/effort` with no arguments to open an interactive slider, `/effort` followed by a level name to set it directly, or `/effort auto` to reset to the model default. You can run it while Claude is working, and once you confirm the [cache warning](/docs/en/prompt-caching#changing-effort-level), if Claude Code shows one, Claude Code applies the new level to the next request in the turn +* **`/effort`**: run `/effort` with no arguments to open an interactive slider, `/effort` followed by a level name to set it directly, or `/effort auto` to clear your saved level for the active model. You can run it while Claude is working, and once you confirm the [cache warning](/docs/en/prompt-caching#changing-effort-level), if Claude Code shows one, Claude Code applies the new level to the next request in the turn * **In `/model`**: use left/right arrow keys to adjust the effort slider when selecting a model * **`--effort` flag**: pass a level name to set it for a single session when launching Claude Code * **Environment variable**: set `CLAUDE_CODE_EFFORT_LEVEL` to a level name or `auto` -* **Settings**: set `effortLevel` to `low`, `medium`, `high`, or `xhigh` in your settings file. `max` isn't accepted here, and `ultracode` has its own [`ultracode`](/docs/en/settings-reference#ultracode) key +* **Settings**: set a per-model level in [`modelSettings`](/docs/en/settings-reference#modelsettings), or set [`effortLevel`](/docs/en/settings-reference#effortlevel) to `low`, `medium`, `high`, or `xhigh` as the default for models without one. `max` isn't accepted in either key, and `ultracode` has its own [`ultracode`](/docs/en/settings-reference#ultracode) key * **From a connected device**: in a [Remote Control](/docs/en/remote-control#what-connected-devices-see) session, pick a level from the effort control on your phone or in your browser. The level applies to the current session only. Requires Claude Code v2.1.234 or later * **Skill and subagent frontmatter**: set `effort` in a [skill](/docs/en/skills#frontmatter-reference) or [subagent](/docs/en/sub-agents#supported-frontmatter-fields) markdown file to override the effort level when that skill or subagent runs -The environment variable takes precedence over all other methods, then your configured level, then the model default. Frontmatter effort applies when that skill or subagent is active, overriding the session level but not the environment variable. +Frontmatter effort applies when that skill or subagent is active, overriding the session level but not the environment variable. The `effortLevel` key in [managed settings](/docs/en/managed-settings) is a starting default, not enforcement: users can change it for a session with `/effort` or `--effort`, and the managed value re-asserts as the default in new sessions. @@ -703,13 +713,13 @@ A custom ID that embeds a family name, such as `my-gateway/claude-opus-5`, count Use the following environment variables to control the model names that the aliases map to. Each value must be a full model name, or the equivalent identifier for your API provider. To choose the model your sessions start on, set [`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions), which this table omits. -| Environment variable | Description | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ANTHROPIC_DEFAULT_FABLE_MODEL` | The model to use for `fable`, and the model ID Claude Code recognizes as Fable 5 for [automatic model fallback](#automatic-model-fallback) on third-party providers | -| `ANTHROPIC_DEFAULT_OPUS_MODEL` | The model to use for `opus`, or for `opusplan` when Plan Mode is active. | -| `ANTHROPIC_DEFAULT_SONNET_MODEL` | The model to use for `sonnet`, or for `opusplan` when Plan Mode is not active. | -| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | The model to use for `haiku`, or [background functionality](/docs/en/costs#background-token-usage) | -| `CLAUDE_CODE_SUBAGENT_MODEL` | The model Claude Code uses for all [subagents](/docs/en/sub-agents#choose-a-model), [agent teams](/docs/en/agent-teams), and agents in a [workflow](/docs/en/workflows). Accepts an alias such as `haiku` or a full model name, and overrides the per-invocation `model` parameter and the subagent definition's `model` frontmatter. Set to `inherit` to use normal model resolution instead | +| Environment variable | Description | +| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ANTHROPIC_DEFAULT_FABLE_MODEL` | The model to use for `fable`, and the model ID Claude Code recognizes as Fable 5 for [automatic model fallback](#automatic-model-fallback) on third-party providers | +| `ANTHROPIC_DEFAULT_OPUS_MODEL` | The model to use for `opus`, or for `opusplan` when Plan Mode is active. | +| `ANTHROPIC_DEFAULT_SONNET_MODEL` | The model to use for `sonnet`, or for `opusplan` when Plan Mode is not active. | +| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | The model to use for `haiku`, or [background functionality](/docs/en/costs#background-token-usage) | +| `CLAUDE_CODE_SUBAGENT_MODEL` | The default model for [subagents](/docs/en/sub-agents#choose-a-model), [agent team](/docs/en/agent-teams#specify-teammates-and-models) teammates, and [workflow](/docs/en/workflows) agents that aren't assigned a model another way. Accepts an alias such as `haiku` or a full model name. A per-invocation model or a definition's `model` field, including `inherit`, takes precedence | Note: `ANTHROPIC_SMALL_FAST_MODEL` is deprecated in favor of `ANTHROPIC_DEFAULT_HAIKU_MODEL`. diff --git a/content/en/docs/claude-code/monitoring-usage.md b/content/en/docs/claude-code/monitoring-usage.md index 4e366173a3..91b6a35fde 100644 --- a/content/en/docs/claude-code/monitoring-usage.md +++ b/content/en/docs/claude-code/monitoring-usage.md @@ -70,6 +70,14 @@ When you set an `OTEL_EXPORTER_OTLP_*` variable in managed settings, Claude Code * **Protocols**: when you set `OTEL_EXPORTER_OTLP_PROTOCOL`, Claude Code removes every developer-set per-signal protocol. * **Credentials**: when you set `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_EXPORTER_OTLP_CLIENT_KEY`, or `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`, Claude Code removes the developer-set per-signal versions of that variable, plus every developer-set endpoint variable, generic or per-signal, since those credentials would otherwise reach a collector the managed settings didn't choose. * **Exporter selectors**: `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, and the beta `OTEL_TRACES_EXPORTER` follow normal per-key precedence. A developer's setting can still disable a signal or switch it to the console exporter, so set the selectors in managed settings too if you need them locked. Across [admin sources](/docs/en/managed-settings#precedence-within-the-managed-tier), `OTEL_LOGS_EXPORTER` follows the [telemetry unit](/docs/en/server-managed-settings#per-key-exceptions-across-managed-sources) while the other two selectors merge per key. Requires Claude Code v2.1.223 or later. +* **Beta tracing endpoints**: with [detailed beta tracing](#traces-beta) active, Claude Code exports logs and traces to `BETA_TRACING_ENDPOINT` instead of through the logs and traces exporters. Claude Code therefore removes a developer-set `BETA_TRACING_ENDPOINT` whenever any of these managed settings decides either signal's destination: + + * A generic or logs/traces endpoint or credential + * An [`otelHeadersHelper`](/docs/en/settings-reference#otelheadershelper) + * A logs or traces exporter selector set to `none`, `console`, or empty, values that keep the signal off a collector + * `CLAUDE_CODE_ENABLE_TELEMETRY` turned off + + A metrics-only endpoint or credential doesn't remove it. Before v2.1.251, a developer-set `BETA_TRACING_ENDPOINT` redirected the logs and traces that detailed beta tracing exports even when managed settings pinned the collector. Claude Code doesn't remove per-signal variables that you set in managed settings itself, so you can route one signal to a different collector by setting its variable there, as the [SIEM example](#send-events-to-a-siem) does. If you set a per-signal credential there, Claude Code removes the developer-set endpoint for that signal. @@ -77,6 +85,8 @@ This removal behavior changes where telemetry is delivered, not what Claude Code Before v2.1.217, every variable followed per-key settings precedence independently, so a signal-specific endpoint set in user settings or the shell redirected that signal away from the managed collector. +When the desktop app or a [self-hosted environment](/docs/en/self-hosted-environments) runner launches Claude Code and names an OTLP endpoint in the environment it provides, Claude Code pins the destination the same way: the launcher's telemetry variables remove developer-set variables exactly as managed settings do. Claude Code doesn't remove variables that the launcher itself set. Requires Claude Code v2.1.251 or later. + ## Configuration details ### Common configuration variables @@ -266,7 +276,9 @@ When `OTEL_LOG_TOOL_CONTENT=1`, this span also records a `tool.output` span even **`claude_code.hook`** -This span is emitted only when detailed beta tracing is active, which requires `ENABLE_BETA_TRACING_DETAILED=1` and `BETA_TRACING_ENDPOINT` in addition to the trace exporter configuration above. In interactive CLI sessions, this also requires your organization to be allowlisted for the feature. Agent SDK and non-interactive `-p` sessions are not gated. It is not emitted when only `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` is set. +This span appears only when detailed beta tracing is active, which requires `ENABLE_BETA_TRACING_DETAILED=1` and `BETA_TRACING_ENDPOINT`. Set the pair in your shell, user settings, or managed settings; both variables are ignored in [project and local settings](/docs/en/settings-reference#variables-claude-code-ignores-in-env). `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` alone doesn't produce it. + +In interactive CLI sessions, detailed beta tracing also requires your organization to be allowlisted for the feature. Agent SDK and non-interactive `-p` sessions don't require allowlisting. | Attribute | Description | Gated by | | ------------------------ | ------------------------------------------------ | ----------------------- | @@ -1333,7 +1345,9 @@ For a comprehensive guide on measuring return on investment for Claude Code, inc * `user_prompt` events include the verbatim `command_name` for custom, plugin, and MCP commands * Trace spans include the same `tool_input` attribute and input-derived attributes such as `file_path`, with the same truncation as `tool_input` * Tool input and output content is not logged in trace spans by default. To include it, set `OTEL_LOG_TOOL_CONTENT=1`. When enabled, span events include full tool input and output content truncated at the content limit (60 KB by default) per attribute. This can include raw file contents from Read tool results and Bash command output. Configure your telemetry backend to filter or redact these attributes as needed -* Raw Anthropic Messages API request and response bodies are not logged by default. To include them, set `OTEL_LOG_RAW_API_BODIES`. With `=1`, each API call emits `api_request_body` and `api_response_body` log events whose `body` attribute is the JSON-serialized payload, truncated at the content limit (60 KB by default). With `=file:`, untruncated bodies are written to `.request.json` and `.response.json` files under that directory and the events carry a `body_ref` path instead of the inline body. Ship the directory with a log collector or sidecar rather than through the telemetry stream. In both modes, bodies contain the full conversation history, including the system prompt, every prior user and assistant turn, and tool results, so enabling this implies consent to everything the other `OTEL_LOG_*` content flags would reveal. Claude's extended-thinking content is always redacted from these bodies regardless of other settings +* Raw Anthropic Messages API request and response bodies are not logged by default. To include them, set `OTEL_LOG_RAW_API_BODIES` in your shell, user settings, or managed settings. It's ignored in [project and local settings](/docs/en/settings-reference#variables-claude-code-ignores-in-env). The bodies contain the full conversation history, including the system prompt, every prior user and assistant turn, and tool results, so enabling this implies consent to everything the other `OTEL_LOG_*` content flags would reveal. Claude Code always redacts Claude's extended-thinking content from these bodies, regardless of other settings. The value you set determines how Claude Code delivers the bodies: + * With `=1`, Claude Code emits `api_request_body` and `api_response_body` log events for each API call. The events' `body` attribute carries the JSON-serialized payload, truncated at the content limit (60 KB by default) + * With `=file:`, Claude Code writes untruncated bodies to `.request.json` and `.response.json` files under that directory, and the events carry a `body_ref` path instead of the inline body. Ship the directory with a log collector or sidecar rather than through the telemetry stream ## Monitor Claude Code on Amazon Bedrock diff --git a/content/en/docs/claude-code/plugins-reference.md b/content/en/docs/claude-code/plugins-reference.md index 8a3576bccc..db07a409e8 100644 --- a/content/en/docs/claude-code/plugins-reference.md +++ b/content/en/docs/claude-code/plugins-reference.md @@ -605,7 +605,7 @@ Before v2.1.207, these fields substituted `${user_config.KEY}` values; update pl Non-sensitive values are stored under the [`pluginConfigs`](/docs/en/settings-reference#pluginconfigs) key in your user `settings.json` as `pluginConfigs[].options`. -Sensitive values go to the macOS Keychain, or to `~/.claude/.credentials.json` on platforms where no supported keychain is available. Keychain storage is shared with OAuth tokens and has an approximately 2 KB total limit, so keep sensitive values small. +On macOS, Claude Code stores sensitive values in the macOS Keychain, falling back to `~/.claude/.credentials.json` when the Keychain rejects the write. On platforms without a supported keychain, it stores them in `~/.claude/.credentials.json`. Keychain storage is shared with OAuth tokens and has an approximately 2 KB total limit, so keep sensitive values small. Claude Code reads all `pluginConfigs` values from only three settings sources: diff --git a/content/en/docs/claude-code/self-hosted-environments-testing.md b/content/en/docs/claude-code/self-hosted-environments-testing.md index 6413d48684..4271fed94c 100644 --- a/content/en/docs/claude-code/self-hosted-environments-testing.md +++ b/content/en/docs/claude-code/self-hosted-environments-testing.md @@ -188,7 +188,9 @@ Both `claude -p ... --environment` and `claude -p ... --cloud` authenticate with ### Long-lived CI host -Run `claude auth login` once interactively on the machine that executes the script, using a dedicated user account for automation. The token lives in the OS keychain on macOS, or in `~/.claude/.credentials.json` on Linux and Windows. The CLI refreshes the short-lived access token automatically on each invocation, but the underlying refresh-token grant is capped at 30 days from the initial login, so re-run `claude auth login` interactively on that host every 30 days. +Run `claude auth login` once interactively on the machine that executes the script, using a dedicated user account for automation. Claude Code stores the token in the OS keychain on macOS, or in `~/.claude/.credentials.json` on Linux and Windows. On a macOS host whose Keychain can't be written, as is typical in an SSH session where the login Keychain stays locked, Claude Code stores the token in `~/.claude/.credentials.json` there too. See [Credential management](/docs/en/authentication#credential-management). + +The CLI refreshes the short-lived access token automatically on each invocation, but the underlying refresh-token grant is capped at 30 days from the initial login, so re-run `claude auth login` interactively on that host every 30 days. ### Ephemeral CI runners @@ -204,7 +206,7 @@ Create and delete environments programmatically so each CI run gets a clean one; `$ADMIN_TOKEN` is a claude.ai OAuth access token for an account that holds an Owner role, minted the same way as [Authenticate from CI](#authenticate-from-ci): -* **Mint it**: run `claude auth login` with an account that holds an Owner role, then read the current access token from the OS keychain on macOS or `~/.claude/.credentials.json` on Linux and Windows. +* **Mint it**: run `claude auth login` with an account that holds an Owner role, then read the current access token from wherever [Long-lived CI host](#long-lived-ci-host) says Claude Code stored it. * **Read it fresh each run**: the CLI rotates the access token, and the same 30-day refresh-grant cap applies, so don't store a copy. * **Pass it via stdin**: as the example does, so the token never lands in curl's argument list or your build log. diff --git a/content/en/docs/claude-code/settings-example.md b/content/en/docs/claude-code/settings-example.md index 96e3bfc1f9..e78fca8147 100644 --- a/content/en/docs/claude-code/settings-example.md +++ b/content/en/docs/claude-code/settings-example.md @@ -56,7 +56,7 @@ One developer's personal settings. It picks a model and effort, adjusts the term { // Start every session on Sonnet 5 "model": "claude-sonnet-5", - // Reason more deeply than the default high level; /effort saves a new level, and --effort overrides it for one session + // Reason more deeply than the default high level on models without a saved level; /effort saves a level per model, and --effort sets one for a single session "effortLevel": "xhigh", // Vim keybindings in the prompt "editorMode": "vim", diff --git a/content/en/docs/claude-code/settings-reference.md b/content/en/docs/claude-code/settings-reference.md index 8f9c399477..cf6b752576 100644 --- a/content/en/docs/claude-code/settings-reference.md +++ b/content/en/docs/claude-code/settings-reference.md @@ -650,7 +650,7 @@ scope: "Which settings files can set the key: user (~/.claude/settings.json), pr | [`disableSkillShellExecution`](#disableskillshellexecution) | Stop [skills](/docs/en/skills) and custom commands from running inline shell | Plugins and skills | Any file | | [`disableWorkflows`](#disableworkflows) | Turn [dynamic workflows](/docs/en/workflows) off for everyone; use `enableWorkflows` for yourself | Hooks and automation | Any file | | [`editorMode`](#editormode) | Use [vim key bindings](/docs/en/interactive-mode#vim-editor-mode) in the input prompt | Interface and terminal | Any file | -| [`effortLevel`](#effortlevel) | Save the [`/effort` level](/docs/en/model-config#adjust-effort-level) so future sessions reason more or less deeply | Model and responses | Any file | +| [`effortLevel`](#effortlevel) | Set a default [effort level](/docs/en/model-config#adjust-effort-level) for models without a saved level of their own | Model and responses | Any file | | [`emojiCompletionEnabled`](#emojicompletionenabled) | Turn off [`:shortcode:` emoji suggestions and replacement](/docs/en/interactive-mode#emoji-shortcodes) in the prompt input | Interface and terminal | Any file | | [`enableAllProjectMcpServers`](#enableallprojectmcpservers) | Approve every server in project [`.mcp.json`](/docs/en/mcp#project-server-approvals-and-workspace-trust) files without a prompt | MCP | Any file | | [`enableArtifact`](#enableartifact) | Turn the [Artifact tool](/docs/en/artifacts) off with a `false` in any file; no file can turn it back on | Remote, desktop, and notifications | Any file | @@ -688,6 +688,7 @@ scope: "Which settings files can set the key: user (~/.claude/settings.json), pr | [`modelOverrides`](#modeloverrides) | [Map model IDs](/docs/en/model-config#override-model-ids-per-version) to your provider's IDs, such as Bedrock ARNs | Model and responses | Any file | | [`modelPicker`](#modelpicker) | Choose which models the [`/model` picker](/docs/en/model-config#available-models) lists, in your own order and with your own labels | Model and responses | User or managed | | [`modelPricing`](#modelpricing) | Report spend at your organization's contracted rates instead of list price | Model and responses | Managed | +| [`modelSettings`](#modelsettings) | Keep a saved [effort level](/docs/en/model-config#adjust-effort-level) per model, which Claude Code writes when you run `/effort` | Model and responses | Any file | | [`otelHeadersHelper`](#otelheadershelper) | Generate rotating [OpenTelemetry](/docs/en/monitoring-usage#dynamic-headers) headers with your own command | Authentication and providers | Any file | | [`outputStyle`](#outputstyle) | Change Claude's role, tone, and output format with an [output style](/docs/en/output-styles) | Model and responses | Any file | | [`parentSettingsBehavior`](#parentsettingsbehavior) | Apply or drop restrictions an [SDK or IDE host](/docs/en/managed-settings#let-an-embedding-host-add-policy) passes when you deploy [managed settings](/docs/en/managed-settings) | Enterprise and managed settings | Managed | @@ -784,7 +785,7 @@ scope: "Which settings files can set the key: user (~/.claude/settings.json), pr | [`switchModelsOnFlag`](#switchmodelsonflag) | Switch models automatically or pause when a [safety classifier](/docs/en/model-config#ask-before-switching) flags a request | Model and responses | Any file | | [`syncClaudeAiSkills`](#syncclaudeaiskills) | Stop downloading the [skills enabled on your claude.ai account](/docs/en/skills#how-synced-skills-behave) and hide the ones already synced | Plugins and skills | User, local, or managed | | [`syntaxHighlightingDisabled`](#syntaxhighlightingdisabled) | Turn off syntax highlighting in diffs and code blocks | Interface and terminal | Any file | -| [`teammateDefaultModel`](#teammatedefaultmodel) | Removed in v2.1.234; [teammates](/docs/en/agent-teams#specify-teammates-and-models) follow the lead's model | Global config settings | Global config | +| [`teammateDefaultModel`](#teammatedefaultmodel) | Removed in v2.1.234; see [Specify teammates and models](/docs/en/agent-teams#specify-teammates-and-models) for how Claude Code picks a teammate's model | Global config settings | Global config | | [`teammateMode`](#teammatemode) | Choose how [agent team teammates display](/docs/en/agent-teams#choose-a-display-mode) | Agents, sessions, and worktrees | Any file | | [`terminalProgressBarEnabled`](#terminalprogressbarenabled) | Hide the terminal progress bar in terminals that support it | Interface and terminal | Any file | | [`terminalTitleFromRename`](#terminaltitlefromrename) | Stop [`/rename`](/docs/en/sessions#name-your-sessions) and `--name` from changing the terminal tab title | Interface and terminal | Any file | @@ -871,7 +872,9 @@ See [Restrict model selection](/docs/en/model-config#restrict-model-selection). ### `effortLevel` -Keep an [effort level](/docs/en/model-config#adjust-effort-level) across sessions. Lower levels are faster and cheaper on straightforward tasks, and higher levels reason more deeply on complex problems. Claude Code writes this key to your user settings when you run `/effort low`, `medium`, `high`, or `xhigh` in an interactive session on your machine. In a `-p` run, the Agent SDK, or a session attached to a remote worker, `/effort` applies to that session only. The message `/effort` prints says which happened. +Set a default [effort level](/docs/en/model-config#adjust-effort-level) for models you haven't saved a level for. Lower levels are faster and cheaper on straightforward tasks, and higher levels reason more deeply on complex problems. + +When you run `/effort low`, `medium`, `high`, or `xhigh` in an interactive session on your machine, Claude Code saves the level for the active model under [`modelSettings`](#modelsettings) rather than writing this key. Within the same settings file, Claude Code uses a model's saved level rather than this key; [`modelSettings`](#modelsettings) states the cross-file precedence. In a `-p` run, the Agent SDK, or a session attached to a remote worker, `/effort` applies to that session only. The message that `/effort` prints says which happened. Before v2.1.251, `/effort` wrote this key. * **Scope**: [`Any file`](#scopes) * **Type**: string, one of: @@ -888,7 +891,7 @@ Keep an [effort level](/docs/en/model-config#adjust-effort-level) across session } ``` -On Opus 4.7, Opus 4.8, and Fable 5, Claude Code holds that model's default effort until you change effort once with `/effort`, `--effort`, or the `/model` picker. After that, it reads this key. See [Adjust effort level](/docs/en/model-config#adjust-effort-level). +On Opus 4.7, Opus 4.8, and Fable 5, Claude Code holds that model's default effort, organization-set or built-in, until you change effort once, for example with an interactive `/effort`, the `/model` picker's effort slider, or `--effort` at launch. After that, Claude Code resolves effort by the precedence stated at [`modelSettings`](#modelsettings). See [Adjust effort level](/docs/en/model-config#adjust-effort-level). ### `enforceAvailableModels` @@ -1117,6 +1120,32 @@ Claude Code decides which models a row applies to from the row's key: * **Any other key**: a key that isn't a built-in model's ID, such as a gateway model alias. Claude Code applies the row to that one ID only. When a model ID matches one of your keys exactly and also falls under a row keyed by a built-in model's ID, Claude Code uses the exact match. * **A Bedrock application inference profile**: once Claude Code has resolved the profile to the model it routes to, through your [`modelOverrides`](#modeloverrides) map or the [`bedrock:GetInferenceProfile` lookup](/docs/en/amazon-bedrock#iam-configuration), Claude Code applies that model's row to the profile. +### `modelSettings` + +Requires Claude Code v2.1.251 or later. Save an [effort level](/docs/en/model-config#adjust-effort-level) for each model you use. In an interactive session on your machine, when you run `/effort low`, `medium`, `high`, or `xhigh` or move the `/model` picker's effort slider, Claude Code saves that level here under the model you're using, so you rarely edit this key yourself. The [`effortLevel`](#effortlevel) entry lists the sessions in which `/effort` applies to that session only. Edit the key by hand to change or remove a level you saved. + +A model's entry here takes precedence over [`effortLevel`](#effortlevel) in the same settings file. Across files, Claude Code resolves each model separately: the highest-precedence [settings file](/docs/en/settings#settings-precedence) that sets either that model's entry or `effortLevel` decides, so an `effortLevel` in managed settings outranks a level you saved in user settings. [Adjust effort level](/docs/en/model-config#adjust-effort-level) lists what else can override a saved level, such as `--effort` at launch. + +* **Scope**: [`Any file`](#scopes) +* **Type**: object mapping a model name to an object with an `effortLevel` field, one of `"low"`, `"medium"`, `"high"`, or `"xhigh"` +* **Default**: unset + +Claude Code writes each entry under the model's canonical name, such as `claude-opus-5`, and matches that model's alias, date-suffixed, `[1m]`, and recognized provider-specific IDs to the same entry. + +This example keeps Opus 5 at `medium` while other models use their own saved or default levels: + +```json settings.json theme={null} +{ + "modelSettings": { + "claude-opus-5": { + "effortLevel": "medium" + } + } +} +``` + +Run `/effort auto` to clear your saved level for the model you're using. Claude Code leaves the other entries and any top-level `effortLevel` in place. + ### `outputStyle` Select an [output style](/docs/en/output-styles) by name. An output style is a saved set of instructions that Claude Code adds to the system prompt to change Claude's role, tone, and output format, such as the built-in Explanatory and Learning styles or one you wrote yourself. @@ -1231,7 +1260,7 @@ Start sessions with [ultracode](/docs/en/workflows#let-claude-decide-with-ultrac } ``` -Ultracode runs the session at `xhigh` effort and takes precedence over `effortLevel`. An Agent SDK `apply_flag_settings` control request also accepts the key. +Ultracode runs the session at `xhigh` effort and takes precedence over `effortLevel` and [`modelSettings`](#modelsettings) entries. An Agent SDK `apply_flag_settings` control request also accepts the key. ## Permission settings @@ -1556,7 +1585,7 @@ This turns the sandbox on, skips permission prompts for sandboxed commands, runs } ``` -Claude Code takes a Boolean key's value from the highest-precedence settings file that sets it, so a managed `enabled` or `failIfUnavailable` overrides anything a developer sets. It merges array keys across every settings file the session loads, so a developer can append entries; see [Keep developers from widening the policy](/docs/en/sandboxing#keep-developers-from-widening-the-policy) for the managed-only locks. To require the sandbox for an organization, see [Enforce sandboxing with managed settings](/docs/en/sandboxing#enforce-sandboxing-with-managed-settings). +Claude Code takes a Boolean key's value from the highest-precedence settings scope that sets it, so a managed `enabled` or `failIfUnavailable` overrides anything a developer sets. It merges array keys across every settings scope the session loads, so a developer can append entries; see [Keep developers from widening the policy](/docs/en/sandboxing#keep-developers-from-widening-the-policy) for the managed-only locks. To require the sandbox for an organization, see [Enforce sandboxing with managed settings](/docs/en/sandboxing#enforce-sandboxing-with-managed-settings). ### `sandbox.enabled` @@ -1640,7 +1669,7 @@ Name commands that Claude Code always runs outside the sandbox, such as tools th } ``` -Excluded commands still go through the regular permission flow. Exclusion is a convenience, not a security boundary: prefer [`filesystem.allowWrite`](#sandbox-filesystem-allowwrite) when a tool only needs to write somewhere specific. Claude Code merges entries across every settings file the session loads, and there is no managed-only lock for this list, so keep a managed list narrow. +Excluded commands still go through the regular permission flow. Exclusion is a convenience, not a security boundary: prefer [`filesystem.allowWrite`](#sandbox-filesystem-allowwrite) when a tool only needs to write somewhere specific. Claude Code merges entries across every settings scope the session loads, and there is no managed-only lock for this list, so keep a managed list narrow. ### `sandbox.allowUnsandboxedCommands` @@ -1731,7 +1760,7 @@ This lets a build write under `/tmp/build` and lets `kubectl` update your kubeco } ``` -Claude Code merges entries across every settings file the session loads: user, project, local, and managed paths combine rather than replace each other, and Claude Code adds the paths from your `Edit(...)` allow permission rules. An `allowWrite` entry can't lift a [protected path](/docs/en/sandboxing#protected-paths). +Claude Code merges entries across every settings scope the session loads: user, project, local, and managed paths combine rather than replace each other, and Claude Code adds the paths from your `Edit(...)` allow permission rules. An `allowWrite` entry can't lift a [protected path](/docs/en/sandboxing#protected-paths). ### `sandbox.filesystem.denyWrite` @@ -1753,7 +1782,7 @@ This keeps sandboxed commands from changing system configuration or installing b } ``` -Claude Code merges entries across every settings file the session loads, and adds the paths from your `Edit(...)` deny permission rules. +Claude Code merges entries across every settings scope the session loads, and adds the paths from your `Edit(...)` deny permission rules. ### `sandbox.filesystem.denyRead` @@ -1773,7 +1802,7 @@ Block sandboxed commands from reading specific paths, such as credential files t } ``` -Claude Code merges entries across every settings file the session loads, and adds the paths from your `Read(...)` deny permission rules. When [`filesystem.disabled`](#sandbox-filesystem-disabled) is `true`, Claude Code doesn't enforce these entries. +Claude Code merges entries across every settings scope the session loads, and adds the paths from your `Read(...)` deny permission rules. When [`filesystem.disabled`](#sandbox-filesystem-disabled) is `true`, Claude Code doesn't enforce these entries. ### `sandbox.filesystem.allowRead` @@ -1800,12 +1829,12 @@ Place a `.` entry in project settings: it resolves to the project root there and ### `sandbox.filesystem.allowManagedReadPathsOnly` -Honor only the [`allowRead`](#sandbox-filesystem-allowread) entries that come from managed settings, so developers can't re-open read access to paths your organization blocked. Claude Code still merges `denyRead` entries from every settings file the session loads. +Honor only the [`allowRead`](#sandbox-filesystem-allowread) entries that come from managed settings, so developers can't re-open read access to paths your organization blocked. Claude Code still merges `denyRead` entries from every settings scope the session loads. * **Scope**: [`Managed`](#scopes) * **Type**: Boolean * `true`: Claude Code honors only the `allowRead` entries from managed settings - * `false`: `allowRead` entries merge from every settings file the session loads + * `false`: `allowRead` entries merge from every settings scope the session loads * **Default**: `false` This blocks reads of the home directory, re-opens `~/work`, and stops developers from re-opening anything else: @@ -2641,12 +2670,18 @@ This example turns off automatic compaction and routes API requests through a pr * From user settings, `--settings`, and managed settings: at startup, and again in the running session when a saved change alters the merged `env`. * From project and local settings: after you trust the workspace, or at startup in `-p` mode, which never shows the trust dialog, and again when a saved change alters the merged `env`. -* Variables Claude Code classifies as safe, such as model selection, timeouts and limits, feature toggles, and telemetry settings: at startup from every settings file. +* Variables Claude Code classifies as safe, such as model selection, timeouts and limits, feature toggles, and telemetry settings: at startup from every settings file, apart from the [variables project and local settings can't set](#variables-claude-code-ignores-in-env). * After you [move the session with `/cd`](/docs/en/permissions#move-the-session-to-another-directory) on v2.1.246 or later: the new directory's project and local `env` values, on top of the previous directory's. #### Variables Claude Code ignores in `env` -* Project and local settings can't set a few variables, such as `CLAUDE_CODE_PROCESS_WRAPPER`, `CLAUDE_CODE_SYNC_SKILLS`, `CLAUDE_CODE_SYNC_PLUGINS`, `CLAUDE_CODE_PLUGIN_CACHE_DIR`, and `CLAUDE_CODE_PLUGIN_SEED_DIR`; set those in user or managed settings. +* Project and local settings can't set variables that a checked-out repository shouldn't control; set those in your shell, user settings, or managed settings instead. Claude Code drops each one and logs a warning you can see with `claude --debug`. They include: + + * Variables that choose where Claude Code stores or writes its own files: `CLAUDE_CONFIG_DIR`, `CLAUDE_CODE_TMPDIR`, and the operating-system directory variables such as `HOME`, `TMPDIR`, `TMP`, `TEMP`, and the `XDG_*` family. + * Variables that export session content: [`OTEL_LOG_RAW_API_BODIES`](/docs/en/env-vars#variables) and the detailed beta tracing pair `ENABLE_BETA_TRACING_DETAILED` and `BETA_TRACING_ENDPOINT`. + * Variables that change how Claude Code starts or syncs, such as `CLAUDE_CODE_PROCESS_WRAPPER`, `CLAUDE_CODE_SYNC_SKILLS`, `CLAUDE_CODE_SYNC_PLUGINS`, `CLAUDE_CODE_PLUGIN_CACHE_DIR`, and `CLAUDE_CODE_PLUGIN_SEED_DIR`. + + Before v2.1.251, project and local settings could set every variable this list names except `HOME`, `XDG_CONFIG_HOME`, and the variables that change how Claude Code starts or syncs. * Identity variables that Claude Code's hosting environments own, such as `CLAUDE_CODE_REMOTE` and `CLAUDE_CODE_ACCOUNT_UUID`, are ignored from every file. * [`CLAUDE_CODE_MESSAGING_SOCKET` and `CLAUDE_CODE_MESSAGING_TOKEN`](/docs/en/env-vars#variables), which Claude Code exports itself, are ignored from every file. Ignoring the socket variable requires Claude Code v2.1.224 or later, and ignoring the token requires v2.1.228 or later. * [`CLAUDE_CODE_PROJECT_DIR_NAME`](/docs/en/sessions#name-the-project-directory-yourself), which Claude Code reads from the launch environment only, is ignored from every file; requires v2.1.234 or later. @@ -3625,8 +3660,8 @@ Restrict hook execution to hooks your organization deploys. * **Scope**: [`Managed`](#scopes) * **Type**: Boolean * `true`: only managed hooks run, plus Agent SDK hooks and hooks from plugins your managed settings force-enable. See [What runs under `allowManagedHooksOnly`](#what-runs-under-allowmanagedhooksonly) - * `false`: hooks from every settings file and plugin run -* **Default**: unset, so hooks from every settings file and plugin run + * `false`: hooks from every settings scope and plugin run +* **Default**: unset, so hooks from every settings scope and plugin run ```json managed-settings.json theme={null} { @@ -4341,7 +4376,7 @@ On Claude Code v2.1.232 or later, you can write `extraKnownMarketplaces` as `add ### `pluginConfigs` -Store the non-sensitive answers you give a plugin's [`userConfig`](/docs/en/plugins-reference#user-configuration) configuration dialog, keyed by plugin ID. Claude Code writes this key to your user settings when you fill in the dialog, so you don't need to edit it by hand. Sensitive options go to the macOS Keychain instead, or to `~/.claude/.credentials.json` on platforms without a supported keychain. +Store the non-sensitive answers you give a plugin's [`userConfig`](/docs/en/plugins-reference#user-configuration) configuration dialog, keyed by plugin ID. Claude Code writes this key to your user settings when you fill in the dialog, so you don't need to edit it by hand. Claude Code stores sensitive options in the macOS Keychain instead, falling back to `~/.claude/.credentials.json` when the Keychain rejects the write; on platforms without a supported keychain, it stores them in `~/.claude/.credentials.json`. * **Scope**: [`User or managed`](#scopes) * **Type**: object mapping a plugin ID to an object with an `options` field, mapping each option name to a string, number, Boolean, or array of strings, and an optional `mcpServers` field holding per-server user configuration values in the same shape @@ -4407,13 +4442,13 @@ A [`deniedMcpServers`](#deniedmcpservers) entry takes precedence, so a server on ### `allowManagedMcpServersOnly` -Make the managed allowlist the only one that applies. Claude Code then reads [`allowedMcpServers`](#allowedmcpservers) from managed settings alone and ignores allowlists in user, project, and local settings; [`deniedMcpServers`](#deniedmcpservers) still merges from every file, so users can still block servers for themselves. Administrators set it so a user's own settings can't broaden what the managed allowlist permits. +Make the managed allowlist the only one that applies. Claude Code then reads [`allowedMcpServers`](#allowedmcpservers) from managed settings alone and ignores allowlists in user, project, and local settings; [`deniedMcpServers`](#deniedmcpservers) still merges from every settings scope, so users can still block servers for themselves. Administrators set it so a user's own settings can't broaden what the managed allowlist permits. * **Scope**: [`Managed`](#scopes) * **Type**: Boolean * `true`: Claude Code reads `allowedMcpServers` from managed settings alone and ignores allowlists in user, project, and local settings - * `false`: allowlists from every settings file merge -* **Default**: `false`, so allowlists from every settings file merge + * `false`: allowlists from every settings scope merge +* **Default**: `false`, so allowlists from every settings scope merge This example locks the allowlist to managed settings and allows only the server named `github`: @@ -5004,7 +5039,15 @@ Run your own command to produce the credential Claude Code sends with model requ } ``` -Claude Code caches the value and reruns the command after the interval you set with [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/docs/en/env-vars). In interactive sessions, when the command comes from project or local settings, Claude Code doesn't run it until you accept the workspace trust prompt. See [Credential management](/docs/en/authentication#credential-management). +Claude Code caches the value and reruns the command in these cases: + +* After the cache lifetime, five minutes by default or the interval you set with [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/docs/en/env-vars). +* When a request to the Anthropic API, directly or through an [LLM gateway](/docs/en/llm-gateway), fails with `401` or `403`. +* Before sending a request to the Anthropic API, directly or through an LLM gateway, when the cached output is a JWT that expired after the helper produced it. Requires Claude Code v2.1.246 or later. + +The last two cases apply only when the helper's output is the credential Claude Code sends and `ANTHROPIC_AUTH_TOKEN` isn't set. + +In interactive sessions, when the command comes from project or local settings, Claude Code doesn't run it until you accept the workspace trust prompt. See [Credential management](/docs/en/authentication#credential-management). ### `awsAuthRefresh` @@ -5040,7 +5083,7 @@ Unlike [`awsAuthRefresh`](#awsauthrefresh), Claude Code always runs this command ### `forceLoginMethod` -Restrict which kind of account people can log in with. Set `"claudeai"` to allow only claude.ai accounts, `"console"` to allow only Claude Console accounts, or `"gateway"` to send people to a [cloud gateway](/docs/en/claude-apps-gateway) instead of a first-party login. Administrators set it in managed settings and pair it with [`forceLoginOrgUUID`](#forceloginorguuid) to keep developers' claude.ai logins inside one organization. +Restrict which kind of account people can log in with. Set `"claudeai"` to allow only claude.ai accounts, `"console"` to allow only Claude Console accounts, or `"gateway"` to send people to a [cloud gateway](/docs/en/claude-apps-gateway) instead of a first-party login. Administrators set it in managed settings and pair it with [`forceLoginOrgUUID`](#forceloginorguuid) to keep developers' claude.ai logins inside one organization. If you set it to `"claudeai"` or `"console"` in any settings file, Claude Code also stops offering the [keyless Console sign-in](/docs/en/authentication#sign-in-without-an-api-key) in the sessions that file applies to. * **Scope**: [`Any file`](#scopes). Claude Code honors `"gateway"` only from a managed source on the machine: `managed-settings.json`, the macOS plist or Windows HKLM registry, or a policy helper. It treats `"gateway"` as unset in user, project, local, HKCU, and server-managed settings, the same rule as [`forceLoginGatewayUrl`](#forcelogingatewayurl). * **Type**: string, one of: @@ -5075,7 +5118,7 @@ A value that isn't a valid URL is dropped on its own; the rest of the managed se ### `forceLoginOrgUUID` -From a managed source, require claude.ai account logins to belong to one Anthropic organization, a single UUID, or to any of several, an array. From any settings file, a single UUID also pre-selects that organization during a claude.ai or Claude Console login; an array pre-selects nothing. +From a managed source, require claude.ai account logins to belong to one Anthropic organization, given as a single UUID, or to any of several organizations, given as an array. From any settings file, Claude Code also uses a single UUID to pre-select that organization during a claude.ai or Claude Console login, and pre-selects nothing for an array. If you set the key in any settings file, Claude Code also stops offering the [keyless Console sign-in](/docs/en/authentication#sign-in-without-an-api-key) in the sessions that file applies to and creates an API key instead. * **Scope**: [`Any file`](#scopes). Only a managed source enforces the restriction; a single UUID in any other settings file pre-selects the organization during login without restricting it. * **Type**: string, one UUID, or array of strings, several UUIDs diff --git a/content/en/docs/claude-code/settings.md b/content/en/docs/claude-code/settings.md index e1de253a4b..bc88b2981a 100644 --- a/content/en/docs/claude-code/settings.md +++ b/content/en/docs/claude-code/settings.md @@ -626,12 +626,14 @@ For a complete personal file, team file, and organization file, each shown with To try a value without saving it, set it when you start Claude Code. The value applies to that session and your settings files stay as they were. You have three ways to do it: * **`--settings`**: pass a key as JSON, inline or as a path to a file. Claude Code applies it above your user, project, and local files and below managed settings. It can set any key your user settings file can set; it can't set `Managed` or `Global config` keys. -* **A flag for that key**: some keys have their own flag, such as `--model` for `model` and `--effort` for `effortLevel`. +* **A flag for that key**: some keys have their own flag, such as `--model` for `model` and `--effort` for `effortLevel` and `modelSettings`. * **An environment variable**: export the key's paired variable before you run `claude`, such as `ANTHROPIC_MODEL` for `model`. Each key's entry on the [settings reference](/docs/en/settings-reference) lists its per-session overrides and which one takes precedence, so check the entry for the key you want to change. -Commands you run inside a session mostly save your choice: `/config` writes to your settings files, and `/model` and `/effort` save the value as your default for new sessions. Pressing `s` in the `/model` picker switches the model without saving it, and some `/effort` levels, such as `max` and `ultracode`, apply to the current session only; see [Adjust effort level](/docs/en/model-config#adjust-effort-level). +Commands you run inside a session mostly save your choice: `/config` writes to your settings files, `/model` saves the value as your default for new sessions, and `/effort` on your machine saves the level as your default for the model you're using. + +If you press `s` in the `/model` picker, Claude Code switches the model without saving it as your user default. Claude Code applies some `/effort` levels, such as `max` and `ultracode`, to the current session only; see [Adjust effort level](/docs/en/model-config#adjust-effort-level). For example, to start one session on Opus without changing your default: @@ -646,7 +648,7 @@ Claude Code watches your settings files and reloads them when they change, so it Claude Code reads some keys only once, at session start, so an edit to one of them doesn't reach the running session. Admin-side keys that also wait for a restart, such as `requiredMinimumVersion`, are listed under [where and when a policy applies](/docs/en/managed-settings#where-and-when-a-policy-applies). The ones you're most likely to edit mid-session: * [`model`](/docs/en/settings-reference#model): use [`/model`](/docs/en/model-config#setting-your-model) to switch mid-session. Each model has its own prompt cache, so the first request after a switch re-reads the whole conversation uncached; see [Switching models](/docs/en/prompt-caching#switching-models) -* [`effortLevel`](/docs/en/settings-reference#effortlevel): use [`/effort`](/docs/en/model-config#adjust-effort-level) to change it mid-session +* [`effortLevel`](/docs/en/settings-reference#effortlevel) and [`modelSettings`](/docs/en/settings-reference#modelsettings): use [`/effort`](/docs/en/model-config#adjust-effort-level) to change effort mid-session * [`outputStyle`](/docs/en/settings-reference#outputstyle): part of the system prompt, so Claude Code applies the edit after `/clear` or a restart @@ -700,11 +702,12 @@ For a few security-sensitive keys, Claude Code honors a stricter value from a lo ### Lists merge instead of overriding -When you set the same list key, such as `permissions.allow`, in more than one file, Claude Code combines the lists instead of picking one, so each file can add entries without removing another file's. Three keys that hold model lists follow their own rules: +When you set the same list key, such as `permissions.allow`, in more than one file, Claude Code combines the lists instead of picking one, so each file can add entries without removing another file's. Four keys that hold model lists or per-model entries follow their own rules: * [`fallbackModel`](/docs/en/settings-reference#fallbackmodel) is an ordered chain where position carries meaning, so Claude Code takes the whole value from the highest-precedence file that defines it. * [`modelPicker`](/docs/en/settings-reference#modelpicker) holds one ordered list of rows plus a replace flag, so Claude Code never merges rows from two sources. It takes the whole value from the highest of managed settings, `--settings`, and user settings that defines it, and ignores the key in project and local settings. Requires Claude Code v2.1.242 or later. * [`availableModels`](/docs/en/settings-reference#availablemodels): when the managed settings Claude Code applies define it, Claude Code applies that list as-is and ignores entries you add in user, project, or local settings, unless an app that embeds Claude Code supplies its own model list; see [Exceptions to managed settings precedence](#exceptions-to-managed-settings-precedence). Across managed sources the list never merges either; [how Claude Code combines managed sources](/docs/en/managed-settings#how-claude-code-combines-managed-sources) says which source's list applies. Across non-managed scopes Claude Code merges the arrays as usual. +* [`modelSettings`](/docs/en/settings-reference#modelsettings): Claude Code resolves it one model at a time, together with [`effortLevel`](/docs/en/settings-reference#effortlevel). The `modelSettings` entry states which file's value applies to a model. diff --git a/content/en/docs/claude-code/skills.md b/content/en/docs/claude-code/skills.md index 1dc035a1c3..85cad0dbef 100644 --- a/content/en/docs/claude-code/skills.md +++ b/content/en/docs/claude-code/skills.md @@ -389,7 +389,7 @@ The table below shows where the command name comes from for each layout: In a plugin skill, the frontmatter `name` replaces the directory name in the last segment of the command, so `my-plugin/skills/review/SKILL.md` with `name: fancy` becomes `/my-plugin:fancy`. The bare `/fancy` also invokes the skill unless another command already uses that name. If the `name` you write already starts with the plugin's own prefix, Claude Code doesn't add the prefix again on v2.1.246 or later. For example, `name: my-plugin:fancy` still becomes `/my-plugin:fancy`. From v2.1.216 through v2.1.245, Claude Code doubled the prefix when the `name` already carried it. -In [non-interactive sessions](/docs/en/headless), Claude Code doesn't reserve the names `help` and `feedback` for their terminal-only built-in commands, so a plugin skill with one of those names keeps its bare command there. Claude Code still reserves the name of every other terminal-only built-in, such as `/login`, even though the command can't run in those sessions. In those sessions Claude Code also skips a synced skill named `help` or `feedback`, because it [skips a synced skill](#when-a-synced-skill-name-matches-another-command) whose name matches any built-in command whether or not that command can run. From v2.1.216 through v2.1.220, `help` and `feedback` were reserved too, so a plugin skill with one of those names was invocable only by its namespaced command in non-interactive sessions. +In [non-interactive sessions](/docs/en/headless), the names `help` and `feedback` aren't reserved for their terminal-only built-in commands, so a plugin skill with one of those names keeps its bare command there. Every other terminal-only built-in's name, such as `/login`, stays reserved even though the command can't run in those sessions. A synced skill named `help` or `feedback` is still skipped there, because Claude Code [skips a synced skill](#when-a-synced-skill-name-matches-another-command) whose name matches any built-in command whether or not that command can run. For a plugin-root `SKILL.md`, there is no skill directory to take the name from, so `name` supplies the whole final segment. Without a `name` field, Claude Code falls back to the plugin's directory name. diff --git a/content/en/docs/claude-code/slash-commands.md b/content/en/docs/claude-code/slash-commands.md index 1dc035a1c3..85cad0dbef 100644 --- a/content/en/docs/claude-code/slash-commands.md +++ b/content/en/docs/claude-code/slash-commands.md @@ -389,7 +389,7 @@ The table below shows where the command name comes from for each layout: In a plugin skill, the frontmatter `name` replaces the directory name in the last segment of the command, so `my-plugin/skills/review/SKILL.md` with `name: fancy` becomes `/my-plugin:fancy`. The bare `/fancy` also invokes the skill unless another command already uses that name. If the `name` you write already starts with the plugin's own prefix, Claude Code doesn't add the prefix again on v2.1.246 or later. For example, `name: my-plugin:fancy` still becomes `/my-plugin:fancy`. From v2.1.216 through v2.1.245, Claude Code doubled the prefix when the `name` already carried it. -In [non-interactive sessions](/docs/en/headless), Claude Code doesn't reserve the names `help` and `feedback` for their terminal-only built-in commands, so a plugin skill with one of those names keeps its bare command there. Claude Code still reserves the name of every other terminal-only built-in, such as `/login`, even though the command can't run in those sessions. In those sessions Claude Code also skips a synced skill named `help` or `feedback`, because it [skips a synced skill](#when-a-synced-skill-name-matches-another-command) whose name matches any built-in command whether or not that command can run. From v2.1.216 through v2.1.220, `help` and `feedback` were reserved too, so a plugin skill with one of those names was invocable only by its namespaced command in non-interactive sessions. +In [non-interactive sessions](/docs/en/headless), the names `help` and `feedback` aren't reserved for their terminal-only built-in commands, so a plugin skill with one of those names keeps its bare command there. Every other terminal-only built-in's name, such as `/login`, stays reserved even though the command can't run in those sessions. A synced skill named `help` or `feedback` is still skipped there, because Claude Code [skips a synced skill](#when-a-synced-skill-name-matches-another-command) whose name matches any built-in command whether or not that command can run. For a plugin-root `SKILL.md`, there is no skill directory to take the name from, so `name` supplies the whole final segment. Without a `name` field, Claude Code falls back to the plugin's directory name. diff --git a/content/en/docs/claude-code/sub-agents.md b/content/en/docs/claude-code/sub-agents.md index 31d8c7a313..8265d4713e 100644 --- a/content/en/docs/claude-code/sub-agents.md +++ b/content/en/docs/claude-code/sub-agents.md @@ -62,7 +62,7 @@ Explore and Plan skip your CLAUDE.md files and the parent session's git status t A capable agent for complex, multi-step tasks that require both exploration and action. - * **Model**: inherits from the main conversation + * **Model**: the [`CLAUDE_CODE_SUBAGENT_MODEL`](#choose-a-model) model if you set one and nothing assigns a model another way, otherwise the main conversation's model; [Choose a model](#choose-a-model) states the full order * **Tools**: every tool [available to subagents](#available-tools) * **Purpose**: complex research, multi-step operations, code modifications @@ -72,11 +72,11 @@ Explore and Plan skip your CLAUDE.md files and the parent session's git status t Claude Code includes additional helper agents for specific tasks. These are typically invoked automatically, so you don't need to use them directly. - | Agent | Model | When Claude uses it | - | :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | claude | Inherits | When a task doesn't fit a more specialized agent. A catch-all with every tool [available to subagents](#available-tools). Also the default agent for a dispatched [background session](/docs/en/agent-view); [which permission mode it starts in](/docs/en/agent-view#permission-mode-model-and-effort) depends on how the session was started | - | statusline-setup | Sonnet | When you run `/statusline` to configure your status line | - | claude-code-guide | Haiku | When you ask questions about Claude Code features | + | Agent | Model | When Claude uses it | + | :---------------- | :---------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | claude | None of its own; follows the [model order](#choose-a-model) when Claude spawns it as a subagent | When a task doesn't fit a more specialized agent. A catch-all with every tool [available to subagents](#available-tools). Also the default agent for a dispatched [background session](/docs/en/agent-view); [which permission mode it starts in](/docs/en/agent-view#permission-mode-model-and-effort) depends on how the session was started | + | statusline-setup | Sonnet | When you run `/statusline` to configure your status line | + | claude-code-guide | Haiku | When you ask questions about Claude Code features | @@ -293,7 +293,7 @@ The following fields can be used in the YAML frontmatter. Only `name` and `descr | `description` | Yes | When Claude should delegate to this subagent | | `tools` | No | [Tools](#available-tools) the subagent can use. Inherits every tool available to subagents if omitted. If no entry in the list resolves to a tool, the subagent usually [fails to launch](/docs/en/errors#agent-would-be-spawned-with-zero-tools) with an error naming the entries. To preload Skills into context, use the `skills` field rather than listing `Skill` here | | `disallowedTools` | No | Tools to deny, removed from inherited or specified list | -| `model` | No | [Model](#choose-a-model) to use: `sonnet`, `opus`, `haiku`, `fable`, a full model ID (for example, `claude-opus-5`), or `inherit`. Defaults to `inherit` | +| `model` | No | [Model](#choose-a-model) to use: `sonnet`, `opus`, `haiku`, `fable`, a full model ID such as `claude-opus-5`, or `inherit`. When you omit it, the subagent uses the `CLAUDE_CODE_SUBAGENT_MODEL` model if you set one, otherwise the main conversation's model | | `permissionMode` | No | [Permission mode](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`, or `manual` as an alias for `default`. The `manual` alias requires Claude Code v2.1.200 or later. Ignored for [plugin subagents](#choose-the-subagent-scope) | | `maxTurns` | No | Maximum number of agentic turns before the subagent stops. When the subagent reaches the limit, Claude Code returns its output marked as partial, and Claude can [resume it](#resume-subagents) to continue. The partial marking requires Claude Code v2.1.246 or later | | `skills` | No | [Skills](/docs/en/skills) to preload into the subagent's context at startup. The full skill content is injected, not only the description. Subagents can still invoke unlisted project, user, and plugin skills through the Skill tool | @@ -342,22 +342,26 @@ The `model` field controls which [AI model](/docs/en/model-config) the subagent * **Model alias**: use one of the available aliases: `sonnet`, `opus`, `haiku`, or `fable` * **Full model ID**: use a full model ID such as `claude-opus-5` or `claude-sonnet-5`. Accepts the same values as the `--model` flag -* **inherit**: use the same model as the main conversation -* **Omitted**: defaults to `inherit` and uses the same model as the main conversation +* **inherit**: use the same model as the main conversation, even when you set `CLAUDE_CODE_SUBAGENT_MODEL` +* **Omitted**: use the model from the [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/en/model-config#environment-variables) environment variable, or the main conversation's model when you haven't set that variable When Claude invokes a subagent, it can also pass a `model` parameter for that specific invocation. Claude Code resolves the subagent's model in this order: -1. The [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/en/model-config#environment-variables) environment variable, when set to a model alias or model ID -2. The per-invocation `model` parameter -3. The subagent definition's `model` frontmatter +1. The per-invocation `model` parameter +2. The subagent definition's `model` frontmatter, where `inherit` selects the main conversation's model +3. The [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/en/model-config#environment-variables) environment variable, when you set it to a model alias or model ID 4. The main conversation's model -As of v2.1.196, setting `CLAUDE_CODE_SUBAGENT_MODEL` to `inherit` is the same as leaving it unset: resolution continues with the per-invocation `model` parameter, then the frontmatter. In earlier versions, `inherit` forced subagents onto the main conversation's model and ignored both of those sources. +Setting `CLAUDE_CODE_SUBAGENT_MODEL` by itself doesn't change the model the built-in Explore and Plan subagents run on. + +Before v2.1.251, `CLAUDE_CODE_SUBAGENT_MODEL` came first in this order and overrode both the per-invocation parameter and the frontmatter, including `model: inherit`. + +Setting the variable to `inherit` is the same as leaving it unset. Before v2.1.196, that value forced subagents onto the main conversation's model and ignored the other sources. -Claude Code checks the environment variable, per-invocation parameter, and frontmatter values against your organization's [`availableModels`](/docs/en/model-config#restrict-model-selection) allowlist. For a blocked value, it substitutes another model: +Claude Code checks the per-invocation parameter, frontmatter, and environment variable values against your organization's [`availableModels`](/docs/en/model-config#restrict-model-selection) allowlist. For a blocked value, it substitutes another model: * When the blocked value is a family alias such as `opus`, Claude Code runs the subagent on the newest version of that family the allowlist permits, following the same [substitution rules and provider scope](/docs/en/model-config#restrict-model-selection) as `/model`. Before v2.1.222, Claude Code ran the subagent on the inherited model for a blocked family alias as well. -* For any other blocked value, on providers where that substitution doesn't operate, or when the allowlist permits no version of the family, Claude Code runs the subagent on the inherited model instead. +* For any other blocked value, on providers where that substitution doesn't operate, or when the allowlist permits no version of the family, Claude Code runs the subagent on the inherited model instead. If you set `CLAUDE_CODE_SUBAGENT_MODEL`, Claude Code tries that model first, under these same rules. In interactive sessions, Claude Code shows a warning naming the requested model and the model the subagent runs on, for either substitution. diff --git a/content/en/docs/claude-code/terminal-config.md b/content/en/docs/claude-code/terminal-config.md index 1392996902..83043c3e76 100644 --- a/content/en/docs/claude-code/terminal-config.md +++ b/content/en/docs/claude-code/terminal-config.md @@ -308,7 +308,7 @@ Run `/tui fullscreen` to switch and save the preference. Your conversation relau ## Paste large content -When you paste more than 800 characters or more than two lines into the prompt, Claude Code collapses the input to a placeholder such as `[Pasted text #1 +120 lines]` so the input box stays usable. The full content is still sent to Claude when you submit. +When you paste more than 800 characters or more than three lines into the prompt, Claude Code collapses the input to a placeholder such as `[Pasted text #1 +120 lines]` so the input box stays usable. In a terminal window shorter than 12 rows the line limit drops, so Claude Code collapses a three-line paste at 11 rows and any multi-line paste at 10 rows or fewer. Claude Code still sends the full content when you submit. When you delete with a word or line shortcut such as `Ctrl+W` or `Ctrl+K`, or with a vim delete through an `f`/`t` motion such as `df]`, and the deleted range reaches inside a placeholder, Claude Code removes the placeholder whole. You can paste the deletion back to restore it, with [`Ctrl+Y`](/docs/en/interactive-mode#text-editing) after `Ctrl+W`, `Ctrl+U`, or `Ctrl+K`, or with [`p` in NORMAL mode](/docs/en/interactive-mode#editing-normal-mode) after a vim delete. diff --git a/content/en/docs/claude-code/third-party-integrations.md b/content/en/docs/claude-code/third-party-integrations.md index 7e4934deb9..7d0dea912b 100644 --- a/content/en/docs/claude-code/third-party-integrations.md +++ b/content/en/docs/claude-code/third-party-integrations.md @@ -151,7 +151,7 @@ If your organization has specific infrastructure requirements, compare the optio Authentication Claude.ai SSO or email - API key + API key or a [Console sign-in without one](/docs/en/authentication#sign-in-without-an-api-key) API key or AWS credentials API key or AWS credentials GCP credentials diff --git a/content/en/docs/claude-code/tools-reference.md b/content/en/docs/claude-code/tools-reference.md index 13a03d4e05..5d4219808a 100644 --- a/content/en/docs/claude-code/tools-reference.md +++ b/content/en/docs/claude-code/tools-reference.md @@ -180,7 +180,7 @@ Claude Code never auto-backgrounds three kinds of command. It stops them at the * A command that starts with `sleep`. * A command that runs `git` anywhere in it. -* A compound command Claude Code can't fully parse into simple commands. +* A compound command Claude Code can't fully parse into simple commands. Claude Code treats a parameter expansion such as `${VAR}` as unparseable, so it stops a command that ends in `; exit "${PIPESTATUS[0]}"` at the timeout even when the rest of that command parses. The result of a command moved to the background states what happened: diff --git a/content/en/docs/claude-code/troubleshoot-install.md b/content/en/docs/claude-code/troubleshoot-install.md index c875ff6dfc..45e190dec2 100644 --- a/content/en/docs/claude-code/troubleshoot-install.md +++ b/content/en/docs/claude-code/troubleshoot-install.md @@ -1007,7 +1007,31 @@ Run `/login` to re-authenticate. If this happens frequently, check that your sys Parallel sessions on one machine share a saved login and coordinate its renewal so that only one process refreshes the token at a time. Before v2.1.211, waking the machine from sleep could cause two sessions to renew with the same token, which revoked the saved login and prompted every open session to log in again at once. -On macOS, login can also fail when the Keychain is locked or its password is out of sync with your account password, which prevents Claude Code from saving credentials. Run `claude doctor` to check Keychain access. To unlock the Keychain manually, run `security unlock-keychain ~/Library/Keychains/login.keychain-db`. If unlocking doesn't help, open Keychain Access, select the `login` keychain, and choose Edit > Change Password for Keychain "login" to resync it with your account password. +On macOS, Claude Code saves credentials to the login Keychain. When the Keychain rejects the write, such as when it's locked in an SSH session or its password is out of sync with your account password, Claude Code saves your login to the plaintext `~/.claude/.credentials.json` file instead. A Console login that creates an API key fails until the Keychain is writable again. + +To make the Keychain writable again and move your login back into the encrypted Keychain: + + + + Run `claude doctor` to check Keychain access. When the Keychain rejects writes, the report lists a warning that starts with `macOS Keychain is not writable`, followed by a suggested fix. When the report lists no Keychain warning, the Keychain is writable and you can skip to the last step. + + + + ```bash theme={null} + security unlock-keychain ~/Library/Keychains/login.keychain-db + ``` + + Enter your Keychain password when the command asks for it, then run `claude doctor` again. When the unlock worked, the report no longer lists the Keychain warning. + + + + Open Keychain Access, select the `login` keychain, and choose **Edit > Change Password for Keychain "login"** to resync it with your account password. Then run `claude doctor` again. Go on to the next step once the report no longer lists the Keychain warning. + + + + Once the Keychain is writable again, Claude Code moves the credentials back the next time it writes a credential. To force it now, run `/logout` and then `/login`. Logging out removes all stored credentials, including the plaintext file's contents, saved MCP server logins, and plugin sensitive values, so expect to re-authorize MCP servers and re-enter plugin secrets afterwards. Logging in again stores your login in the Keychain. + + ### Bedrock, Agent Platform, or Foundry credentials not loading diff --git a/content/en/docs/claude-code/whats-new/2026-w34.md b/content/en/docs/claude-code/whats-new/2026-w34.md index a6ac0a440d..fb5b0b0ad7 100644 --- a/content/en/docs/claude-code/whats-new/2026-w34.md +++ b/content/en/docs/claude-code/whats-new/2026-w34.md @@ -17,7 +17,7 @@ research preview -

The /design skill brings Claude Design's artboard workflow into the CLI and Claude Code Desktop, built on artifacts. Run it with a brief and Claude publishes a canvas of editable artboards for your UI. Pick one, tweak it, then have Claude implement it. Available on Pro, Max, Team, and Enterprise. Requires v2.1.233 or later.

+

The /design skill brings Claude Design's artboard workflow into the CLI and Claude Code Desktop, built on artifacts. Run it with a brief and Claude publishes a canvas of editable artboards for your UI. Pick one, tweak it, then have Claude implement it. Available on Pro, Max, Team, and Enterprise. Requires v2.1.234 or later.