
tooling
Skills for effective use of developer tooling
- version
- 0.3.1
- GitHub stars
- 13
Install
/plugin install tooling@llm-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add pbdeuchler/llm-plugins.
Contents
Discovered from sourceSkills 3
Using ast-grep for Structural Code Search
Overview
ast-grep (sg) matches code by AST structure, not text. Use it instead of grep/ripgrep when you need to match code patterns regardless of whitespace, variable names, or formatting. Patterns must be valid, parsable code in the target language.
When to Use
Prefer ast-grep over grep when:
- Finding function calls with specific argument shapes
- Matching patterns where variable names differ but structure is the same
- Rewriting code patterns across a codebase (migrations, deprecations)
- Finding anti-patterns that regex can't express (e.g. "await inside a loop")
Use grep instead when:
- Searching for string literals, comments, or non-code text
- Simple keyword search (import names, error messages)
- ast-grep is not installed
CLI Quick Reference
# Search for a pattern
sg run -p 'console.log($$$ARGS)' -l javascript src/
# Search and replace (interactive)
sg run -p '$A && $A()' -r '$A?.()' -l typescript --interactive src/
# Apply all replacements without prompting
sg run -p 'var $X = $Y' -r 'const $X = $Y' -l javascript -U src/
# JSON output for programmatic use
sg run -p '$FUNC($$$)' -l python --json src/
# Read from stdin
echo 'let x = 1' | sg run -p 'let $X = $Y' -l javascript --stdin
Metavariable Syntax
| Syntax | Matches | Example |
|---|---|---|
$NAME | Exactly one AST node | console.log($MSG) matches console.log("hi") but not console.log("hi", 2) |
$$$NAME | Zero or more nodes | console.log($$$ARGS) matches any number of arguments |
$_NAME | One node, non-capturing | $_OBJ.$METHOD() matches without binding $_OBJ |
Reuse enforces equality: $A == $A matches x == x but not x == y.
Language-Specific Patterns
Always pass -l <language>. The language determines how patterns are parsed.
JavaScript/TypeScript:
# Find React hooks
sg run -p 'use$HOOK($$$)' -l typescript src/
# Optional chaining candidates
sg run -p '$A && $A.$B' -r '$A?.$B' -l typescript src/
# Async/await patterns
sg run -p 'await $PROMISE' -l javascript src/
Python:
# Find print statements
sg run -p 'print($$$)' -l python src/
# Dictionary access patterns
sg run -p '$DICT[$KEY]' -l python src/
# With statement patterns
sg run -p 'with open($$$ARGS) as $F: $$$BODY' -l python src/
Go:
# Error handling
sg run -p 'if $ERR != nil { return $$$VALS }' -l go ./
# Function calls
sg run -p '$PKG.$FUNC($$$)' -l go ./
Rust:
# Unwrap calls (potential panics)
sg run -p '$EXPR.unwrap()' -l rust src/
# Match expressions
sg run -p 'match $VAL { $$$ARMS }' -l rust src/
Pattern Pitfalls
| Mistake | Why It Fails | Fix |
|---|---|---|
Using regex in -p | Patterns must be valid code | Write the code structure you want to find |
$VAR + Name | Parsed as $VARN + ame | Use constraints or transform in YAML rules |
| Single quotes in C/Rust patterns | 'x' is a char literal, not a string | Use "x" for strings |
Forgetting -l flag | ast-grep cannot infer language from patterns | Always specify language explicitly |
$A($B, $C) for variadic calls | Only matches exactly 2 args | Use $A($$$ARGS) for any arity |
YAML Rules for Complex Matching
When CLI patterns aren't expressive enough, use YAML rules:
id: no-unwrap-in-production
language: rust
rule:
pattern: $EXPR.unwrap()
not:
inside:
kind: function_item
has:
field: name
regex: '^test_'
message: "Use expect() or proper error handling instead of unwrap()"
severity: warning
Key rule combinators:
all: All sub-rules must match (AND)any: Any sub-rule can match (OR)not: Sub-rule must NOT matchinside: Target is inside another nodehas: Target contains a descendantfollows/precedes: Sibling ordering
Run rules: sg scan --rule path/to/rule.yml src/
Red Flags
- Using grep with complex regex when ast-grep would match the structure directly
- Forgetting
$$$and missing variadic matches - Writing patterns that aren't valid code in the target language
- Not specifying
-land getting parse failures
Using qmd for Knowledge Base Search
Overview
qmd is a local search engine for markdown documents. It combines BM25 keyword search, vector semantic search, and LLM-powered hybrid re-ranking. Use it to find relevant context in documentation, notes, and knowledge bases when grep is too literal and you need conceptual matching.
When to Use
Prefer qmd over grep when:
- Searching documentation or notes for conceptually related content
- You know what you're looking for but not the exact terms used
- You need to find relevant context across a large markdown knowledge base
- Building context for a task from scattered documentation
Use grep instead when:
- Searching code files (qmd indexes markdown only)
- Looking for exact string matches or regex patterns
- The search target is a known identifier, import, or error message
Search Modes
| Mode | Command | Speed | Best For |
|---|---|---|---|
| Keyword (BM25) | qmd search | Fast | Known terms, exact phrases |
| Semantic (vector) | qmd vsearch | Slow | Conceptual queries, fuzzy recall |
| Hybrid (re-ranked) | qmd query | Slowest | Highest quality, broad exploration |
Default to qmd search unless keyword results are insufficient. Escalate to vsearch or query only when needed.
CLI Quick Reference
# Keyword search (fast, use first)
qmd search "authentication flow"
# Semantic search (finds conceptually related content)
qmd vsearch "how users log in"
# Hybrid with LLM re-ranking (most thorough)
qmd query "best practices for session management"
# Restrict to a collection
qmd search "rate limiting" -c api-docs
# More results
qmd search "error handling" -n 20
# Full document content in results
qmd search "deployment" --full
# With line numbers
qmd search "config" --full --line-numbers
# JSON output for structured processing
qmd search "auth" --json --full
# Retrieve a specific document
qmd get "docs/auth.md" --full
# Retrieve from a specific line
qmd get "docs/auth.md:45" -l 100
# Batch retrieve by glob
qmd multi-get "docs/**/*.md" --json
Collection Management
# Add a collection
qmd collection add ~/projects/docs --name project-docs --mask "**/*.md"
# List collections
qmd collection list
# Remove a collection
qmd collection remove old-notes
# Rebuild keyword index
qmd update
# Generate/update vector embeddings (required for vsearch/query)
qmd embed
# Check index health
qmd status
Output Formats
| Flag | Format | Use Case |
|---|---|---|
| (default) | Human-readable | Interactive use |
--json | JSON | Programmatic processing |
--files | CSV: docid,score,filepath,context | File-oriented workflows |
--xml | XML | Structured integration |
--md | Markdown | Documentation pipelines |
Filtering and Scoring
# Minimum relevance threshold
qmd search "deployment" --min-score 0.5
# All results above threshold
qmd search "config" --all --min-score 0.3
# Skip large files
qmd search "setup" --max-bytes 50000
Practical Patterns
Gather context before starting a task:
# Find all relevant docs for a feature area
qmd search "authentication" -c project-docs -n 10 --files
# Then retrieve the most relevant ones
qmd get "docs/auth-design.md" --full --line-numbers
Escalation pattern when keywords miss:
# 1. Try keyword first (fast)
qmd search "retry logic"
# 2. If too few results, try semantic
qmd vsearch "how failures are retried"
# 3. If still unclear, use hybrid
qmd query "error recovery and retry mechanisms"
Bulk context loading:
qmd multi-get "design-docs/*.md" --json
Common Mistakes
| Mistake | Fix |
|---|---|
Using qmd query for every search | Start with qmd search, escalate only if needed |
Forgetting to run qmd embed | Required once before vsearch/query work |
| Searching code files with qmd | qmd indexes markdown only; use grep or ast-grep for code |
Not specifying -c with many collections | Restrict to relevant collection for better signal |
Ignoring --min-score with --all | Unfiltered results include low-relevance noise |
Red Flags
- Running
qmd queryrepeatedly in a loop (expensive; cache or batch instead) - Using qmd when a simple grep for a known string would suffice
- Forgetting
qmd updateafter documents change - Not running
qmd embedafter adding new collections
Use uv and uvx Instead of Python Directly
Overview
uv is a fast, reproducible Python package and project manager. When uv is
on PATH, prefer it over direct python, pip, pipx, and venv calls. It
resolves and caches dependencies deterministically, manages the interpreter,
and makes ad-hoc tool runs reproducible without polluting the global
environment.
Check availability with command -v uv. If uv is not installed, fall back to
python/pip as usual - this guidance applies only when uv is present.
Command Mappings
| Instead of | Use |
|---|---|
python script.py | uv run script.py |
python -m module | uv run python -m module |
python -c '...' | uv run python -c '...' |
python (REPL) | uv run python |
pip install X | uv pip install X (ad hoc) or uv add X (project dep) |
python -m pip install X | uv pip install X |
python -m venv .venv | uv venv .venv |
pipx run X | uvx X |
pipx install X | uv tool install X |
pip-compile / freeze | uv lock / uv pip compile |
Why uv run / uvx
uv runensures the project's locked dependencies are present and uses the pinned interpreter before executing - no manual activate step, no stale venv.uvx TOOLruns a CLI tool in an ephemeral, cached environment. Reach for it for one-off tools (uvx ruff check,uvx black .,uvx httpie) instead of globally installing them.- For project work, prefer
uv add(records the dep inpyproject.tomland the lockfile) overuv pip install(which mutates the environment without recording intent).
Exceptions
python --version/python -Vcapability probes are fine as-is.- If the repo standardizes on Poetry, Conda, or plain pip and
uvis absent, follow the repo. Do not introduceuvwhere the project does not use it. - An already-activated, project-sanctioned virtualenv is acceptable; do not fight an established workflow.
Quick Reference
uv run app.py # run a script with project deps
uv run pytest # run an installed dev tool
uvx ruff check . # run a tool without installing it
uv add httpx # add a dependency to the project
uv pip install requests # ad-hoc install into the active env
uv venv .venv # create a virtualenv
uv sync # install exactly what the lockfile pins
Hooks 1
Sponsors
Details
- Marketplace
- pbdeuchler/llm-plugins
- Source
- plugins/tooling
- Author
- PBD
- Category
- Community