List Issues Suggestions1 Discussions Insights

🧙 Gardener: clarified steps, added checks and rationale. Review and merge if useful.

open+2~6proposed by tester · Sep 11, 2026 · based on v1

Conversation Checks Proposed changes8 Result

Result · becomes v2

Install jq and cspell

The script calls cspell through npx --yes, so a global install is optional but makes runs faster. Check for the latest version of jq and cspell before installation.

Why: Having the latest versions ensures compatibility and functionality.

$jq --version && npm install -g cspell

jq downloads

Create the spell-check script

Non-Markdown files exit immediately, so code edits pay nothing. This script checks for spelling issues in Markdown files only.

Why: This script is essential for identifying spelling errors in Markdown files.

mkdir -p .claude/hooks && cat > .claude/hooks/spellcheck-md.sh <<'EOF'
#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
case "$FILE" in
  *.md|*.mdx|*.markdown) ;;
  *) exit 0 ;;
esac
ISSUES=$(npx --yes cspell lint --no-progress --no-summary "$FILE" 2>/dev/null)
if [ -n "$ISSUES" ]; then
  echo "Possible spelling issues in $FILE:" >&2
  echo "$ISSUES" | head -n 15 >&2
  exit 2
fi
exit 0
EOF

Make the script executable

Ensure the script has the correct permissions to run.

Why: Executable permissions are necessary for the script to run properly.

$chmod +x .claude/hooks/spellcheck-md.sh

Merge into .claude/settings.json to enable the spell-checking functionality after edits.

Why: This step integrates the spell-check script into the editing process.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/spellcheck-md.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Claude Code hooks guide

Test with a planted typo

Ask Claude to add a sentence containing 'recieve' to the README to verify the spell-check functionality.

Why: Testing ensures that the setup works as intended and catches errors.

–The hook report lists the misspelling with file and line
–Claude fixes the typo in a follow-up edit without being asked
–Editing a .ts file triggers no spell-check

Add a project dictionaryOptional

Silence false positives on product names and jargon by listing them in cspell.json at the repo root. This helps maintain the accuracy of spell-check results.

Why: A project dictionary helps reduce unnecessary alerts for known terms.

cat > cspell.json <<'EOF'
{
  "version": "0.2",
  "words": ["setfork", "your-product-name", "kubectl"]
}
EOF

Verify cspell configurationOptional

Check that the cspell configuration file is correctly set up and includes necessary words.

Why: Ensuring the configuration is correct prevents issues during spell-checking.

A person is needed here: Is the cspell.json file configured properly?

Check for updates regularlyOptional

Periodically check for updates to jq and cspell to ensure optimal performance and features.

Why: Keeping tools updated prevents compatibility issues and improves functionality.

A person is needed here: When was the last time you updated these tools?