How to configure permissions and hooks in Claude Code

Direct answer

Run /permissions in Claude Code to view and manage permission rules. To persist them, put allow, ask, and deny in settings.json. Hooks use the same settings files and run formatting, tests, or safety checks around tool calls. Permission precedence is deny → ask → allow, so an allow rule cannot override a deny rule. These settings control local tools on your computer. BetterToken changes the model API Base URL, API Key, and routing only; it does not bypass local permissions or run hooks for you.

Choose permissions or hooks

Requirement	Use
Run a specific command without prompting	`permissions.allow`
Ask every time before an operation	`permissions.ask`
Block sensitive file reads or dangerous commands	`permissions.deny`
Format or test after a file change	`PostToolUse` hook
Check or block an action before it runs	`PreToolUse` hook
Explain team conventions to the model	`CLAUDE.md`, not a permission rule

Choose the correct scope

File	Scope	Commit to the repository?
`~/.claude/settings.json`	All projects for the current user	No
`.claude/settings.json`	Current project and team	Yes
`.claude/settings.local.json`	Current project on this machine	No

Put permissions, hooks, and environment variables in settings.json, not ~/.claude.json. The latter stores application state and UI settings.

Configure minimal permission rules

Inspect existing rules with /permissions

In Claude Code, run:

/permissions

The UI shows allow, ask, and deny rules with their source files. Check for existing team or managed rules before choosing a user or project setting.

Add narrow rules

This project-level example allows common tests and lint, asks before every git push, and blocks .env reads:

{
  "permissions": {
    "allow": [
      "Bash(npm run lint *)",
      "Bash(npm test *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Replace the commands with scripts that exist in your project. Do not enable bypassPermissions only to remove prompts; the official documentation limits that mode to isolated containers or VMs.

Verify in /permissions

Save the file and run /permissions again. Confirm each rule appears under the expected source, then trigger one allow, ask, and deny case to verify the behavior.

Add a copyable formatting hook

This example runs the project formatter after Claude Code uses Edit or Write:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run format"
          }
        ]
      }
    ]
  }
}

If the file already has permissions, merge hooks into the same top-level JSON object. Do not create a standalone .claude/hooks.json. Run npm run format manually first to confirm it succeeds.

Command hooks run with your system user’s permissions. Use only scripts you have reviewed, and never print API Keys, tokens, .env contents, or other secrets from a hook.

Verify the hook

Run /hooks in Claude Code.
Open PostToolUse and confirm it lists Edit|Write and npm run format.
Ask Claude to modify a test file.
Check the hook output and file format, and confirm the hook ran once without errors.

Claude Code normally reloads settings changes automatically. If it does not, exit the session and restart Claude Code.

Common errors

Symptom	Cause	Fix
Permission rules never apply	They are in `~/.claude.json` or the wrong directory	Move them to `~/.claude/settings.json`, `.claude/settings.json`, or `.claude/settings.local.json`
An allowed action is still blocked	It matches a deny or managed rule	Check sources in `/permissions`; deny takes precedence over ask and allow
A hook never runs	Event or matcher does not match the tool	Inspect `/hooks`; `PreToolUse` runs before execution, `PostToolUse` after success, and matchers are case-sensitive
The hook runs but the command fails	Wrong script, working directory, or dependency	Run the same command manually from the project directory first
Prompts remain after connecting BetterToken	API provider and local permissions are separate	Keep the BetterToken Base URL and configure narrow Claude Code permissions separately
You need to disable all hooks temporarily	A hook may interfere with debugging	Add `"disableAllHooks": true`, then remove it or set it to `false` after debugging

BetterToken boundaries

BetterToken handles Claude Code model API access, model routing, balance, and usage. Claude Code still controls:

File read and write access
Bash confirmation behavior
When hooks run and which scripts they execute
Sandbox, MCP, and project rules

For 401, Base URL, or model mapping errors, see the Claude Code setup guide. For command prompts and automation, troubleshoot permissions and hooks here.

Claude Code

Claude Desktop

Codex

Cursor

Cline

Model calls

Service assurance

Cost and tokens

Concepts

How to configure permissions and hooks in Claude Code

Direct answer

Choose permissions or hooks

Choose the correct scope

Configure minimal permission rules

Add a copyable formatting hook

Verify the hook

Common errors

BetterToken boundaries

References

​Direct answer

​Choose permissions or hooks

​Choose the correct scope

​Configure minimal permission rules

​Add a copyable formatting hook

​Verify the hook

​Common errors

​BetterToken boundaries

​Related docs

​References

Direct answer

Choose permissions or hooks

Choose the correct scope

Configure minimal permission rules

Add a copyable formatting hook

Verify the hook

Common errors

BetterToken boundaries

Related docs

References