Claude Code CLI Configuration

Hooks

Hooks automate quality checks and enable long-running sessions. They MUST be configured for professional workflows.

Hook Exit Codes

Exit codes decide whether a hook is a gate or a comment. Claude Code treats exit 2 as the blocking status; every other non-zero code is a non-blocking error that lets the action proceed².

Exit code	Effect on PostToolUse	Effect on Stop
0	Success. stderr goes to the debug log only; Claude never sees it	Claude stops
1 (or any other non-zero)	Non-blocking error, stderr not shown to Claude	Claude stops anyway
2	Tool already ran, but Claude sees stderr	Blocks the stop; stderr becomes the reason to continue

Hooks MUST NOT end a check with || true and MUST NOT rely on exit code 1 to gate anything.

PostToolUse: Auto-Format

MUST auto-format after file changes. This catches the “last 10%” of style issues, and MUST surface a formatter failure to Claude instead of discarding it:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-file.sh",
            "args": ["npm", "run", "format", "--", "--write"]
          }
        ]
      }
    ]
  }
}

check-file.sh runs the command it is given against the file Claude just wrote, and reports a failure the only way PostToolUse can — stderr plus exit 2:

#!/usr/bin/env bash
# .claude/hooks/check-file.sh - run "<argv> <edited file>" after Write or Edit.
set -uo pipefail

file=$(jq -r '.tool_input.file_path // empty')
[ -n "$file" ] || exit 0

if ! output=$("$@" "$file" 2>&1); then
  printf '%s failed on %s:\n%s\n' "$*" "$file" "$(tail -n 20 <<<"$output")" >&2
  exit 2
fi

exit 0

Make it executable with chmod +x .claude/hooks/check-file.sh.

PostToolUse: Auto-Lint

SHOULD lint after file changes, using the same script:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-file.sh",
            "args": ["npm", "run", "lint:file", "--"]
          }
        ]
      }
    ]
  }
}

A per-file lint hook is a fast signal, not proof that the change is clean. The whole-change gate below MUST still run.

Stop: Verify Completion

MUST verify before accepting completion on important tasks. A Stop hook that runs the gate commands directly does not work: the shell reports exit 1 on failure, which Claude Code treats as non-blocking. Call a script that exits 2 instead:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/verify-complete.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/verify-complete.sh - Stop hook completion gate.
set -uo pipefail

hook_input=$(cat)

# Claude Code overrides the hook after 8 consecutive blocks; stop asking
# once a previous block already resumed the turn.
if [ "$(jq -r '.stop_hook_active // false' <<<"$hook_input")" = "true" ]; then
  exit 0
fi

failures=""

run_gate() {
  local label=$1
  shift
  local output
  if ! output=$("$@" 2>&1); then
    failures+="${label} failed:"$'\n'"$(tail -n 20 <<<"$output")"$'\n\n'
  fi
}

run_gate "npm test" npm test
run_gate "npm run lint" npm run lint
run_gate "npm run typecheck" npm run typecheck

if [ -n "$failures" ]; then
  printf '%s' "$failures" >&2
  exit 2
fi

exit 0

Why

Every gate runs, so one failing suite does not hide the next; the stderr text becomes the reason Claude is shown for continuing. The stop_hook_active check prevents a gate that can never pass from looping, and Claude Code caps continuations at eight consecutive blocks regardless². A Stop hook is therefore a strong gate, not a guarantee that Claude never stops early.

Hooks MAY instead exit 0 and print blocking JSON on stdout; Claude receives the reason exactly as it receives exit-2 stderr²:

{
  "decision": "block",
  "reason": "npm test failed: 2 failing in src/auth.test.ts"
}

Make the script executable with chmod +x .claude/hooks/verify-complete.sh. A gate whose script is missing or not executable exits 127, which Claude Code reports as a non-blocking error — the session stops with the gate silently disabled².

For a completion condition that applies to one session rather than every session in the project, SHOULD use /goal³ instead of editing settings.json.

Permissions

MUST configure permissions to avoid prompt fatigue without sacrificing safety.

crefft’s Standard Allowlist

Allow rules MUST name reviewed commands. They MUST NOT pre-approve a package runner or environment runner, because those execute whatever argument follows them:

{
  "permissions": {
    "allow": [
      "Bash(npm run build)",
      "Bash(npm run lint)",
      "Bash(npm run typecheck)",
      "Bash(npm test *)",
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git show *)",
      "Bash(git branch *)",
      "Bash(rg *)",
      "Edit(src/**)",
      "Edit(tests/**)",
      "Edit(test/**)",
      "Edit(docs/**)"
    ]
  }
}

Why

No blanket npx. Claude Code strips a fixed set of wrappers before matching a Bash rule, and environment runners such as npx, docker exec, and devbox run are deliberately not in that set: a rule matches whatever follows the runner, so Bash(npx *) pre-approves any package the registry will serve.³ Approve the inner command instead, one rule per command.

Package scripts belong to the repository. Bash(npm run *) approves every script package.json defines now and every script a branch, a dependency bump, or a pull request adds later. Name the scripts you reviewed. A team MAY widen this to Bash(npm run *) for a repository whose manifest it owns and reviews; it MUST NOT do so for code it has not reviewed.

No blanket Read, Glob, or Grep. Read-only tools already run without approval inside the working directory and additional directories,³ so Read(*) adds nothing there and grants the rest of the filesystem, including ~/.aws and ~/.ssh.

Narrow git mutations. Bash(git *) matches every subcommand and every option before it, including git -c core.fsmonitor=<script> diff, which runs a program of the caller’s choosing.³ Allow read-only subcommands; route add, commit, checkout, and push through ask rules.

Ask Rules for Mutation and Network

Commands that change history or reach the network SHOULD prompt rather than run unattended:

{
  "permissions": {
    "ask": [
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git checkout *)",
      "Bash(git push *)",
      "Bash(npm install *)",
      "Bash(npx *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Bash(ssh *)"
    ]
  }
}

Argument-level Bash patterns are fragile — Bash(curl https://github.com/ *) misses curl -X GET, a redirect, or URL=… && curl $URL — so gate the tool and use WebFetch(domain:example.com) for reviewed domains instead of trying to constrain URLs inside a shell rule.³

crefft’s Standard Denylist

Secret material MUST be denied for reads as well as edits:

{
  "permissions": {
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(curl * | bash)",
      "Bash(wget * | bash)",
      "Bash(chmod 777 *)",
      "Bash(> /dev/sd*)",
      "Read(.env)",
      "Read(.env.*)",
      "Read(**/secrets/**)",
      "Read(**/*secret*)",
      "Read(**/*password*)",
      "Read(**/*credential*)",
      "Read(**/*token*)",
      "Read(**/*.pem)",
      "Read(**/*.key)",
      "Read(**/id_rsa*)",
      "Read(~/.aws/**)",
      "Read(~/.ssh/**)",
      "Edit(.env)",
      "Edit(.env.*)",
      "Edit(**/secrets/**)",
      "Edit(**/*secret*)",
      "Edit(**/*password*)",
      "Edit(**/*credential*)",
      "Edit(**/*token*)",
      "Edit(**/*.pem)",
      "Edit(**/*.key)",
      "Edit(**/id_rsa*)"
    ]
  }
}

.mcp.json Configuration

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@0.0.80"]
    }
  }
}

Every entry MUST declare a type. Claude Code reads an entry that has a url but no type as a stdio server, skips it, and reports the misconfiguration.⁶

Slack

Slack serves MCP over JSON-RPC 2.0 on Streamable HTTP at https://mcp.slack.com/mcp. SSE connections and Dynamic Client Registration are not supported.⁷ A bare URL is not an authenticated configuration:

• Registered app. Every MCP client MUST be backed by a registered Slack app with a fixed app ID, and only Marketplace-published or internal apps may use MCP.⁷ Claude Code is one of Slack’s listed partner clients, so a team MAY connect through it without building an app of its own.
• Admin approval. Workspace admins approve MCP clients through the standard Slack app approval process, and an app’s allowed IP ranges apply to MCP traffic too.⁷
• Confidential OAuth. A client of your own authenticates with its client_id and client_secret against https://slack.com/oauth/v2_user/authorize and https://slack.com/api/oauth.v2.user.access, or discovers them from https://mcp.slack.com/.well-known/oauth-authorization-server. Desktop clients SHOULD use PKCE.⁷
• Least-privilege scopes. Grant only the user-token scopes the tools you actually call: search:read.public to search public messages, channels:history to read a channel, chat:write to post.⁷ A read-only workflow MUST NOT request write scopes.

claude mcp add --transport http slack https://mcp.slack.com/mcp

Then run /mcp inside the session: it runs the OAuth flow for remote servers and shows each server’s connection state.⁶

MCP for Visual Iteration

SHOULD use Claude Code’s built-in Chrome integration⁴ for screenshots and browser checks, because it needs no MCP server and drives the browser you are already signed into:

claude --chrome

Prerequisites MUST be met before relying on it⁴:

• Chrome, Edge, or another Chromium browser, plus the Claude in Chrome extension 1.0.36 or later
• Sign-in with /login on a direct Anthropic plan (Pro, Max, Team, or Enterprise) — API-key and claude setup-token sessions keep the integration off
• Not available under Windows Subsystem for Linux

Where those prerequisites do not hold, SHOULD use Microsoft’s @playwright/mcp, pinned to an exact version⁶:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@0.0.80", "--isolated", "--headless"]
    }
  }
}

Why

@anthropic/mcp-puppeteer does not exist on the public registry, and @modelcontextprotocol/server-puppeteer is marked deprecated (“Package no longer supported”)⁷, so both fail before browser automation starts. @playwright/mcp 0.0.80 is the current release⁶ and requires Node.js 18 or newer.

Pin the version: @latest re-resolves on every launch, so an unpinned npx line runs whatever was published since the config was reviewed. --isolated keeps the browser profile in memory, so a session cannot inherit or persist cookies from a previous run, and lets several clients share one workspace without fighting over the persistent profile⁶.

The server drives a real browser with network access. Treat any page it visits as untrusted input: point it at your own development server, and MUST NOT give it credentials that matter more than the task.

Then in conversation:

Take a screenshot of http://localhost:3000/login

Why the browser package is pinned

Prerequisite. @playwright/mcp 0.0.80 requires Node.js 18 or newer.[^8]

Pin the version. @playwright/mcp@latest re-resolves on every start, so a release can change agent behavior between two runs of the same task. Pin the version and bump it deliberately. --isolated keeps the browser profile in memory, and --headless overrides the headed default.[^8]

MCP or CLI. Microsoft notes that CLI invocations exposed as Skills are more token-efficient for coding agents, because they avoid loading large tool schemas and accessibility trees into context, and keeps MCP for work that benefits from persistent browser state and iterative reasoning over page structure, such as exploratory automation and self-healing tests.[^8] Visual iteration is that second case, so this guide configures MCP; a team whose browser work is scripted SHOULD compare the pinned Playwright CLI Skill.

---

Stop Hooks for Auto-Resume

Stop hooks verify completion and auto-resume when criteria are not met. Use the same enforcing gate as Stop: Verify Completion — a plain npm test && npm run lint command exits 1 on failure, which Claude Code treats as non-blocking:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/verify-complete.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

Auto-resume is bounded: Claude Code ends the turn after eight consecutive blocks². A long-running session MUST NOT be planned on the assumption that the hook resumes indefinitely.

Syncing from crefft

Manual installs and automated syncs MUST call scripts/sync-claude-config.sh from a checkout at a pinned release tag. The script requires Bash, Git, and Python 3. It reads agents/ and commands/ at the repository root, plus configs/claude/skills/, configs/claude/infrastructure/, and configs/claude/settings.json. A missing component is an error before any destination write.

Ownership and Settings

The script writes .claude/crefft-receipt.json, recording the release tag, resolved commit SHA, and SHA-256 of every installed file. Consumers MUST commit the receipt alongside the installed files.

Later syncs replace or remove only receipt-owned files. Project-specific agents, commands, and skills beside those files survive. A conflicting unowned path, a symlink, or a locally modified owned file stops the entire sync with a conflict list before any write. The script never deletes whole component directories. Repeating the same release changes neither the files nor the receipt.

For an earlier manual installation without a receipt, consumers MAY pass --adopt to claim existing files whose contents are identical to the release. Different contents still conflict; file modes and timestamps do not establish identity. Review and relocate conflicting files rather than deleting them blindly.

Existing .claude/settings.json is kept, even on upgrades. It is installed only when absent unless --overwrite-settings explicitly permits replacing it. An existing unowned settings file is not claimed by default.

Version Pinning

Consumers MUST select a release tag, not main. The script verifies that HEAD resolves to that tag, that VERSION matches it, and that source inputs are clean. It records both the tag and resolved commit in the receipt. Tarball-only installs are not supported because they lack the Git metadata needed to verify the checkout.

Consumers SHOULD also supply --commit with a full SHA obtained through their release-review process; the workflow exposes the same check as CREFFT_COMMIT. A mismatch fails before destination writes. Passing the checkout’s own SHA without independently reviewing it adds no protection.