Pattern-based ops for finding content across files or zooming into a known location. Reach for these when you don't know the exact file yet, or when you want context around a match.
| Op | Syntax | What it does |
|---|---|---|
grep |
grep:PATTERN:PATH or grep:PATTERN:PATH:LIMIT |
10 results default, code + doc extensions only. Auto-reads full file if PATH is a concrete file < 20KB with a match. Append :no-auto-read to suppress (parity with glob). |
grep (context) |
grep:PATTERN:PATH:LIMIT:CONTEXT |
Show CONTEXT lines before/after each match (like grep -C). Match lines: path:lineno:content. Context lines: path-lineno-content. Non-adjacent groups separated by --. |
grep (count) |
grep:PATTERN:PATH:LIMIT:CONTEXT:count |
Return match counts per file instead of content. Output: filepath:COUNT per line. |
grep_around |
grep_around:PATTERN:PATH or grep_around:PATTERN:PATH:N:LIMIT |
Every match across files with N lines context (default N=3, LIMIT=10). Alias for grep:PATTERN:PATH:LIMIT:CONTEXT with sane defaults — useful for "show me how everyone uses this". Output capped at ~16KB (see below). |
around |
around:PATTERN:PATH or around:PATTERN:PATH:N |
Show N lines (default 10) before and after the first match of PATTERN in a single file. Uses line-numbered output like read. Output capped at ~16KB (see below). |
around_line |
around_line:PATH:LINE or around_line:PATH:LINE:N |
Show N lines (default 10) of context around a specific line number. Target line marked with →. |
between |
between:SYMBOL:PATH or between:re:START:END:PATH |
Return a chunk of a file. Symbol mode (default): full body of a named function/method/class via tree-sitter (PHP, Python, JS, TS, Go, Rust, Java, Ruby — symbols with :: like PHP Foo::bar work). Pattern mode (re: prefix): inclusive line slice from first line matching START regex to first line after matching END regex (language-agnostic). |
A large :N context on a file of long (e.g. minified) lines can over-fetch — one op can dump hundreds of KB and blow your context budget. around: and grep_around: cap their output at ~16KB, truncating at a line boundary with a footer that points at the narrower tools (smaller :N, or between: for a whole symbol). Tune via builtin-ops.around.max_bytes / builtin-ops.grep_around.max_bytes in .supertool.json (or SUPERTOOL_AROUND_MAX_BYTES / SUPERTOOL_GREP_AROUND_MAX_BYTES). See configuration.md.
grep: with an explicit CONTEXT argument (grep:PATTERN:PATH:LIMIT:CONTEXT) shares the grep_around: code path, so it is capped under the same grep_around.max_bytes budget. Plain grep: (no context) is unaffected — it has its own LIMIT/max_results bound.
Find all usages of a function across a codebase, with 2 lines of context:
./supertool 'grep:handle_request:src/:20:2'Count which files reference a symbol most:
./supertool 'grep:MyClass:src/:50:0:count'Show how a pattern is used everywhere ("show me how everyone uses this"):
./supertool 'grep_around:def handle:src/:5:15'Jump to a known line and see surrounding context:
./supertool 'around_line:src/app/Module.py:142:8'Extract a full function body by name:
./supertool 'between:handle_request:src/app/Module.py'
./supertool 'between:MyClass::handle:src/app/Module.php'Extract a block by regex anchors (language-agnostic):
./supertool 'between:re:^def handle_request:^def :src/app/Module.py'- reads.md — when you know the path and want raw content
- map.md — when you want all symbols in a file/directory at once (faster than grep for orientation)
- docs/validators.md — validators fire on edits triggered after search-guided changes