> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filesystem Tools

> Direct file and directory management on the local system. Read, write, edit, search, and organize files with text and binary support.

## **Overview**

### **Tool Name**

```json theme={null}
filesystem_tools
```

### **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

<Steps>
  <Step title="Read and Write" icon="file-pen">
    Reliable text and binary I/O with encoding control and safe byte limits.
  </Step>

  <Step title="Edit in Place" icon="pen-to-square">
    Line-level edits for quick fixes and scripted refactors.
  </Step>

  <Step title="Organize Folders" icon="folder-plus">
    Create, move, and visualize directory structures.
  </Step>

  <Step title="Search at Scale" icon="magnifying-glass">
    Find by name, content, or regex across nested trees.
  </Step>

  <Step title="Know Your Files" icon="circle-info">
    Retrieve permissions, timestamps, sizes, and checksums when needed.
  </Step>
</Steps>

## **Input Parameters for Each Function**

### `read_file`

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **file\_path** | Absolute or relative path to the file. | String |
| **encoding** | Text encoding used when decoding content. | String |
| **max\_bytes** | Maximum bytes to read for large files. | Integer |

<Tip>
  Set `max_bytes` when sampling logs or very large files to improve responsiveness.
</Tip>

<Note>
  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.
</Note>

### **`read_text_file`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **file\_path** | Path to the text file. | String |
| **encoding** | Character encoding, default UTF-8. | String |
| **line\_numbers** | Include line numbers in the returned text. | Boolean |

### **`edit_file`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **file\_path** | Path to the file to modify. | String |
| **line\_number** | Line number to target for the operation. | Integer |
| **new\_content** | Replacement or inserted content. | String |
| **operation** | One of `replace` `insert` `append` `delete`. | String |

<Note>
  For multi-line inserts or replaces, include newline characters in `new_content` as needed.
</Note>

### **`read_media_file`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **file\_path** | Path to the binary media file. | String |
| **return\_format** | One of `base64` `binary` `metadata` for safe retrieval. | String |

### **`read_multiple_files`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **file\_paths** | Array of file paths to read. | List |
| **encoding** | Text encoding for all files when applicable. | String |
| **include\_metadata** | Include file metadata with each result. | Boolean |

### **`write_file`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **file\_path** | Destination path to create or overwrite. | String |
| **content** | Text content to write. | String |
| **encoding** | Text encoding used for writing. | String |
| **create\_directories** | Create parent folders if they do not exist. | Boolean |

### **`directory_tree`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **directory\_path** | Root directory for tree generation. | String |
| **max\_depth** | Limit traversal depth. | Integer |
| **show\_hidden** | Include hidden files and directories. | Boolean |

### **`create_directory`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **directory\_path** | Directory path to create. | String |
| **recursive** | Create missing parents. | Boolean |
| **permissions** | Octal permission string like `755`. | String |

### **`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`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **directory\_path** | Directory to list. | String |
| **recursive** | Include contents of subdirectories. | Boolean |
| **sort\_by** | One of `name` `size` `date` `type`. | String |

### **`move_file`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **source\_path** | Current file or folder path. | String |
| **destination\_path** | Target path or new name. | String |
| **overwrite** | Overwrite if destination exists. | Boolean |

### **`search_files`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **search\_path** | Directory to search within. | String |
| **search\_pattern** | Pattern to match text, names, or extensions. | String |
| **search\_type** | One of `name` `content` `extension` `regex`. | String |
| **recursive** | Search subdirectories. | Boolean |
| **case\_sensitive** | If true, matches are case sensitive. | Boolean |

<Tip>
  Use `search_type: "regex"` with care. Anchor your patterns to reduce false positives and improve performance.
</Tip>

### **`get_file_info`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **file\_path** | Path to the file. | String |
| **include\_permissions** | Include permission bits in the response. | Boolean |
| **include\_checksums** | Compute checksums for integrity checks. | Boolean |

### **`list_directory`**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **directory\_path** | Directory to list. | String |
| **filter\_pattern** | Wildcard or regex filter for names. | String |
| **show\_hidden** | Include hidden files. | Boolean |

<Warning>
  **Editing or moving system files can break running processes.** Validate targets and keep backups for critical paths.
</Warning>

## **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](/docs/Genbot-Toolkit/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.