brew-agent-md

brew-agent-md is a read-only CLI checkup. In one command it inventories local Homebrew CLI capabilities, inspects user and ancestor-project AGENTS.md / CLAUDE.md files, and reports which capabilities those instructions already mention.

npx brew-agent-md

The command scans brew list --formula / brew list --cask, verifies each matching executable with command -v, and reports the catalog in Essential → Productive → Kitchen sink order. It never installs packages, writes files, or uses hooks.

Until the package has been published, run it from a checkout:

node bin/brew-agent-md.js

Why this is not a giant tool dump

An agent should not assume a package is installed just because it is useful. This project separates recommendations from machine capability:

• Essential: bounded repository search and discovery, structured data, GitHub, HTTP, and persistent interactive sessions (rg, fd, jq, yq, ast-grep, gh, tmux).
• Productive: verification, syntax-aware review, repeatable checks, and data summaries (shellcheck, shfmt, difftastic, scc, qsv, duckdb).
• Kitchen sink: specialist data, document, media, security, and infrastructure tools. These are intentionally opt-in recommendations.

Print the entire, installable catalog (with exact Homebrew install commands) without changing a file:

npx brew-agent-md --catalog
npx brew-agent-md --catalog --ring essential,productive

Run a focused checkup:

npx brew-agent-md
npx brew-agent-md --ring essential,productive

Checkup behavior

For every non-baseline catalogued tool, the checkup reports whether it is available, installed but missing from PATH, or not installed; it also says whether an inspected instruction file mentions it. Common baseline tools such as git and curl remain in the static catalog but are intentionally omitted from the actionable checkup. Missing packages are suggestions only, ordered from Essential through Kitchen sink. The command does not edit the instructions, install software, or prescribe a workflow. For example, a usable but undocumented ripgrep entry includes:

- Use `rg` for repository text search; it is fast and respects ignore files. Prefer it to recursive `grep`.
- When running a CLI interactively, use `tmux` so the session stays attachable and can receive input.

This gives an agent grounded context for a follow-on conversation while leaving the final tool and instruction-file choices with the user.

Research basis

The initial rings are grounded in recurring agent-community recommendations rather than a generic “modern CLI” list. rg/fd support low-noise discovery, ast-grep adds structural code search, and jq/yq keep structured data out of fragile text parsing. The more specialized tools are intentionally lower-ring. See research notes for the sources and selection criteria.

Publishing

This package has no runtime dependencies and uses Node's built-in test runner. Before publishing, choose an available npm package name and run:

npm test
npm publish --access public

After publication, the first command in this README is the distribution one-liner. For a scoped package, change the package name and use npx @scope/brew-agent-md.

Development

npm test
npm run lint

The catalog is deliberately curated rather than attempting to enumerate Homebrew's entire formula API: Homebrew contains libraries, services, and tools whose semantics are too broad to give agents safe generic instructions. Add an entry only when it has a stable executable, a concrete agent-useful behavior, and a correct formula-to-command mapping.