The catalogue/Filesystem
Filesystem
app.filesystem
Safe file operations with read, write, search, and more
Version1.0.0
Categorydevelopment
AuthNo auth
Tools18
Transportstdio
LicenceMIT
01
What it does
The app, in its own words.
Filesystem operations: read, write, edit, patch, search (glob/grep), list, tree, stat, hash, copy, move, delete, and mkdir. Path-traversal safe, shell-injection safe, gitignore aware.
02
Tools
18 tools the agent can call.
Every one is declared with typed parameters and returns structured results, so the host can render them instead of narrating them.
- appendAppend content to the end of a file. Creates the file (and parents) if it does not exist. Does NOT require a prior read.
- copyCopy a file or directory. For directories set recursive: true. Fails if destination exists unless overwrite: true.
- deleteDelete a file or directory. Set recursive: true for non-empty directories. Idempotent: succeeds if path does not exist.
- editReplace exact string occurrence(s) in a file. Fails if oldString appears zero or multiple times — pass replaceAll: true for every match. Returns a unified diff.
- globFind files matching a glob pattern. Results sorted by mtime (most recently modified first). Honors ignore patterns and respectGitignore.
- grepSearch file contents for a regex pattern using ripgrep. output_mode: "content" (matches with context), "files" (per-file counts), "count" (totals only).
- hashCompute the cryptographic hash of a file (default sha256). Streams the file so it works on large files.
- listList directory entries with metadata (name, type, size, mtime, kind). Optionally recursive via depth. Honors ignore patterns and respectGitignore. Paginates with limit + cursor.
- list_rootsList the workspace roots this app can access.
- mkdirCreate a directory. Creates parent directories as needed by default. Idempotent: returns created=false if already exists.
- moveMove or rename a file or directory. Fails if destination exists unless overwrite: true.
- patchApply a unified diff (patch format) to a file. Uses fuzzy matching (fuzzFactor 2). For single-point changes prefer `edit`.
- readRead a text file with optional line-based pagination. Returns content formatted as "cat -n" (numbered lines) plus metadata. Use offset+limit for ranges or head/tail for the first/last N lines. Binary files are rejected.
- read_batchRead multiple text files in a single call. Individual failures do not abort the batch.
- read_mediaRead a binary file and return base64 + detected MIME type. Hard cap 10 MB. For text files use read.
- statReturn metadata for a single path: exists, type, size, mtime, permissions. Does NOT read content.
- treeReturn a hierarchical JSON tree of a directory up to depth levels. Capped by maxNodes. Use list for flat pagination or glob for pattern match.
- writeWrite content to a file, overwriting if it exists. Safety: an existing file must have been read first in this session. For new files, parent directories are created automatically. Use `edit` for in-place modifications.
Reading further
The manifest and the source for Filesystem live in the monorepo, alongside the other apps.