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

> Learn how AI assistants execute file system operations like directory listing and recursive searches in large codebases using JSON tools for safe and efficient navigation.

- Repository: [Lucas Valbuena/system-prompts-and-models-of-ai-tools](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools)
- Tags: deep-dive
- Published: 2026-02-25

---

**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

```json
{
  "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

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

```

### Searching TypeScript While Ignoring Build Artifacts

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

```

### Deep Directory Listing with Absolute Path

```json
{
  "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.