clover's git

config

1	---
2	name: update-config
3	description: Configure Claude Code settings.json and settings.local.json, including hooks, permissions, environment variables, and hook troubleshooting. Use for requests to change Claude Code configuration or automate behavior around Claude tool events.
4	---
5
6	Adapted from Claude Code 2.1.289's built-in `update-config` skill for Codex.
7
8	Before choosing settings keys or hook payloads, read the relevant current [settings reference](https://code.claude.com/docs/en/settings-reference) or [hooks reference](https://code.claude.com/docs/en/hooks). The built-in skill's generated JSON schema is replaced by these live references.
9
10	Claude tool names below are hook matchers, not Codex tool names. From Codex, use the available file and shell tools for edits and pipe-tests. Hooks fire inside Claude Code; verify them in a disposable Claude session when available. A pipe-test alone does not prove that Claude loaded or ran a hook. Report runtime verification accurately. `/config` and `/hooks` are Claude UI commands for the user.
11
12	# Update Config Skill
13
14	Modify Claude Code configuration by updating settings.json files.
15
16	## When Hooks Are Required (Not Memory)
17
18	If the user wants something to happen automatically in response to an EVENT, they need a **hook** configured in settings.json. Memory/preferences cannot trigger automated actions.
19
20	**These require hooks:**
21	- "Before compacting, ask me what to preserve" → PreCompact hook
22	- "After writing files, run prettier" → PostToolUse hook with Write|Edit matcher
23	- "When I run bash commands, log them" → PreToolUse hook with Bash matcher
24	- "Always run tests after code changes" → PostToolUse hook
25
26	**Hook events:** PreToolUse, PostToolUse, PreCompact, PostCompact, Stop, Notification, SessionStart
27
28	## CRITICAL: Read Before Write
29
30	**Always read the existing settings file before making changes.** Merge new settings with existing ones - never replace the entire file.
31
32	## CRITICAL: Use request_user_input_async for Ambiguity
33
34	When the user's request is ambiguous, use request_user_input_async to clarify:
35	- Which settings file to modify (user/project/local)
36	- Whether to add to existing arrays or replace them
37	- Specific values when multiple options exist
38
39	## Decision: /config command vs Direct Edit
40
41	**Suggest the `/config` slash command** for these simple settings:
42	- `theme`, `editorMode`, `verbose`, `model`
43	- `language`, `alwaysThinkingEnabled`
44	- `permissions.defaultMode`
45
46	**Edit settings.json directly** for:
47	- Hooks (PreToolUse, PostToolUse, etc.)
48	- Complex permission rules (allow/deny arrays)
49	- Environment variables
50	- MCP server configuration
51	- Plugin configuration
52
53	## Workflow
54
55	1. **Clarify intent** - Ask if the request is ambiguous
56	2. **Read existing file** - Read the target settings file with the available file or shell tools
57	3. **Merge carefully** - Preserve existing settings, especially arrays
58	4. **Edit file** - Edit the file, or create it if absent within the requested scope
59	5. **Confirm** - Tell user what was changed
60
61	## Merging Arrays (Important!)
62
63	When adding to permission arrays or hook arrays, **merge with existing**, don't replace:
64
65	**WRONG** (replaces existing permissions):
66	```json
67	{ "permissions": { "allow": ["Bash(npm *)"] } }
68	```
69
70	**RIGHT** (preserves existing + adds new):
71	```json
72	{
73	"permissions": {
74	"allow": [
75	"Bash(git *)", // existing
76	"Edit(.claude)", // existing
77	"Bash(npm *)" // new
78	]
79	}
80	}
81	```
82
83	## Settings File Locations
84
85	Choose the appropriate file based on scope:
86
87	| File | Scope | Git | Use For |
88	|------|-------|-----|---------|
89	| `~/.claude/settings.json` | Global | N/A | Personal preferences for all projects |
90	| `.claude/settings.json` | Project | Commit | Team-wide hooks, permissions, plugins |
91	| `.claude/settings.local.json` | Project | Gitignore | Personal overrides for this project |
92
93	Settings load in order: user → project → local (later overrides earlier).
94
95	## Settings Schema Reference
96
97	### Permissions
98	```json
99	{
100	"permissions": {
101	"allow": ["Bash(npm *)", "Edit(.claude)", "Read"],
102	"deny": ["Bash(rm -rf *)"],
103	"ask": ["Edit(//etc/*)"],
104	"defaultMode": "default" | "plan" | "acceptEdits" | "dontAsk",
105	"additionalDirectories": ["/extra/dir"]
106	}
107	}
108	```
109
110	**Permission Rule Syntax:**
111	- Exact match: `"Bash(npm run test)"`
112	- Prefix wildcard: `"Bash(git *)"` - matches `git`, `git status`, `git commit`, etc.
113	- Tool only: `"Read"` - allows all Read operations
114	- File paths: `"Edit(src/**)"` - path rules in `permissions` use `Edit(path)` for every file-writing tool (Write, Edit, NotebookEdit) and `Read(path)` for reads. `Write(path)`, `NotebookEdit(path)` and `Glob(path)` rules are not matched by file permission checks. Bare tool names (`"Write"`), deny/ask `Tool(param:value)` rules and hook `if` conditions still use each tool's own name
115
116	### Environment Variables
117	```json
118	{
119	"env": {
120	"DEBUG": "true",
121	"MY_API_KEY": "value"
122	}
123	}
124	```
125
126	### Model & Agent
127	```json
128	{
129	"model": "sonnet", // or "fable", "opus", "haiku", full model ID
130	"agent": "agent-name",
131	"alwaysThinkingEnabled": true
132	}
133	```
134
135	### Attribution (Commits & PRs)
136	```json
137	{
138	"attribution": {
139	"commit": "Custom commit trailer text",
140	"pr": "Custom PR description text"
141	}
142	}
143	```
144	Set `commit` or `pr` to empty string `""` to hide that attribution. To hide all of it, set both to `""` and also set `"sessionUrl": false`. Write this object form, not `"attribution": false`: older Claude Code versions reject true or false here and then skip the whole settings file.
145
146	### MCP Server Management
147	```json
148	{
149	"enableAllProjectMcpServers": true,
150	"enabledMcpjsonServers": ["server1", "server2"],
151	"disabledMcpjsonServers": ["blocked-server"]
152	}
153	```
154
155	### Plugins
156	```json
157	{
158	"enabledPlugins": {
159	"formatter@anthropic-tools": true
160	}
161	}
162	```
163	Plugin syntax: `plugin-name@source` where source is `claude-code-marketplace`, `claude-plugins-official`, or `builtin`.
164
165	### Other Settings
166	- `language`: Preferred response language (e.g., "japanese")
167	- `cleanupPeriodDays`: Days to keep transcripts before automatic cleanup (default: 30; minimum 1)
168	- `respectGitignore`: Whether to respect .gitignore (default: true)
169	- `spinnerTipsEnabled`: Show tips in spinner
170	- `timeFormat`: Clock format for times shown in the UI: "auto" (default), "12-hour", "24-hour", "24-hour-utc", or a strftime pattern such as "%H:%M"
171	- `timeZone`: IANA time zone for times shown in the UI, e.g. "UTC" (default: system time zone)
172	- `spinnerVerbs`: Customize spinner verbs (`{ "mode": "append" | "replace", "verbs": [...] }`)
173	- `spinnerTipsOverride`: Override spinner tips (`{ "excludeDefault": true, "tips": ["Custom tip"] }`)
174	- `syntaxHighlightingDisabled`: Disable diff highlighting
175
176
177	## Hooks Configuration
178
179	Hooks run commands at specific points in Claude Code's lifecycle.
180
181	### Hook Structure
182	```json
183	{
184	"hooks": {
185	"EVENT_NAME": [
186	{
187	"matcher": "ToolName|OtherTool",
188	"hooks": [
189	{
190	"type": "command",
191	"command": "your-command-here",
192	"timeout": 60,
193	"statusMessage": "Running..."
194	}
195	]
196	}
197	]
198	}
199	}
200	```
201
202	### Hook Events
203
204	| Event | Matcher | Purpose |
205	|-------|---------|---------|
206	| PermissionRequest | Tool name | Run before permission prompt |
207	| PreToolUse | Tool name | Run before tool, can block |
208	| PostToolUse | Tool name | Run after successful tool |
209	| PostToolUseFailure | Tool name | Run after tool fails |
210	| Notification | Notification type | Run on notifications |
211	| Stop | - | Run when Claude stops (including clear, resume, compact) |
212	| PreCompact | "manual"/"auto" | Before compaction |
213	| PostCompact | "manual"/"auto" | After compaction (receives summary) |
214	| UserPromptSubmit | - | When user submits |
215	| SessionStart | - | When session starts |
216
217	**Common tool matchers:** `Bash`, `Write`, `Edit`, `Read`, `Glob`, `Grep`
218
219	### Hook Types
220
221	**1. Command Hook** - Runs a shell command:
222	```json
223	{ "type": "command", "command": "prettier --write $FILE", "timeout": 30 }
224	```
225
226	**2. Prompt Hook** - Evaluates a condition with LLM:
227	```json
228	{ "type": "prompt", "prompt": "Is this safe? $ARGUMENTS" }
229	```
230	Only available for tool events: PreToolUse, PostToolUse, PermissionRequest.
231
232	**3. Agent Hook** - Runs an agent with tools:
233	```json
234	{ "type": "agent", "prompt": "Verify tests pass: $ARGUMENTS" }
235	```
236	Only available for tool events: PreToolUse, PostToolUse, PermissionRequest.
237
238	### Hook Input (stdin JSON)
239	```json
240	{
241	"session_id": "abc123",
242	"tool_name": "Write",
243	"tool_input": { "file_path": "/path/to/file.txt", "content": "..." },
244	"tool_response": { "success": true } // PostToolUse only
245	}
246	```
247
248	### Hook JSON Output
249
250	Hooks can return JSON to control behavior:
251
252	```json
253	{
254	"systemMessage": "Warning shown to user in UI",
255	"continue": false,
256	"stopReason": "Message shown when blocking",
257	"suppressOutput": false,
258	"decision": "block",
259	"reason": "Explanation for decision",
260	"hookSpecificOutput": {
261	"hookEventName": "PostToolUse",
262	"additionalContext": "Context injected back to model"
263	}
264	}
265	```
266
267	**Fields:**
268	- `systemMessage` - Display a message to the user (all hooks)
269	- `continue` - Set to `false` to block/stop (default: true)
270	- `stopReason` - Message shown when `continue` is false
271	- `suppressOutput` - Hide stdout from transcript (default: false)
272	- `decision` - "block" for PostToolUse/Stop/UserPromptSubmit hooks (deprecated for PreToolUse, use hookSpecificOutput.permissionDecision instead)
273	- `reason` - Explanation for decision
274	- `hookSpecificOutput` - Event-specific output (must include `hookEventName`):
275	- `additionalContext` - Text injected into model context
276	- `permissionDecision` - "allow", "deny", or "ask" (PreToolUse only)
277	- `permissionDecisionReason` - Reason for the permission decision (PreToolUse only)
278	- `updatedInput` - Modified tool input (PreToolUse only)
279
280	### Common Patterns
281
282	**Auto-format after writes:**
283	```json
284	{
285	"hooks": {
286	"PostToolUse": [{
287	"matcher": "Write|Edit",
288	"hooks": [{
289	"type": "command",
290	"command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write \"$f\"; } 2>/dev/null || true"
291	}]
292	}]
293	}
294	}
295	```
296
297	**Log all bash commands:**
298	```json
299	{
300	"hooks": {
301	"PreToolUse": [{
302	"matcher": "Bash",
303	"hooks": [{
304	"type": "command",
305	"command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt"
306	}]
307	}]
308	}
309	}
310	```
311
312	**Stop hook that displays message to user:**
313
314	Command must output JSON with `systemMessage` field:
315	```bash
316	# Example command that outputs: {"systemMessage": "Session complete!"}
317	echo '{"systemMessage": "Session complete!"}'
318	```
319
320	**Run tests after code changes:**
321	```json
322	{
323	"hooks": {
324	"PostToolUse": [{
325	"matcher": "Write|Edit",
326	"hooks": [{
327	"type": "command",
328	"command": "jq -r '.tool_input.file_path // .tool_response.filePath' | grep -E '\\.(ts|js)$' && npm test || true"
329	}]
330	}]
331	}
332	}
333	```
334
335
336	## Constructing a Hook (with verification)
337
338	Given an event, matcher, target file, and desired behavior, follow this flow. Each step catches a different failure class — a hook that silently does nothing is worse than no hook.
339
340	1. **Dedup check.** Read the target file. If a hook already exists on the same event+matcher, show the existing command and ask: keep it, replace it, or add alongside.
341
342	2. **Construct the command for THIS project — don't assume.** The hook receives JSON on stdin. Build a command that:
343	- Extracts any needed payload safely — use `jq -r` into a quoted variable or `{ read -r f; ... "$f"; }`, NOT unquoted `| xargs` (splits on spaces)
344	- Invokes the underlying tool the way this project runs it (npx/bunx/yarn/pnpm? Makefile target? globally-installed?)
345	- Skips inputs the tool doesn't handle (formatters often have `--ignore-unknown`; if not, guard by extension)
346	- Stays RAW for now — no `|| true`, no stderr suppression. You'll wrap it after the pipe-test passes.
347
348	3. **Pipe-test the raw command.** Synthesize the stdin payload the hook will receive and pipe it directly:
349	- `Pre|PostToolUse` on `Write|Edit`: `echo '{"tool_name":"Edit","tool_input":{"file_path":"<a real file from this repo>"}}' | <cmd>`
350	- `Pre|PostToolUse` on `Bash`: `echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | <cmd>`
351	- `Stop`/`UserPromptSubmit`/`SessionStart`: most commands don't read stdin, so `echo '{}' | <cmd>` suffices
352
353	Check exit code AND side effect (file actually formatted, test actually ran). If it fails you get a real error — fix (wrong package manager? tool not installed? jq path wrong?) and retest. Once it works, wrap with `2>/dev/null || true` (unless the user wants a blocking check).
354
355	4. **Write the JSON.** Merge into the target file (schema shape in the "Hook Structure" section above). If this creates `.claude/settings.local.json` for the first time, add it to .gitignore — the Write tool doesn't auto-gitignore it.
356
357	5. **Validate syntax + schema in one shot:**
358
359	`jq -e '.hooks.<event>[] | select(.matcher == "<matcher>") | .hooks[] | select(.type == "command") | .command' <target-file>`
360
361	Exit 0 + prints your command = correct. Exit 4 = matcher doesn't match. Exit 5 = malformed JSON or wrong nesting. A broken settings.json silently disables ALL settings from that file — fix any pre-existing malformation too.
362
363	6. **Prove the hook fires** — only for `Pre|PostToolUse` on a matcher you can trigger in-turn (`Write|Edit` via Edit, `Bash` via Bash). `Stop`/`UserPromptSubmit`/`SessionStart` fire outside this turn — skip to step 7.
364
365	For a **formatter** on `PostToolUse`/`Write|Edit`: introduce a detectable violation via Edit (two consecutive blank lines, bad indentation, missing semicolon — something this formatter corrects; NOT trailing whitespace, Edit strips that before writing), re-read, confirm the hook **fixed** it. For **anything else**: temporarily prefix the command in settings.json with `echo "$(date) hook fired" >> /tmp/claude-hook-check.txt; `, trigger the matching tool (Edit for `Write|Edit`, a harmless `true` for `Bash`), read the sentinel file.
366
367	**Always clean up** — revert the violation, strip the sentinel prefix — whether the proof passed or failed.
368
369	**If proof fails but pipe-test passed and `jq -e` passed**: the settings watcher isn't watching `.claude/` — it only watches directories that had a settings file when this session started. The hook is written correctly. Tell the user to start a new session so the new settings load. You can't do this yourself.
370
371	7. **Handoff.** Report whether Claude actually ran the hook, only the pipe-test passed, or a new Claude session is needed. Point to the settings file for review, editing, or disabling. The UI only shows "Ran N hooks" if a hook errors or is slow — silent success is invisible by design.
372
373
374	## Example Workflows
375
376	### Adding a Hook
377
378	User: "Format my code after Claude writes it"
379
380	1. **Clarify**: Which formatter? (prettier, gofmt, etc.)
381	2. **Read**: `.claude/settings.json` (or create if missing)
382	3. **Merge**: Add to existing hooks, don't replace
383	4. **Result**:
384	```json
385	{
386	"hooks": {
387	"PostToolUse": [{
388	"matcher": "Write|Edit",
389	"hooks": [{
390	"type": "command",
391	"command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write \"$f\"; } 2>/dev/null || true"
392	}]
393	}]
394	}
395	}
396	```
397
398	### Adding Permissions
399
400	User: "Allow npm commands without prompting"
401
402	1. **Read**: Existing permissions
403	2. **Merge**: Add `Bash(npm *)` to allow array
404	3. **Result**: Combined with existing allows
405
406	### Environment Variables
407
408	User: "Set DEBUG=true"
409
410	1. **Decide**: User settings (global) or project settings?
411	2. **Read**: Target file
412	3. **Merge**: Add to env object
413	```json
414	{ "env": { "DEBUG": "true" } }
415	```
416
417	## Common Mistakes to Avoid
418
419	1. **Replacing instead of merging** - Always preserve existing settings
420	2. **Wrong file** - Ask user if scope is unclear
421	3. **Invalid JSON** - Validate syntax after changes
422	4. **Forgetting to read first** - Always read before write
423
424	## Troubleshooting Hooks
425
426	If a hook isn't running:
427	1. **Check the settings file** - Read ~/.claude/settings.json or .claude/settings.json
428	2. **Verify JSON syntax** - Invalid JSON silently fails
429	3. **Check the matcher** - Does it match the tool name? (e.g., "Bash", "Write", "Edit")
430	4. **Check hook type** - Is it "command", "prompt", or "agent"?
431	5. **Test the command** - Run the hook command manually to see if it works
432	6. **Use --debug** - Run `claude --debug` to see hook execution logs