When to Use gabb vs Grep/Read

Pre-Flight Checklist (Before ANY Read on Code Files)

Before calling Read on a code file, run this check:

□ Is file extension in [.py, .pyi, .ts, .tsx, .rs, .kt, .kts, .cpp, .cc, .cxx, .hpp, .hh]?
  ├─ NO  → Use Read directly (unsupported language)
  └─ YES → Have I called gabb_structure on this file in this session?
           ├─ NO  → Call gabb_structure FIRST, then decide what to read
           └─ YES → Use Read with offset/limit based on structure output

Why checklists work: They force a pause before automatic behavior.

The Core Decision

Ask yourself: "Am I looking for CODE (functions, classes, symbols)?"

Supported Languages

For .js, .jsx, .go, .java, .c, .h → Use Grep/Read

Start Here: The Two-Step Pattern

Step 1: Get cheap overview (no source code, just structure)

gabb_structure file="path/to/file.py"

MANDATORY for any supported code file. Returns symbol names, kinds, line numbers.

Step 2: Get specific code (one of these based on what you need)

• gabb_symbols name="FunctionName" include_source=true - get a specific symbol's code
• Read file="path" offset=150 limit=50 - read specific line range from structure output

Quick Reference

Use include_source=true on gabb_symbols, gabb_symbol, gabb_definition - NOT on gabb_structure.

Specialized Tools

For call tracing, type hierarchies, and other tasks:

• callers.md / callees.md - trace call graph
• hierarchy.md - supertypes/subtypes
• definition.md - jump to definition
• rename.md - safe renaming
• implementations.md - find interface implementations

When to Fall Back to Grep/Read

1. Searching text content (error messages, comments, strings)
2. Unsupported file types (.js, .go, .java, .json, .md)
3. Finding config values or non-code content