How to Use Wildcard Permissions Syntax in Claude Code: Complete Guide with Examples

Claude Code's wildcard permissions syntax uses the pattern Tool(pattern) where * matches any substring and ** matches recursive path segments, allowing you to authorize entire categories of commands or file operations without listing them individually.

Claude Code's permission system lets you control which tools the AI agent can invoke using concise wildcard patterns instead of exhaustive whitelists. The shanraisshan/claude-code-best-practice repository documents how to leverage this wildcard permissions syntax effectively across Bash commands and file system operations. Understanding these patterns helps you balance productivity with security by pre-approving routine actions while maintaining strict controls over sensitive operations.

Understanding the Wildcard Permissions Syntax

Claude Code implements a Tool Permission Syntax that follows the pattern Tool(pattern), where the tool name (such as Bash, Edit, or Write) is followed by a pattern in parentheses. The asterisk (*) serves as a wildcard that matches any substring, allowing it to appear at the start, middle, or end of the pattern.

For file system operations, the double asterisk (**) acts as a convenient shorthand for "any number of path segments," enabling recursive matching under a directory. According to the source documentation in best-practice/claude-settings.md (lines 223-227), this syntax applies uniformly across tool types, with specific handling for Bash commands that also matches optional output redirections (e.g., Bash(python:*)).

How Wildcards Work Under the Hood

The permission system processes wildcard rules through three distinct components before executing any command:

• Permission parser: Reads the permissions section from .claude/settings.json or project-level documentation and expands each entry into a match-any rule. The parser treats * as "match any substring" regardless of position.
• Tool dispatcher: Compares incoming tool requests against compiled allow, ask, and deny rule sets. Matches against allow execute immediately, ask triggers confirmation dialogs, and deny blocks the request.
• Sandbox: Executes approved commands in an isolated environment. Wildcard evaluation occurs before sandboxing, meaning the sandbox only receives commands that have already passed permission checks.

As documented in tips/claude-boris-tips-feb-26.md (lines 79-80), the system supports "full wildcard syntax" across all tools, making permissions both expressive and auditable.

Common Wildcard Patterns and Use Cases

The repository provides specific recommendations for when to apply different wildcard patterns:

Bash(npm run *) Allows execution of any npm script without enumerating each one individually. Ideal for projects with numerous build, test, and dev scripts.

Edit(/docs/)** Grants full write access to the documentation tree while keeping source code directories locked down. The ** pattern matches any file recursively under /docs/.

Bash(git push *) in ask Requires confirmation before any push operation. Placing destructive or remote-state-changing commands in the ask list adds a safety layer while maintaining workflow flexibility.

Bash(*) or Bash Equivalent to "allow all commands." Use this only when operating in a properly sandboxed environment where you trust the isolation layer.

Bash(curl *) in deny Prevents arbitrary network calls by blocking all curl commands, reducing the attack surface for malicious or accidental data exfiltration.

Configuration File Setup

Define your wildcard rules in the project's .claude/settings.json file or document them in version-controlled files like best-practice/claude-settings.md. The configuration uses three arrays: allow, ask, and deny.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Edit(/docs/**)",
      "Write(*.md)",
      "Bash(*)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(rm *)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(.env)"
    ]
  }
}

In practice, this configuration produces the following behaviors:

# Allowed – matches Bash(npm run *)

$ claude run Bash(npm run build)

# Triggers confirmation – matches Bash(git push *) in ask list

$ claude run Bash(git push origin main)

# Blocked – matches Bash(curl *) in deny list

$ claude run Bash(curl https://malicious.example.com)

# Allowed – matches Edit(/docs/**)

$ claude edit Edit(/docs/guide/intro.md)

# Denied – attempts to edit outside allowed tree

$ claude edit Edit(/src/main.ts)

The README.md (lines 29-31) also mentions that you can use the /permissions command within Claude Code to view and manage these settings interactively.

Summary

• Pattern structure: Use Tool(pattern) where * matches any substring and ** matches recursive directories.
• Rule types: Place patterns in allow for automatic execution, ask for confirmation prompts, or deny to block completely.
• Bash specifics: Wildcards match command arguments and output redirections (e.g., Bash(python:*)).
• Security order: Permission checks occur before sandboxing, ensuring only authorized commands reach the execution environment.
• Configuration location: Store rules in .claude/settings.json or reference templates in best-practice/claude-settings.md.

Frequently Asked Questions

What is the difference between * and ** in Claude Code permissions?

The single asterisk (*) matches any substring within a single path segment or command argument, while the double asterisk (**) matches any number of directory levels recursively. For example, Edit(/docs/*) matches files directly in the docs folder, but Edit(/docs/**) matches files in /docs/ and all its subdirectories.

Can I use wildcards in the middle of a command pattern?

Yes. According to the Bash wildcard notes in best-practice/claude-settings.md (lines 223-227), the * wildcard can appear at the start, middle, or end of the pattern. This allows patterns like Bash(*:install) to match various package managers or Write(*config*.json) to match configuration files with varying prefixes.

Where should I define wildcard permission rules for my project?

Define active permissions in your repository's .claude/settings.json file, which Claude Code reads at runtime. For documentation and version control purposes, reference implementations and explanations are maintained in best-practice/claude-settings.md and workflow files like /.claude/commands/workflows/best-practice/workflow-claude-settings.md.

Do wildcard permissions bypass the Claude Code sandbox?

No. Wildcard rules are evaluated before the sandbox layer receives the command. The permission check acts as a filter—only commands matching allow rules proceed to the sandbox, while deny rules prevent execution entirely. This means wildcards control whether the sandbox is ever invoked, not the security of the sandbox itself.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}