# Tool Ast Grep

> User-invoked skill tool-ast-grep. A human runs it by name.

- Skill: `niksavis/tool-ast-grep` (Agent Skill)
- Install (CLI): `npx skillmds@latest add niksavis/tool-ast-grep`
- Raw SKILL.md: https://api.skillmd.com/api/skills/niksavis/tool-ast-grep/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: niksavis (https://skillmd.com/u/niksavis)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/niksavis/tool-ast-grep

---

<!-- Generated by `basicly skills-build` from skill.yaml. Do not edit; edit the source. -->

# tool-ast-grep

## When To Use

- Perform syntax-aware code search where regex is too noisy.
- Apply structural refactors with AST-level metavariables.
- Match multi-line language constructs safely.

## Trusted Commands

```bash
sg --pattern 'console.log($ARG)' --lang ts
sg --pattern 'useEffect($FN, [])' --lang tsx src/
sg --pattern 'console.log($ARG)' --rewrite 'logger.info($ARG)' --lang ts
sg --pattern '$X' --rewrite '$Y' --lang ts --interactive
sg --pattern 'def $NAME($$$ARGS): $$$BODY' --lang python
sg --json --pattern 'print($$$ARGS)' --lang python .
```

## Safe Defaults

- Always set `--lang` explicitly for predictable parsing.
- Start with search-only patterns before rewrite mode.
- Review every rewrite in git diff before staging.

## Common Pitfalls

- Binary name is `sg`, not `ast-grep`.
- `$VAR` matches one node; `$$$VARS` matches multiple nodes.
- Parse failures in malformed files can hide expected matches.

## Output Interpretation

- Default output includes file and location for each match.
- `--json` returns structured match objects with range and bindings.

## Why It Matters For Agents

- Enables safe refactors that understand syntax nesting and boundaries.
- Greatly reduces false positives compared with regex replacements.

## Repo Conventions

- Prefer ast-grep over text replacement for semantic code edits.
- Keep rewrite patterns narrow and validated against sample files.

## Trigger Examples

- Should trigger: "Replace all Python `print(...)` calls with logger calls structurally."
- Should trigger: "Find functions missing docstrings by syntax pattern."
- Should not trigger: "Download a binary release artifact over HTTP."