@toolu/opencode 6.8.0

package/plugins/agent-browser/skills/agent-browser/scripts/agent-browser.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# agent-browser wrapper — bakes token-lean defaults onto the read-heavy command
+# family so the agent spends context on the accessibility tree, not raw HTML or
+# screenshots. Injection is fail-open via a STATIC per-subcommand allow-map: a
+# default flag is added ONLY where that subcommand accepts it, so shaping can
+# never turn a working call into a usage error; every other subcommand passes
+# through untouched. A leading `--raw` bypasses all shaping. The binary is never
+# auto-installed — a missing one prints an install guide and exits non-zero.
+#
+# $AGENT_BROWSER_BIN overrides the binary (absolute path or PATH name), for
+# pointing at a custom build or for tests.
+
+BIN="${AGENT_BROWSER_BIN:-agent-browser}"
+DEFAULT_MAX_OUTPUT=4000
+
+install_guide() {
+  echo "agent-browser not found — install: npm i -g agent-browser && agent-browser install  (or: brew install agent-browser / cargo install agent-browser)" >&2
+}
+
+require_bin() {
+  command -v "$BIN" >/dev/null 2>&1 || { install_guide; exit 127; }
+}
+
+# Exact-token or --opt=value match against the remaining args.
+has_flag() {
+  local needle="$1"; shift
+  local a
+  for a in "$@"; do
+    case "$a" in
+      "$needle" | "$needle="*) return 0 ;;
+    esac
+  done
+  return 1
+}
+
+# --raw: total bypass, no shaping.
+if [ "${1:-}" = "--raw" ]; then
+  shift
+  require_bin
+  exec "$BIN" "$@"
+fi
+
+require_bin
+
+# No subcommand — let agent-browser print its own help/usage.
+if [ "$#" -eq 0 ]; then
+  exec "$BIN"
+fi
+
+cmd="$1"; shift   # remaining flags/args stay in "$@"
+
+inject=()
+case "$cmd" in
+  snapshot)
+    # -i (interactive-only compact tree) unless the caller already scoped it.
+    if ! has_flag -i "$@" && ! has_flag -a "$@" \
+       && ! has_flag -s "$@" && ! has_flag -d "$@"; then
+      inject+=(-i)
+    fi
+    has_flag --json "$@"               || inject+=(--json)
+    has_flag --max-output "$@"         || inject+=(--max-output "$DEFAULT_MAX_OUTPUT")
+    has_flag --content-boundaries "$@" || inject+=(--content-boundaries)
+    ;;
+  get)
+    has_flag --json "$@"               || inject+=(--json)
+    has_flag --max-output "$@"         || inject+=(--max-output "$DEFAULT_MAX_OUTPUT")
+    has_flag --content-boundaries "$@" || inject+=(--content-boundaries)
+    ;;
+  find | diff)
+    has_flag --json "$@"       || inject+=(--json)
+    has_flag --max-output "$@" || inject+=(--max-output "$DEFAULT_MAX_OUTPUT")
+    ;;
+  *)
+    : # unknown/binary-output subcommand — inject nothing (fail-open passthrough)
+    ;;
+esac
+
+exec "$BIN" "$cmd" "${inject[@]+"${inject[@]}"}" "$@"

package/plugins/ast-grep/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "ast-grep",
+  "version": "6.8.0",
+  "description": "Structural code search & rewrite (ast-grep): skill, wrapper, and a PreToolUse Grep→ast-grep nudge registered into the toolu hook engine.",
+  "author": {
+    "name": "Falconiere Barbosa",
+    "email": "hello@falconiere.io"
+  },
+  "homepage": "https://github.com/falconiere/toolu",
+  "repository": "https://github.com/falconiere/toolu.git",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "ast-grep",
+    "structural-search",
+    "hooks"
+  ]
+}

package/plugins/ast-grep/.codex-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "ast-grep",
+  "version": "6.8.0",
+  "description": "Structural code search & rewrite (ast-grep): skill, wrapper, and a PreToolUse Grep→ast-grep nudge registered into the toolu hook engine.",
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks.json"
+}

package/plugins/ast-grep/README.md

@@ -0,0 +1,21 @@
+# ast-grep
+
+Structural code search & rewrite (ast-grep): a skill, a wrapper, and a `PreToolUse` `Grep → ast-grep` nudge registered into the toolu hook engine.
+
+## Install
+
+```
+/plugin install ast-grep@toolu
+```
+
+Standalone, no dependencies.
+
+## What it provides
+
+- **`ast-grep` skill** — an always-active protocol that mandates ast-grep (tree-sitter AST patterns) over Grep/sed for any find-or-rewrite-by-code-shape task, falling back to Grep only for exact literals.
+- **`search-nudge` (`PreToolUse`)** — nudges Grep on code files, and `grep`/`rg` in Bash, toward the proper structural tool.
+- **`byte-savings` (`PostToolUse`)** + `byte-savings-report.sh` — instrumentation for tokens saved by structural search.
+
+## The ast-grep binary
+
+The skill drives the `ast-grep` (a.k.a. `sg`) CLI — a tree-sitter AST pattern matcher and rewriter. Install it via `brew install ast-grep`, `cargo install ast-grep`, or `npm i -g @ast-grep/cli`. The plugin's hook modules register themselves into the core toolu dispatcher at `SessionStart` and run only while this plugin is installed.

package/plugins/ast-grep/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/register.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/ast-grep/hooks/post-tools.d/byte-savings.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# PostToolUse instrumentation — measure how many bytes targeted/structural tools
+# inject into context, so the "ast-grep returns far less than reading whole
+# files" claim is MEASURED, not asserted.
+#
+# Honest by construction: it records the REAL byte count each tool returned. For
+# a Read of a single on-disk file it also records that file's full size (the
+# bytes a whole read costs), so a ranged Read shows a real saving. It does NOT
+# fabricate a counterfactual for searches — it records what ast-grep/Grep
+# actually returned, and the report aggregates per tool so the volume gap is
+# visible. Append-only ledger; never blocks; emits nothing to context.
+#
+# Inputs (exported by post-tools/mod.sh): $tool_name $input $PROJECT_ROOT
+: "${tool_name:=}"
+: "${input:=}"
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Classify the tool; ignore everything we don't measure as cheaply as possible.
+kind=""
+case "$tool_name" in
+  Read) kind="read" ;;
+  Grep) kind="grep" ;;
+  Glob) kind="glob" ;;
+  Bash|Shell)
+    cmd=$(jq -r '.tool_input.command // ""' <<<"$input" 2>/dev/null)
+    # Matches `ast-grep …`, `sg …`, and piped forms (`… | ast-grep …`) — the
+    # leading-space alternative subsumes the pipe case, so no separate pattern.
+    case "$cmd" in
+      ast-grep*|sg\ *|*\ ast-grep\ *) kind="ast-grep" ;;
+      *) exit 0 ;;
+    esac
+    ;;
+  *) exit 0 ;;
+esac
+
+# Returned bytes = byte length of the tool's textual response. tool_response may
+# be a string (Read/Grep) or an object (Bash); coerce to text then measure.
+resp=$(jq -r '
+  .tool_response
+  | if   type == "string" then .
+    elif type == "object" then (.content? // .stdout? // .output? // tostring)
+    else tostring end' <<<"$input" 2>/dev/null)
+[ -n "$resp" ] || exit 0
+returned=$(printf '%s' "$resp" | wc -c | tr -d ' ')
+[ -n "$returned" ] || exit 0
+
+# Full-file bytes (single-file Read only): the cost a whole read would incur.
+full=0
+if [ "$kind" = "read" ]; then
+  fp=$(jq -r '.tool_input.file_path // ""' <<<"$input" 2>/dev/null)
+  if [ -n "$fp" ] && [ -f "$fp" ]; then
+    full=$(wc -c < "$fp" 2>/dev/null | tr -d ' ')
+    [ -n "$full" ] || full=0
+  fi
+fi
+
+# Append one compact record to the per-session ledger. Session-scoped so a
+# stale id can never grow unbounded; the report aggregates a single session.
+sid=$(jq -r '.session_id // "unknown"' <<<"$input" 2>/dev/null | tr -cd 'A-Za-z0-9-')
+[ -n "$sid" ] || sid="unknown"
+ledger_dir="${TOOLU_CONFIG_DIR:-${CODEX_HOME:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}}/toolu/byte-savings"
+mkdir -p "$ledger_dir" 2>/dev/null || exit 0
+printf '{"kind":"%s","returned":%s,"full":%s}\n' "$kind" "$returned" "$full" \
+  >> "$ledger_dir/$sid.jsonl" 2>/dev/null
+
+exit 0

package/plugins/ast-grep/hooks/pre-tools.d/search-nudge.sh

@@ -0,0 +1,170 @@
+#!/bin/bash
+# Pre-tool check: Enforce search hierarchy
+#   1. ast-grep (structural / AST patterns) — first on code files
+#   2. Grep    (exact literals on non-code files, or after ast-grep returned nothing)
+#
+# Grep on code files is nudged toward ast-grep when patterns look structural.
+# Bash grep/rg is always nudged toward proper tools.
+#
+# Inputs (from parent dispatcher pre-tools/mod.sh, via `export`):
+#   $tool_name - name of the tool being invoked
+#   $input     - raw JSON payload on stdin
+
+: "${tool_name:=}"
+: "${input:=}"
+
+# Core lib comes from the toolu dispatcher via TOOLU_LIB_DIR (set by
+# plugins/toolu/hooks/pre-tools/mod.sh before registry dispatch). Outside
+# that pipeline there is no relative path to it — fail SOFT: this module is
+# an advisory extra and must never break tool calls by erroring.
+[ -n "${TOOLU_LIB_DIR:-}" ] && [ -f "$TOOLU_LIB_DIR/detect.sh" ] && [ -f "$TOOLU_LIB_DIR/config.sh" ] || exit 0
+# shellcheck source=../../../toolu/hooks/lib/detect.sh
+. "$TOOLU_LIB_DIR/detect.sh"
+# shellcheck source=../../../toolu/hooks/lib/config.sh
+. "$TOOLU_LIB_DIR/config.sh"
+
+# Decide ast-grep state lazily: config + CLI detection are only consulted when
+# a structural pattern or grep/rg invocation is actually matched, so the
+# common Bash/Grep tool call pays nothing.
+ASTGREP_STATE=""
+astgrep_state() {
+  if [ -z "$ASTGREP_STATE" ]; then
+    if ! toolu_enabled skills ast-grep; then
+      ASTGREP_STATE="opt-out"
+    elif [ "$(detect_ast_grep)" = "ast-grep" ]; then
+      ASTGREP_STATE="available"
+    else
+      ASTGREP_STATE="missing"
+    fi
+  fi
+  printf '%s' "$ASTGREP_STATE"
+}
+
+# ── Structural pattern keywords (shared) ────────────────────────────────────
+STRUCT_RE='(^|\s)(fn |impl |async fn|async |class |function |struct |trait |interface |type |pub (fn|struct|enum|trait|mod|type|async)|export (function|class|interface|type|const|default)|enum |mod |const fn|#\[derive|#\[cfg|#\[test|@Component|@Injectable|@Module|=>|-> Result|-> impl|dyn |Box<|Arc<|Vec<|Option<|where |for .*in )'
+
+# ── Non-code file globs (Grep is sole tool for these) ──────────────────────
+NON_CODE_GLOB_RE='\*\.(toml|md|markdown|json|jsonc|yaml|yml|txt|env|sql|sh|bash|zsh|fish|lock|cfg|ini|conf|csv|xml|html|svg|css|graphql|gql|proto|makefile|dockerfile)'
+NON_CODE_TYPE_RE='^(toml|json|yaml|md|markdown|html|css|sql|sh|bash|make|docker|config|xml|csv|graphql|proto)$'
+
+# ── Non-code path segments (hooks, docs, config dirs) ──────────────────────
+NON_CODE_PATH_RE='(\.claude/|docs/|\.github/|infra/|scripts/|\.config|Makefile|Dockerfile|Cargo\.toml|package\.json|tsconfig)'
+
+# ── Grep tool ───────────────────────────────────────────────────────────────
+if [[ "$tool_name" == "Grep" ]]; then
+  pattern=$(echo "$input" | jq -r '.tool_input.pattern // ""')
+  glob_filter=$(echo "$input" | jq -r '.tool_input.glob // ""')
+  type_filter=$(echo "$input" | jq -r '.tool_input.type // ""')
+  path_filter=$(echo "$input" | jq -r '.tool_input.path // ""')
+
+  # ── ALLOW: Non-code file types (Grep is sole tool — ast-grep can't do these)
+  if [[ -n "$glob_filter" ]] && echo "$glob_filter" | grep -qiE "$NON_CODE_GLOB_RE"; then
+    exit 0
+  fi
+  if [[ -n "$type_filter" ]] && echo "$type_filter" | grep -qiE "$NON_CODE_TYPE_RE"; then
+    exit 0
+  fi
+  if [[ -n "$path_filter" ]] && echo "$path_filter" | grep -qiE "$NON_CODE_PATH_RE"; then
+    exit 0
+  fi
+
+  # ── STOP: Structural code pattern → ast-grep (only when installed)
+  if echo "$pattern" | grep -qE "$STRUCT_RE"; then
+    case "$(astgrep_state)" in
+      available)
+        jq -n '{
+          "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "additionalContext": "STOP: Structural code pattern detected. Use ast-grep: `ast-grep run --pattern \"your pattern\" --lang rust/typescript .` AST-aware matching is far more accurate. Grep is for exact literals on non-code files, or after ast-grep returned nothing."
+          }
+        }'
+        ;;
+      missing)
+        jq -n '{
+          "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "additionalContext": "WARN: structural code pattern detected but ast-grep is not installed. Falling back to Grep — expect false positives. Install ast-grep (`cargo install ast-grep` or `brew install ast-grep`) for AST-aware matching."
+          }
+        }'
+        ;;
+      opt-out|*)
+        : # user opted out of ast-grep — no nudge, no install hint
+        ;;
+    esac
+    exit 0
+  fi
+
+  exit 0
+fi
+
+# ── Bash tool: catch grep/rg being used for code search ────────────────────
+if [[ "$tool_name" == "Bash" || "$tool_name" == "Shell" ]]; then
+  command=$(echo "$input" | jq -r '.tool_input.command // ""')
+
+  # Strip heredoc bodies
+  cmd_only=$(printf '%s\n' "$command" | strip_heredocs)
+
+  # Catch grep/rg invocations
+  if echo "$cmd_only" | grep -qE '(^|\s|&&|\|\||;)(grep|rg|ripgrep)\s'; then
+    # Structural patterns → ast-grep (only when installed)
+    if echo "$cmd_only" | grep -qE "$STRUCT_RE"; then
+      case "$(astgrep_state)" in
+        available)
+          jq -n '{
+            "hookSpecificOutput": {
+              "hookEventName": "PreToolUse",
+              "additionalContext": "STOP: grep/rg for structural code search. Use ast-grep: `ast-grep run --pattern \"your pattern\" --lang rust/typescript .` grep/rg is for piping command output or non-code files."
+            }
+          }'
+          ;;
+        missing)
+          jq -n '{
+            "hookSpecificOutput": {
+              "hookEventName": "PreToolUse",
+              "additionalContext": "WARN: structural grep/rg detected but ast-grep is not installed. Proceeding with grep/rg — expect false positives. Install ast-grep (`cargo install ast-grep` or `brew install ast-grep`) for AST-aware matching."
+            }
+          }'
+          ;;
+        opt-out|*)
+          : # ast-grep opted out — no STOP/WARN
+          ;;
+      esac
+      exit 0
+    fi
+
+    # All other grep/rg → nudge toward proper tools.
+    # The Grep-tool-vs-bash-grep advice is independent of ast-grep, so this
+    # fires even when ast-grep is opted out; we just drop the ast-grep half.
+    case "$(astgrep_state)" in
+      available)
+        jq -n '{
+          "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "additionalContext": "grep/rg in Bash detected. Use ast-grep for structural patterns on code files, Grep tool for exact literals on non-code files. Bash grep/rg only for piping command output."
+          }
+        }'
+        ;;
+      missing)
+        jq -n '{
+          "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "additionalContext": "grep/rg in Bash detected. Use Grep tool for exact literals on non-code files. Bash grep/rg only for piping command output. (ast-grep not installed — structural matching unavailable.)"
+          }
+        }'
+        ;;
+      opt-out|*)
+        jq -n '{
+          "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "additionalContext": "grep/rg in Bash detected. Use Grep tool for exact literals on non-code files. Bash grep/rg only for piping command output."
+          }
+        }'
+        ;;
+    esac
+    exit 0
+  fi
+
+  exit 0
+fi
+
+exit 0

package/plugins/ast-grep/hooks/register.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# SessionStart registry sync for the ast-grep plugin.
+#
+# Mirrors hooks/pre-tools.d/*.sh and hooks/post-tools.d/*.sh into the toolu
+# runtime registry (${TOOLU_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}/toolu/{pre,post}-tools.d/)
+# under the namespaced filename ast-grep@toolu__<name>.sh, and prunes entries
+# bearing OUR prefix whose source module no longer exists. Other plugins'
+# entries are never touched. The core toolu dispatcher executes the synced
+# copies, gated on this plugin being installed.
+#
+# Silent on success (SessionStart stdout becomes context); errors are
+# non-fatal — a failed sync means the registry copy is stale, not broken.
+
+SPEC="ast-grep@toolu"
+SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
+if [ -n "${TOOLU_CONFIG_DIR:-}" ]; then
+  CONFIG_ROOT="$TOOLU_CONFIG_DIR"
+elif [ "${TOOLU_HOST_OVERRIDE:-}" = codex ] || { [ -z "${TOOLU_HOST_OVERRIDE:-}" ] && [ -n "${PLUGIN_ROOT:-}" ]; }; then
+  CONFIG_ROOT="${CODEX_HOME:-$HOME/.codex}"
+else
+  CONFIG_ROOT="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+fi
+REG_ROOT="$CONFIG_ROOT/toolu"
+
+# Consume stdin so Claude Code's hook IPC never stalls.
+cat > /dev/null 2>&1 || true
+
+# Mirror one source dir into its matching registry dir (atomic, self-pruning).
+sync_dir() {
+  local src_dir="$1" reg_dir="$2" src name dst tmp
+  [ -d "$src_dir" ] || return 0
+  mkdir -p "$reg_dir" 2>/dev/null || return 0
+
+  # Clear OUR orphaned atomic-write residue from prior crashed runs (a death
+  # between cp and mv leaves <spec>__<name>.sh.tmp.<pid>; nothing executes
+  # them, but nothing else cleans them either). Age-gated so a concurrent
+  # SessionStart's in-flight tmp (seconds old) is never clobbered.
+  find "$reg_dir" -maxdepth 1 -name "${SPEC}__*.sh.tmp.*" -mmin +1 -delete 2>/dev/null
+
+  # Sync: copy each source module if missing or changed (atomic tmp+mv).
+  for src in "$src_dir"/*.sh; do
+    [ -f "$src" ] || continue
+    name=$(basename "$src")
+    dst="$reg_dir/${SPEC}__${name}"
+    if [ ! -f "$dst" ] || ! cmp -s "$src" "$dst"; then
+      tmp="${dst}.tmp.$$"
+      if cp "$src" "$tmp" 2>/dev/null; then
+        mv "$tmp" "$dst" 2>/dev/null || rm -f "$tmp"
+      else
+        rm -f "$tmp" 2>/dev/null
+      fi
+    fi
+  done
+
+  # Prune: remove OUR entries whose source module is gone. Never glob outside
+  # our own spec prefix.
+  for dst in "$reg_dir/${SPEC}__"*.sh; do
+    [ -f "$dst" ] || continue
+    name=$(basename "$dst")
+    src="$src_dir/${name#"${SPEC}"__}"
+    [ -f "$src" ] || rm -f "$dst"
+  done
+}
+
+sync_dir "$SELF_DIR/pre-tools.d"  "$REG_ROOT/pre-tools.d"
+sync_dir "$SELF_DIR/post-tools.d" "$REG_ROOT/post-tools.d"
+
+exit 0

package/plugins/ast-grep/scripts/byte-savings-report.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# byte-savings-report.sh <ledger.jsonl>
+#
+# Aggregates a per-session byte-savings ledger (written by the post-tools
+# byte-savings instrumentation module) into a per-kind summary: bytes each tool
+# returned into context (with a ~token estimate at 4 bytes/token) and, for
+# single-file Reads, the targeting saving vs reading the whole file. Read-only.
+set -u
+
+ledger="${1:-}"
+command -v jq >/dev/null 2>&1 || { echo "byte-savings-report: jq required" >&2; exit 1; }
+[ -n "$ledger" ] && [ -f "$ledger" ] || {
+  echo "usage: byte-savings-report.sh <ledger.jsonl>" >&2; exit 1; }
+
+jq -rs '
+  group_by(.kind)
+  | map({ kind: .[0].kind,
+          n: length,
+          returned: (map(.returned) | add),
+          full: (map(.full) | add) }) as $g
+  | ($g | map(.returned) | add) as $tot
+  | ( $g[]
+      | if .kind == "read" and .full > 0
+        then "\(.kind): returned=\(.returned) full=\(.full) saved=\((((.full - .returned) * 100) / .full) | floor)% (n=\(.n))"
+        else "\(.kind): returned=\(.returned) (n=\(.n))"
+        end ),
+    "TOTAL returned: \($tot) bytes (~\(($tot / 4) | floor) tok)"
+' "$ledger"

package/plugins/ast-grep/skills/ast-grep/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: ast-grep
+description: "ALWAYS ACTIVE — Structural code search and rewrite protocol. You MUST use ast-grep instead of Grep/sed for any 'find/rewrite by code shape' task (AST patterns, not text). Falls back to Grep for exact literals only."
+---
+
+# ast-grep Structural Search & Rewrite Protocol
+
+You have ast-grep (tree-sitter AST pattern matcher + rewriter) via the `ast-grep` / `sg` CLI.
+This protocol is **MANDATORY and ALWAYS ACTIVE**.
+
+## Hard Constraints
+
+- Use `ast-grep run -p '<pattern>'` BEFORE Grep when the query is about **code shape** (AST), not text.
+- Use `ast-grep run -p '...' -r '...'` BEFORE sed/Edit-loops when rewriting many call sites.
+- Always pass `-l <lang>` for clarity (`typescript`, `tsx`, `javascript`, `rust`, `python`, `go`, ...).
+- Never edit hand-rolled regex over multi-line code — use ast-grep instead.
+
+## Position in the Search Stack
+
+```
+comemory → "what was decided / where is X" (memory)
+ast-grep → "find / rewrite this code shape" (AST structural)   ← here
+Grep     → "find exact literal `FOO_BAR`"                     (text)
+Glob     → "list paths matching `**/*.test.ts`"               (paths)
+Read     → "open known file"                                   (verify)
+```
+
+## When to Use ast-grep
+
+✓ "Find all `useState($X)` calls without initial value"
+✓ "Find all `try` blocks without `catch`"
+✓ "Replace `console.log($X)` with `logger.info($X)` repo-wide"
+✓ "Find all functions returning `Promise<void>`"
+✓ "Find all `export default function` declarations"
+✓ "Find all `await fetch($URL)` without error handling"
+✓ Bulk safe refactor across many files (AST-aware, comment-preserving)
+
+## When NOT to Use ast-grep
+
+✗ Semantic intent ("how does auth work") → check comemory memory, then Grep on keywords + Read on hits
+✗ Exact literal in config files (`*.toml`, `*.md`, `*.json`) → Grep
+✗ Path/filename patterns → Glob
+✗ Single-file targeted edit → Read + Edit
+
+## CLI Reference
+
+### Search
+```bash
+ast-grep run -p '<pattern>' -l <lang> [paths...]
+ast-grep run -p '<pattern>' -l typescript apps/api/src
+```
+
+### Rewrite (preview)
+```bash
+ast-grep run -p '<pattern>' -r '<replacement>' -l <lang> [paths...]
+```
+Shows diff. Add `-U` (or `--update-all`) to apply.
+
+### Apply rewrite
+```bash
+ast-grep run -p '<pattern>' -r '<replacement>' -l <lang> -U [paths...]
+```
+
+### Inspect AST (debugging patterns)
+```bash
+ast-grep run -p '<pattern>' -l <lang> --debug-query=ast
+```
+
+### Strictness
+```bash
+--strictness smart      # default — ignores trivia
+--strictness relaxed    # ignores comments
+--strictness signature  # ignores text — match by shape only
+```
+
+## Pattern Syntax (Quick)
+
+- `$X` — single named metavariable (any node)
+- `$$$ARGS` — multi-node metavariable (zero or more)
+- `$_` — anonymous wildcard
+- Same metavariable name = same content (linear pattern)
+
+Examples:
+| Want | Pattern |
+|------|---------|
+| any `console.log` call | `console.log($$$)` |
+| `useState` with no arg | `useState()` |
+| same var assigned to itself | `$X = $X` |
+| arrow fn with single body expr | `($$$) => $BODY` |
+| catch-all `try` no catch | `try { $$$ } finally { $$$ }` |
+
+## Workflow — Search
+
+1. Draft pattern. Run with `--debug-query=ast` once to verify shape.
+2. Run real search: `ast-grep run -p '...' -l <lang> <paths>`.
+3. If too many hits → narrow with `--strictness smart` or extra context nodes.
+4. If zero hits → broaden to `$_` / `$$$`, recheck AST.
+
+## Workflow — Rewrite
+
+1. **Preview first**: never use `-U` until diff looks right.
+2. Run preview: `ast-grep run -p '...' -r '...' -l <lang> <paths>`.
+3. Read the diff. Confirm metavariables map correctly.
+4. Apply: same command with `-U`.
+5. Run your project's typecheck/lint (use the detected package manager — see `detect_node_pm` / `detect_rust` in `hooks/lib/detect.sh`) to verify zero regressions.
+6. Save the pattern if reusable — when the `comemory` plugin is installed, persist it via its wrapper: `comemory.sh save "ast-grep <name> pattern" "<pattern + what it matches>" --kind pattern --tags "ast-grep"`.
+
+## Self-Check Before Editing
+
+> "Am I about to write a regex over multi-line code? → ast-grep instead."
+> "Am I about to Edit-loop the same change across many files? → ast-grep rewrite instead."
+> "Am I searching for code by shape (call form, signature, control flow)? → ast-grep, not Grep."
+
+## Config (sgconfig.yml — optional, lazy)
+
+If a recurring rule emerges (e.g. forbid `console.log` in apps/api), promote it to `sgconfig.yml`:
+```bash
+ast-grep new project   # bootstrap config
+ast-grep new rule      # add reusable rule
+ast-grep scan          # run all configured rules
+```
+Hold off until pattern is proven across ≥3 files.
+
+## Cross-Reference
+
+- Memory: `skills/agent-memory/SKILL.md`
+- Project rules: `AGENTS.md`, `CLAUDE.md`, and other host instruction files

package/plugins/ast-grep/skills/ast-grep/references/ast-grep-advanced.md

@@ -0,0 +1,44 @@
+# ast-grep Advanced Usage
+
+## Complex Rules (inline YAML)
+
+For patterns beyond simple `--pattern`, use `scan` with inline YAML:
+
+```bash
+mod.sh ast-grep scan 'id: find-async
+language: rust
+rule:
+  kind: function_item
+  has:
+    pattern: async fn \$NAME
+    stopBy: end'
+```
+
+## Critical Rules
+
+- `stopBy: end` required in `has`/`inside` for deep matching — without it, only direct children match
+- `scan` rules require `kind` field
+- `--max-results` only works in `scan` — use `| head -N` for `search`
+- Escape `$` as `\$` in inline-rules strings (not needed in `--pattern` with single quotes)
+
+## Common Patterns
+
+```bash
+# Rust: impl blocks for a trait
+mod.sh ast-grep search 'impl $TRAIT for $TYPE { $$$BODY }' --lang rust
+
+# Rust: async functions
+mod.sh ast-grep search 'async fn $NAME($$$ARGS)' --lang rust
+
+# Rust: functions returning Result
+mod.sh ast-grep search 'fn $NAME($$$ARGS) -> Result<$$$>' --lang rust
+
+# TypeScript: console.log calls
+mod.sh ast-grep search 'console.log($$$ARGS)' --lang typescript
+
+# File paths only (no content)
+mod.sh ast-grep files 'impl $TRAIT for $TYPE { $$$BODY }' --lang rust
+
+# Debug pattern parsing
+mod.sh ast-grep debug 'fn $NAME($$$ARGS)' --lang rust
+```