📁 File Operations

Detailed reference for file operation tools available in Code Puppy.

list_files

List files and directories with intelligent filtering and safety features.

Signature

list_files(directory=".", recursive=True)

Parameters

Parameter	Type	Default	Description
directory	string	"."	Path to list
recursive	boolean	true	Include subdirectories

Features

• Automatically ignores common artifacts (node_modules, __pycache__, .git)
• Token-safe output (limits results for large directories)
• Smart home directory detection
• Rich file metadata and visual formatting

read_file

Read file contents with optional line-range selection.

Signature

read_file(file_path, start_line=None, num_lines=None)

Parameters

Parameter	Type	Default	Description
file_path	string	required	Path to file
start_line	int	None	Starting line (1-based)
num_lines	int	None	Number of lines to read

Features

• Automatic token counting
• Line-range selection for large files
• Protection against excessively large files

edit_file

Comprehensive file editing with multiple strategies.

Payload Types

ContentPayload - Create or Overwrite

{
  "file_path": "example.py",
  "content": "print('hello world')",
  "overwrite": true
}

ReplacementsPayload - Targeted Replacements

{
  "file_path": "example.py",
  "replacements": [
    {"old_str": "foo", "new_str": "bar"},
    {"old_str": "baz", "new_str": "qux"}
  ]
}

DeleteSnippetPayload - Remove Text

{
  "file_path": "example.py",
  "delete_snippet": "# TODO: remove this"
}

Best Practices

delete_file

Safely delete files with diff generation.

Signature

delete_file(file_path)

Features

• Shows diff of deleted content
• Proper error handling
• Respects safety settings

grep

Search across files using ripgrep.

Signature

grep(search_string, directory=".")

Parameters

Parameter	Type	Default	Description
search_string	string	required	Pattern to search (supports rg flags)
directory	string	"."	Root directory

Examples

# Simple search
grep("TODO")

# Case-insensitive
grep("--ignore-case error")

# Word boundaries
grep("-w function")

# Regex pattern
grep("def \\w+\\(")