list_directory - List Directory

Overview

The list_directory tool lists the names of files and subdirectories directly within a specified directory path. Can optionally ignore entries matching provided glob patterns.

Tool Name

• Internal Name: list_directory
• Display Name: ReadFolder
• Icon: Folder

Parameters

Required Parameters

Parameter	Type	Description
path	string	The absolute path to the directory to list (must be absolute, not relative).

Optional Parameters

Parameter	Type	Description
ignore	string[]	List of glob patterns to ignore.
file_filtering_options	object	File filtering options.
file_filtering_options.respect_git_ignore	boolean	Whether to respect .gitignore patterns when listing files. Only available in git repositories. Defaults to true.
file_filtering_options.respect_sii_ignore	boolean	Whether to respect .siiignore patterns when listing files. Defaults to true.

Features

1. Directory Listing:

   • Lists direct child files and subdirectories
   • Does not recursively list subdirectory contents
   • Returns filename, path, type, size, and modification time

2. Filtering:

   • Supports glob patterns to ignore specific files
   • Respects .gitignore rules (optional)
   • Respects .siiignore rules (optional)

3. Security Restrictions:

   • Path must be absolute
   • Path must be within project root directory

4. Return Information:

   • File/directory name
   • Full path
   • Whether it's a directory
   • File size (bytes)
   • Last modification time

Usage Examples

Basic Usage

{
  "path": "/home/user/project/src"
}

Ignore Specific Patterns

{
  "path": "/home/user/project",
  "ignore": ["*.log", "*.tmp", "node_modules"]
}

Custom Filtering Options

{
  "path": "/home/user/project",
  "file_filtering_options": {
    "respect_git_ignore": false,
    "respect_sii_ignore": true
  }
}

List Root Directory

{
  "path": "/home/user/project"
}

Return Value

The tool returns an object containing:

• llmContent: Detailed list of directory contents
• returnDisplay: User-friendly display information
• summary: Operation summary (e.g., "Listed 15 items in directory")

File Entry Format

Each file/directory entry contains:

{
  name: string;          // File or directory name
  path: string;          // Absolute path
  isDirectory: boolean;  // Whether it's a directory
  size: number;          // File size (bytes), 0 for directories
  modifiedTime: Date;    // Last modification time
}

Error Handling

Possible error scenarios:

1. Path Errors:

   • Path is not absolute
   • Path is outside project root directory
   • Path does not exist

2. Access Errors:

   • No read permission
   • Path is a file, not a directory

3. Parameter Errors:

   • Missing required parameters
   • Incorrect parameter types

Glob Pattern Guide

Supported glob patterns:

• *: Matches any characters (excluding /)
• **: Matches any characters (including /)
• ?: Matches a single character
• [abc]: Matches any character in brackets
• {a,b}: Matches any pattern in braces

Examples:

• *.js: Matches all JavaScript files
• test/**: Matches everything under test directory
• *.{js,ts}: Matches all JavaScript and TypeScript files

Notes

1. Non-Recursive: This tool only lists direct children, not subdirectory contents recursively
2. Performance: May take time for directories with many files
3. Permissions: Ensure sufficient permissions to read the directory
4. Symbolic Links: Symbolic links are recognized but not followed

Related Tools

• glob: Find files using glob patterns
• read_file: Read file content
• search_file_content: Search file content
• read_many_files: Read multiple files in batch