Skip to main content
The filesystem tool gives agents the ability to explore codebases, read and edit files, create new files, search across files, and navigate directory structures. Paths are resolved relative to the working directory, though agents can also use absolute paths.

​
Available tools

ToolDescription
read_fileRead the complete contents of a file. Supports text files and images (jpg, png, gif, webp).
read_multiple_filesRead several files in one call — more efficient than sequential read_file calls.
write_fileCreate or overwrite a file with new content. Creates parent directories automatically.
edit_fileMake find-and-replace edits to an existing file without rewriting the entire content.
list_directoryList files and directories at a given path.
directory_treeRecursive tree view of a directory as a JSON structure.
search_files_contentSearch for text or regex patterns across files.
create_directoryCreate one or more directories (including nested structures).
remove_directoryRemove one or more empty directories.

​
Configuration

toolsets:
  - type: filesystem

​
Options

​
ignore_vcs
boolean
default:"false"
When true, ignores .gitignore patterns and includes all files in listings and searches.
​
post_edit
array
Commands to run automatically after any file is edited or written.
​
post_edit[].path
string
Glob pattern that determines which files trigger this command (e.g. *.go, src/**/*.ts).
​
post_edit[].cmd
string
Shell command to run. Use ${file} to reference the absolute path of the edited file.

​
Post-edit hooks

Automatically format or lint files after the agent edits them: 
toolsets:
  - type: filesystem
    post_edit:
      - path: "*.go"
        cmd: "gofmt -w ${file}"
      - path: "*.ts"
        cmd: "prettier --write ${file}"
      - path: "*.py"
        cmd: "black ${file}"

​
Example agent

agent.yaml
agents:
  root:
    model: openai/gpt-4o
    description: Coding assistant with filesystem access
    instruction: |
      You are a coding assistant. Use the filesystem tools to read and
      modify code. Always check the current content before editing.
    toolsets:
      - type: filesystem
        post_edit:
          - path: "*.go"
            cmd: "gofmt -w ${file}"
Use read_multiple_files to read several files in a single tool call rather than calling read_file repeatedly. This reduces the number of round-trips and speeds up multi-file analysis.

​
Security considerations

The filesystem tool can read and write any file accessible to the process. Use the instruction field to scope the agent to specific directories, and configure Permissions to require confirmation before writes:
permissions:
  ask:
    - write_file
    - edit_file

Shell

Execute commands alongside file operations.

LSP

Add code intelligence on top of filesystem access.

Permissions

Control which file operations require confirmation.

Configuration

Full toolset configuration reference.

Build docs developers (and LLMs) love

Get started for freeTalk to us