FilesystemBackend

FilesystemBackend

Bases: BackendProtocol

Backend that reads and writes files directly from the filesystem.

Files are accessed using their actual filesystem paths. Relative paths are resolved relative to the current working directory. Content is read/written as plain text, and metadata (timestamps) are derived from filesystem stats.

METHOD	DESCRIPTION
__init__	Initialize filesystem backend.
ls_info	List files and directories in the specified directory (non-recursive).
read	Read file content with line numbers.
write	Create a new file with content.
edit	Edit a file by replacing string occurrences.
grep_raw	Search for a regex pattern in files.
glob_info	Find files matching a glob pattern.
upload_files	Upload multiple files to the filesystem.
download_files	Download multiple files from the filesystem.
als_info	Async version of ls_info.
aread	Async version of read.
agrep_raw	Async version of grep_raw.
aglob_info	Async version of glob_info.
awrite	Async version of write.
aedit	Async version of edit.
aupload_files	Async version of upload_files.
adownload_files	Async version of download_files.

__init__

__init__(
    root_dir: str | Path | None = None,
    virtual_mode: bool = False,
    max_file_size_mb: int = 10,
) -> None

Initialize filesystem backend.

PARAMETER	DESCRIPTION
root_dir	Optional root directory for file operations. If provided, all file paths will be resolved relative to this directory. If not provided, uses the current working directory. TYPE: str | Path | None DEFAULT: None
virtual_mode	Enables sandboxed operation where all paths are treated as virtual paths rooted at root_dir. Path traversal (using .. or ~) is disallowed and all resolved paths must remain within the root directory. When False (default), absolute paths are allowed as-is and relative paths resolve under cwd. TYPE: bool DEFAULT: False
max_file_size_mb	Maximum file size in megabytes for operations like grep's Python fallback search. Files exceeding this limit are skipped during search. Defaults to 10 MB. TYPE: int DEFAULT: 10

ls_info

ls_info(path: str) -> list[FileInfo]

List files and directories in the specified directory (non-recursive).

PARAMETER	DESCRIPTION
path	Absolute directory path to list files from. TYPE: str

RETURNS	DESCRIPTION
list[FileInfo]	List of FileInfo-like dicts for files and directories directly in the directory. Directories have a trailing / in their path and is_dir=True.

read

read(file_path: str, offset: int = 0, limit: int = 2000) -> str

Read file content with line numbers.

PARAMETER	DESCRIPTION
file_path	Absolute or relative file path. TYPE: str
offset	Line offset to start reading from (0-indexed). TYPE: int DEFAULT: 0
limit	Maximum number of lines to read. TYPE: int DEFAULT: 2000

RETURNS	DESCRIPTION
str	Formatted file content with line numbers, or error message.

write

write(file_path: str, content: str) -> WriteResult

Create a new file with content.

PARAMETER	DESCRIPTION
file_path	Path where the new file will be created. TYPE: str
content	Text content to write to the file. TYPE: str

RETURNS	DESCRIPTION
WriteResult	WriteResult with path on success, or error message if the file already exists or write fails. External storage sets files_update=None.

edit

edit(
    file_path: str, old_string: str, new_string: str, replace_all: bool = False
) -> EditResult

Edit a file by replacing string occurrences.

PARAMETER	DESCRIPTION
file_path	Path to the file to edit. TYPE: str
old_string	The text to search for and replace. TYPE: str
new_string	The replacement text. TYPE: str
replace_all	If True, replace all occurrences. If False (default), replace only if exactly one occurrence exists. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
EditResult	EditResult with path and occurrence count on success, or error message if file not found or replacement fails. External storage sets files_update=None.

grep_raw

grep_raw(
    pattern: str, path: str | None = None, glob: str | None = None
) -> list[GrepMatch] | str

Search for a regex pattern in files.

Uses ripgrep if available, falling back to Python regex search.

PARAMETER	DESCRIPTION
pattern	Regular expression pattern to search for. TYPE: str
path	Directory or file path to search in. Defaults to current directory. TYPE: str | None DEFAULT: None
glob	Optional glob pattern to filter which files to search. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
list[GrepMatch] | str	List of GrepMatch dicts containing path, line number, and matched text.
list[GrepMatch] | str	Returns an error string if the regex pattern is invalid.

glob_info

glob_info(pattern: str, path: str = '/') -> list[FileInfo]

Find files matching a glob pattern.

PARAMETER	DESCRIPTION
pattern	Glob pattern to match files against (e.g., '*.py', '**/*.txt'). TYPE: str
path	Base directory to search from. Defaults to root (/). TYPE: str DEFAULT: '/'

RETURNS	DESCRIPTION
list[FileInfo]	List of FileInfo dicts for matching files, sorted by path. Each dict contains path, is_dir, size, and modified_at fields.

upload_files

upload_files(files: list[tuple[str, bytes]]) -> list[FileUploadResponse]

Upload multiple files to the filesystem.

PARAMETER	DESCRIPTION
files	List of (path, content) tuples where content is bytes. TYPE: list[tuple[str, bytes]]

RETURNS	DESCRIPTION
list[FileUploadResponse]	List of FileUploadResponse objects, one per input file.
list[FileUploadResponse]	Response order matches input order.

download_files

download_files(paths: list[str]) -> list[FileDownloadResponse]

Download multiple files from the filesystem.

PARAMETER	DESCRIPTION
paths	List of file paths to download. TYPE: list[str]

RETURNS	DESCRIPTION
list[FileDownloadResponse]	List of FileDownloadResponse objects, one per input path.

als_info async

als_info(path: str) -> list[FileInfo]

Async version of ls_info.

aread async

aread(file_path: str, offset: int = 0, limit: int = 2000) -> str

Async version of read.

agrep_raw async

agrep_raw(
    pattern: str, path: str | None = None, glob: str | None = None
) -> list[GrepMatch] | str

Async version of grep_raw.

aglob_info async

aglob_info(pattern: str, path: str = '/') -> list[FileInfo]

Async version of glob_info.

awrite async

awrite(file_path: str, content: str) -> WriteResult

Async version of write.

aedit async

aedit(
    file_path: str, old_string: str, new_string: str, replace_all: bool = False
) -> EditResult

Async version of edit.

aupload_files async

aupload_files(files: list[tuple[str, bytes]]) -> list[FileUploadResponse]

Async version of upload_files.

adownload_files async

adownload_files(paths: list[str]) -> list[FileDownloadResponse]

Async version of download_files.