update-config

name	update-config
description	Configure the agent via settings.json — permissions, hooks, env vars, and tool rules
when_to_use	Use when the user wants to configure automated behaviours ("from now on when X", "each time X"), grant or revoke tool permissions ("allow bash", "deny write to /etc"), set environment variables, or modify .claude/settings.json and ~/.claude/settings.json. For simple preferences (model choice, verbosity) use the Config tool instead.
argument-hint	what to configure, e.g. 'allow npm commands' or 'run go test before committing'
context	inline
allowed-tools	["read_file"]

Help the user configure the agent by editing the appropriate settings file.

$ARGUMENTS

Settings file locations

Scope	Path	Who sees it
User (global)	~/.claude/settings.json	You, all projects
Project	.claude/settings.json	Everyone in the repo (commit this)
Local	.claude/settings.local.json	You only, this project (gitignore this)

Priority: local → project → user (local wins on conflict).

Settings schema

{
  // Tool permission rules — evaluated top-to-bottom, first match wins.
  // Each rule applies to one tool. Use "*" to match all tools.
  "permissions": {
    "allow": [
      "bash(npm *)",          // allow npm commands
      "bash(go test *)",      // allow go test
      "write_file(src/**)"    // allow writes under src/
    ],
    "deny": [
      "bash(rm -rf *)",       // deny dangerous rm
      "write_file(/etc/**)"   // deny writes to /etc
    ]
  },

  // Environment variables injected into every tool execution.
  "env": {
    "GOFLAGS": "-mod=vendor",
    "NODE_ENV": "development"
  },

  // Hooks — shell commands the harness runs on specific events.
  // Claude itself does NOT run these; the harness does.
  "hooks": {
    // Fires before every tool call. Exit non-zero to block the call.
    "PreToolUse": [
      {
        "matcher": "bash",          // tool name pattern (glob)
        "hooks": [
          { "command": "echo 'about to run bash'" }
        ]
      }
    ],
    // Fires after every tool call.
    "PostToolUse": [
      {
        "matcher": "write_file",
        "hooks": [
          { "command": "gofmt -w $CLAUDE_FILE_PATH 2>/dev/null || true" }
        ]
      }
    ],
    // Fires when the agent finishes a turn.
    "Stop": [
      {
        "hooks": [
          { "command": "notify-send 'Agent done'" }
        ]
      }
    ]
  }
}

Common configuration patterns

Allow a tool or command family:

{ "permissions": { "allow": ["bash(npm *)"] } }

Block a dangerous pattern:

{ "permissions": { "deny": ["bash(rm -rf *)"] } }

Auto-format Go files after every write:

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "write_file", "hooks": [{ "command": "gofmt -w $CLAUDE_FILE_PATH || true" }] }
    ]
  }
}

Run tests before every commit:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "bash(git commit*)", "hooks": [{ "command": "go test ./..." }] }
    ]
  }
}

Set a project-wide environment variable:

{ "env": { "DATABASE_URL": "postgres://localhost/myapp_dev" } }

Steps

1. Read the current contents of the relevant settings file (user or project scope based on the request).
2. Determine the minimal change needed.
3. Show the user the proposed diff before writing.
4. Write the updated JSON, preserving all existing settings.
5. Confirm what was changed and what it does.