Middleware that adds virtual filesystem capabilities to agents.

Provides tools for file operations in an isolated, persistable filesystem:

• list_files: List all files (with optional pattern filtering)
• read_file: Read file contents with line numbers and pagination
• create_file: Create new files (errors if file exists)
• replace_file_text: Make targeted edits with string replacement
• replace_file_lines: Replace a range of lines by line number
• find_in_file: Find text or regex matches within a single file
• delete_file: Delete files from the filesystem
• move_file: Move or rename files and directories

Usage

{:ok, agent} = Agent.new(
  model: model,
  middleware: [Filesystem]
)

# Agent can now use filesystem tools

Configuration

Basic Configuration

• :filesystem_scope - Scope tuple identifying the filesystem (e.g. {:agent, id}, {:user, id}, {:project, id})
• :enabled_tools - List of tool names to enable (default: all tools)
• :custom_tool_descriptions - Map of custom descriptions per tool
• :custom_display_texts - Map of custom display_text labels (per tool) shown in the UI when the tool runs. Useful when a consuming project wants user-facing language different from the defaults (e.g. "Writing document" instead of "Creating file").

Selective Tool Enabling

Enable only specific tools (e.g., read-only access):

{:ok, agent} = Agent.new(
  model: model,
  filesystem_opts: [
    enabled_tools: ["list_files", "read_file"]  # Read-only
  ]
)

Available tools: "list_files", "read_file", "create_file", "replace_file_text", "replace_file_lines", "find_in_file", "delete_file", "move_file"

Custom Tool Descriptions

Override default tool descriptions:

{:ok, agent} = Agent.new(
  model: model,
  filesystem_opts: [
    custom_tool_descriptions: %{
      "read_file" => "Custom description for reading files...",
      "create_file" => "Custom description for creating files..."
    }
  ]
)

Custom Display Texts

Override the default UI label shown when a tool runs. Only the tools you specify are overridden; the rest keep their defaults.

{:ok, agent} = Agent.new(
  model: model,
  filesystem_opts: [
    custom_display_texts: %{
      "create_file" => "Writing document",
      "delete_file" => "Removing document"
    }
  ]
)

File Organization

Use hierarchical paths to organize files:

create_file(file_path: "/reports/q1-summary.md", content: "...")
create_file(file_path: "/images/diagram.png", content: "...")
list_files(pattern: "/reports/*")

Pattern Filtering

The list_files tool supports wildcard patterns:

• * matches any characters
• Examples: *summary*, *.md, reports/*

Path Security

Paths are validated to prevent security issues:

• Paths must start with "/"
• Path traversal attempts ("..") are rejected
• Home directory shortcuts ("~") are rejected