---
title: List Files Tool | Kilo Code Docs
description: Learn how the list_files tool displays files and directories within a specified location to help Kilo Code understand your project structure.
---

# list_files

The `list_files` tool displays the files and directories within a specified location. It helps Kilo Code understand your project structure and navigate your codebase effectively.

## Parameters

The tool accepts these parameters:

- `path` (required): The path of the directory to list contents for, relative to the current working directory
- `recursive` (optional): Whether to list files recursively. Use `true` for recursive listing, `false` or omit for top-level only.

## What It Does

This tool lists all files and directories in a specified location, providing a clear overview of your project structure. It can either show just the top-level contents or recursively explore subdirectories.

## When is it used?

- When Kilo Code needs to understand your project structure
- When Kilo Code explores what files are available before reading specific ones
- When Kilo Code maps a codebase to better understand its organization
- Before using more targeted tools like `read_file` or `search_files`
- When Kilo Code needs to check for specific file types (like configuration files) across a project

## Key Features

- Lists both files and directories with directories clearly marked
- Offers both recursive and non-recursive listing modes
- Intelligently ignores common large directories like `node_modules` and `.git` in recursive mode
- Respects `.gitignore` rules when in recursive mode
- Marks files ignored by `.kilocodeignore` with a lock symbol (🔒) when `showKiloCodeIgnoredFiles` is enabled
- Optimizes performance with level-by-level directory traversal
- Sorts results to show directories before their contents, maintaining a logical hierarchy
- Presents results in a clean, organized format
- Automatically creates a mental map of your project structure

## Limitations

- File listing is capped at about 200 files by default to prevent performance issues
- Has a 10-second timeout for directory traversal to prevent hanging on complex directory structures
- When the file limit is hit, it adds a note suggesting to use `list_files` on specific subdirectories
- Not designed for confirming the existence of files you've just created
- May have reduced performance in very large directory structures
- Cannot list files in root or home directories for security reasons

## How It Works

When the `list_files` tool is invoked, it follows this process:

1. **Parameter Validation**: Validates the required `path` parameter and optional `recursive` parameter
2. **Path Resolution**: Resolves the relative path to an absolute path
3. **Security Checks**: Prevents listing files in sensitive locations like root or home directories
4. **Directory Scanning**:
   - For non-recursive mode: Lists only the top-level contents
   - For recursive mode: Traverses the directory structure level by level with a 10-second timeout
   - If timeout occurs, returns partial results collected up to that point
5. **Result Filtering**:
   - In recursive mode, skips common large directories like `node_modules`, `.git`, etc.
   - Respects `.gitignore` rules when in recursive mode
   - Handles `.kilocodeignore` patterns, either hiding files or marking them with a lock symbol
6. **Formatting**:
   - Marks directories with a trailing slash (`/`)
   - Sorts results to show directories before their contents for logical hierarchy
   - Marks ignored files with a lock symbol (🔒) when `showKiloCodeIgnored` is enabled
   - Caps results at 200 files by default with a note about using subdirectories
   - Organizes results for readability

## File Listing Format

The file listing results include:

- Each file path is displayed on its own line
- Directories are marked with a trailing slash (`/`)
- Files ignored by `.kilocodeignore` are marked with a lock symbol (🔒) when `showKiloCodeIgnored` is enabled
- Results are sorted logically with directories appearing before their contents
- When the file limit is reached, a message appears suggesting to use `list_files` on specific subdirectories

Example output format:

```
src/
src/components/
src/components/Button.tsx
src/components/Header.tsx
src/utils/
src/utils/helpers.ts
src/index.ts
...
File listing truncated (showing 200 of 543 files). Use list_files on specific subdirectories for more details.
```

When `.kilocodeignore` files are used and `showKiloCodeIgnored` is enabled:

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

## Examples When Used

- When starting a new task, Kilo Code may list the project files to understand its structure before diving into specific code.
- When asked to find specific types of files (like all JavaScript files), Kilo Code first lists directories to know where to look.
- When providing recommendations for code organization, Kilo Code examines the current project structure first.
- When setting up a new feature, Kilo Code lists related directories to understand the project conventions.

## Usage Examples

Listing top-level files in the current directory:

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

Recursively listing all files in a source directory:

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

Examining a specific project subdirectory:

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