/tool-misses

name: tool-misses
description: >
  Scan recent Claude Code sessions for "command not found" errors and BSD/GNU
  incompatibilities on macOS, fix them via Homebrew, and record availability in
  CLAUDE.md; runs only when the user invokes /tool-misses (scan | on | off | status).
disable-model-invocation: true
metadata:
  keywords:
    - gsed
    - ggrep
    - gnu-sed
  user-invocable: true
allowed-tools: Bash Read Edit Write AskUserQuestion

Tool Misses

Scan recent Claude Code sessions for tool failures — missing commands and BSD/GNU incompatibilities — then fix them with Homebrew and record availability in CLAUDE.md.

Response Style

Skip narration and transitional commentary. Run each step, then present the findings or ask the user directly. Do not preface tool calls with sentences like "Now I'll run the scanner" or "Let me check whether Homebrew is installed", and do not paraphrase script output the user can already see — show the tables and the questions, nothing else.

Workflow

Step 0: Handle enable/disable arguments

This skill accepts an optional argument that controls its companion PostToolUse hook (`suggest-tool-misses.sh`), which nudges the user toward this skill when a tool failure is detected in Bash output. The hook reads a persistent marker file at `~/.claude/.disable-tool-misses-hook` and stays silent whenever it exists.

Dispatch on the argument before doing anything else:

• `off`, `disable`, `stop`, `mute`, or `silence` → silence the hook:

  touch ~/.claude/.disable-tool-misses-hook

Confirm suggestions are off until re-enabled with `/tool-misses on`, then STOP (do not run a scan).

• `on`, `enable`, `start`, or `unmute` → re-enable the hook:

  rm -f ~/.claude/.disable-tool-misses-hook

Confirm suggestions are back on, then STOP (do not run a scan).

• `status` → report whether the hook is on or off:

  test -f ~/.claude/.disable-tool-misses-hook && echo "off" || echo "on"

Report the result, then STOP.

• No argument, `scan`, or anything else → proceed to Step 1.

Step 1: Detect tool misses

Run the scanner script against recent session transcripts:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/tool-misses/scripts/detect-tool-misses.py

This scans `~/.claude/projects/*/*.jsonl` files from the last 14 days. It looks at Bash `tool_use` + `tool_result` pairs and matches error output against two pattern sets:

• **Missing tools**: `command not found` errors
• **Wrong version / incompatibility**: BSD vs GNU errors (e.g., `grep -P` failing,

`sed -i` syntax differences, `find -printf` not supported)

Output is JSON with `missing_tools[]`, `wrong_version_tools[]`, and `scan_summary{}`.

If the script finds no misses, report that and stop.

Step 2: Check current state

For each detected tool, check whether it has already been resolved:

command -v <tool>        # Is it installed now?
command -v g<tool>       # Is the GNU version available?
brew --prefix 2>/dev/null # Is Homebrew installed?

Categorize each tool as: still missing, now installed but not in CLAUDE.md, or fully resolved.

Step 3: Look up fixes

Consult `references/tool-database.md` for each detected tool to find:

• The correct Homebrew formula
• The g-prefix command name (for GNU tools)
• Guidance text for CLAUDE.md

For tools not in the database, note them as "unknown — manual resolution needed".

Step 4: Present report

Show the findings in tables grouped by status:

## Missing Tools (not currently installed)
| Tool | Error | Homebrew Formula | Occurrences |
|------|-------|------------------|-------------|
| filterdiff | command not found | patchutils | 3 |

## BSD/GNU Incompatibilities
| Tool | Error Pattern | Fix | g-prefix |
|------|---------------|-----|----------|
| grep | invalid option -- P | brew install grep | ggrep |

## Already Resolved (installed since the error)
| Tool | Status |
|------|--------|
| jq   | Now installed |

## GNU Tools Available but Not in CLAUDE.md
| Tool | g-prefix | Formula |
|------|----------|---------|
| gsed | gsed     | gnu-sed |

Only show sections that have entries. If everything is resolved, say so and skip to Step 8.

If the scanner output includes `ignored_tools`, mention how many were skipped:

(3 previously dismissed tools hidden — edit ~/.claude/tool-misses-ignored.json to reset)

Step 5: Prompt for action — per tool

Present each detected tool individually for the user to decide. For each tool, use AskUserQuestion with these options:

• **Install + add to CLAUDE.md** (Recommended) — Install via Homebrew and record in CLAUDE.md
• **Install only** — Install but don't modify CLAUDE.md
• **CLAUDE.md only** — Already installed, just add the CLAUDE.md entry
• **Dismiss permanently** — Not needed; hide from future scans

If a tool has no known Homebrew formula, adjust options to only show "Dismiss permanently" and "Skip for now".

**Dismiss behavior:** When the user dismisses a tool, add it to `~/.claude/tool-misses-ignored.json`:

{
  "ignored": ["qmd", "init_common"],
  "notes": {
    "qmd": "Dismissed 2026-02-08 — short-term experiment",
    "init_common": "Dismissed 2026-02-08 — shell function, not a tool"
  }
}

Read the file first (or start with empty `{"ignored":[], "notes":{}}`) and merge. The scanner automatically filters out tools in this list on future runs.

Step 6: Install tools

For each tool the user approved for installation:

brew install <formula>

After each install, verify it worked:

command -v <tool> && echo "OK" || echo "FAILED"

If a GNU tool was installed, also verify the g-prefix command:

command -v g<tool> && echo "OK" || echo "FAILED"

Report any install failures and continue with the rest.

Step 7: Update CLAUDE.md

Add a `## Tool Availability (macOS)` section to `~/.claude/CLAUDE.md` (global config, since these are system-wide tools). Follow these rules:

• Consult `re