codemap_list

List directory contents with optional depth for recursive listing.

iolistdirectoryrecursivebrowse

Parameters

Name	Type	Required	Description
`target`	`string`	✅ Required	Directory path (relative or absolute)
`depth`	`number`	❌ Optional	Recursion depth (1-10). 1=direct contents only, 2=one level of subdirectories, etc. (default: `1`)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_list",
  "arguments": {
    "target": "src/components"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "data": {
    "directory": "src/components",
    "entries": [
      {
        "name": "Button.tsx",
        "type": "file",
        "relativePath": "src/components/Button.tsx"
      },
      {
        "name": "Input.tsx",
        "type": "file",
        "relativePath": "src/components/Input.tsx"
      },
      {
        "name": "ui",
        "type": "directory",
        "relativePath": "src/components/ui"
      }
    ],
    "count": 3,
    "depth": 1
  }
}

ℹ️When to Use This Tool

codemap_list

Browse project structure to understand directory organization
Find all files of a specific type (e.g., all .ts files)
Count files or directories in a project
Verify directory contents before operations
Generate file inventories or documentation

💡Common Patterns

Directory Inventory Pattern

1. List with appropriate depth
2. Filter by type (file vs directory)
3. Process or display results

File Discovery Pattern

1. List with deep recursion (depth 5-10)
2. Filter by extension or naming pattern
3. Operate on filtered results

Structure Validation

1. List expected directory
2. Verify required files/directories exist
3. Report missing or unexpected items

💡Pro Tips

Use depth=1 for performance: Shallow listings are fast. Only increase depth when you need recursive results.
Maximum depth is 10: Deep recursion is capped at 10 levels to prevent performance issues. For full project scans, use depth=10.
Results include relative paths: Use relativePath field for portability across systems rather than constructing paths manually.
Filter programmatically: The tool returns all entries - filter by type, extension, or name pattern in your code rather than making multiple list calls.
Combine with peek for metadata: List gives you names and types. Use peek to get file sizes, modification times, and content previews.

✅Best Practices

Start with depth=1 and increase only if needed - saves time
Filter results in code rather than making multiple list calls
Use relativePath from results for cross-platform compatibility
For large directories, consider depth limits to avoid overwhelming output
Cache list results if you'll process them multiple times
Combine list with other tools (peek, read) for comprehensive directory analysis

⚠️Common Mistakes

❌ Mistake: Using depth=10 by default, causing slow performance on large projects
✅ Instead: Start with depth=1 or 2 and increase only when necessary

❌ Mistake: Listing the same directory repeatedly instead of caching results
✅ Instead: Store list results in a variable if you need to process them multiple times

❌ Mistake: Constructing file paths manually instead of using relativePath field
✅ Instead: Use the relativePath from results - it's portable and correct

❌ Mistake: Expecting files to be sorted in a specific order
✅ Instead: Sort results explicitly in your code if order matters

❌ Mistake: Not handling empty directories, causing logic errors
✅ Instead: Check result.count before processing entries array

❌ Mistake: Using list when you only need to check if one file exists
✅ Instead: Use peek or read for single-file checks - list is for discovering multiple items

Parameters

Usage Examples

MCP Usage (for AI Agents like Claude)

Example Output

JSON Response

Related Tools

codemap_io_peek

codemap_io_read

codemap_io_create

codemap_io_delete