list_files

The list_files tool displays files and directories under a specified path, helping VJSP understand project structure and achieve efficient navigation of the codebase.

Parameter Description

This tool supports the following parameter configurations:

• path (required): Directory path for listing content, relative to the current working directory
• recursive (optional): Whether to list files recursively. When set to true, recursive listing is enabled; when set to false or omitted, only top-level content is listed

Feature Overview

This tool can list all files and directories under a specified path, clearly presenting the project structure. It supports two display modes: displaying only top-level directory content, or recursively traversing all subdirectories and displaying their content.

Applicable Scenarios

• When VJSP needs to understand the overall project structure
• When VJSP needs to check available file listings before reading specific files
• When VJSP needs to map the codebase to further understand its organizational architecture
• As a preparatory operation before using precise tools such as read_file, search_files
• When VJSP needs to search for specific types of files (e.g., configuration files) within the project

Core Features

• Lists both files and directories simultaneously, with clear directory identification
• Supports both recursive and non-recursive file listing modes
• In recursive mode, intelligently ignores common large directories such as node_modules, .git, etc.
• In recursive mode, follows .gitignore configuration rules
• When showVJSPIgnoredFiles is enabled, files ignored by .vjspignore are marked with a lock icon (🔒)
• Employs layer-by-layer directory traversal to optimize tool performance
• Sorts results, with directories displayed before their internal content to maintain logical hierarchy
• Presents listing results in a clean and organized format
• Automatically establishes logical mapping of project structure

Limitations

• To avoid performance issues, file listing results are limited to approximately 200 files by default
• Directory traversal has a 10-second timeout mechanism to prevent process hanging in complex directory structures
• When the file count limit is reached, a prompt is provided suggesting to execute list_files on specific subdirectories
• Not suitable for use as a validation tool to verify whether newly created files exist
• Performance may degrade when running in very large directory structures
• For security reasons, files under the root directory or user home directory cannot be listed

Workflow

After calling the list_files tool, the following workflow is executed:

1. Parameter Validation: Validates the validity of the required parameter path and the optional parameter recursive

2. Path Resolution: Resolves relative paths to absolute paths

3. Security Validation: Prohibits listing files under sensitive paths such as the root directory or user home directory

4. Directory Scanning:

   • Non-recursive mode: Only lists top-level directory content
   • Recursive mode: Traverses directory structure layer by layer, with a 10-second timeout
   • If timeout is triggered, returns partial results collected up to the timeout

5. Result Filtering:

   • In recursive mode, skips common large directories such as node_modules, .git, etc.
   • In recursive mode, follows .gitignore configuration rules
   • Parses .vjspignore filtering rules and performs hiding or lock marking operations on matched files

6. Result Formatting:

   • Adds trailing slash (/) to identify directories
   • Sorts results, with directories displayed before their internal content to ensure logical hierarchy
   • When showVJSPIgnored is enabled, marks ignored files with a lock icon (🔒)
   • By default, limits results to 200 files while providing prompts for individual subdirectory queries
   • Formats results neatly to enhance readability

Result Display Format

File listing results conform to the following specifications:

• Each file path is displayed on a separate line
• Directories are identified with a trailing slash (/)
• When showVJSPIgnored is enabled, files ignored by .vjspignore are marked with a lock icon (🔒)
• Results are sorted logically, with directories displayed before their internal content
• When the file count limit is reached, a prompt appears suggesting to execute list_files on specific subdirectories

Result display example:

src/
src/components/
src/components/Button.tsx
src/components/Header.tsx
src/utils/
src/utils/helpers.ts
src/index.ts
...
File listing results truncated (543 total files, currently displaying 200). Execute list_files on specific subdirectories to view complete content.

Display example when .vjspignore is enabled and showVJSPIgnored is turned on:

src/
src/components/
src/components/Button.tsx
src/components/Header.tsx
🔒 src/secrets.json
src/utils/
src/utils/helpers.ts
src/index.ts

Real-World Application Scenarios

• When starting a new task, VJSP will first list project files and understand the overall structure before processing specific code in depth
• When receiving instructions to search for specific types of files (e.g., all JavaScript files), VJSP will first list directories to determine the search scope
• Before providing code organization optimization suggestions, VJSP will first analyze the structural layout of the current project
• When building new feature modules, VJSP will list relevant directories to adapt to the project's development standards

Usage Examples

List top-level files in the current directory:

<list_files>
<path>.</path>
</list_files>

Recursively list all files in the source directory:

<list_files>
<path>src</path>
<recursive>true</recursive>
</list_files>

View contents of a specific project subdirectory:

<list_files>
<path>src/components</path>
<recursive>false</recursive>
</list_files>