Configuration¶
claude-toolbox provides opinionated defaults for permissions, statusline, hooks, and project settings.
How Configuration Works¶
Note
Claude Code settings are split between two project-scoped files:
.claude/settings.json— upstream-managed defaults, synced from this template (permissions baseline, env vars, model, plugins, statusline).claude/settings.local.json— your per-repo overrides, never synced (hooks, MCP server enables, additional permissions, personal preferences)
Use settings.local.json for personal settings. Template sync merges most settings, but replaces permissions.deny with the upstream secrets baseline and reports removed entries; permissions.allow remains union-merged. The guard protects both settings files from agent edits. A person can edit them directly, or enable the scoped disable_selfmod exception described below.
Permission Baselines¶
The permission guard separates secrets, destructive operations and changes to its own configuration. Its baseline allows ordinary logs, dependencies, build output and .env.example; projects can add their own restrictions. A settings allow entry cannot override a secrets deny.
The tables below are generated from klaude-plugin/scripts/guard/guard-rules.json with make generate-guard. Template sync replaces permissions.deny with the secrets projection; project additions belong in .claude/kk-guard.json. See template sync for dropped-entry reports and the sync_exclusions opt-out. Per-repo MCP tool permissions go in settings.local.json.
Self-modification protection also blocks an agent from adding an allow entry to .claude/settings.json or .claude/settings.local.json. The disable_selfmod example below lets the user authorize those edits for a chosen project; it does not loosen secrets.
Secrets¶
These globs generate the Claude settings deny list and apply in the guard. Add project globs in .claude/kk-guard.json under secrets; user exceptions never loosen secrets.
| Scope | Glob |
|---|---|
| Project | ./**/*.kubeconfig |
| Project | ./**/*.pem |
| Project | ./**/*.tfstate |
| Project | ./**/*.tfstate.backup |
| Project | ./**/.env |
| Project | ./**/.env.*.local |
| Project | ./**/.env.local |
| Project | ./**/.kube/** |
| Project | ./**/.terraform/** |
| Project | ./**/id_ecdsa |
| Project | ./**/id_ed25519 |
| Project | ./**/id_rsa |
| Project | ./**/kubeconfig |
| Project | ./**/kubeconfig.yaml |
| Project | ./**/kubeconfig.yml |
| Project | ./**/service-account*.json |
| Home | ~/.aws/** |
| Home | ~/.claude/.credentials.json |
| Home | ~/.config/gcloud/** |
| Home | ~/.docker/config.json |
| Home | ~/.gnupg/** |
| Home | ~/.kube/** |
| Home | ~/.netrc |
| Home | ~/.pypirc |
| Home | ~/.ssh/** |
Destructive commands¶
Add rules in project config under destructive. User config at ~/.claude/kk-guard.json can disable categories or exempt individual commands with allow_patterns. Native Codex forbids take precedence over those exceptions.
| Category | Command | Denied operation | Codex forbid |
|---|---|---|---|
| filesystem | rm | rm deletes files and directories with no undo | Yes |
| filesystem | shred | shred overwrites file contents before deleting them | Yes |
| filesystem | find | find -delete removes every file the search matches | No |
| filesystem | rsync | rsync --delete (and its --del alias) removes destination files missing from the source | No |
| git | git clean | git clean deletes untracked files, which are not recoverable from git | No |
| git | git reset | git reset --hard discards every uncommitted change | No |
| git | git checkout | git checkout -- <path> and git checkout . discard uncommitted edits | No |
| git | git restore | git restore without --staged discards uncommitted edits in the working tree | No |
| git | git restore | git restore --worktree discards uncommitted edits in the working tree even alongside --staged | No |
| git | git branch | git branch -D deletes a branch even when it is not merged | No |
| git | git branch | git branch --delete --force (also -d -f and -df) deletes a branch even when it is not merged | No |
| git | git push | force pushes and remote deletes rewrite or remove history that may exist only on the remote | No |
| git | git stash drop | git stash drop discards stashed work that git cannot recover | No |
| git | git stash clear | git stash clear discards every stash entry | No |
| infra | terraform destroy | terraform destroy tears down live infrastructure | No |
| infra | terraform apply | terraform apply -destroy tears down live infrastructure | No |
| infra | kubectl delete | kubectl delete removes live cluster resources | No |
| infra | helm uninstall | helm uninstall removes a live release and its resources | No |
| infra | helm delete | helm delete removes a live release and its resources | No |
| infra | docker rm | docker rm removes containers and their writable layers | No |
| infra | docker rmi | docker rmi removes images | No |
| infra | docker container rm | docker container rm removes containers and their writable layers | No |
| infra | docker image rm | docker image rm removes images | No |
| infra | docker system prune | docker system prune removes every unused container, network and image | No |
| infra | docker volume rm | docker volume rm deletes persistent data volumes | No |
| infra | docker volume prune | docker volume prune deletes every unused data volume | No |
| privilege | sudo | sudo runs a command as the administrator | Yes |
| privilege | su | su switches to another user account | Yes |
| privilege | doas | doas runs a command as another user | Yes |
The hook exempts literal rm targets strictly beneath its temporary roots: /tmp, /private/tmp, /var/folders, /private/var/folders, $TMPDIR. Secrets and protected configuration still apply. Codex native rules forbid rm even for temporary targets.
Protected configuration¶
The guard blocks mutations of these paths, including moving their parent directories:
.claude/settings.json.claude/settings.local.json.claude/kk-guard.json~/.claude/settings.json~/.claude/settings.local.json~/.claude/kk-guard.json.codex/hooks.json.codex/rules/**.codex/scripts/**~/.claude/plugins/**
Project config may add paths under selfmod. To let an agent edit settings or guard files for one checkout, the user can add this entry to ~/.claude/kk-guard.json (substitute the absolute project path):
This exception does not allow reading or writing secrets.
Guard Configuration¶
The baseline ships inside the Claude plugin and runs even when neither configuration file exists. The Codex template carries the same engine and declaration. These files are independent of provider permission settings:
| File | Owner and purpose |
|---|---|
<project>/.claude/kk-guard.json | Committed project restrictions; adds secrets globs, destructive rules or protected paths |
~/.claude/kk-guard.json | Machine owner's exceptions; loosens destructive categories or self-modification protection for selected projects |
Project restrictions¶
Project configuration only adds protection. For example:
{
"version": 1,
"secrets": ["./**/local-secrets.json"],
"selfmod": [".project-policy.json"],
"destructive": {
"deployment": [
{"program": "deploy", "subcommand": "prod", "reason": "deploy prod changes production"}
]
}
}
Secrets globs use ./**/ for project paths, ~/ for home paths, or // for absolute paths. They match requested and resolved paths. Project-relative policy stays anchored to the project root even when a shell runs in a subdirectory. Destructive rules use program, optional ordered subcommand, argument regex lists flags_any/flags_all/flags_none, and a reason; use the shipped declaration as the complete rule reference. The only supported named exemption is targets_under_tmp. Project config cannot disable categories or remove baseline rules. Template sync leaves this project-owned file alone.
User exceptions¶
The user edits this file directly; the guard protects it from agent writes. Merge entries into an existing projects object rather than replacing other project entries. For example:
{
"version": 1,
"projects": {
"*": {"allow_patterns": ["^git clean -n"]},
"/absolute/path/to/ops": {"disable_categories": ["infra"]},
"/absolute/path/to/claude-toolbox": {"disable_selfmod": true}
}
}
Use physical absolute project paths (pwd -P). The engine combines * with the single longest matching directory prefix; shorter matching prefixes contribute nothing. Lists are combined, and disable_selfmod is enabled if either selected entry enables it. A parent path covers nested repositories and worktrees.
allow_patterns applies separately to each normalized simple command, including extracted shell bodies. Thus ^git clean -n can exempt git clean -nd, but not the rm in git clean -nd; rm -rf ./work. These patterns never exempt secrets or protected configuration. disable_selfmod permits settings/guard edits only; it also leaves secrets protected. On Codex, native forbids for rm, shred, sudo, su and doas still win over guard exceptions.
Missing config files leave the baseline active. Invalid JSON or invalid supported values produce a visible systemMessage and skip that file's changes; the other valid layer still applies. Unknown keys are reported and ignored. Secrets are never loosened by user configuration.
Hooks¶
The Claude plugin ships two hooks. It needs Bash, jq, Python 3.8+ and Claude Code 2.1.295+ for the declared onFailure: "block" behavior.
| Hook | Trigger | Description |
|---|---|---|
| Plugin root export | SessionStart | Exports TOOLBOX_PLUGIN_ROOT into the session environment so every Bash call has a reliable path to the plugin installation directory |
| Permission guard | PreToolUse on Bash, Read, Grep, Glob, Edit, Write, NotebookEdit, and capy execution tools | Enforces secrets, destructive-command rules, and protected configuration paths; denies on guard failures |
Ordinary allowed calls produce no output and exit 0; invalid-config warnings may emit systemMessage. Denials emit JSON, a reason on stderr, and exit 2. Missing/broken interpreters, a corrupt declaration, crashes and malformed engine output deny the call. Claude also blocks hook failures/timeouts through onFailure: "block". A machine without a working Python interpreter blocks every matched tool, including reads, until repaired.
Codex adapters preserve the guard's denial reason and exit status. A normal policy denial does not mean the hook needs repair; the separate "adapter could not run" diagnostic indicates an adapter failure, such as a missing guard wrapper or unreadable hook input.
The wrapper runs the standard-library-only engine with -I -S, isolating Python environment/user-site settings and skipping unused site startup. On macOS it prefers Python at the standard Homebrew locations, then system Python; elsewhere it checks system Python first. PATH lookup remains the final fallback. Homebrew is not required.
Destructive operations are denied in every permission mode, including bypass mode. The reason names the matched category and the way through: the user runs the operation directly or configures an applicable exception. Disabling Claude hooks removes destructive and self-modification protection. Template users retain the native secrets settings baseline; plugin-only users have no such fallback.
The guard checks capy_execute, capy_execute_file, and capy_batch_execute even when capy is registered under a different MCP server name. Shell code uses the same checks as Bash; other languages use the literal-path, write-call and spawned-command scans described below. Every batch command is checked independently, and one denied command blocks the entire batch before execution.
For capy code, omitted cwd means the project root. Relative cwd overrides resolve from that root; absolute overrides select that directory. Each batch command starts in the selected directory. The capy_execute_file.path input stays project-root-relative regardless of where its processing code runs. These path parameters are literal paths, without shell-variable or tilde expansion.
Code in other languages, whether sent to capy or passed inline to an interpreter in Bash (python3 -c, node -e, a heredoc), is also checked for the commands it starts. The check is lexical. It runs when the code, with its line comments removed, names a process-starting call (subprocess, os.system, child_process, exec(, spawn, popen, exec.Command and similar) or contains a backtick string. Only the code counts here: a call that is merely named inside a string or a comment does not, except that a string which is exactly a spawn module's name ("child_process", "subprocess", "os/exec") is taken for an import. Every string literal is then read as a possible command and the destructive rules apply: a command string such as os.system("git reset --hard"), or adjacent literals forming an argument list such as ["kubectl", "-n", ns, "delete", "pod", name]. Category exceptions and allow_patterns apply as in Bash, where an exception matches a whole command: one that the code is still building, such as "rm -rf build " + extra, is matched with its unknown operand, as rm -rf build $extra would be. This is stricter than Bash in one respect: while a command is still being built, no exception applies to anything in it, including a complete command chained before the continuation or nested in a shell body, and a string passed through .split() counts as still being built. Code that names no such call keeps its literals as data. A literal that merely looks like a destructive command, in code that does name one, is denied.
The temporary-cleanup exemption is narrower here than in Bash. It applies only when the whole command is handed directly to a recognised spawn call, as a closed literal list or a single string, and every target is an absolute path under a temporary root: subprocess.run(["rm", "-rf", "/tmp/build"]). A command that is kept in a variable, concatenated, formatted or given a relative target does not earn it, because the guard cannot see what finally runs. Nor does one whose call takes further operands, as in exec.Command("rm", "-rf", "/tmp/build", extra). One known gap remains: a Node shell line followed by a variable argument list, spawnSync("rm -rf /tmp/build", args, {shell: true}), is treated as whole although Node appends args.
Deleting through a library call is treated as rm, whether or not the code starts a process. The recognised calls are Python's shutil.rmtree (also as rmtree imported by name), os.remove and os.unlink; Node's fs.rm, fs.rmdir and fs.unlink with their Sync forms, also when rmSync, rmdirSync or unlinkSync is imported by name; an unlink(...) function, whose target counts as unknown when it is given several; and an .unlink() method called without a positional argument, as on a pathlib path. A bare rm(...) or rmdir(...) is not one of them, and a call named in a comment or a string is ignored. The rm rule decides the rest, so the filesystem category, its exceptions and the temporary-cleanup exemption apply: shutil.rmtree("/tmp/build") is allowed, while a relative target or one that is not a single literal is denied, as rm "$dir" is in Bash.
This scan is a floor for ordinary code, not containment. It does not see a script that is written to a file and then run, a command assembled at runtime or across separate calls (cmd.append("delete"), a builder chain), a destructive library call other than those deletions (an API client, fs.promises, a deletion call in another language), or a spawn mechanism outside the recognized set. Code inside a string is scanned only where it is plainly run: after -c, -e or --eval in an argument list whose program is a known interpreter, or directly after a variable program such as sys.executable, not as the argument of exec(...) or eval(...). With a variable program, another option before the flag ([sys.executable, "-u", "-c", code]) hides the code, and the code is always read as interpreter code, so a shell body there ([shell, "-c", "rm -rf build"]) is not checked as a command. Inline code for php -r, Rscript -e and deno eval in Bash is not inspected at all.
Line comments are recognised without knowing the language: # or // at the start of a line or after whitespace begins one, and the rest of that line is not scanned for commands or deletion calls. Code that follows such a marker on the same line is therefore missed: after a Python floor division written a // b, after Lua's length operator in n = #items, or in a JavaScript private member declared at the start of a line. A marker attached to code, as in $#array, this.#field or a//b, is not a comment.
A command handed directly to a recognised spawn call as its first argument also gets the secrets and protected-configuration rules, as it would in Bash: subprocess.run("cat .env", shell=True) and subprocess.run(["cp", "payload", ".claude/settings.json"]) are denied. Every other literal gets the destructive rules only, so prose that mentions a secret path is not mistaken for a read. A command string that reaches the call through a variable is therefore checked for destructive commands but not for the secret paths inside it; a secret path that is a literal of its own is always checked.
Inspection is static: the guard does not execute submitted code or read the contents of an execute-file input. Paths assembled dynamically are outside its detection coverage, and non-shell mutation checks cover recognized literal write-call forms. Grep/Glob checks cover the search root, not every result's contents. Other execution tools need their own payload mapping. The Codex template supplies Bash, patch and capy adapters; see Codex limitations.
For shell paths, the guard retains possible directories after literal relative changes and checks existing matches of unquoted filename wildcards. Quoted or escaped wildcard characters remain literal. Interpreter checks decode common character escapes in literal paths while preserving raw strings. These checks inspect filenames and submitted text, without executing code or reading matched file contents.
Statusline¶
Rich statusline with model, context %, git branch, session duration, thinking mode, and rate limits.
Themes: Set CLAUDE_STATUSLINE_THEME to darcula, nord, or catppuccin, and CLAUDE_STATUSLINE_MODE to dark (default) or light to match your terminal background.
Recommended Settings¶
Tip
Configure via claude /config. The config file is usually at ~/.claude.json.
I can't recommend enough disabling auto-compact — I've seen many a time claude starting to compact conversations in the middle of a task, which produces very poor results for the remaining work it does after compacting.
Full /config settings
> /config
────────────────────────────────────────────────────────────
Configure Claude Code preferences
Auto-compact false
Show tips true
Reduce motion false
Thinking mode true
Prompt suggestions true
Rewind code (checkpoints) true
Verbose output false
Terminal progress bar true
Default permission mode Default
Respect .gitignore in file picker true
Auto-update channel latest
Theme Dark mode
Notifications Auto
Output style default
Language Default (English)
Editor mode vim
Show code diff footer true
Show PR status footer true
Model opus
Auto-connect to IDE (external terminal) false
Claude in Chrome enabled by default false
Project Instructions¶
CLAUDE.md— project-specific instructions for Claude Code (checked into the repo).claude/CLAUDE.extra.md— behavioral instructions (independent thinking, fail-loud, assumptions)AGENTS.md— equivalent instructions for Codex