GC-201b · Module 2

File System & Search Tools

3 min read

Gemini CLI's built-in file system tools are more capable than most developers realize. read_file supports offset and limit parameters for reading specific sections of large files — critical for multi-thousand-line files where loading everything wastes context. glob finds files by pattern with the speed of native filesystem calls. search_file_content performs ripgrep-style regex searches across your entire codebase. list_directory maps directory structures. Together, these tools make Gemini a surprisingly effective codebase navigator.

The codebase_investigator tool is the deep analysis engine. Unlike simple file reads and searches, the investigator follows references, maps dependencies, traces data flows, and builds a holistic understanding of code structure. When you ask "how does authentication work in this project?" the investigator does not just search for files with "auth" in the name — it traces the authentication flow from route handler to middleware to token validation to database query. This is the difference between search and investigation.

# Gemini's file system tools in action:

# Read specific lines of a large file
"Read lines 150-200 of src/api/router.ts"
# Uses read_file with offset/limit

# Find all TypeScript files in the API layer
"Find all .ts files in src/api/"
# Uses glob with pattern matching

# Search for a pattern across the codebase
"Find all uses of the deprecated createUser function"
# Uses search_file_content with regex

# Deep analysis of a system
"Trace the payment processing flow from API endpoint to database write"
# Uses codebase_investigator for multi-file analysis

Do This

  • Use offset/limit when reading large files — only load what you need
  • Use codebase_investigator for architectural analysis and dependency tracing
  • Use .geminiignore to exclude directories that should never be searched

Avoid This

  • Load entire large files when you only need a specific function or section
  • Use simple file reads when you need the investigator's cross-file analysis
  • Search without .geminiignore and waste tokens scanning node_modules and dist/