📁 File Operations Reference

These tools allow the AI to explore and modify your project's directory structure and file contents.

These tools allow the AI to explore and modify your project's directory structure and file contents.

🔍 Exploration Tools

list_dir

Lists the contents of a directory.

  • Usage: List the files in the src/ directory
  • Parameters:
    • DirectoryPath: Absolute path to the directory.
  • Output: Returns a list of files and subdirectories with sizes and modification times.

Search for exact text or regex patterns across files.

  • Usage: Search for 'AuthService' in the whole project
  • Parameters:
    • Query: The string or regex to search for.
    • SearchPath: Directory or file to search in.
    • IsRegex: (Bool) Whether the query is a regular expression.
  • Output: Filename, line number, and matching line content.

find_by_name

Find files or directories matching a glob pattern.

  • Usage: Find all .css files in the components folder
  • Parameters:
    • Pattern: Glob pattern (e.g., *.py).
    • SearchDirectory: Where to start the search.
  • Output: List of matching paths.

📝 Modification Tools

read_file

View the contents of a specific file.

  • Usage: Show me the content of requirements.txt
  • Parameters:
    • AbsolutePath: Path to the file.
    • StartLine / EndLine: (Optional) Read specific line range.
  • Output: File content with line numbers.

write_file

Create a new file or overwrite an existing one.

  • Usage: Create a new file named utils.py with a secret key generator
  • Parameters:
    • TargetFile: Path to the file.
    • CodeContent: The text to write.
  • Output: Success status and file path.

replace_file_content

Edit a specific block of text within a file.

  • Usage: Fix the typo in line 45 of auth.py
  • Parameters:
    • TargetFile: Path to the file.
    • TargetContent: Exact string to be replaced.
    • ReplacementContent: New content.
  • Output: Status and diff of the change.

multi_replace_file_content

Perform multiple non-contiguous edits in a single file. Useful for large refactors.

  • Usage: Update the class name and the main method at the same time
  • Parameters: Array of replacement chunks.

🛡️ Best Practices for AI

  • Read Before Write: The AI should always use read_file or view_file_outline before attempting to edit or overwrite.
  • Use Incremental Edits: replace_file_content is safer than write_file for existing codebase files.