Claude Code Settings Editor

Stop hand-editing settings.json. Click your Claude Code config together in the browser.

Every one of the 129 settings on a card: what it does, your current value, the default, the pro, the con and a suggestion. Press Submit and it backs up your file before it writes a single byte.

Why

Claude Code has a lot of settings, and settings.json tells you nothing about any of them. You have to know that the key exists, what it accepts, and what it costs you when you get it wrong. A typo is a silently broken config, and a bad value can quietly restrict your subagents or delete your chat history.

This tool reads your settings file, lays every setting out with its description, current value, default, pros, cons and a suggested value, lets you click through them, and then writes the file back safely: validated, backed up, merged, re-parsed, and restored from the backup if anything went wrong.

No dependencies, no accounts, no telemetry. It is one Python script and a browser page on localhost.

Quick start

git clone https://github.com/joostgerritsendb/claude-code-settings-editor
cd claude-code-settings-editor
python build-settings-editor.py --serve      # or double-click start.bat (Windows) / ./start.sh (macOS, Linux)

Your browser opens on http://localhost:8799/. Change what you like, click Submit to Claude Code, done. The server applies the changes and stops by itself. Most settings hot-reload into running sessions; model and outputStyle need a restart (or /model mid-session).

About the suggestions

The "Suggestion" line on each card, and the pros and cons next to it, are my personal opinion, based on my own subjective experience of running Claude Code day to day. They are not official guidance, they are not endorsed by Anthropic, and they are not advice you should follow without thinking about your own setup, your own workflow and your own risk appetite.

Read them as "here is what one user found", not as "here is what you must do". The authoritative source is always Anthropic's own documentation: code.claude.com/docs/en/settings.

You use this tool and its suggestions at your own risk. As the MIT licence says in capital letters: no warranty of any kind. If a suggestion turns out not to suit you, that is exactly why every change is backed up first, and why you can put any setting back with one click. If you disagree with a suggestion, open an issue or a PR. Better copy on a card helps the next person.

Tested on

Built and tested on Windows 11 Pro (build 26200) with Python 3.12 and Claude Code 2.1.207.

The code is pure Python standard library and uses no platform-specific calls, so macOS and Linux should work and start.sh is there for them, but I have not verified it on either. If you run it on a Mac or on Linux, an issue or a PR confirming it (or fixing it) is very welcome and will get you into the contributors list.

Features

• 129 settings across 12 categories, each with a description, the pro, the con, a suggestion, the allowed values and a badge when the setting is undocumented.
• Current vs default on every card, so you can see at a glance what you have actually changed.
• Search, category filters and a "Changed" toggle to find a setting in seconds.
• Safe apply: validate every change against the catalog, write a timestamped backup of settings.json to ~/.claude/settings-backups/, merge only the keys you changed, re-parse the result, and restore the backup automatically if it does not parse.
• Read-only guard: hooks, statusLine and enabledPlugins are shown but not editable. They are too structured for a form; ask Claude Code to change those in a session.
• Unknown keys preserved. Anything in your settings.json the catalog does not know is listed separately and written back untouched.
• Remove a key with one click, to put the setting back to Claude Code's default.
• Optional team example profile: show a reference value on every card, handy for a team sharing a house config.
• Docs-freshness check: --check-docs sha256-hashes the official Claude Code settings docs page and compares it with the recorded hash. If the docs changed, or the catalog is older than 30 days, the page shows an amber "catalog may be outdated" banner.
• 100% local. No telemetry, no accounts, no dependencies beyond the Python standard library. The only network call in the whole tool is the optional docs-freshness check.

Safety

Every apply, in order: validate against the catalog (one bad value and nothing at all is written, and you are told why) -> copy settings.json to ~/.claude/settings-backups/{N}-{timestamp}-settings.json -> merge only the changed keys -> re-parse the file -> restore the backup automatically if it does not parse. To roll back by hand, copy the backup you want over ~/.claude/settings.json.

If your settings.json is corrupt before you start, the tool says so, names the file and the JSON error, and writes nothing.

Team example profile

Copy example-settings.sample.json to example-settings.json to show a reference profile on every card, handy for a team sharing a house config. Generate your own with:

python build-settings-editor.py --snapshot-example --label "Our team defaults"

That writes example-settings.json from your current settings (catalog keys only; env.*, *Helper and companyAnnouncements are excluded, so no secret can end up in a file you share). The file is gitignored by default. The label from the file is what each card shows.

Troubleshooting

Submit downloaded a JSON file instead of applying. You opened the HTML file directly instead of running --serve. A page opened from disk cannot talk to the applier. Run --serve (or start.bat), or hand the downloaded settings-changes.json to Claude Code and ask it to apply it.

Port 8799 is busy. It bumps automatically through 8800-8808. Or pass --port 9000.

Amber "catalog may be outdated" banner. The catalog is older than 30 days, or --check-docs saw the official docs page change. Everything still works; ask Claude Code to refresh settings_catalog.json from https://code.claude.com/docs/en/settings and rebuild. PRs with a refreshed catalog are very welcome.

Nothing seems to have changed. Read the terminal. It prints every key: old -> new it applied plus the backup path. If it printed "Validation failed", nothing was written and the reason is listed.

Settings worth knowing before you flip them

• availableModels also restricts which models your subagents may use, not just your session picker.
• permissions.defaultMode: bypassPermissions stops Claude Code asking for confirmation before it runs commands. Fast, and exactly as risky as it sounds.
• A low cleanupPeriodDays deletes your local chat history older than that many days.

Commands

Command	What it does
python build-settings-editor.py --serve	build, serve on localhost, apply what you submit
python build-settings-editor.py	build output/claude-settings-editor.html only
python build-settings-editor.py --open	open the built file directly (Submit falls back to a download)
python build-settings-editor.py --serve --no-open	serve without opening a browser
python build-settings-editor.py --port 9000	serve on a specific port
python build-settings-editor.py --check-docs	check whether the official docs page changed
python build-settings-editor.py --snapshot-example --label "..."	write example-settings.json from your settings
python apply-settings.py	re-apply output/latest-decisions.json by hand
python apply-settings.py --selftest	check the validation and merge logic

Files

File	What it is
build-settings-editor.py	builds the HTML, serves it, runs the applier on submit
apply-settings.py	validates, backs up and merges the submitted changes
settings_catalog.json	the catalog of settings; it drives the whole UI
example-settings.sample.json	a generic example profile to copy to example-settings.json
_manifest.json	docs-freshness tracking (sha256 hashes + last refreshed)
start.bat / start.sh	double-click launchers
output/claude-settings-editor.html	the generated page
output/latest-decisions.json	what you last submitted

Privacy

Your settings never leave your machine. The page is generated on your computer, served from your computer, and submitted back to your computer. There is no account, no telemetry and no analytics.

The single network call in the whole tool is the optional --check-docs freshness check, which fetches Anthropic's public settings documentation page to see whether it has changed. Nothing is sent.

example-settings.json is the only file designed to be shared, and even then env.* variables, *Helper keys and announcements are excluded from it so a credential cannot end up in a file you hand to a colleague.

Contributing

Issues and pull requests are welcome. The most valuable ones:

• Catalog updates when Anthropic ships new settings: edit settings_catalog.json, bump _manifest.json, run python apply-settings.py --selftest, and open the PR. The tool tells you when this is needed by showing an amber banner.
• macOS and Linux confirmations or fixes. See Tested on.
• Better copy on any setting's pro, con or suggestion. If you have been bitten by a setting, the next person should read about it on the card.

Author

Joost Gerritsen, CEO of Digibeetle, a company that makes EU digital law navigable for the people who have to apply it.

• LinkedIn: jbagerritsen
• Digibeetle: digibeetle.eu

If this saved you a trip into settings.json, a star costs nothing and helps other Claude Code users find it.

Licence

MIT. See LICENSE.

---

_{Built with Claude Code (Opus 4.8), 2026-07-13.}