LS Tool

​

Overview

​

Parameters

​

Features

​

Tree Structure

- /path/to/project/
  - src/
    - main.go
    - handler.go
    - utils/
      - helpers.go
      - config.go
  - tests/
    - main_test.go
  - go.mod
  - README.md

​

Automatic Filtering

• Hidden files and directories (starting with .)
• Common system directories (__pycache__, node_modules, etc.)
• Files matching .gitignore patterns
• Files matching .crushignore patterns

​

Depth Control

{
  "path": "/path/to/project",
  "depth": 2
}

​

Result Limits

• Maximum files: 1000 files per listing
• Truncation notice: Shown if limit exceeded
• Depth warning: Shown when depth limit is reached

​

Output Format

​

Standard Output

- /path/to/project/
  - src/
    - main.go
    - server.go
  - README.md

​

Truncated Output

There are more than 1000 files in the directory. Use a more specific path or use the Glob tool to find specific files. The first 1000 files and directories are included below.

- /path/to/project/
  - src/
    ...

​

Depth Limited Output

The directory tree is shown up to a depth of 3. Use a higher depth and a specific path to see more levels.

- /path/to/project/
  - src/
    - components/
      - (3 levels shown)

​

Usage Examples

​

List Current Directory

{
  "path": "."
}

{}

​

List Specific Directory

{
  "path": "/path/to/project/src"
}

​

Limit Depth

{
  "path": "/path/to/project",
  "depth": 2
}

​

Ignore Patterns

{
  "path": "/path/to/project",
  "ignore": ["*.log", "tmp/*", "**/_test.go"]
}

​

Large Project Exploration

{
  "path": "/path/to/large-project/src",
  "depth": 3,
  "ignore": ["node_modules", "dist", "build"]
}

​

Best Practices

​

When to Use LS

1. Initial exploration - Understanding project structure
2. Before editing - Verifying file locations
3. After changes - Checking new files were created
4. Navigation - Finding your way in unfamiliar code

​

Effective Usage

1. Start at project root - Get overall structure first
2. Use depth limits - Prevent overwhelming output
3. Explore incrementally - Go deeper into specific areas
4. Combine with Glob - LS for structure, Glob for specific files

​

Managing Large Directories

1. Use specific paths - List subdirectories instead of root
2. Set depth limits - Show only relevant levels
3. Use ignore patterns - Skip irrelevant directories
4. Use Glob instead - For finding specific file patterns

​

Common Patterns

​

Project Exploration

// Top-level overview
{"path": ".", "depth": 1}

// Source code structure  
{"path": "./src", "depth": 2}

// Test structure
{"path": "./tests"}

​

Verify File Creation

// After creating files
{"path": "./generated", "depth": 1}

// Check specific directory
{"path": "./src/components"}

​

Exclude Common Directories

{
  "path": ".",
  "ignore": [
    "node_modules",
    "dist",
    "build",
    ".git",
    "vendor"
  ]
}

​

Permissions

​

Auto-Approved

• Listing directories within the working directory

​

Requires Permission

• Listing directories outside the working directory

{
  "allow": {
    "ls": ["~/projects", "/etc/nginx"]
  }
}

​

Cross-Platform Notes

​

Path Separators

• Windows: C:/Users/name/project/
• Unix: /home/user/project/

​

Hidden Files

• Files starting with . are hidden
• Automatically skipped by LS

• Files with hidden attribute are not automatically skipped
• Files starting with . are skipped for consistency

​

Case Sensitivity

• Unix/Linux/macOS - Case-sensitive file system
• Windows - Case-insensitive file system

​

Troubleshooting

​

Directory Not Found

• Check path is correct
• Use absolute paths to avoid ambiguity
• Verify directory exists
• Check permissions

​

Too Many Files

• Use more specific path
• Increase depth limit if set too low
• Use ignore patterns to exclude directories
• Use Glob tool instead for specific patterns

​

Empty Output

• Check if directory is empty
• Verify files aren’t all hidden
• Check ignore patterns aren’t too broad
• Check .gitignore and .crushignore

​

Performance Issues

• Use depth limits
• Specify narrower paths
• Exclude large directories with ignore
• Use Glob for targeted searches

​

LS vs Other Tools

​

LS vs Glob

• Understanding directory structure
• Seeing file organization
• Exploring unfamiliar projects
• Hierarchical view needed

• Finding files by pattern
• Searching specific file types
• Working with specific extensions
• Targeting specific files

​

LS vs Bash ls

• Tree view of directory structure
• Recursive listing with depth control
• Respects .gitignore automatically
• Cross-platform consistent output
• Integrated into Crush workflow

• Detailed file information (sizes, permissions)
• Sorting options
• Custom formatting
• Scripting with other commands

​

LS vs View

• Exploring directory structure
• Finding file locations
• Understanding project layout
• Multiple files at once

• Reading file contents
• Understanding code
• Checking file details
• Getting LSP diagnostics

​

Common Workflows

​

Project Exploration

1. LS root directory with depth=2
2. Identify key directories (src, tests, etc.)
3. LS each directory for detailed structure
4. Use Glob to find specific file types
5. Use View to read relevant files

​

Verification After Changes

1. Make changes with Edit or Write
2. LS the affected directory to verify structure
3. Use Glob to find the new files
4. Use View to check file contents

​

Navigation

1. LS current location to see available paths
2. Identify target directory from tree
3. LS target directory for details
4. Use View to read files of interest

​

Configuration

{
  "tools": {
    "ls": {
      "max_depth": 3,
      "max_files": 1000
    }
  }
}

​

Configuration Options

• max_depth - Default maximum depth for traversal
• max_files - Maximum files to return (default 1000)

​

Advanced Usage

​

Combining with Other Tools

// Explore structure
{"tool": "ls", "path": "./src", "depth": 2}

// Find specific files
{"tool": "glob", "pattern": "src/**/*.go"}

// Search contents
{"tool": "grep", "pattern": "func.*Handler", "path": "src"}

​

Incremental Exploration

// Step 1: Top level
{"path": ".", "depth": 1}

// Step 2: Source directory
{"path": "./src", "depth": 2}

// Step 3: Specific subdirectory
{"path": "./src/handlers"}

​

Filtering Large Projects

{
  "path": ".",
  "depth": 3,
  "ignore": [
    "node_modules",
    "vendor",
    ".git",
    "dist",
    "build",
    "coverage",
    "*.log"
  ]
}