Skip to main content
Back to Blog
· Futurist Systems

Which Claude Code permissions should a small team allow or deny?

Allow the build, test and git commands the team runs every day; deny reads of secret files and any destructive git or shell command; leave everything else on ask. The shared .claude/settings.json we use and the reasoning behind each line.

Claude Code permissions security team setup

Allow the narrow set of commands the team runs every day without thinking (build, typecheck, lint, git add, git commit, git push, opening pull requests), deny reads of secret files and any command that destroys work (git reset --hard, force push, rm -rf), and leave everything else on the default prompt. Put that list in the repo’s .claude/settings.json so it is reviewed like code and applies to every developer and every agent session.

How the rules work

Claude Code reads permissions.allow, permissions.deny and permissions.ask arrays from its settings files. Each entry names a tool and, optionally, a pattern:

  • Bash(npm run build *) allows any command that starts with npm run build. The older Bash(npm run build:*) spelling still works; the space form is the one to write today.
  • Read(./.env) matches reads of that file through Claude’s own file tools; put it in deny to keep secrets out of the context.
  • WebFetch(domain:example.com) scopes fetches to one domain.
  • mcp__server__tool names one tool of one MCP server.

A deny rule wins over an allow rule for the same command, so a broad allow and a narrow deny can coexist. Settings merge across levels: the user’s ~/.claude/settings.json, the repo’s shared .claude/settings.json, and the personal .claude/settings.local.json. For a team, the shared project file is the one that matters, because it is the only one everyone has.

Our shared allow list

This is the complete permissions.allow in our website repo’s .claude/settings.json, quoted as it stands; it uses the older :* spelling, which still works:

"allow": [
  "Bash(npm run build:*)",
  "Bash(npm run dev:*)",
  "Bash(npm run check:*)",
  "Bash(npm run i18n:validate:*)",
  "Bash(npx vercel:*)",
  "Bash(git add:*)",
  "Bash(git commit:*)",
  "Bash(git push:*)",
  "Bash(gh pr:*)",
  "Bash(gh issue:*)"
]

Why each line is there:

  • Build, check, validate. The repo rule says the build must pass before a commit, so the agent runs it constantly. Prompting for it every time trains people to approve without reading.
  • git add, git commit, git push. The pull-request workflow needs all three. Pushing is allowed because main is protected on the git host and a pre-push hook runs lint, build and typecheck locally; a push cannot land on main by itself.
  • gh pr and gh issue. Opening and commenting on pull requests and filing backlog issues are daily actions. Merging is not: a PreToolUse hook blocks any gh pr merge regardless of this allow line (see the next section).

Notice what is absent. There is no Bash(*), no git checkout, no rm, no curl. Those still prompt, and the prompt is the point.

Where allow and deny are not enough

Permission rules match the command string. A hook runs a script with the whole tool call as input and can refuse it with a reason, which lets you enforce policy that a pattern cannot express. Our merge gate is a PreToolUse hook on Bash:

"PreToolUse": [
  { "matcher": "Bash", "hooks": [{ "type": "command", "command": "bash .claude/hooks/block-direct-merge.sh" }] }
]

The script looks for gh pr merge anywhere in the command, including inside bash -c '...' or a heredoc, and refuses it with a reason that points to the merge script instead. A PreToolUse hook refuses in one of two documented ways: exit with code 2 and write the reason to stderr, or print JSON of the form {"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"..."}}. The reason text matters: the agent reads it and takes the right path on the next turn. An earlier version tried to be clever about ignoring the phrase inside commit messages and lost an arms race against every way a shell can hide a string; matching the raw command and asking people to pass long bodies through --body-file was simpler and safe.

The same mechanism fits other team rules: refuse commits to main, refuse edits under migrations/ without a ticket number in the branch name, refuse npm publish outside CI.

A deny list worth copying

Every team’s deny list is short and specific to its own disasters. A starting point:

"deny": [
  "Read(./.env)",
  "Read(./.env.*)",
  "Read(./**/secrets/**)",
  "Bash(git reset --hard *)",
  "Bash(git push --force *)",
  "Bash(git push -f *)",
  "Bash(rm -rf *)"
]

Secrets first: a denied read keeps the value out of the model’s context, which is cheaper than any rule about not printing it. One limit to know: a Read deny covers Claude’s own file tools, not a cat .env typed into Bash. Pair the deny with Claude Code’s sandbox so shell commands cannot reach what the file tools may not. Destructive git second: these are the commands whose undo is a recovery, not a revert. Add your own, one line per incident.

Modes and the bypass flag

permissions.defaultMode sets what happens to everything not covered by a rule. The modes:

  • default: every uncovered action prompts.
  • acceptEdits: file edits are auto-approved, and so are the shell commands that only create or move files in the working directory (mkdir, touch, mv, cp); other commands still prompt.
  • plan: Claude reads and plans without changing anything.
  • auto: Claude decides on its own which actions to approve.
  • dontAsk: uncovered actions are refused instead of prompted.
  • bypassPermissions: no checks at all.

auto and bypassPermissions are ignored when set in the project or local settings file, so a committed file cannot silently switch the team into either. For a shared team file we keep default and widen the allow list instead, because an auto-accept mode turns every missing deny rule into a silent yes.

The bypass mode exists for sandboxed containers with no credentials and no network. On a developer laptop with a real git remote, treat it the way you treat sudo in a shell alias: not in a shared setup. permissions.disableBypassPermissionsMode: "disable" switches it off, and the setting works from any settings scope, so a team can commit it.

Checklist

  1. Write .claude/settings.json in the repo with allow, deny and hooks; review it in a pull request.
  2. Allow only build, check, and the git and PR commands your workflow needs. No Bash(*).
  3. Deny reads of .env and secret directories, and the destructive git commands; turn on the sandbox so Bash cannot read what the file tools may not.
  4. Enforce anything a pattern cannot express with a PreToolUse hook that refuses with a reason.
  5. Keep defaultMode on default; widen allow line by line when a prompt becomes routine; commit disableBypassPermissionsMode: "disable".
  6. Keep personal grants in .claude/settings.local.json, out of version control.
  7. Re-read the file once a quarter and remove lines nobody can explain.

This file is one of the things we read in a Claude Code health check; the scope is on the fleet setup page.

Ready to automate your business?

Get a free workflow analysis to discover your highest-ROI automation opportunities.