# Claude Code CLI Configuration > [crefft](/index.md) > [AI](/guides/ai.md) > Claude Code CLI The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). ## Overview This guide covers Claude Code CLI[^1] configuration: hooks, permissions, subagents, commands, and MCP. For universal AI workflows (Hero Flow, TDD, Visual Iteration), see [AI Workflows](/guides/ai/ai-workflows.md). ## Quick Reference | Task | Command/File | | ------------- | ----------------------- | | Start session | `claude` | | Plan mode | `/plan` | | Headless mode | `claude -p "prompt"` | | Permissions | `/permissions` | | Clear context | `/clear` | | Config file | `.claude/settings.json` | | Hook scripts | `.claude/hooks/*.sh` | | Subagents | `.claude/agents/*.md` | | Commands | `.claude/commands/*.md` | | MCP servers | `.mcp.json` | *** ## Table of Contents 1. [Configuration Files](#configuration-files) 2. [Hooks](#hooks) 3. [Permissions](#permissions) 4. [Subagents](#subagents) 5. [Custom Commands](#custom-commands) 6. [MCP Integration](#mcp-integration) 7. [Long-Running Sessions](#long-running-sessions) 8. [Syncing from crefft](#syncing-from-crefft) *** ## Configuration Files Claude Code uses several configuration files: ```text project/ ├── .claude/ │ ├── settings.json # Permissions, hooks, preferences │ ├── hooks/ # Hook scripts invoked from settings.json │ │ ├── check-file.sh │ │ └── verify-complete.sh │ ├── agents/ # Reusable subagent definitions │ │ ├── code/ # Code quality agents │ │ │ ├── architect.md │ │ │ ├── reviewer.md │ │ │ └── ... │ │ ├── system/ # Infrastructure agents │ │ │ ├── architect.md │ │ │ ├── docker.md │ │ │ └── ... │ │ └── security/ # Security agents │ │ └── ... │ └── commands/ # Custom slash commands │ ├── code.md │ ├── system.md │ └── ... ├── .mcp.json # MCP server configuration ├── AGENTS.md # Project context (see agents-md.md) ├── CLAUDE.md # `@AGENTS.md` import └── GEMINI.md # `@./AGENTS.md` import ``` ### settings.json Structure ```json { "permissions": { "allow": [...], "deny": [...] }, "hooks": { "PostToolUse": [...], "PreToolUse": [...], "Stop": [...] }, "preferences": { "autoCompact": true, "compactThreshold": 100000 } } ``` See [configs/claude/settings.json](/raw/configs/claude/settings.json) for crefft's standard configuration. *** ## Hooks Hooks automate quality checks and enable long-running sessions. They **MUST** be configured for professional workflows. ### Hook Types | Hook | When it Runs | Use Case | | ------------- | ------------------------- | ------------------------------ | | `PostToolUse` | After Claude uses a tool | Auto-format, auto-lint | | `PreToolUse` | Before Claude uses a tool | Validation, logging | | `Stop` | When Claude stops | Verify completion, auto-resume | ### 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[^3]. | 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. #### Why `|| true` replaces the check's status with 0, and exit 1 is non-blocking, so both turn a failed check into a silent success: ```bash # Don't: both of these report success to Claude Code sh -c 'npm run lint || true' # exits 0 even when lint fails sh -c 'npm test && npm run lint' # exits 1, which does not block Stop # Do: report the reason on stderr and exit 2 printf 'lint failed on src/auth.ts\n' >&2 exit 2 ``` ### 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: ```json { "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: ```bash #!/usr/bin/env bash # .claude/hooks/check-file.sh - run " " 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`. #### Why `args` selects Claude Code's exec form, so the script path and each argument are passed verbatim with no shell tokenization — the correct form whenever a command references a path placeholder such as `${CLAUDE_PROJECT_DIR}`[^3]. Reading `.tool_input.file_path` into a quoted variable keeps paths containing spaces intact. Truncating to the last 20 lines keeps the feedback short enough to be actionable. ### PostToolUse: Auto-Lint **SHOULD** lint after file changes, using the same script: ```json { "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: ```json { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/verify-complete.sh", "args": [] } ] } ] } } ``` ```bash #!/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[^3]. 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[^3]: ```json { "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[^3]. For a completion condition that applies to one session rather than every session in the project, **SHOULD** use `/goal`[^4] instead of editing `settings.json`. ### Hook Input Hook commands receive a JSON payload on **stdin** (there are no `$CLAUDE_*` environment variables for tool data). Extract fields with `jq`: | JSON field | Value | Event | | ----------------------- | ------------------------------------------------ | --------------------------- | | `.tool_input.file_path` | Path to file being written/edited | `PostToolUse` | | `.tool_name` | Name of tool being used | `PreToolUse`, `PostToolUse` | | `.stop_hook_active` | `true` when a stop hook already resumed the turn | `Stop` | Example: `file=$(jq -r '.tool_input.file_path // empty')` *** ## Permissions **MUST** configure permissions to avoid prompt fatigue without sacrificing safety. ### Permission Syntax ```text ToolName(pattern) ``` Examples: * `Bash(npm run build)` — Allow exactly `npm run build` * `Bash(npm run *)` — Allow every script `package.json` defines * `Edit(src/**)` — Allow file writes/edits in src/ and subdirectories (file-tool path rules are matched as `Edit(path)`; `Write(path)` rules are not matched and are dead) * `Read(~/.ssh/**)` — Match everything under the home directory's `.ssh` Rules are evaluated deny, then ask, then allow, and the first match wins. A deny rule therefore cannot carry allowlist exceptions, and an ask rule prompts even when a narrower allow rule also matches.[^4] ### 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: ```json { "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.[^4] 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,[^4] 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=