File Tools
Last updated
Tools that find, read, edit, remove, restore, open and track files.
| Tool | Description |
|---|---|
find_files | Locate files (queries: [{dir, pattern, file_pattern, recursive}]). mode=list returns a directory's entries (alphabetical), mode=glob matches paths against a filename pattern and, since v1.0.23, returns them most recently modified first, mode=search greps file contents by RE2 regex. Mode is inferred when omitted: pattern + file_pattern → search, pattern alone → glob, neither → list. Glob patterns must carry a literal — all-wildcard (**/*) is rejected. Matches merge and deduplicate across queries. mode=list and mode=glob are capped at 128 KiB in total and the tail reports how many entries were dropped. Since v1.0.11 mode=search is paged instead of truncated: output=files (the default) returns one {path, count, lines} row per matching file — since v1.0.23 lines carries the row numbers of its first five matches, ready for read_files lines — output=content returns the matching lines with their line numbers, multiline=true (v1.0.23) matches the regex against whole files so . crosses newlines and reports every row a match spans, offset / limit (default 256) walk the pages, and context_lines adds surrounding lines — marked context: true and not counted toward offset / limit. A single match line is cut at 512 bytes. Every page ends with [files a-b of N ...] / [lines a-b of N ...] carrying the next offset, or last page; the queries and output must stay identical between pages |
read_files | Batched read of one or more files (files: [{path, offset, limit, lines, context_lines, full}]); text, PDF, DOCX, PPTX, CSV/TSV, image, or audio/video — a media file comes back as a verbatim transcript through the configured speech-to-text model, so there is no separate transcription tool. Reads up to 2048 lines by default (1 MiB cap for documents, 10 MiB for images); offset/limit page through larger files — page for PDF, slide for PPTX, row for CSV. Since v1.3.21 lines takes 1-based rows of a plain-text file and reads context_lines lines (default 64, 0 = the rows alone) on each side, merging overlapping windows and marking skipped text with a ... line (offset/limit are then ignored), and the same path may appear more than once in files, its results joined in order. Since v1.0.11 a truncated text read ends with [lines a-b of N; call again with offset=... for more], so the continuation offset never has to be guessed. Text lines arrive as "<row>\t<line>"; the number is added by the reader and is not in the file, so it must be stripped before a line is reused as an write_file anchor. Must be called before write_file changes an existing file: since v1.0.23 the edit is refused unless the file was read in this run and its modification time is unchanged since that read. Since v1.3.21 a decision model can filter the result against the task. At 16,384 runes or more, it checks individual blocks and marks omissions. Content is kept when no decision model is configured or the check fails. Set full: true on a file entry to bypass filtering without changing pagination or line selection; use it and read all pages before a full rewrite |
write_file | filename is required and is absolute or relative to the work directory. mode=write creates or replaces a file with write_content; mode=patch applies patch_contents. Each patch requires old_string and new_string and accepts replace_all. Anchors resolve against the original contents; edits on the same line are allowed if their ranges do not overlap. An empty new_string deletes the match; with replace_all it deletes every match. Ambiguous matches without replace_all, overlapping edits, and patches that would empty a non-empty file reject the whole batch. Patches are limited to 1 MiB. To change an existing file, read it with read_files in this turn and leave it unchanged on disk; a successful write counts as a fresh read. The default display label is Write; patch mode displays Edit |
remove_file | Added in v1.3.11, replacing edit_file(mode=remove). Moves one file (filename, required; absolute or relative to the work directory) aside into ~/.config/agenvoy/.store/temp/ instead of deleting it, records the move in file history, and returns where it went; restore_file puts it back. Every call asks for confirmation unless the user already allowed every call for this turn. Used only on an explicit request or a Skill step; a skill or script tool is removed with edit_skill / edit_tool mode=remove. Not available to subagent legs. The tool-call line reads Remove(<path>) |
restore_file | Added in v1.3.11, replacing edit_file(mode=restore). Puts a recorded version back by version (an id from a file_history row, which names both the file and the state; takes precedence over task_id), or undoes a whole task with task_id (a task id from chat_history, or current for the task running now), returning every file that task touched to before it ran; filename together with task_id narrows the undo to that one file. Send all three fields: use 0 for an unused version and an empty string for an unused task ID or filename. It also brings back a file remove_file moved aside. Every call asks for confirmation unless the user already allowed every call for this turn. Not available to subagent legs. The tool-call line reads Restore(...) with the path, version N or the task id |
file_history | Recorded versions of every file the tools changed — when each changed, what the task was after, and what the content was. mode=list returns versions newest-first, filterable by path, task_id, from/to local time, and limit (capped at 24); mode=read diffs the newest recorded version of each path against what is on disk now. This is the snapshot layer restore_file restores from |
open_file | Open a file or URL with the OS default handler (play a video, view an image, open a PDF viewer; since v1.2.1 also a link or a system settings pane such as x-apple.systempreferences:...). A URL always asks the user to confirm. Replaces run_command open/xdg-open, which the sandbox cannot reach. 10 s cap |
edit_file was Removed in v1.3.20; use write_file. Replace content with write_content and targets with patch_contents.Removed in v1.3.21:
read_files uses lines and context_lines in place of around and context; find_files uses context_lines in place of context; write_file, remove_file, and restore_file use filename in place of path.