CowboyLogic/ai-dev / skills/client-config-claudecode
client-config-claudecode
FlaggedManage and maintain Claude Code configuration files and settings. Use this skill whenever the user wants to view, edit, add, remove, or understand any Claude Code settings — permissions, hooks, MCP servers, environment variables, model settings, sandbox, auto mode, or any other configuration field. Trigger on: "add permission", "allow tool", "deny tool", "configure hook", "add MCP server", "change model", "update settings", "show my settings", "what settings do I have", or "set default mode".
| File | Kind | Size |
|---|---|---|
| CHANGELOG.md | markdown | 18.3 KB |
| README.md | markdown | 3.2 KB |
| SKILL.md | skill md | 8.5 KB |
| assets/sources.json | config | 3.2 KB |
| evals/evals.json | config | 10.2 KB |
| references/hooks.md | markdown | 28.0 KB |
| references/mcp.md | markdown | 16.1 KB |
| references/permissions.md | markdown | 21.6 KB |
| references/settings-schema.md | markdown | 39.2 KB |
| scripts/show-settings.py | script | 8.6 KB |
| scripts/update-references.py | script | 5.4 KB |
| scripts/validate-settings.py | script | 35.9 KB |
references/permissions.md
View on GitHub# Permissions Reference
Upstream: `https://code.claude.com/docs/en/permissions.md` and `https://code.claude.com/docs/en/permission-modes.md`.
## Structure in settings.json
```json
{
"permissions": {
"allow": [],
"deny": [],
"ask": [],
"defaultMode": "default",
"additionalDirectories": [],
"blockReadsOutsideWorkingDirectories": false,
"blockWritesOutsideWorkingDirectories": false,
"denyInsteadOfPrompting": false,
"disableBypassPermissionsMode": "disable",
"disableAutoMode": "disable"
},
"skipDangerousModePermissionPrompt": true,
"skipAutoPermissionPrompt": true
}
```
**Rule evaluation order**: deny → ask → allow. First match in that order wins; specificity doesn't change it. A broad deny (`Bash(aws *)`) beats a narrower allow (`Bash(aws s3 ls)`), and a matching ask prompts even if a more specific allow also matches.
A **bare tool name** in `deny` (e.g. `Bash`, or the equivalent `Bash(*)`) removes the tool from Claude's context entirely; a scoped rule (`Bash(rm *)`) keeps the tool and blocks matching calls.
| Key | Notes |
| --- | --- |
| `permissions.blockReadsOutsideWorkingDirectories` | Read/Grep/Glob/LSP refuse paths outside the working directories in every mode, incl. `bypassPermissions`; recognized Bash file readers (`cat` etc.) prompt. `true` from any source applies (v2.1.257+) |
| `permissions.blockWritesOutsideWorkingDirectories` | Changelog only (v2.1.314): Write, Edit and NotebookEdit refuse paths outside the working directories in every permission mode |
| `permissions.denyInsteadOfPrompting` | `true` denies a tool call that would otherwise wait on a permission prompt, so an unattended session keeps going (v2.1.319+). A call still runs if an allow rule, the permission mode or auto mode's classifier approves it; a `PermissionRequest` hook can answer instead. *User or managed* and `--settings`; a repository cannot set it. Applies in `-p`, terminal, VS Code, local Desktop, subagents and agent teams |
| `permissions.disableBypassPermissionsMode` | `"disable"` — rejects `--dangerously-skip-permissions` and ignores subagent `permissionMode: bypassPermissions` |
| `permissions.disableAutoMode` | `"disable"` — same as top-level `disableAutoMode` |
| `skipDangerousModePermissionPrompt` | *(User, local, or managed; top-level key)* Skip the bypass-mode confirmation dialog; Claude Code writes `true` when you accept it once |
| `skipAutoPermissionPrompt` | *(User or managed; top-level key)* Skip the one-time auto mode notice |
---
## Rule syntax: `Tool` or `Tool(specifier)`
Parentheses inside the specifier are literal — no escaping needed.
### Match all uses
```text
Bash → all bash commands (Bash(*) is equivalent)
WebFetch → all web fetches
Read → all file reads
Edit → all file edits
```
### Bash rules (wildcards)
```text
Bash(npm run *) → commands starting with "npm run " (also bare "npm run")
Bash(git commit *) → git commits
Bash(git log * main) → git log ... main
Bash(* --version) → any program's --version
Bash(npm run build) → exact match only
Bash(ls:*) → same as Bash(ls *) — ":*" only valid at the end
```
- The space before `*` enforces a word boundary: `Bash(ls *)` matches `ls -la` and `ls` but NOT `lsof`; `Bash(ls*)` matches both.
- Put the `*` **after the subcommand**. Everything before the first `*` is what limits the rule. An allow rule with `*` before the subcommand, such as `Bash(git * main)`, produces a startup warning (it also matches `git push origin main` and `git -c core.fsmonitor=<script> diff main`).
- A trailing space-plus-`*` matches the bare command only when it is the rule's only wildcard: `Bash(* --help *)` matches `npm --help x` but not `npm --help`.
### Read / Edit rules (gitignore patterns)
```text
Read(./.env) → relative to cwd
Read(.env) → any .env at or under cwd (bare filenames match at any depth)
Read(./secrets/**) → recursive under secrets/
Read(~/Documents/*.pdf) → home-relative
Read(//Users/alice/file) → absolute (double-slash!)
Edit(/src/**/*.ts) → anchored to the settings source (single slash)
```
> [!WARNING]
> `/path` anchors to the *settings source*, not the filesystem root: project and local settings → primary working directory; user settings → `~/.claude/`; `--settings <file>` → that file's directory; CLI flags/session rules → primary working directory. Use `//path` for absolute, `~/` for home.
- `Edit` rules cover all built-in file-editing tools. A path rule written for `Write`, `NotebookEdit`, `Glob`, or legacy `MultiEdit` is accepted but never consulted (startup warning). Always write `Edit(path)` / `Read(path)`. A bare tool-name rule such as a `Write` deny still applies at the tool level.
- `Read` rules are applied best-effort to Grep/Glob, `@file` mentions, and IDE selection context.
- A `Read` deny rule also blocks Edit/Write on the same path (including creating a file). NotebookEdit isn't covered — add an `Edit` deny too.
- Read/Edit deny rules also apply to recognized Bash file commands (`cat`, `head`, `tail`, `sed`, `tee`) and redirect targets, but NOT to commands that read without naming the file (`grep -r pattern .`) or scripts that open files themselves. Use the sandbox for OS-level enforcement.
- Single-segment directory patterns (`src/**`): as an **allow** rule it matches only `<cwd>/src`; as a **deny/ask** rule it matches `src` at *any* depth. Use `**/src/**` for any depth, `/src/**` for top-level only.
- `!` negation (deny/ask only): `Read(*.env)` then `Read(!sample.env)` in the same file's list carves out `sample.env`. Only reaches rules from the same source and listed before it.
- Symlinks: allow rules require both the symlink path and its target to match (else prompts); deny rules block if *either* matches.
- Windows paths are normalized to POSIX: `C:\Users\alice` → `/c/Users/alice`, so `//c/**/.env`.
### WebFetch rules
```text
WebFetch(domain:github.com) → requests to github.com
WebFetch(domain:*.npmjs.org) → subdomains at any depth (not npmjs.org itself)
WebFetch(domain:*) → every domain (domain: rules also feed the sandbox allowed/denied domain list)
```
A bare `WebFetch` allow fetches freely without changing the sandbox network allowlist; `WebFetch(domain:*)` also lets sandboxed commands reach any host. A bare `WebFetch` deny removes the tool; `WebFetch(domain:*)` deny keeps it and refuses every fetch. Wildcards need v2.1.172+.
### MCP rules
```text
mcp__puppeteer → all tools from puppeteer server
mcp__puppeteer__* → same (wildcard form)
mcp__puppeteer__puppeteer_navigate → specific tool
mcp__claude_ai_<server>__<tool> → claude.ai connector tools
```
An `mcp__` rule with parentheses (parameter match) is skipped when loaded from a settings file — use `--disallowedTools` for that.
An MCP allow rule reaches only the server it names (v2.1.299; the permissions docs now state it). For a server whose normalized name contains `__` or ends in `_`, write `mcp__<whole normalized name>__*`: for a server named `reports__v2` that is `mcp__reports__v2__*`, and the bare `mcp__reports__v2` or `mcp__reports` does not allow its tools. Changelog only (v2.1.299): deny and ask rules for `mcp__<server>` now also apply to such servers. For a server whose name contains `__`, the same wildcard form holds for an agent's `tools:` list (changelog only; see `agent-creator-claudecode`, which does not cover a trailing `_` there).
### Tool-name wildcards
Deny/ask rules accept globs in the tool-name position: `"*"` (every tool), `"mcp__*"` (every MCP tool). Allow rules accept tool-name globs only after a literal `mcp__<server>__` prefix (e.g. `mcp__github__get_*`); `"*"`, `"B*"`, or `"mcp__*"` as an allow rule is skipped with a warning. Use canonical tool names (e.g. `TaskStop`, not the label "Stop Task").
### Agent (subagent) rules
```text
Agent(Explore) → Explore subagent
Agent(Plan) → Plan subagent
Agent(my-agent) → custom named agent
```
### Skill rules
```text
Skill(commit) → exact skill name
Skill(review-pr *) → prefix match with any arguments
```
A deny rule naming an alias or unqualified name still blocks the skill (e.g. `Skill(deploy)` blocks nested `apps/web:deploy`); an allow rule matches only the skill's own name and the name in Claude's invocation. Source: `https://code.claude.com/docs/en/skills.md`.
### PowerShell rules (same shape as Bash)
```text
PowerShell(Get-ChildItem *) → also matches aliases gci, ls, dir
PowerShell(Remove-Item *)
```
Aliases are canonicalized; matching is case-insensitive. `|`, `;`, and (PS7+) `&&`/`||` split compound commands — every subcommand must match.
### Cd rules (controls `/cd`, not model-invocable)
```text
Cd(~/code/*) → ~/code/app only (single segment)
Cd(~/code/**) → ~/code and everything under it
Cd(**/node_modules) → any node_modules dir at any depth
```
A bare `Cd` deny disables `/cd`. Any `Cd` allow rule switches `/cd` to allowlist mode. With no `Cd` rules, `/cd` prompts to trust unfamiliar directories.
### Match by input parameter: `Tool(param:value)`
Deny/ask rules only (not allow), built-in tools only — matches a top-level scalar input field:
```text
Agent(model:opus) → Agent calls requesting the Opus tier (alias, not full ID)
Agent(isolation:worktree) → Agent calls requesting a git worktree
Bash(run_in_background:true) → backgrounded Bash calls
```
One parameter per rule; `*` wildcard supported; omitted params never match. A tool's primary content field (`command`, `file_path`, `path`, `notebook_path`, `url`) can't be matched this way — the rule is ignored with a startup warning.
---
## Permission modes (`defaultMode`)
| Mode | Behavior |
| --- | --- |
| `default` | Prompts on first use of each tool. Labeled **Manual**; `"manual"` is accepted as an alias (v2.1.200+) |
| `acceptEdits` | Auto-accepts file edits + common fs commands (`mkdir`, `touch`, `mv`, `cp`) in working/additional dirs |
| `plan` | Reads and runs read-only commands; no source edits until you approve a plan |
| `auto` | Auto-approves with background classifier safety checks |
| `dontAsk` | Auto-denies anything that would prompt; reads inside working dirs and pre-approved tools still run. `AskUserQuestion` and `requiresUserInteraction` MCP tools are denied, as are reads from network paths |
| `bypassPermissions` | Skips prompts, including writes to protected paths like `.git` and `.claude` — DANGEROUS, isolated environments only |
- `auto` and `bypassPermissions` do NOT take effect as `defaultMode` from project or local settings (v2.1.257+) — set them in `~/.claude/settings.json`.
- `--permission-mode` / `--dangerously-skip-permissions` override `defaultMode` for one session.
- **Network paths** (UNC `\\server\share\file` on Windows, `/net/...` automounts on macOS/Linux): from v2.1.292 a file-tool read of one keeps its prompt even with a matching allow rule, an `"allow"` from a `PreToolUse` hook, or auto mode (the classifier doesn't decide it); `dontAsk` denies it. `bypassPermissions` runs it without the prompt.
- In cloud sessions only `acceptEdits`, `plan`, `default`, and `auto` are honored.
**Which mode a session starts in** when `defaultMode` and `--permission-mode` are unset (first matching row wins):
| Session | Starts in |
| --- | --- |
| Any settings file sets `disableAutoMode: "disable"` | `default` |
| `claude -p` or the Agent SDK | `default` in sessions that fetch feature flags. Where flags aren't fetched (third-party provider, telemetry off): `auto` from v2.1.285, `default` before |
| Org HIPAA configuration applied and the session is eligible | `default` from v2.1.285 (auto mode stays available to switch to) |
| Terminal or VS Code extension | `auto` from v2.1.283; earlier: `auto` on Pro/Max/Team in sessions that fetch flags, `default` otherwise |
Changelog only (v2.1.302): `claude -p` and Agent SDK sessions with no permission mode now start in `default` on third-party providers, with telemetry off, or on a fresh install, where the `-p` row above says `auto`; `--permission-mode auto` keeps `auto`. The permission-modes docs page still shows the earlier behavior.
When `auto` is selected but unavailable to the session (a settings file turned it off, an unsupported model, or Anthropic disabled it server-side), the session starts in Manual. The first session after an install or upgrade can choose its mode before flags arrive and so can differ from this table.
**Auto mode classifier model:** it runs on Claude Sonnet 5 by default, not on your `/model` choice, and a classifier model Anthropic configures server-side takes precedence. When the session model is Claude Sonnet 4.6, or `availableModels` excludes Sonnet 5, it runs on the session's model instead, or on an Opus model when the session runs on a Fable model. `CLAUDE_CODE_AUTO_MODE_MODEL` (v2.1.302+; permission-modes docs) picks the model for the client-side classifier; it does not change the model for server-side auto mode. From v2.1.302 (changelog only), a conversation too long for the server-side classifier's safety check is compacted instead of every checked tool call being denied.
**Auto mode behind an LLM gateway or with telemetry/feature flags off** (changelog only, v2.1.319; the permission-modes docs page documents the variable but not this behavior): calls the server-side check cannot review are asked about or denied, with no fallback to the built-in classifier; set `CLAUDE_CODE_AUTO_MODE_SERVER=0` to keep using Claude Code's own classifier (Bedrock, Vertex and Foundry are unchanged). `CLAUDE_CODE_AUTO_MODE_SERVER=1` turns the server-side check on behind a gateway even with `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` set; if managed settings set the latter, they must set the `1` too. The variable itself is documented in the env-vars and permission-modes pages; the v2.1.319 behavior is not. In `claude -p`, auto-mode refusals for lack of a safety check now exit 1 (v2.1.319, changelog only). Also changelog only (v2.1.319): when permission rules or `autoMode` settings are very large, auto mode explains why it refused and, unless `autoMode` deny rules are set, asks you in the terminal, instead of refusing without a reason.
**Bash deny/ask matching** (changelog only, v2.1.319): fixes a case where `deny` and `ask` rules missed commands written with quoted words. Changelog only (v2.1.321–v2.1.325): further permission-check fixes. Deny and ask rules now also match commands run through `sudo`, `env` and similar wrappers; a `Bash` allow rule with an attached wildcard such as `Bash(ls*)` no longer skips the prompt in some cases, and one that names a variable such as `Bash(NODE_ENV*)` now asks; some compound commands that ran unprompted now ask; Write and Edit no longer write a path covered by a `Read` deny rule; deny rules and protected-file prompts apply to the file a `cp` or `mv` into a directory writes; and relative deny and ask rules such as `Read(./.env)` keep covering the project after a `cd` and also apply in added directories.
**Other prompting changes** (changelog only, v2.1.325): read-only git commands now ask first in a repository that is not the project's or one you trusted (name it with `--add-dir`, not the `additionalDirectories` setting, to run them unprompted), and scheduled tasks and `/loop` ask before running a skill that declares `allowed-tools` or hooks (add `Skill(name)` to `permissions.allow` to run it unattended).
**Actions no mode auto-approves** (even `bypassPermissions`): explicit `ask` rules; org connector tools set to `ask`; `AskUserQuestion` and MCP tools marked `requiresUserInteraction`; `rm`/`rmdir` targeting a critical path (circuit breaker — no allow rule or hook `"allow"` approves it; `dontAsk` denies it, `auto` sends it to the classifier); cross-session messaging safeguards; reads outside working dirs while `blockReadsOutsideWorkingDirectories` is on.
---
## Common patterns
### Allow common dev commands
```json
{
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(npm test *)",
"Bash(npm install *)",
"Bash(git status)",
"Bash(git diff *)",
"Bash(git log *)",
"Bash(git add *)",
"Bash(git commit *)",
"WebSearch"
]
}
}
```
### Protect sensitive files
```json
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)",
"Read(~/.ssh/**)",
"Bash(curl *)",
"Bash(wget *)"
]
}
}
```
### Ask before risky operations
```json
{
"permissions": {
"ask": [
"Bash(git push *)",
"Bash(rm *)",
"Bash(docker *)"
]
}
}
```
### Compound commands
A rule like `Bash(safe-cmd *)` does NOT allow `safe-cmd && other-cmd`. Separators: `&&`, `||`, `;`, `|`, `|&`, `&`, newline — each subcommand must match an allow rule. Deny/ask rules match any subcommand, including inside `$(...)`, subshells, and loop bodies. A dangling `&&`/`||` makes the command unparseable (no allow match). "Don't ask again" on a compound command saves one rule per subcommand (up to 5).
### What a Bash rule doesn't match
Rules match command text, not the program. `Bash(git push *)` in deny does NOT stop `git -C . push`, `/usr/bin/git push`, or `sh -c 'git push'`. For real boundaries use the sandbox or a PreToolUse hook.
### Wrapper stripping (Bash)
Stripped before matching (not configurable): `timeout`, `time`, `nice`, `nohup`, `stdbuf`, `command`, `builtin`, zsh `noglob`, and bare `xargs` (no flags). Not stripped: `command -v`, zsh `nocorrect`. A leading assignment of known-safe env vars is stripped for **allow** rules; deny/ask rules match past any leading assignment. Runners (`npx`, `docker exec`, `devbox run`, `direnv exec`, `mise exec`) are NOT stripped — write the full runner+command pair. Exec wrappers (`watch`, `setsid`, `ionice`, `flock`) and `find -exec`/`-delete` can't be approved by a prefix rule; use an exact-match rule.
### Redirections
Output redirects (`>`, `>>`, `2>`) and `tee` targets are checked against `Edit` rules, protected paths, and working dirs (`tee` v2.1.269+). Input redirects (`<`) are checked against `Read` rules (v2.1.257+). `/dev/null`, `2>&1`, here-docs are exempt.
### Built-in read-only Bash commands (no prompt, any mode)
`ls`, `cat`, `echo`, `pwd`, `head`, `tail`, `grep`, `find`, `wc`, `which`, `diff`, `stat`, `du`, `cd`, read-only `git` forms. Not configurable (add `ask`/`deny` to override). Still prompt when: an unquoted glob hits a write/exec-capable command (`find`, `sort`, `sed`, `git`), `docker` targets another daemon, `file` uses `-m`/`-f`, a Windows UNC path appears, or the command can't be parsed (>10,000 chars always prompts). `cd` into a working/additional dir is read-only, except `cd`+`git` into a different dir and `cd`+redirect with an unclear target.
---
## additionalDirectories
Extend file access beyond the working directory:
```json
{
"permissions": {
"additionalDirectories": ["../shared-libs/", "~/my-configs/"]
}
}
```
Settings-file `additionalDirectories` grant file access only — no skills, agents, commands, settings, or CLAUDE.md load from them. Directories added with `--add-dir` / `/add-dir` additionally load skills, commands, subagents, and `enabledPlugins`/`extraKnownMarketplaces`.
---
## Managed-only settings (ignored outside managed sources)
`allowAllClaudeAiMcps`, `allowClaudeInChromeWithManagedMcp`, `allowedChannelPlugins`, `allowedProviders`, `allowManagedHooksOnly`, `allowManagedMcpServersOnly`, `allowManagedPermissionRulesOnly`, `availableModelsMatch`, `blockedMarketplaces`, `channelsEnabled`, `deniedModels`, `disableCommandPluginSources`, `disableSideloadFlags`, `forceRemoteSettingsRefresh`, `managedMcpServers`, `managedSourcesBehavior`, `parentSettingsBehavior`, `pluginSuggestionMarketplaces`, `pluginTrustMessage`, `policyHelper`, `sandbox.filesystem.allowManagedReadPathsOnly`, `sandbox.network.allowManagedDomainsOnly`, `strictKnownMarketplaces`, `strictPluginOnlyCustomization`, `wslInheritsWindowsSettings`. Also managed-only: `gatewayInternalNetworks`, `requiredMinimumVersion`/`requiredMaximumVersion`, browser/mobile-simulator controls, `sshHostAllowlist`, `disableDesktopLocalSessions`, `sandbox.bwrapPath`/`socatPath`, `modelPricing`, `claudeMd`.
`forceLoginGatewayUrl` is not managed-only: v2.1.295+ also reads it from user settings on a machine with no managed source (see `settings-schema.md`).
`disableBypassPermissionsMode` works from any scope but is typically placed in managed settings.
## Settings precedence (highest → lowest)
1. Managed settings (can't be overridden, including by CLI args)
2. Command line arguments
3. Local project settings (`.claude/settings.local.json`)
4. Shared project settings (`.claude/settings.json`)
5. User settings (`~/.claude/settings.json`)
Deny always wins regardless of scope — a user-level deny blocks a project-level allow and vice versa. `--disallowedTools` can add restrictions beyond managed settings; `--allowedTools` can't override a managed deny.
"Yes, and don't ask again" saves the rule to `.claude/settings.local.json` at the git repo root (v2.1.211+), so it applies across subdirectories and worktrees.
## Project allow rules require workspace trust
`permissions.allow` and `permissions.additionalDirectories` from a project's `.claude/settings.json` apply only after accepting the workspace-trust dialog (`deny`/`ask` apply immediately). `.claude/settings.local.json` is exempt from trust unless it's tracked in git or `.claude` is a symlink. `claude -p` / SDK sessions never show the dialog and don't apply untrusted project allow rules.
## Hooks and permissions
PreToolUse hooks run before the permission prompt. A hook `"allow"` does not bypass matching deny/ask rules. A hook exiting 2 blocks even when an allow rule would permit the call.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |