File Access Toolset¶

The File Access toolset provides tools for reading, writing, and editing files on any fsspec-compatible filesystem. This includes local files, S3, GitHub repositories, and more.

Basic Usage¶

agents:
  my_agent:
    tools:
      - type: file_access
        fs: "file:///workspace"

Filesystem Options¶

The fs field accepts either a URI string or a full filesystem configuration:

URI String¶

tools:
  - type: file_access
    fs: "file:///home/user/project"

Filesystem Config¶

tools:
  - type: file_access
    fs:
      type: github
      org: sveltejs
      repo: svelte
      sha: main

Composed Filesystems¶

Mount multiple filesystems together using the mounts type:

tools:
  - type: file_access
    fs:
      type: mounts
      mounts:
        docs: "github://sveltejs:svelte@main"
        src: "file:///workspace/src"
        data:
          type: s3
          bucket: my-bucket

Available Tools¶

File Access Default Tools

`list_directory`

List files in a directory with filtering support.

Supports: - Glob pattern matching (, , .py, etc.) - Exclude patterns for filtering - Recursive directory traversal with depth control - Safety limits to prevent overwhelming output

Parameters:

Name	Type	Required	Description
`path`	string	✓	Base directory to list
`pattern`	string		Glob pattern to match files against. Use ".py" to match Python files in current directory only, or "/.py" to match recursively. The max_depth parameter limits how deep "**" patterns search.
`exclude`	array		List of patterns to exclude (uses fnmatch against relative paths)
`max_depth`	integer		Maximum directory depth to search (default: 1 = current dir only). Only affects recursive "**" patterns.

Hints: read-only, idempotent

Category: read

`read`

Read the content of a text file, or use vision capabilities to read images or documents.

Supports: - Text files with optional line-based partial reads - Binary files (images, PDFs, audio, video) returned as BinaryContent - Automatic image resizing for better model compatibility - Structure maps for large code files - Multiple text encodings

Parameters:

Name	Type	Required	Description
`path`	string	✓	File path to read
`encoding`	string		Text encoding to use for text files (default: utf-8)
`line`	integer		Optional line number to start reading from (1-based, text files only)
`limit`	integer		Optional maximum number of lines to read (text files only)

Hints: read-only, idempotent

Category: read

`grep`

Search file contents for patterns using grep.

Supports: - Regex pattern matching - File filtering with glob patterns - Context lines before/after matches - Fast subprocess grep (ripgrep/grep) with Python fallback - Case-sensitive and case-insensitive search

Parameters:

Name	Type	Required	Description
`pattern`	string	✓	Regex pattern to search for
`path`	string	✓	Base directory to search in
`file_pattern`	string		Glob pattern to filter files (e.g. "*/.py")
`case_sensitive`	boolean		Whether search is case-sensitive
`max_matches`	integer		Maximum number of matches to return
`context_lines`	integer		Number of context lines before/after match

Hints: read-only, idempotent

Category: search

`write`

Write content to a file.

Parameters:

Name	Type	Required	Description
`path`	string	✓	File path to write
`content`	string	✓	Content to write
`mode`	string		Write mode ('w' for overwrite, 'a' for append)
`overwrite`	boolean		Must be True to overwrite existing files (safety check)

Category: edit

`delete_path`

Delete a file or directory from the filesystem.

Supports: - File deletion - Directory deletion with safety checks - Recursive directory deletion - Empty directory validation

Parameters:

Name	Type	Required	Description
`path`	string	✓	Path to delete
`recursive`	boolean		Whether to delete directories recursively

Hints: destructive

Category: delete

`download_file`

Download a file from a URL to the filesystem.

Supports: - HTTP/HTTPS downloads - Progress tracking - Speed monitoring - Automatic directory creation - Configurable chunk size and timeout

Parameters:

Name	Type	Required	Description
`url`	string	✓	URL to download from
`target_dir`	string		Directory to save the file (relative to cwd if set)
`chunk_size`	integer		Size of chunks to download (overrides default)

Hints: open-world

Category: read

`edit`

Edit a file by replacing specific content with smart matching.

Uses sophisticated matching strategies to handle whitespace, indentation, and other variations. Shows the changes as a diff in the UI.

Parameters:

Name	Type	Required	Description
`path`	string	✓	File path (absolute or relative to session cwd)
`old_string`	string	✓	Text content to find and replace
`new_string`	string	✓	Text content to replace it with
`description`	string	✓	Short Human-readable description of what the edit accomplishes
`replace_all`	boolean		Whether to replace all occurrences (default: False)
`line_hint`	integer		Line number hint to disambiguate when multiple matches exist. If the pattern matches multiple locations, the match closest to this line will be used. Useful after getting a "multiple matches" error.

Category: edit

`regex_replace_lines`

Apply regex replacement to a line range specified by line numbers or text markers.

Applies re.subn(pattern, replacement, line, count=count) to each line individually within the specified range. Because matching is per-line, avoid patterns that match the empty string (e.g. .*, [\s\S]*, \d*) — subn will match both the content and the trailing empty string, duplicating the replacement.

Useful for systematic edits: - Remove/add indentation - Comment/uncomment blocks - Rename variables within scope - Delete line ranges

Examples: # Remove a function regex_replace_lines(ctx, "file.py", "def old_func(", " return", r".+\n", "")

# Indent by line numbers
regex_replace_lines(ctx, "file.py", 10, 20, r"^", "    ")

# Uncomment a section
regex_replace_lines(ctx, "file.py", "# START", "# END", r"^# ", "")

Parameters:

Name	Type	Required	Description
`path`	string	✓	File path to edit
`start`	integer	✓	Start of range - int (1-based line number) or str (unique text marker)
`end`	integer	✓	End of range - int (1-based line number) or str (first occurrence after start)
`pattern`	string	✓	Regex pattern to search for within the range
`replacement`	string	✓	Replacement string (supports \1, \2 capture groups; empty removes)
`count`	integer		Max replacements per line (0 = unlimited)

Category: edit

Configuration Reference¶

File Access Toolset¶

Configuration for file access toolset (supports local and remote filesystems).

File Access Toolset (YAML)
toolsets:
- type: file_access
  fs: null  # Filesystem URI string or configuration object. If None, use agent default FS.
  model: null
  storage_options: {}  # Additional options for URI-based filesystems (ignored when using config object).
  conversion: null  # Optional conversion configuration for markdown conversion.
  max_file_size_kb: 64  # Maximum file size in kilobytes for read/write operations (default: 64KB).
  max_grep_output_kb: 64  # Maximum grep output size in kilobytes (default: 64KB).
  use_subprocess_grep: true  # Use ripgrep/grep subprocess if available (faster than Python regex).
  enable_diagnostics: false  # Run LSP CLI diagnostics (type checking, linting) after file writes.
  large_file_tokens: 12000  # Token threshold for switching to structure map instead of full content.
  map_max_tokens: 2048  # Maximum tokens for structure map output when reading large files.
  edit_tool: simple  # Which edit tool to expose: "simple" (single replacement),
  max_image_size: 2000  # Max width/height for images in pixels. Larger images are auto-resized
  max_image_bytes: null  # Max file size for images in bytes. Images exceeding this are compressed
  namespace: null  # Optional namespace prefix for tool names

Examples¶

Local Development¶

tools:
  - type: file_access
    fs: "file:///home/user/project"
    max_file_size_kb: 128

GitHub Repository Access¶

tools:
  - type: file_access
    fs:
      type: github
      org: fastapi
      repo: fastapi
      cached: true

Multi-Source Documentation¶

tools:
  - type: file_access
    fs:
      type: mounts
      mounts:
        svelte: "github://sveltejs:svelte@main"
        react: "github://facebook:react@main"
        local: "file:///docs"