Sensible Claude Code Defaults

Install from the VS Code Marketplace

Sets up Claude Code to run on AWS Bedrock, then keeps checking that the setup still works. It writes a short, fixed list of keys to your own ~/.claude/settings.json, keeps your Bedrock API key in your computer's keychain, and tells you plainly when something is wrong — a missing region, an ageing key, a setting that drifted.

An independent tool. Not affiliated with, endorsed by, or sponsored by Anthropic, PBC.

Getting started

Click the braces-and-heartbeat icon in the activity bar on the left. The panel that opens does the rest:

1. Set up now. One button.
2. Paste your Bedrock API key. If you don't have one yet, Create a key opens the exact page in the Amazon console and tells you which tab to use. The panel says where the key goes before you continue.
3. Watch it test. The panel asks Amazon whether the key works and tells you in one sentence, with one button for whatever comes next.

That is the whole setup. Afterwards the panel shows a single line — everything working, or the one thing that isn't and the button that fixes it — with the full list of checks behind Details for whoever is helping you. Every panel action is also in the command palette under Sensible Defaults, for people who prefer it.

Corporate Windows devices

To open Claude in a terminal, run Sensible Defaults: Open Claude Terminal from the Command Palette or use the terminal icon in the Sensible Defaults view title. It launches the verified executable directly, without relying on PATH. Review and trust your workspace first; the launcher does not bypass Workspace Trust.

To also make claude available in new PowerShell/cmd terminals, run Sensible Defaults: Enable Claude in VS Code Terminals. The extension checks the existing command search path and the installed Claude Code binary, then asks before adding the binary directory to new integrated terminals. Reopen your terminal and run claude --version, then claude. Claude Code's own Launch in terminal button checks VS Code's process PATH, which terminal-only changes do not affect. That upstream button may still fail; use Sensible Defaults: Open Claude Terminal instead.

This does not install another Claude copy, create launcher scripts, modify the system PATH, or bypass application controls. Existing executables and script launchers are preserved. Disable Claude Terminal Repair reverses the preference; reopen terminals afterwards. External terminals still need an IT-approved standalone CLI installation. The repair is native-Windows only, not a change to the Windows host from WSL or a remote Linux window.

If a device blocks settings writes or secure key storage, setup shows the failure and keeps your input for retry. Use Copy Diagnostics for Support to collect a redacted report. A certificate error may indicate TLS inspection, but does not prove a specific proxy vendor: ask IT to check the trusted CA configuration. The extension does not import certificates, change NODE_EXTRA_CA_CERTS, or disable certificate verification; existing CA settings are preserved.

Windows permissions are checked using icacls. If its export cannot be read or validated, the warning remains and offers diagnostics for support; it does not claim your settings are private or blindly change an unknown ACL. The check detects grants to Everyone, Users and Authenticated Users, not every possible corporate group or administrator. Never attach your settings file to a chat: it contains your key.

What this extension writes

Everything is written to your user profile, never inside a project folder:

Opting into Windows terminal repair also saves the sensibleDefaults.enableWindowsTerminalCli preference in your VS Code user settings. The terminal PATH addition itself is nonpersistent and is revalidated after reload.

Inside settings.json it manages nine keys and nothing else. The rest of the file — your own settings, their order, your indentation — is left exactly as it was. Here is the whole list, with what the defaults that ship inside the extension set each one to:

The shipped defaults use Amazon's global inference profiles. Requests can be processed outside the AWS region receiving the call. The Model availability section lists model versions and their documented processing geographies, with exact IDs and the last access result for your credential and source region. The catalogue is refreshed through the same GitHub channel as the defaults, so compatible new models can appear without an extension update.

Use Processing policy to limit which geographies the extension may probe and recommend. By default it follows the scopes of your configured model IDs. It never silently switches to a global profile. A custom ID whose geography is not in the catalogue is labelled Unclassified; it is not a residency guarantee. This extension preference does not enforce AWS IAM policy or establish legal compliance.

Enable automatic checks to refresh configured models after 24 hours and alternatives after seven days, when VS Code starts or regains focus. Explicit access denials are eligible after a day; connection failures back off. New catalogue targets are checked when eligible. Fresh results are reused across windows and restarts. Recheck models refreshes immediately.

Each configured Opus, Sonnet, and Haiku ID is verified separately. A working Haiku cannot hide a blocked Sonnet. A blocked unselected release is informational; it does not make a working setup unhealthy. Review available upgrade previews freshly verified candidates in your permitted geography. Existing pins stay in place until you apply a change, and user/Claude Code edits remain protected.

Model evidence is saved locally under the extension's storage directory, outside Settings Sync. It includes IDs, safe reason codes, and timestamps, never the API key. A one-way credential identity is computed in memory and included in the opaque cache context hash; key replacement or removal invalidates the old evidence. Copy administrator request prepares access details for you to review and send yourself.

Both lists are checkable: the nine keys are MANAGED_KEYS in src/config/types.ts, and the values are manifest/defaults.json.

Before any change you get a preview listing every line that will change, and a copy of the previous file is saved to the backups folder above. Restore Previous Configuration puts any of those copies back.

Claude Code writes some of these keys too. Its own /setup-bedrock command and its model-selection prompt write the region and the model names directly. The extension does not fight that: when a managed value no longer matches what it last wrote, the panel reports it — "Claude Code changed the Opus model" — and leaves the value alone. Use Reset to Recommended on that row if you want the recommended value back; nothing is overwritten until you do.

If you use WSL, Remote-SSH, or a dev container

The settings are written on the machine Claude Code runs on, not the machine your screen is attached to. This is the right thing, but it surprises people, so here it is spelled out.

When you open a folder with WSL, Remote-SSH, or Dev Containers, VS Code splits itself across two machines: the window stays on your own computer, and everything that runs code moves to the other side — the Linux distribution, the server you connected to, the container. Claude Code goes with it. So does this extension.

That means the file being managed is the one over there:

A few consequences worth knowing:

• Windows users on WSL: nothing is written to your C: drive. If you go looking in C:\Users\<you>\.claude you will find nothing, or something old. That is expected, not a failure.
• Each machine keeps its own settings and its own key. Connecting to a second server means setting your Bedrock API key there too. They are separate computers, and a keychain does not travel.
• A local window and a remote window are configuring different files. If you fix something and it seems not to have applied, check which one you were in. VS Code shows it in the bottom-left corner: WSL: Ubuntu, SSH: myserver, or nothing at all for a local window.

Not sure which file you are looking at? Run Check Configuration, then Copy Diagnostics for Support — the report names the exact path, and a Remote row saying wsl, ssh-remote, dev-container or local.

Where your Bedrock API key is stored

Your key lives in your editor's secret storage, which is encrypted on disk with a key held in your operating system's keychain — Keychain on macOS, DPAPI on Windows, the login keyring on Linux. That copy is the real one: it is what Set Bedrock API Key writes, what Update Bedrock API Key replaces, and what the age reminder measures.

It is also written into ~/.claude/settings.json, readable only by you — mode 0600 on macOS and Linux, and on Windows an access list with the broad principals removed. That second copy is not optional and not an oversight:

• The Claude Code panel inside VS Code starts its program from VS Code itself, and a program cannot read your keychain. The settings file is the only place it can find the key.
• Integrated terminals get the key a different way — the extension hands it to each new terminal directly, so a terminal never reads it from disk.

Remove Bedrock API Key clears all three at once: secret storage, settings file, and terminals. It does not cancel the key at Amazon — do that in the Bedrock console if you want it to stop working everywhere.

If you already ran Claude Code's own /setup-bedrock, your key is in the settings file but not in secret storage. The panel offers Use the key from my settings file, which saves it without making you find it again. If the two ever hold different keys, nothing is overwritten: the panel asks which one you want.

None of this stops the key being read by what Claude Code starts. That is the first item under Residual risk, and it is the part worth reading.

Network requests

The extension makes the following categories of outbound request. It sends no telemetry, analytics, or crash reports. Any future telemetry would require an opt-in, disclosure, and honouring telemetry.telemetryLevel.

1. Recommended settings and model catalogue.

GET https://raw.githubusercontent.com/cutler-sg/sensible-claude-code-defaults/main/manifest/defaults.json

At most once an hour per window when checks run, and on Check for Updated Recommendations. No key or machine identifier is sent. A five-second timeout falls back to the last valid cached copy, then the bundled copy. Organisations can supply their own manifest URL.

2. Model availability metadata.

GET https://bedrock.<your region>.amazonaws.com/foundation-model-availability/<foundation model id>

Uses your Bedrock bearer key to check agreement, entitlement, authorisation, and regional availability. This requires permission for GetFoundationModelAvailability. A metadata denial does not prove inference is unavailable. New unconfigured candidates require positive preflight before the extension invokes them.

3. Model invocation checks.

POST https://bedrock-runtime.<your region>.amazonaws.com/model/<exact model or profile id>/invoke

During setup, when you run a connection/model check, or after you enable automatic checks. Each request sends a fixed . message and asks for one output token; AWS charges normal inference costs, including input overhead. No project content is sent. Automatic batches use at most two concurrent requests and twelve runtime calls within a 30-second budget. Configured targets may be tested even if your key cannot read availability metadata. Redirects are rejected for authenticated model checks. Raw AWS response text is never displayed or logged.

AWS can automatically initiate a Marketplace subscription on first invocation if the calling principal has the required permissions. Preflight reduces unnecessary invocations but is not an atomic subscription guarantee. An organisation requiring a strict no-subscription policy must withhold Marketplace subscription permissions. The extension never calls agreement-creation APIs. Automatic checks are off until enabled, and can be disabled at any time.

These requests are not proxied by anything of ours: the extension has no proxy configuration of its own and uses the editor's own network stack, so your http.proxy settings apply.

Residual risk

Two things this extension cannot fix, stated plainly rather than left for you to discover.

Every program Claude Code starts inherits your key

Claude Code passes credentials to everything it starts through the process environment. Every program Claude Code launches — every tool, every MCP server, every command it runs on your behalf — inherits your Bedrock API key. Storing the key in a keychain does not change that, and no setting in this extension can.

What actually limits the damage is the key itself: how much it is allowed to do, and how long it lasts.

• Give the key access to Bedrock and nothing else.
• Prefer a key with an expiry. AWS recommends short-term keys for production use; a long-term key is more convenient for a setup you want to keep working, which is why this extension accepts either.
• Replace it periodically. The panel reminds you after 90 days and insists after 180.
• If you administer the AWS account, cap key lifetime centrally with iam:ServiceSpecificCredentialAgeDays rather than relying on people to rotate.

The project scan finds some copies of your key, not all of them

When a key is saved, the panel checks your open project folders for a copy of it — the case where a tutorial told you to paste it into a .env and it is now on its way to a git remote. A clean result is worth something, but it is not a guarantee. Here is exactly what it does and does not do. The whole of it is src/credential/leakScan.ts, if you would rather read the code than take this on trust.

It looks at the places a key actually gets pasted, inside the folders you currently have open:

• files named .env or .env.something, and .envrc
• files ending in .json, .md, .txt, .yaml, .yml, .toml, .sh, .ps1, .bat, .cmd or .bak — the last one because a settings file copied before editing becomes settings.json.bak
• Dockerfile, and Dockerfile.anything
• the shell profiles: .zshrc, .bashrc, .bash_profile, .zprofile and .profile

It does not look at anything else — your source files, your notebooks, your editor's own settings, your shell history, your terminal scrollback, or any folder you do not have open in this window. It ignores files larger than 1 MB.

It skips some folders. node_modules, .git and .venv are skipped wherever they appear. dist and out are skipped only when they sit directly inside a folder you have open, because that is where build output lives — a dist or out further down is an ordinary source folder and is read normally.

It stays inside the folders you opened. It does not follow shortcuts or symbolic links out of a folder. If a folder you opened is itself a shortcut to somewhere else, the scan reads the real location it points at and names files by where they actually are.

It stops after three seconds, or 5,000 files. On a large project it will not have looked at everything, and it says so — a row reading "we ran out of time" is not a clean result, and the panel never reports one as if it were. If it finds a copy of your key and runs out of time, it tells you both: the file it found is real, but the list is not necessarily the whole list, and running the check again picks up where it left off.

It does not look inside your git history. If the key has ever been committed, it is in past versions of the repository and in every clone of it. Deleting the line today does not remove it, and neither does deleting the branch. When the scan finds your key in a file that git is tracking, it says so and tells you to replace the key — because replacing it is the only thing that actually works.

It never edits your files. Nothing in this extension writes inside a project folder, ever. If your key is found, you are shown which file, and you remove it.

It does not run in a folder you have not trusted. Reading your project files is the one thing this extension does that touches your code, so in a restricted window it does not read them at all, and the panel says the folder was not checked rather than pretending it was clean.

Getting help

Copy Diagnostics for Support puts a report on your clipboard describing your setup: your versions and platform, which recommended settings are in force, your ~/.claude/settings.json, the health check results, and the last 50 lines from the extension's output log. Your Bedrock API key — and anything else that looks like a credential — is replaced with «redacted» before it reaches the clipboard, so the report is safe to paste into a public issue. Nothing is written to a file: the report exists only on your clipboard until you paste it.

Questions and bugs both go to GitHub issues. A way for your key to end up somewhere it should not be is the one thing that does not go in a public issue — email security@cutler.sg instead; the scope is in SECURITY.md.

Uninstalling

Uninstalling the extension removes the extension. It does not undo what the extension wrote, so here is the rest of it.

Do this first, while the extension is still installed: run Remove Bedrock API Key. That is the only convenient way to get the key out of your editor's secret storage — VS Code does not clear an extension's secrets when you uninstall it (microsoft/vscode#123817, still open), and there is no per-extension item you can go and delete by hand on any platform: the secrets live encrypted inside VS Code's own state, and the only thing in your macOS Keychain, Windows DPAPI store or Linux keyring is the key that decrypts all of them, shared by every extension. If you have already uninstalled, reinstall, run the command, and uninstall again.

Then, at your leisure:

• ~/.claude/settings.json keeps the nine keys, your Bedrock API key among them. Nothing removes them for you. Delete the env entries you no longer want, or restore a backup before you uninstall.
• ~/.claude/sensible-defaults/ stays. It holds state.json and up to ten backups of your previous settings — and a backup taken after you set your key contains that key in plain text. rm -rf ~/.claude/sensible-defaults when you are done with them.
• Cached recommendations and model-check evidence sit in VS Code's own extension storage. Model evidence includes tested model IDs, source region context, and timestamps. These files go when VS Code cleans up the extension's data.
• Your project folders have nothing to clean up. The extension never wrote anything inside one.

Why this exists

Claude Code on Bedrock needs half a dozen environment variables to be right at once, in a file most people have no reason to open, and the failure modes all look the same from the outside: it just does not work. This extension writes those variables, keeps your key somewhere better than a shell profile, and turns "it does not work" into a sentence naming which one of them is wrong.

That is the whole of it. It is not a proxy and it is not a gateway: your requests go from Claude Code straight to AWS, it never sees a prompt or a response, and it performs only the minimal inference checks described above. It configures a tool that somebody else wrote, and says so.

MIT licensed. The source is at github.com/cutler-sg/sensible-claude-code-defaults — every claim on this page is a file in it.