Skip to main content

​
Overview

​
Tool Name

​
Purpose

The filesystem_tools provide a comprehensive interface for local file and directory operations. Use them to read and write content, edit files by line, manage folders, search by name or content, visualize trees, and retrieve rich metadata for governance and troubleshooting.

​
Functions Available

  1. read_file: Read file content with automatic format detection and optional byte limit.
  2. read_text_file: Read text files with encoding and optional line numbering.
  3. edit_file: Modify files by replacing, inserting, appending, or deleting at line level.
  4. read_media_file: Access binary media content or metadata in safe formats.
  5. read_multiple_files: Batch read many files with optional shared encoding and metadata.
  6. write_file: Create or overwrite files with optional directory creation and encoding.
  7. directory_tree: Generate a visual tree of directories with depth control.
  8. create_directory: Create folders with optional recursion and permissions.
  9. list_allowed_directories: Show the directories your environment permits you to access.
  10. list_directory_with_sizes: List directory entries and compute sizes, optionally recursive.
  11. move_file: Move or rename files and directories with optional overwrite.
  12. search_files: Search by name, content, extension, or regex across a path.
  13. get_file_info: Return metadata such as size, timestamps, and permissions.
  14. list_directory: Basic listing of directory contents with optional filters.

​
Key Features

Read and Write

Reliable text and binary I/O with encoding control and safe byte limits.

Edit in Place

Line-level edits for quick fixes and scripted refactors.

Organize Folders

Create, move, and visualize directory structures.

Search at Scale

Find by name, content, or regex across nested trees.

Know Your Files

Retrieve permissions, timestamps, sizes, and checksums when needed.

​
Input Parameters for Each Function

​
read_file

Set max_bytes when sampling logs or very large files to improve responsiveness.
Very large read_file responses are capped before they are written into thread history. When the serialized response exceeds the file-read inline budget (default 262,144 bytes / 256 KB, configurable with GENESIS_TOOL_OUTPUT_FILE_READ_BUDGET), Genesis returns tool_output_capped, preview, truncation_info, full_output_ref, and agent_guidance instead of the full inline payload. Use start_byte, max_bytes, start_line, max_lines, end_byte, tail_bytes, or search_pattern to narrow follow-up reads. When full_output_ref is not null, the full text is saved under truncated_tool_outputs/<thread_id>/... in the apps BotGit repo and can be re-read with file(action="read", file_path=full_output_ref, repo_id="apps", start_byte=0, max_bytes=N), continuing from each response’s continuation.next_start_byte. The byte range is the shape that returns the saved copy exactly as written; the whole-file and line-window paths read in text mode and rewrite line endings.

​
read_text_file

​
edit_file

For multi-line inserts or replaces, include newline characters in new_content as needed.

​
read_media_file

​
read_multiple_files

​
write_file

​
directory_tree

​
create_directory

​
list_allowed_directories

This function does not require parameters. It returns the set of directories that are safe to traverse in your environment.

​
list_directory_with_sizes

​
move_file

​
search_files

Use search_type: "regex" with care. Anchor your patterns to reduce false positives and improve performance.

​
get_file_info

​
list_directory

Editing or moving system files can break running processes. Validate targets and keep backups for critical paths.

​
Use Cases

  1. Config management
    • Update YAML or JSON settings across environments with read_text_file and edit_file.
  2. Log triage
    • Sample the last megabytes of a large log using read_file with max_bytes.
  3. Repo structuring
    • Create a new project skeleton with create_directory and verify with directory_tree.
  4. Code search
    • Find usages of a function name across a codebase with search_files search_type: "content".
  5. Governance checks
    • Pull get_file_info with checksums for release packaging or audit trails.

​
Workflow/How It Works

  1. Inspect or search using list_directory, list_directory_with_sizes, or search_files.
  2. Read content with read_text_file or read_file. For binaries, use read_media_file.
  3. Modify with edit_file or write new content with write_file and optional create_directories.
  4. Restructure with move_file or create_directory, then visualize using directory_tree.
  5. Collect metadata using get_file_info for validation and documentation.

​
Integration Relevance

  • file_manager_tools to register and attach files once created or modified.
  • git_action for versioning changes that originate on the filesystem.
  • document_index_tools to index folders after writing or reorganizing content.
  • project_manager_tools to tie filesystem operations to tasks or milestones.
  • artifact_manager_tools to track generated outputs and link them back to runs.

​
Configuration Details

  • Use platform appropriate path separators and avoid trailing spaces in paths.
  • Default encoding is UTF-8. Specify encodings explicitly when working with legacy files.
  • For permission fields, use standard octal strings such as 755 or 644.
  • Recursive operations can be expensive on large trees. Apply max_depth and filters.

​
Limitations or Notes

  1. All operations respect OS permissions and may fail without proper access.
  2. Large files can consume significant memory or time to process. Use limits and sampling.
  3. Network mounted volumes may perform differently than local disks.
  4. Encoding detection is best effort and may be inaccurate for mixed content files.
  5. Concurrent writers can cause conflicts. Coordinate long running edits and moves.

​
Output

  • Reads: File content plus encoding info and optional metadata.
  • Capped Oversized Read: When read_file is too large to keep inline, truncation_info includes bucket, bytes_in, bytes_out, budget_bytes, and spill_path. The shared agent_guidance explains that this routine cap is not a context limit or an error; see Code Executor Tools — Output for the full spill and failed-save guidance.
  • Writes and Edits: Confirmation with file details and sizes.
  • Listings: Entries with names, sizes, dates, and optional recursion summaries.
  • Trees: A compact visual structure of folders and files.
  • Search: Array of matches with paths and match context.
  • Metadata: Permissions, timestamps, and checksums when requested.