gs
Drill into a known file to retrieve its symbols, imports, importers, and related files. Identify who uses a file or calls a symbol directly, with optional filtering via match.
Instructions
Drill into a known file. Returns these sections as compact text:
Symbols — top-level + per-class methods (name, kind, line range, extends/implements). With cross-file callers attached per exported symbol (inline if 1 caller; newline-per-caller block if ≥2). For huge files (>20 symbols, no
match), symbols are reordered by caller count (most-used first) and truncated to top 15.Imports — 1-hop internal outbound dependencies (library imports stripped).
Importers — 1-hop reverse: files in this repo that import this one. With
match, additionally lists EVERY indexed file (importer or not, any language) whose CONTENT references the matched term even when its filename does not (a registry, admin, or config file using the symbol — or a frontend file referencing a backend name). That subsection IS the complete "who uses " answer: it is exhaustive over indexed content, so a subsystem absent from it does NOT use the symbol — do not grep to enumerate or re-verify use-sites, and do not keep hunting in subsystems the section rules out.Related — files sharing rare identifier/string-literal tokens with this file (with
match: with the matched symbols' code region), shown only when NO import edge connects them. These are name-reference relations the import graph cannot see — Django migrations↔models, config-by-name registration, cross-language (JS↔Python) pairs. Treat them as first-class neighbors: the shared token shown is the reason they are related. Use this AFTER find surfaces a candidate file. This is the right tool for "who uses this file" / "who calls this symbol" — no separate call needed.
view controls which sections you get (default full = all four). symbols, imports, importers, callers each return one section in isolation when you want a byte-light answer.
For god-files (large classes, large routers, large config modules), pass match to filter symbols/imports/importers/callers to one area — e.g. match: "auth" or match: "/^handle/". Substring is case-insensitive; wrap in slashes for regex.
Prefer this over Read when you need shape, neighbors, or usage. Reach for Read only for implementation details inside a method body. If you have called gs on 5+ files for one question, you are enumerating — go back to find with a sharper path glob or a different concept token instead.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | Which sections to return. Default "full" = symbols (with inline callers) + imports + importers. Use one of the narrower views to halve or quarter the output when you know what you need: "symbols" (shape only, no callers), "imports" (outbound only), "importers" (inbound only), "callers" (per-symbol cross-file callers in expanded form, no symbol shape). | |
| match | No | Filter all sections by name. Substring (case-insensitive) by default; use `|` to OR substrings (`match: "resource|tile"`); wrap in slashes for regex (`match: "/^handle/"`). Use this on large/god-files to avoid a wall of output — e.g. `match: "tile"` on a big models.py reduces output to just tile-related symbols, their callers, and matching imports/importers. | |
| symbol | No | Deliver the BODY of the named symbol(s) inline, sliced from their indexed line range — so you read a method WITHOUT a Read at a guessed offset. Comma/pipe-separate names (`serialize,restore_state`). A bare name matches the method (`serialize` → `Graph.serialize`). Each body is followed by `callers:`/`calls:` POINTERS (file + line range) so the next hop is one more `gs --symbol` call, not a windowed Read. Use this the moment a file’s symbol list shows the method you need — it replaces the read-at-offset hunt on god-files. If the name is NOT a declared symbol (a runtime/template-injected value, a string key, a config token), it falls back to an in-tool GREP: returns the body lines where the token appears, with context — so you never shell out to grep. Overrides `view`/`match`. | |
| file_path | Yes | Relative path to the file (e.g. "src/auth/service.ts"). Suffix matches are accepted. |