Download Now
← Back to Blog

Understanding Project Code in Minutes — Introduction to ZAgent's Powerful Code Analysis Tool

Original article by Brian | "The Last Humans"

June 18, 2026

This is the third article in the "Give LLMs a Chance to Be Human" series.

In large projects, the place where Agents waste the most time is not writing code, but finding context. It needs to know where the entry point is, where the core types are, which functions call which, and which modules a feature request passes through. If relying only on glob, grep, and read, the Agent often has to jump between files, reading a lot of code that isn't critical.

The value of the code_analyzer tool is here: it first organizes the codebase into a structured map, then lets the Agent purposefully dive into local files. It's not a replacement for grep and read, but makes these tools more precise.

1. What Problem Does It Solve?

When a user asks: "How are sessions created, saved, and restored in this project?"

A regular Agent would typically first glob to find files, then grep session, and then open a bunch of matching files. The problem is that keyword matching doesn't equal structural importance. A word might appear in comments, type definitions, UI text, or test code—the Agent needs to spend time filtering.

But ZAgent's code_analyzer tool thinks differently. It first answers more structured questions:

  • What source files are in the project?
  • What language is each file, and how many lines?
  • What functions, classes, or structures are defined?
  • Which functions call which functions?
  • Which files import which modules or symbols?
  • Where is a symbol defined?
  • What are the reference and call paths for a symbol?

This information allows ZAgent to quickly form a "code terrain map," then decide which files to read next.

2. Tree-sitter: Understanding Code Better Than Plain Text Search

ZAgent's code_analyzer tool prioritizes using the tree-sitter extractor. That is, it doesn't simply use regex to scan function names in text, but parses code into syntax trees, then extracts structural information from those trees.

This brings several benefits:

  • Can distinguish between definitions, calls, imports, and other different semantics
  • Can reduce noise from plain text searches
  • Can output results in similar data structures across multiple languages
  • Can provide information like file, line, and symbol that the Agent can use to continue locating

In scenarios where tree-sitter extractor is not supported, the code also retains regex extractor as a fallback path. This is a pragmatic design: prioritizing structural accuracy while ensuring more languages or edge files still have basically usable analysis results.

3. Graphify: Expressing Code Structure with Graphs

Code is not a group of isolated files, but a network of relationships. code_analyzer organizes functions, classes, calls, and imports into a graph structure.

The underlying implementation uses petgraph's directed graph:

  • Nodes represent functions, classes, files, or symbols
  • Edges represent connections like call relationships, import relationships
  • A -> B can represent "A calls B" or "A depends on B"

This graphify approach is very suitable for Agents. Because Agents don't just need to know "where is a certain function," they also need to know:

  • Who calls it?
  • Who does it call?
  • Which modules does this module depend on?
  • Which nodes are central nodes with the widest reach?
  • Which code forms a relatively cohesive functional cluster?

Currently, ZAgent's code_analyzer can group nodes in the graph into clusters. For large codebases, this kind of structure can help Agents upgrade from "reading files" to "reading module relationships."

4. How to Combine These Tools in ZAgent

code_analyzer is best suited for first-round structural scanning, but it shouldn't work alone. A high-quality way to use ZAgent often combines tools like this:

1. Use glob to Determine Project Shape

For example, first use glob to find:

**/Cargo.toml
**/package.json
**/src/**

This step is used to determine whether the project is Rust, TypeScript, Python, or a multi-language mix.

2. Use code_analyzer(action="analyze") to Build Code Structure Graph

For example, use the following parameters to get the code structure overview:

{
  "action": "analyze",
  "path": "src-tauri/src",
  "languages": ["rust"]
}

The returned result will include handles, statistics, file structure, function/class definitions, call edges, and import edges. This way, without reading the entire project at once, you can know where the main modules are.

3. Use code_analyzer(action="symbols") to Search Symbols

If the user asks about session creation logic, the Agent can search:

{
  "action": "symbols",
  "handle": "<handle returned by analyze>",
  "query": "session",
  "kind": "function"
}

This is more precise than grep session because it returns a structured symbol list.

4. Use code_analyzer(action="definitions") to Locate Definitions

When the Agent sees candidate symbols like create_tools_for_mode, session_new, SessionManager, it can directly query definition locations:

{
  "action": "definitions",
  "handle": "<handle>",
  "symbol": "create_tools_for_mode",
  "exact": true
}

5. Use code_analyzer(action="references") or call_graph to See Impact Scope

For example, if about to modify a tool registration function, the Agent shouldn't just read the function itself—it also needs to know who calls it:

{
  "action": "call_graph",
  "handle": "<handle>",
  "symbol": "create_tools_for_mode",
  "direction": "incoming",
  "depth": 2
}

This helps the Agent determine whether the modification will affect regular sessions, plan mode, scheduled tasks, or only a certain local entry point.

6. Use grep to Verify Text-Level Details

code_analyzer handles structure, grep handles supplementing text evidence. For example:

rg "DEFAULT_SESSION_TOOLS|create_tools_for_mode|stock_pool"

This step is suitable for searching configuration items, string constants, frontend fields, comments, and test cases.

7. Use read for Detailed Reading of Relevant Files

Once the Agent already knows the key files and line numbers, using read to open files won't mean reading through the entire project aimlessly. At this point, it reads the "files most likely to need changes," which is much more efficient.

5. A Real Scenario: Analyzing Tool Registration Issues

Assume a user reports: "Why don't default sessions have optional tools like browser, wiki, and code analyzer?"

ZAgent might proceed as follows:

1. Use glob to Find Session-Related Files

src-tauri/src/commands/**/*.rs
src/components/**/*.tsx
src/types/**/*.ts

2. Use code_analyzer to Analyze Backend Rust Code and Quickly Find Tool Creation Functions

It might discover:

  • create_tools_by_names
  • create_tools_for_mode
  • session_new_with_options

3. Use call_graph to See Which Processes Call create_tools_for_mode

This step can determine whether "default session" and "user-created new session" use the same tool list.

4. Use grep to Search Frontend Default Options

rg "TOOL_OPTIONS|DEFAULT_SESSION_TOOLS|DEFAULT_BASIC_TOOLS"

5. Use read to Read Backend Registration Logic and Frontend New Session Dialog in Detail

By this step, ZAgent doesn't need to read the entire project—just a few specific files:

  • src-tauri/src/commands/mod.rs
  • src-tauri/src/commands/session.rs
  • src/types/index.ts
  • src/components/dialogs/NewSessionDialog.tsx

This is the core advantage of code_analyzer: it lets the Agent first establish structural judgments, then use traditional tools to verify details, and only then proceed to modifications.

6. Why Is It Fast?

"Fast" is not just about execution speed—it's more importantly about reducing the Agent's exploration rounds. The speed advantage of code_analyzer comes from several aspects:

  • Tree-sitter parsing is more direct than having LLMs read files one by one
  • Output is structured JSON; the Agent can query by handle, section, and symbol with pagination
  • symbols, definitions, references, call_graph let the Agent navigate by problem, not by filename guessing
  • Structured truncation avoids returning too much content at once, reducing context waste
  • Graph structure elevates "where the code is" to "how the code connects"

For medium-to-large projects, this approach can significantly shorten the time to "understand the project." ZAgent no longer needs to read a dozen files before forming a judgment—it first gets an index map, then reads precisely.

7. It Doesn't Replace grep and read

A common misconception is: with code analyzer, you don't need glob, grep, or read anymore. In reality, it's exactly the opposite.

A better division of labor is:

  • glob: Determines project file layout
  • code_analyzer: Builds code structure and relationship graphs
  • grep: Searches text, configuration, copy, tests, edge strings
  • read: Understands business semantics and specific implementations

code_analyzer helps ZAgent find direction faster; grep and read let ZAgent ground conclusions in specific code evidence. The combination of these four tools is ZAgent's efficient workflow for interpreting codebases.

8. When to Use It

Scenarios particularly suitable for using code_analyzer:

  • First time encountering an unfamiliar project
  • Needing to understand a cross-file feature chain
  • Needing to evaluate the impact scope of a function, type, or module
  • Needing dependency sorting before refactoring
  • Needing to quickly locate entry points and core modules in a large project
  • Wanting the Agent to analyze before modifying, reducing the probability of wrong changes

If the task is just changing one line of copy in a known file, read is enough. But as long as the problem involves "project structure," "call relationships," "where this feature is implemented," or "where this change will affect," code_analyzer should become one of ZAgent's first tools.

9. Conclusion

The core value of the code_analyzer tool is not generating code, but improving the quality and speed of the Agent's code understanding. It uses tree-sitter to parse source code into structure, uses graphs to express calls and dependencies, and exposes these results in an Agent-friendly way.

In practical work, its best positioning is a "codebase map." The Agent first looks at the map, then uses glob, grep, and read to go to the scene.

This way, analysis is faster, explanations are more grounded, and modifications are more stable.

How to Download ZAgent

  1. Download from loadskill.net website:
    https://www.loadskill.net/download.html
  2. Download from GitHub:
    https://github.com/briancai/zagent-tauri/releases/tag/v1.0.0