I've used Claude Code daily since it came out. Here are the best practices, tools, and configuration patterns I've picked up. Most of this applies to Codex too.<\/p>\n
\nTL;DR
\nMy opinionated setup for Claude Code:
\nhttps:\/\/github.com\/vinta\/hal-9000<\/a><\/p>\n<\/blockquote>\nCLAUDE.md<\/h2>\n
The Global CLAUDE.md<\/h3>\n
Your
~\/.claude\/CLAUDE.md<\/code> should only contain:<\/p>\n\n
- Your preferences and nudges to correct agent behaviors<\/li>\n
- You probably don't need to tell it YAGNI or KISS as bare principles. They're already built in.<\/li>\n<\/ul>\n
Pro tip 1: before adding something to
CLAUDE.md<\/code>, ask it, "Is this already covered in your system prompt?"<\/strong>
\nPro tip 2: try my refactor-claude-md<\/a> skill!<\/p>\nHere are some parts of my
CLAUDE.md<\/code> I found useful:<\/p>\n## Communication Style\n\n### Surface Assumptions\n\nProceeding on a guess is right; proceeding silently is not.\n\nWhere my request left a decision open and you resolved it by guessing, name that assumption as its own bullet so I can catch what I forgot to tell you.\n\nWhen I ask for advice or a recommendation, first surface the assumptions my question takes for granted and the missing information that would change your answer (and how), so I can catch the framing I got wrong.\n\n### Use AskUserQuestion\n\nWhen you ask the user anything whose answer is a selection rather than a sentence (multiple-choice, yes\/no questions whether they gate next steps or offer optional follow-up work, picking from a list, choosing between approaches), ask with theAskUserQuestion<\/code> tool instead of plain text, so the user clicks an option instead of typing.\n\nWhen presenting approaches, put the summary in each option's label and the pros\/cons in its description. Plain text is fine when the answer is open-ended. This changes the format of questions, not whether to ask: never use it to ask permission for work you already have enough information to do.\n\n## Workflow\n\n- Before proposing a design of your own, invoke thebest-practices<\/code> skill to study prior art. Assume prior art exists; spend original design only where your problem actually differs\n- When a finding invalidates the approach you're executing (contradicts it, or makes it unnecessary), stop and lead with it: what it kills, what the plan is now. Mentioning it in passing while continuing does not count\n\n### Prefer Online Sources\n\nTraining data goes stale: library\/framework\/SDK APIs, config keys, CLI flags, cloud services, platform features, syntax, and versions change, and guessing has repeatedly cost debugging round-trips.\n\nInvoke thefind-docs<\/code> skill BEFORE writing code or config that touches any of those, and BEFORE answering questions about them. Being about to write such code is trigger enough, even when no question was asked. Confidence is not an exemption, and neither is the library being well known. Answering from training data, or fetching a remembered docs URL instead of invoking the skill, does not satisfy this rule.\n\nIf the user provides URLs,WebFetch<\/code> each one as a primary source before searching further. Never skip user-provided URLs. For topicsfind-docs<\/code> covers poorly,WebFetch<\/code> the official docs instead of falling back to training data.<\/code><\/pre>\nAlso see:<\/p>\n
\n
- GitHub: vinta\/hal-9000 - The user-level CLAUDE.md<\/a><\/li>\n
- A Complete Guide To AGENTS.md<\/a><\/li>\n<\/ul>\n
The Project CLAUDE.md<\/h3>\n
For project-specific instructions, put them in the project-level
CLAUDE.md<\/code>.<\/p>\nThe highest-signal content in your project
CLAUDE.md<\/code> (or any skill) is the Gotchas<\/strong> section. Build these from the failure points Claude Code actually runs into.<\/p>\nAlso see:<\/p>\n
\n
- Twitter: @trq212 - Lessons from Building Claude Code: How We Use Skills<\/a><\/li>\n
- GitHub: anthropics\/claude-plugins-official - CLAUDE.md templates<\/a><\/li>\n<\/ul>\n
Per File Type Rules<\/h2>\n
For language-specific or per-file rules<\/a>, put them in
~\/.claude\/rules\/<\/code>, so Claude Code only loads them when editing those file types.<\/p>\nFor instance,
~\/.claude\/rules\/python.md<\/code>:<\/p>\n---\npaths:\n - \"**\/*.py\"\n - \"**\/pyproject.toml\"\n---\n\n# Python\n\n- When choosing a Python library or tool, check https:\/\/awesome-python.com\/llms.txt before picking one\n- Prefer the standard library over adding a dependency (supply-chain hardening) \u2014tomllib<\/code> overtomli<\/code>,pathlib<\/code> over external path libs\n -requests<\/code> is fine since it's the de facto standard\n- Version specifiers inpyproject.toml<\/code>: use>=<\/code> floors (uv'sadd-bounds<\/code> default)\n - Exact reproducibility lives inuv.lock<\/code> +uv sync --locked<\/code>, so==<\/code> pins inpyproject.toml<\/code> would only duplicate the lockfile and blockuv lock --upgrade<\/code>\n - Pin exact==<\/code> versions only where no lockfile exists (standalone scripts, requirements.txt)\n- Useuv<\/code> for project and environment management\n -uv run<\/code> instead ofpython3<\/code> \u2014 picks up the project venv and dependencies automatically\n - Projects with a[build-system]<\/code> needno-build = false<\/code> in[tool.uv]<\/code> \u2014 the globalno-build = true<\/code> in~\/.config\/uv\/uv.toml<\/code> merges down and blocks the editable install\n- Usepytest<\/code> for testing\n- Useruff<\/code> for linting and formatting\n -assert<\/code> is fine in tests but use# noqa: S101 assert<\/code> elsewhere\n- When the linter flags something, read the rule it enforces (ruff rule <CODE><\/code>) and fix the code\n - Suppress with# noqa<\/code> only when the rule does not apply to the project\n - All# noqa<\/code> comments must include the rule name:# noqa: S603 subprocess-without-shell-equals-true<\/code> or# noqa: S603 PLW1510 subprocess-without-shell-equals-true subprocess-run-without-check<\/code> if multiple rules\n- Usety<\/code> for type checking\n- Usety<\/code> LSP tool for code navigation when grep's text matching would be ambiguous\n- UseTypedDict<\/code> for structured dicts \u2014 not plain dicts or dataclasses<\/code><\/pre>\nThe full rules I have:<\/p>\n
\n
- GitHub: vinta\/hal-9000 - .claude\/rules\/<\/a><\/li>\n<\/ul>\n
Output Styles<\/h2>\n
Claude Code provides a built-in method to modify the system prompt to change how Claude responds: Output styles<\/a>. You can also write your own. For instance, something similar to caveman<\/a>, so every reply drops articles, filler, and pleasantries while keeping every technical detail:<\/p>\n
---\nname: Caveman\ndescription: Terse caveman-speak replies \u2014 full technical substance, no filler\nkeep-coding-instructions: true\n---\n\nRespond terse like smart caveman. All technical substance stay. Only fluff die.\n\n## Rules\n\nDrop: articles (a\/an\/the), filler (just\/really\/basically\/actually\/simply), pleasantries (sure\/certainly\/happy to), hedging, decorative tables\/emoji. Fragments OK. Short synonyms (fix, not \"implement a solution for\"), one word when one word enough. Pattern:[thing] [action] [reason]. [next step].<\/code>\n\nLead with answer. First sentence carry verdict or result; reason after, never before.\n\nState each fact once \u2014 never restate same fact in second form.\n\nNot: \"Sure! I'd be happy to help. The issue is most likely caused by your auth middleware not validating token expiry.\"\nYes: \"Bug in auth middleware. Token expiry check use<<\/code> not<=<\/code>. Fix:\"\n\nNever drop not\/never\/no\/only\/except \u2014 flipped meaning worse than any token saved. Numbers, units, technical terms exact.\n\nCode blocks, commands, API names, error strings: byte-exact, never compressed. Long error log: quote shortest decisive line, not whole dump.\n\nToken economics: standard acronyms OK (DB\/API\/HTTP). Never invent abbreviations (cfg\/impl\/req\/res\/fn) \u2014 tokenizer split them same as full word, zero token saved, reader still decode. No causal arrows (\u2192) \u2014 own token, save nothing. Full word cheaper AND clearer.\n\nTool calls: fire direct, no progress narration before or between calls. CLAUDE.md duties survive compressed, never dropped: pre-change outline bullets, named-assumption bullets, findings user need \u2014 write them caveman-terse.\n\nReply in user's language \u2014 compress style, never translate. Drop articles only in languages that have them; where small markers carry case\/role (particles), keep them: grammar, not filler.\n\nNo self-reference. Never announce or name the style, no \"caveman mode on\". Caveman output only \u2014 never normal answer plus caveman recap.<\/code><\/pre>\nWhy an output style instead of the global
CLAUDE.md<\/code>? They land in different places: an output style becomes part of the system prompt, and Claude Code periodically reminds the model to stick to it mid-conversation, whileCLAUDE.md<\/code> gets injected as a user message, where it competes with all your other rules. Plus, you can switch styles in\/config<\/code> without touching your global rules.<\/p>\nOne gotcha: output styles apply to the main conversation only.<\/p>\n
\n
- GitHub: vinta\/hal-9000 - caveman.md<\/a><\/li>\n
- GitHub: vinta\/hal-9000 - asd-ste100.md<\/a><\/li>\n<\/ul>\n
Configurations<\/h2>\n
Settings<\/h3>\n
There are some useful configurations<\/a> you could set in your
~\/.claude\/settings.json<\/code>:<\/p>\n{\n \"$schema\": \"https:\/\/json.schemastore.org\/claude-code-settings.json\",\n \"env\": {\n \"CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY\": \"1\",\n \"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS\": \"1\",\n \"CLAUDE_CODE_RETRY_WATCHDOG\": \"1\",\n \"DISABLE_ERROR_REPORTING\": \"1\",\n \"DISABLE_EXTRA_USAGE_COMMAND\": \"1\",\n \"DISABLE_FEEDBACK_COMMAND\": \"1\",\n \"DISABLE_UPGRADE_COMMAND\": \"1\"\n },\n \"permissions\": {\n \"allow\": [\"...\"],\n \"deny\": [\"...\"],\n \"ask\": [\"...\"],\n \"defaultMode\": \"auto\"\n },\n \"model\": \"opus[1m]\",\n \"effortLevel\": \"high\",\n \"advisorModel\": \"fable\",\n \"cleanupPeriodDays\": 99999,\n \"includeGitInstructions\": false,\n \"showClearContextOnPlanAccept\": true,\n \"teammateMode\": \"auto\",\n \"voice\": { \"enabled\": true },\n \"spellcheck\": { \"enabled\": true }\n}<\/code><\/pre>\nHighlights:<\/p>\n
\n
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"<\/code>: Enable Agent Team<\/a> feature, a fancy way to consume a huge amount of tokens<\/li>\n"permissions.defaultMode": "auto"<\/code>: Use this to pretend it's safer than--dangerously-skip-permissions<\/code><\/li>\n"advisorModel": "fable"<\/code>: Use something faster likesonnet<\/code> as the main model, and let it consult<\/a>fable<\/code> when needed<\/li>\n"includeGitInstructions": false<\/code>: Remove built-in commit\/PR instructions and git status snapshot from the system prompt, since my commit<\/a> skill covers that<\/li>\n"cleanupPeriodDays": 365<\/code>: By default, your chat history (location:~\/.claude\/projects\/<\/code>) will be deleted after 30 days<\/li>\n"voice": { "enabled": true }<\/code>: Enable Voice Dictation<\/a> feature. Code like a boss!<\/li>\n"spellcheck": { "enabled": true }<\/code>: Mark misspelled words in the prompt input usingaspell<\/code> orhunspell<\/code><\/li>\n<\/ul>\nI turned all this settings-tweaking into a skill: audit-claude-settings<\/a> fetches the latest settings and env-vars from official docs, diffs them against your actual config, and suggests changes tied to how you work.<\/p>\n
The full settings I use:<\/p>\n
\n
- GitHub: vinta\/hal-9000 - .claude\/settings.json<\/a><\/li>\n<\/ul>\n
Permissions<\/h3>\n
If you're not using a sandbox or devcontainer for Claude Code, you may want to block some evil<\/strong> commands in your
~\/.claude\/settings.json<\/code>:<\/p>\n{\n \"permissions\": {\n \"defaultMode\": \"auto\",\n \"deny\": [\n \"Read(~\/.aws\/**)\",\n \"Read(~\/.config\/**)\",\n \"Read(~\/.docker\/**)\",\n \"Read(~\/.dropbox\/**)\",\n \"Read(~\/.gnupg\/**)\",\n \"Read(~\/.gsutil\/**)\",\n \"Read(~\/.kube\/**)\",\n \"Read(~\/.npmrc)\",\n \"Read(~\/.orbstack\/**)\",\n \"Read(~\/.pypirc)\",\n \"Read(~\/.ssh\/**)\",\n \"Read(~\/*_history)\",\n \"Read(~\/**\/*credential*)\",\n \"Read(~\/Library\/**)\",\n \"Edit(~\/Library\/**)\",\n \"Read(~\/Dropbox\/**)\",\n \"Edit(~\/Dropbox\/**)\",\n \"Read(\/\/etc\/**)\",\n \"Edit(\/\/etc\/**)\",\n \"Bash(git -c *)\",\n \"Bash(git --config-env*)\",\n \"Bash(git --git-dir*)\",\n \"Bash(gh repo delete *)\",\n \"Bash(su *)\",\n \"Bash(sudo *)\",\n \"Bash(passwd *)\",\n \"Bash(env *)\",\n \"Bash(printenv *)\",\n \"Bash(history *)\",\n \"Bash(fc *)\",\n \"Bash(eval *)\",\n \"Bash(exec *)\",\n \"Bash(rsync *)\",\n \"Bash(sftp *)\",\n \"Bash(telnet *)\",\n \"Bash(socat *)\",\n \"Bash(nc *)\",\n \"Bash(ncat *)\",\n \"Bash(netcat *)\",\n \"Bash(nmap *)\",\n \"Bash(chflags *)\",\n \"Bash(xattr *)\",\n \"Bash(diskutil *)\",\n \"Bash(mkfs *)\",\n \"Bash(security *)\",\n \"Bash(defaults *)\",\n \"Bash(launchctl *)\",\n \"Bash(osascript *)\",\n \"Bash(dscl *)\",\n \"Bash(networksetup *)\",\n \"Bash(scutil *)\",\n \"Bash(systemsetup *)\",\n \"Bash(pmset *)\",\n \"Bash(crontab *)\"\n ],\n \"ask\": [\n \"Bash(open *)\",\n \"Bash(chmod *)\",\n \"Bash(chown *)\",\n \"Bash(kill *)\",\n \"Bash(killall *)\",\n \"Bash(pkill *)\",\n \"Bash(curl *-d *)\",\n \"Bash(curl *--data*)\",\n \"Bash(curl *--json *)\",\n \"Bash(curl *-F *)\",\n \"Bash(curl *--form *)\",\n \"Bash(curl *-T *)\",\n \"Bash(curl *--upload-file *)\",\n \"Bash(curl *-H *)\",\n \"Bash(curl *--header *)\",\n \"Bash(brew install *)\",\n \"Bash(pip install *)\",\n \"Bash(uv pip install *)\",\n \"Bash(uv tool install *)\",\n \"Bash(uv add *)\",\n \"Bash(npm install *)\",\n \"Bash(npm i *)\",\n \"Bash(yarn add *)\",\n \"Bash(pnpm add *)\",\n \"Bash(bun add *)\",\n \"Bash(git push *)\",\n \"Bash(git remote add *)\",\n \"Bash(git remote set-url *)\",\n \"Bash(git config remote.*)\",\n \"Bash(git config * remote.*)\",\n \"Bash(gh repo create *)\",\n \"Bash(gh repo rename *)\",\n \"Bash(gh *--admin*)\",\n \"Bash(gh api *-X *)\",\n \"Bash(gh api *--method *)\"\n ],\n },\n \"hooks\": {\n \"PreToolUse\": [\n {\n \"matcher\": \"Bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"python3 ~\/.claude\/hooks\/guard-bash-paths.py\"\n }\n ]\n }\n ]\n }\n}<\/code><\/pre>\nRule precedence catches people out: Claude Code evaluates
deny<\/code>, thenask<\/code>, thenallow<\/code>, and the first match wins \u2014 specificity never reorders them. So a narrow"allow": ["Bash(curl https:\/\/code.claude.com\/docs\/*)"]<\/code> does nothing while"ask": ["Bash(curl *)"]<\/code> is present, and aPreToolUse<\/code> hook returningallow<\/code> doesn't rescue it either, since a matching ask rule still prompts. Bash patterns have no negation, so carving an exception out of a broad ask rule means narrowing the ask rule itself.<\/p>\nAlso,
"deny": ["Read(~\/.aws\/**)", "Read(~\/.kube\/**)", ...]<\/code> alone is not enough, since Claude Code can still read sensitive files through theBash<\/code> tool. You can write a simple hook to interceptBash<\/code> commands that access blocked files, like thisguard-bash-paths.py<\/code><\/a> hook. However, Claude Code can still write scripts to read sensitive data<\/strong> and bypass all of the above defenses. The safest approach is using sandbox after all.<\/p>\nPlugins<\/h2>\n
Claude Code Plugins<\/a> are simply a way to package skills, commands, agents, hooks, MCP servers, LSP servers, and monitors. Distributing them as a plugin has the following advantages:<\/p>\n
\n
- Auto update (versioned releases)<\/li>\n
- Auto hooks configuration (users don't need to edit their
~\/.claude\/settings.json<\/code> manually)<\/li>\n- Skills have a
\/plugin-name:your-skill-name<\/code> prefix (no more conflicts)<\/li>\n<\/ul>\nTo install a plugin, you need to add a marketplace first. A marketplace is usually just a GitHub repo. Think of it as a namespace.<\/p>\n
\/plugin marketplace add openai\/codex-plugin-cc\n\/plugin marketplace add xai-org\/grok-build-plugin-cc\n\/plugin marketplace add mattpocock\/skills\n\/plugin marketplace add vinta\/hal-9000\n\n# browse plugins\n\/plugin<\/code><\/pre>\nRecommended:<\/p>\n
\n
- GitHub: openai\/codex-plugin-cc<\/a>: OpenAI Codex's official plugin for Claude Code<\/li>\n
- GitHub: xai-org\/grok-build-plugin-cc<\/a>: xAI Grok Build's official plugin for Claude Code<\/li>\n
- GitHub: obra\/superpowers<\/a>: The first skills I ever installed and still find them useful<\/li>\n
- GitHub: mattpocock\/skills<\/a>: This is my new favorite<\/li>\n
- GitHub: vinta\/hal-9000<\/a>: My personal skills<\/li>\n<\/ul>\n
Skills<\/h2>\n
Skills<\/a> can contain executable scripts and hooks, not just Markdown. Use with caution!<\/strong> When in doubt, have your agent review them first.<\/p>\n
Here are skills I've used, mostly installed per project when needed:<\/p>\n
# my skills\nnpx skills add https:\/\/github.com\/vinta\/hal-9000 \\\n--skill commit best-practices brainstorm blindspot simple-english write-like-me refactor-agents-md \\\n--agent codex \\\n-g\n\n# workflow skills\nnpx skills add https:\/\/github.com\/mattpocock\/skills --agent codex -g\nnpx skills add https:\/\/github.com\/cursor\/plugins --skill thermo-nuclear-code-quality-review --agent codex claude-code -g\n\n# writing skills\nnpx skills add https:\/\/github.com\/cursor\/plugins --skill unslop\nnpx skills add https:\/\/github.com\/kotek-7\/dotfiles --skill sanitize-artifacts\nnpx skills add https:\/\/github.com\/shyuan\/writing-humanizer --skill writing-humanizer\n\n# doc skills\nnpx skills add https:\/\/github.com\/upstash\/context7 --skill find-docs --agent codex claude-code -g\nnpx skills add https:\/\/github.com\/humanlayer\/skills --skill show-me --agent codex claude-code -g\n\n# language skills\nnpx skills add https:\/\/github.com\/trailofbits\/skills-curated --skill python-code-simplifier\nnpx skills add https:\/\/github.com\/dagster-io\/skills --skill dignified-python\nnpx skills add https:\/\/github.com\/cursor\/plugins --skill typescript-best-practices\nnpx skills add https:\/\/github.com\/JetBrains\/go-modern-guidelines --skill use-modern-go\nnpx skills add https:\/\/github.com\/wdm0006\/python-skills\n\n# backend skills\nnpx skills add https:\/\/github.com\/vintasoftware\/django-ai-plugins\nnpx skills add https:\/\/github.com\/google\/skills\nnpx skills add https:\/\/github.com\/cloudflare\/skills\nnpx skills add https:\/\/github.com\/supabase\/agent-skills\nnpx skills add https:\/\/github.com\/planetscale\/database-skills\n\n# LLM API skills\nnpx skills add https:\/\/github.com\/openai\/skills\nnpx skills add https:\/\/github.com\/google-gemini\/gemini-skills\n\n# frontend skills\nnpx skills add https:\/\/github.com\/millionco\/react-doctor\nnpx skills add https:\/\/github.com\/vercel-labs\/agent-skills\nnpx skills add https:\/\/github.com\/vercel-labs\/next-skills\n\n# design skills\nnpx skills add https:\/\/github.com\/pbakaus\/impeccable\nnpx skills add https:\/\/github.com\/openai\/skills --skill frontend-skill\n\n# seo\/aeo skills\nnpx skills add https:\/\/github.com\/warpdotdev\/oz-skills --skill seo-aeo-audit\n\n# video skills\nnpx skills add https:\/\/github.com\/remotion-dev\/skills\nnpx skills add https:\/\/github.com\/AmanVarshney01\/tcut\n\n# browser skills\nnpx skills add https:\/\/github.com\/microsoft\/playwright-cli --agent codex claude-code -g\n\nnpx skills list -g\nnpx skills update -g\nnpx skills remove --all -g<\/code><\/pre>\nRecommended:<\/p>\n
\n
\/brainstorming<\/code> from superpowers<\/a>: When in doubt, start with this skill<\/li>\n\/wayfinder<\/code> from mattpocock<\/a>: Let AI ask you a lot of questions until you get annoyed<\/li>\n\/find-docs<\/code> from context7<\/a>: Find the latest documentations<\/li>\n\/frontend-design<\/code> from impeccable<\/a>: The better version of the official\/frontend-design<\/code> skill<\/li>\n\/simplify<\/code>: Run it often, you will like it<\/li>\n<\/ul>\nYou can find more skills on skills.sh<\/a>.<\/p>\n
MCP Servers<\/h2>\n
You probably don't need any MCP servers<\/a> if you can do the same thing with CLI + skills.<\/p>\n
Context7 MCP<\/h2>\n
No, just use the
ctx7<\/code> CLI withfind-docs<\/code> skill instead.<\/p>\nnpx ctx7 setup<\/code><\/pre>\n\n
- GitHub: upstash\/context7<\/a><\/li>\n<\/ul>\n
Playwright MCP<\/h3>\n
No, you should use the
playwright-cli<\/code> skill instead. Both tools support headed mode<\/strong> (the opposite of headless), if you'd like to see the browser.<\/p>\nnpm install -g @playwright\/cli\nnpx skills add https:\/\/github.com\/microsoft\/playwright-cli<\/code><\/pre>\n\n
- GitHub: microsoft\/playwright-cli<\/a><\/li>\n<\/ul>\n
GitHub MCP<\/h3>\n
No, you should use the
gh<\/code> command instead.<\/p>\nbrew install gh<\/code><\/pre>\nCodex MCP<\/h3>\n
Yes, ironically. Other coding agents like Claude Code can use Codex via MCP, which is slightly more stable than directly invoking it with
codex exec<\/code> via CLI.<\/p>\n# Codex reads your local .codex\/config.toml by default\nclaude mcp add codex --scope user -- codex mcp-server<\/code><\/pre>\n\n
- Codex Command Line Options - codex mcp-server<\/a><\/li>\n<\/ul>\n
However, since OpenAI releases the official Claude Code plugin: codex-plugin-cc<\/a>, you should probably use that instead.<\/p>\n
Hooks<\/h2>\n
Both Claude Code<\/a> and Codex<\/a> support hooks. Hooks make Claude Code run specific commands on lifecycle events like
SessionStart<\/code>,UserPromptSubmit<\/code>, andPreToolUse<\/code>.<\/p>\nInstead of reminding Claude Code to run the linter or tests in your prompts (and it still forgets sometimes), just write a
PostToolUse<\/code> hook that runs deterministically:<\/p>\n{\n \"hooks\": {\n \"PostToolUse\": [\n {\n \"matcher\": \"Write|Edit\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"uv run ruff check . >&2 || exit 2\",\n \"if\": \"Edit(**\/*.py)\",\n \"timeout\": 30,\n \"statusMessage\": \"Linting Python code...\"\n }\n ]\n }\n ]\n }\n}<\/code><\/pre>\nIt's worth noting that only exit code
2<\/code> blocks and feeds the output back to Claude, and only throughstderr<\/code><\/strong> \u2014 while tools likeruff<\/code> andty<\/code> print their diagnostics tostdout<\/code><\/strong>. A bareuv run ruff check .<\/code> exits1<\/code>, a non-blocking error, so Claude only gets the first line ofstderr<\/code>, never the lint errors.>&2<\/code> moves them to the stream Claude reads, and|| exit 2<\/code> makes the hook actually block.<\/p>\nAlso, do the path matching in
if<\/code>, not inside a wrapper script.if<\/code> takes the same permission rule syntax<\/a>.<\/p>\nI also wrote some Claude Code plugins that use hooks:<\/p>\n