managing-permissions

name

managing-permissions

description

Guide for configuring Claude Code permissions in settings.json with security best practices for allow, ask, and deny rules. Use when: (1) Setting up or modifying permissions in settings.json, (2) Discussing tool permissions, access control, or security configuration, (3) User mentions allowing, blocking, or restricting specific tools or file access, (4) Configuring Bash command permissions, file access (Read/Edit/Write), or WebFetch restrictions, (5) Questions about what permissions are safe vs risky, (6) Troubleshooting permission-related errors or "permission denied" issues, (7) Reviewing security configuration or hardening Claude Code access.

Managing Permissions

Configure Claude Code permissions to control tool access and protect sensitive files.

Overview

Permissions are configured in settings.json using three groups: allow, ask, and deny.

Rule precedence: Deny > Ask > Allow

Configuration hierarchy (highest to lowest):

1. Managed settings (enterprise policies)
2. Command-line arguments
3. Local project settings (.claude/settings.local.json)
4. Shared project settings (.claude/settings.json)
5. User global settings (~/.claude/settings.json)

Permission Groups

Allow

Grants explicit permission for tool use without confirmation.

When to use: Safe, routine operations that don't risk data loss or security exposure.

Examples: Reading source code, running tests, read-only git commands.

See references/allow-permissions.md for guidance and examples.

Ask

Prompts for user confirmation before allowing tool use.

When to use: Operations requiring review, such as publishing changes or modifying dependencies.

Examples: Git push/commit, package installation, editing critical config files.

See references/ask-permissions.md for examples and avoiding permission fatigue.

Deny

Explicitly blocks tool use. Takes precedence over allow and ask rules.

⚠️ Important: Deny rules are workflow controls, NOT security mechanisms. They have significant limitations (tool-specific, easily bypassed, prefix-only matching for Bash).

When to use:

• Resource management (blocking node_modules, build artifacts to save tokens)
• Workflow guardrails (preventing accidental git push to main)
• Focus management (avoiding deprecated/legacy code)

NOT for security: For protecting secrets and credentials, use hooks instead (PreToolUse hooks provide tool-agnostic protection).

See references/deny-permissions.md for key limitations and proper use cases.

Basic Syntax

All permission rules follow this format:

ToolName(pattern)

Available Tools: Bash, Read, Edit, Write, Glob, Grep, WebFetch, WebSearch, NotebookEdit, Task, Skill, SlashCommand, TodoWrite, AskUserQuestion, BashOutput, KillShell, ExitPlanMode

Most common: Bash, Read, Edit, Write, Glob, Grep, WebFetch

Pattern types:

• Bash: Prefix matching - Bash(git status) matches "git status", "git status file.txt"
• File tools: Glob matching - Read(src/**) matches all files in src/ recursively

Important: Bash patterns use prefix-only matching and can be bypassed with command chaining. See deny-permissions.md for complete limitations.

See references/official-reference.md for complete syntax reference and known limitations.

Configuration Workflow

When setting up permissions:

1. For security: Use hooks - Protect secrets with PreToolUse hooks (deny rules aren't sufficient for security)
2. Add deny rules - Block large files (node_modules, build artifacts) to save tokens, prevent workflow mistakes
3. Add allow rules - Enable routine safe operations
4. Add ask rules - Require confirmation for important operations
5. Test configuration - Verify typical workflows work correctly
6. Iterate - Add rules as needed based on actual usage

Getting Started

For security: Use PreToolUse hooks to protect secrets and credentials (see Claude Code documentation on hooks).

Sample workflow configuration:

{
  "permissions": {
    "deny": [
      // Resource management (save tokens)
      "Read(node_modules/**)",
      "Read(build/**)",
      "Read(dist/**)",
      "Read(*.min.js)",

      // Workflow guardrails (prevent mistakes)
      "Bash(git push origin main:*)",
      "Bash(npm publish:*)"
    ],
    "allow": [
      "Bash(npm run test:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Read(src/**)",
      "Read(tests/**)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(npm install:*)"
    ]
  }
}

Note: Hooks handle security (secrets, credentials). Deny rules handle workflow controls.

Reference Files

Concise guides with practical examples:

• references/allow-permissions.md - What to allow (non-destructive, reversible operations), practical examples, key principles
• references/ask-permissions.md - What to ask for (external changes, dependencies, critical configs), avoiding permission fatigue
• references/deny-permissions.md - Key limitations (tool-specific), proper use cases (resource management, workflow guardrails), why hooks are needed for security
• references/layering-permissions.md - Strategic permission layering (broad allow + narrow ask/deny), how precedence enables maintainable configurations, critical warning about build tools
• references/git-permissions.md - Git-specific permission patterns, security implications of git commands
• references/build-tool-permissions.md - Recommended configuration patterns for build tools (npm, gradle, maven, make, cargo, etc.), core principles, decision framework
• references/official-reference.md - Complete technical reference, glob syntax, known limitations