How AI Assistants Handle File System Operations: Listing Directories and Recursive Searching in Large Codebases

AI assistants perform file system operations through structured JSON-based tools like LS and Glob that enforce absolute paths, read-only access, and optional ignore patterns to safely navigate large repositories.

Modern AI coding assistants abstract file system interactions into declarative tool definitions rather than executing raw shell commands. The repository x1xhlol/system-prompts-and-models-of-ai-tools reveals how systems like Claude Code implement these primitives to handle complex directory structures through schema-validated operations defined in Anthropic/Claude Code/Tools.json and v0 Prompts and Tools/Tools.json.

Core File System Tools: LS and Glob

AI assistants rely on two primary tools for directory exploration and file discovery, each defined with strict JSON schemas that enforce type safety and path validation.

The LS Tool for Directory Listing

The LS tool lists files and sub-directories under an absolute directory path. According to the source definition at lines 151-173 in Anthropic/Claude Code/Tools.json, it accepts:

• path (required): Absolute path to the directory
• ignore (optional): Array of glob patterns to exclude (e.g., **/node_modules, **/.cache)

This design ensures the assistant cannot traverse outside the repository root while allowing efficient filtering of generated or dependency folders that clutter large codebases.

The Glob Tool for Recursive Searching

The Glob tool performs fast, pattern-based searches across the entire repository or a specified base directory. Defined at lines 62-81 in Anthropic/Claude Code/Tools.json, it returns matching file paths sorted by modification time.

Key parameters include:

• pattern (required): Glob pattern such as **/*.py or **/*.{ts,tsx}
• path (optional): Base directory to search within
• ignore (optional): Array of patterns to skip during traversal

The implementation uses underlying filesystem globbing facilities (or language-level implementations like fast-glob) that walk the directory tree once, filtering by pattern during traversal rather than collecting all files then filtering. This approach minimizes I/O overhead in deeply nested repositories.

LSRepo: A Convenience Wrapper for Repository Root Operations

The v0 Prompts and Tools/Tools.json file (lines 63-95) defines LSRepo, a higher-level wrapper around LS optimized for project discovery.

LSRepo defaults to the repository root and adds an optional globPattern argument for quick filtered listings. It also implements a result cap of approximately 200 entries and alphabetical sorting, preventing massive payloads from overwhelming the assistant's context window when exploring directories containing thousands of files (such as node_modules or build artifacts).

Architectural Patterns for Safe File System Operations

Tool-First Design with Schema Validation

Rather than executing shell commands like ls or find, the assistant invokes declarative tool descriptions defined in JSON schema. The execution engine (Claude Code, Vercel AI SDK, etc.) validates inputs against these schemas before touching the filesystem.

This architecture enforces:

• Absolute path requirements: The path parameter must be absolute, preventing relative path traversal attacks
• Type safety: Schema validation ensures ignore is an array of strings, not arbitrary command injections
• Read-only constraints: The tool definitions only permit listing and searching, not writing or executing

Stateless, Deterministic Queries

Both LS and Glob operate as pure queries returning snapshots of filesystem state at call time. They introduce no side effects, making operations deterministic and safe to retry or parallelize. The assistant can issue multiple Glob calls with different patterns without worrying about filesystem mutation.

Performance Optimization Strategies

For large or complex directory structures, the implementation employs several optimization techniques:

• Single-pass traversal: Glob walks the tree once, filtering by pattern during traversal rather than collecting all files then filtering
• Early exclusion: The ignore patterns are applied at the directory level when possible, pruning entire subtrees (like .git or node_modules) before descending
• Result capping: LSRepo limits returns to ~200 entries, forcing the assistant to use more specific Glob patterns for deep exploration rather than ingesting massive directory listings
• Modification-time sorting: Glob returns results sorted by mtime, surfacing recently changed files first—a heuristic that often prioritizes relevant code in active development

Practical Implementation Examples

The following JSON structures illustrate how an AI assistant invokes these tools through the orchestration layer. The surrounding execution engine handles the actual filesystem interaction.

Listing the Repository Root with Exclusions

{
  "name": "LSRepo",
  "input": {
    "taskNameActive": "listing repo",
    "taskNameComplete": "repo listed",
    "path": "/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/x1xhlol/system-prompts-and-models-of-ai-tools/main",
    "ignore": ["**/node_modules", "**/.cache"]
  }
}

Recursively Finding All Python Files

{
  "name": "Glob",
  "input": {
    "taskNameActive": "search assets",
    "taskNameComplete": "assets searched",
    "pattern": "**/assets/**/*.py"
  }
}

Searching TypeScript While Ignoring Build Artifacts

{
  "name": "Glob",
  "input": {
    "taskNameActive": "search source",
    "taskNameComplete": "source searched",
    "pattern": "**/*.ts",
    "ignore": ["**/dist/**", "**/node_modules/**"]
  }
}

Deep Directory Listing with Absolute Path

{
  "name": "LS",
  "input": {
    "taskNameActive": "list deep folder",
    "taskNameComplete": "folder listed",
    "path": "/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/x1xhlol/system-prompts-and-models-of-ai-tools/main/Anthropic/Claude Code",
    "ignore": ["**/*.json"]
  }
}

Summary

• AI assistants use structured tools, not shell commands, to perform file system operations like listing directories and recursive searching.
• The LS tool (defined in Anthropic/Claude Code/Tools.json lines 151-173) lists directory contents with optional glob-based ignore patterns.
• The Glob tool (lines 62-81) performs efficient recursive pattern matching across the repository, returning paths sorted by modification time.
• The LSRepo wrapper (defined in v0 Prompts and Tools/Tools.json lines 63-95) defaults to the repository root and caps results at ~200 entries to prevent context overflow.
• Safety mechanisms include absolute path requirements, read-only access, schema validation, and ignore patterns that prune directories like node_modules before traversal.

Frequently Asked Questions

How do AI assistants prevent directory traversal attacks when listing files?

AI assistants enforce absolute path requirements in the JSON schema definitions for tools like LS and Glob. According to the source definitions in Anthropic/Claude Code/Tools.json, the path parameter must be an absolute path residing within the repository root. This prevents relative path traversal sequences (../) from escaping the sandboxed environment, and the execution engine validates paths before any filesystem access occurs.

What is the difference between the LS and Glob tools in Claude Code?

LS performs a single-directory listing operation, returning immediate children of a specified absolute path with optional ignore patterns for filtering. Glob performs recursive, pattern-based searches across the entire directory tree (or a specified base), using glob syntax like **/*.py to match files at any depth, and returns results sorted by modification time. While LS explores known locations, Glob discovers files matching patterns across the repository.

How do these tools handle repositories with thousands of files or deep nesting?

The implementations optimize for scale through single-pass traversal algorithms that walk the tree once while filtering, early exclusion via ignore patterns that prune entire subtrees like node_modules before descending, and result capping where LSRepo limits returns to approximately 200 entries. These constraints prevent context window overflow and reduce I/O overhead when exploring deeply nested structures containing thousands of files.

Can AI assistants modify or delete files using these tools?

No. The LS, Glob, and LSRepo tools are explicitly read-only queries according to their JSON schema definitions in the repository. They return snapshots of filesystem state without side effects and cannot create, modify, or delete files. Write operations require separate tool definitions (such as WriteFile or EditFile) with distinct schemas and safety validations that are not part of these specific listing and search utilities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}