Learning Agent Development with Google Gemini CLI (Part 2): How Does Gemini CLI Read and Modify Your Code?

In the previous article, my partner Tam revealed how Gemini CLI builds its security “moat” through sandboxing mechanisms. That piece generated enthusiastic responses, with readers showing great interest in this design approach that balances openness with rigor.

Having addressed the foundational “security” question, we naturally ask: within these secure walls, how exactly does AI interact with our code? How does it “comprehend” thousands of files, and how does it act like a surgeon, precisely “operating” to modify code? What design philosophy underlies all this?

Today, I’ve invited Tam back to continue his source code exploration, delivering a deep analysis of Gemini CLI’s file system toolset—essentially AI’s “eyes” and “scalpel.”

Enough preamble—over to Tam.

by Tam -

Chapter 1: Design Philosophy—Building an Interactive Code “World Model” for AI

To understand the power of these file tools, you must first understand their core design philosophy: they’re not isolated feature stacks, but serve a grand purpose—constructing a dynamic, interactive, and sufficiently precise local code “World Model” within the LLM’s limited cognitive scope. This model aims to resolve the fundamental conflict between LLMs’ “statelessness” and software development’s “strong statefulness.”

This philosophy manifests in three core principles:

Layered Perception: Perfectly replicates how human developers understand projects from macro to micro (view directory → search files → read code).
Precise Context Construction and Isolation: Transforms flat text streams into structured, high-quality context with source metadata through delimiters.
Security, Confirmation, and User Sovereignty: Adheres to “AI as assistant, user as master” by separating read/write operations and requiring user confirmation, ensuring ultimate control always remains with developers.

Chapter 2: Code World Explorers—Deep Dive into Read-Only Tools

2.1 list_directory and glob: From “Seeing” to “Searching”

list_directory is AI’s first pair of eyes, and the default enabling of the respect_git_ignore parameter reflects deep understanding of developer experience, naturally excluding irrelevant files like node_modules. glob is the advanced scout—its results being “sorted by modification time (newest first)” is an extremely clever design, letting AI prioritize recently active code and quickly focus on key areas.

2.2 search_file_content: AI’s X-Ray Vision

This grep-powered tool digs deep into code to locate content. It preferentially uses the lightning-fast git grep, with fallback to system grep for universal compatibility. Its highlight is structured output, extremely LLM-friendly:

Found 3 match(es) for pattern "myFunction" in path ".":
---
File: src/utils.ts
L15: export function myFunction()
L22: myFunction.call();
---
File: src/index.ts
L5: import myFunction from './utils';
---

This format lets the model easily parse filenames and line numbers, laying groundwork for subsequent precise reading.

2.3 read_file and read_many_files: Deep Code Readers

read_file is like a scalpel—its offset and limit parameters enable “code slicing” reads, plus it supports reading images and PDFs for multimodal understanding. read_many_files is the CT scanner, a core tool tailor-made for large-scale code comprehension and cross-file refactoring, offering complete filtering through paths, include, exclude parameters. Their shared soul is using delimiters to reshape unordered content into structured, traceable high-quality context.

Chapter 3: Code Reshaper—The Art and Safety of the Replace Tool

If read-only tools are AI’s “eyes,” replace is its “hands.” It aims to solve two core challenges: the “ambiguity” of AI modification instructions and code “state drift.”

3.1 “Context Anchor”: The Essence of old_string Parameter

The core of replace lies in its old_string parameter design. It’s not simply text to be replaced, but a “context anchor.” Documentation strictly requires: “This string must include at least 3 lines of context before and after the target text, with exact whitespace and indentation matching.” This design eliminates ambiguity and combats state drift, ensuring replacement uniqueness and accuracy.

3.2 Ultimate Weapon: Multi-Stage Edit Correction

This is replace tool’s most outstanding design. When a find-replace fails due to tiny differences (like an extra space), it doesn’t immediately error out. Instead, it triggers a “meta-call” to the model, passing the failed instruction, expected modification, and the target area’s actual code, requesting: “Based on the real code, please regenerate a more precise old_string.” This “self-repair” loop is a paradigm revolution in AI tool design, dramatically improving code modification success rates and robustness.

3.3 Security’s Last Gate: Diff Display and User Confirmation

Even after internal repair, before writing to disk, replace still presents a clear Diff (difference comparison) to users. This makes all modifications transparent and auditable, firmly returning the final “Go/No-Go” decision to developers—the cornerstone of building trust.

Chapter 4: The Art of Collaboration—A Complete Code Refactoring Journey

Let’s witness this “code alchemy” in action through a real refactoring task. Task: Comprehensively refactor the old callback-based module legacyFetcher.js to async/await-based dataService.ts.

Exploration and Understanding: AI first calls search_file_content to locate all files depending on the old module, then uses read_many_files to load related files into context at once.
Analysis and Planning: With complete visibility, AI presents a well-organized refactoring plan to users, including creating the new module, modifying dependencies, and deleting the old module.
Executing Modifications: After user approval, AI sequentially calls the replace tool (empty old_string means file creation) to modify each file. Before each modification, it shows Diff and requests approval.
Cleanup: After all dependencies are updated, AI proposes deleting the old module file, completing the operation after user confirmation.

A previously tedious cross-file refactoring task is safely and precisely completed through a few efficient conversations with AI.

Beyond Tools—A New Development Collaboration Paradigm

Gemini CLI’s file system toolset is a thoroughly designed, complete solution aimed at solving core pain points in AI-assisted programming. It addresses the “context gap” through layered perception read-only tools, “operational precision” through replace tools centered on “context anchors” and “self-repair,” and “security boundaries” through mandatory user confirmation and Diff display.

This “code alchemy” opens a new development collaboration paradigm: developers propose strategic intent, while AI serves as the most capable “executor,” safely, precisely, and efficiently completing tactical-level code implementation, thereby freeing developers to focus on higher-dimensional creative work.

Found Tam’s analysis insightful? Give it a thumbs up and share with more friends who need it!

Follow my channel to explore the infinite possibilities of AI, going global, and digital marketing together.

The most powerful tools are those that make us rethink work itself.