---
title: Finding, organizing and cleaning up files
description: Choose indexed or content search, inspect folder coverage, distinguish exact duplicates from similar photos and organize collision-safe outputs.
order: 12
---

# Finding, organizing and cleaning up files

FileHop also supplies the file-management steps around a conversion or editing task. These operations are useful when an agent must first locate the right inputs, estimate the job, organize outputs and preserve a recovery path.

## Choose the search mode

| Need | Tool | What to check |
| --- | --- | --- |
| Know the contents of a particular directory | `list_files` | Name-sorted listing, optional glob and recursion, `nextOffset` for continuation |
| Find likely files by name across shared folders | `file_search` | Ranked indexed search, typo/accent handling and filters; `indexComplete` indicates indexing coverage |
| Find words inside documents or filenames while walking a folder | `search_files` | Separate `name` and `content` criteria; content search includes supported PDF, Word, PowerPoint and Excel text |
| Estimate a folder's contents before bulk work | `folder_summary` | Sizes/counts by kind/extension, largest/newest files, depth, empties, skipped/truncated entries |
| Inspect selected files precisely | `file_info`, `file_read` | Metadata and format details; use format-specific tools for deeper native structure |

For `file_search`, supported query filters include `type:pdf`, `type:image`, `type:folder`, `ext:md`, `size:>10mb`, `date:2026-01-01` and `date:week`. The filename index is built on first use and currently capped at 100,000 files per folder. Search results from an incomplete index are not proof that no other file exists.

`search_files` content hits are bounded snippets, not complete documents: it returns up to five matching lines per file, and `max_results` counts files. Its traversal normally skips hidden entries and build/dependency/version-control directories; inspect the schema and returned skip/truncation data. Image-only scans do not gain recognized text merely because the search supports PDF files.

`list_files` flags symbolic links and does not follow them. Folder summaries also omit links/hidden entries and stop at a bounded entry count. Do not claim a complete disk inventory when a tool reports incomplete coverage.

## Find duplicate files and similar photos

`find_duplicates` accepts shared folders and/or explicit files. Recursive scanning defaults on and hidden entries are skipped. Results distinguish:

- `groups`: identical-content duplicates, with a suggested `keep` path and other copies.
- `similarImages`: visually similar images that are **not byte-identical**, such as resized or re-saved versions.

The keep suggestion is guidance, not proof that the other copies are unnecessary. A smaller similar photo may be a distinct edited deliverable. Review before deleting. `max_groups` defaults to 100 and can be raised to 500; `truncated`, group totals and reported reclaimable bytes may describe more matches than the visible groups. Do not act on unseen groups from a summary count.

`find_empty` finds zero-byte files and empty folders, with bounded results. Empty files can be intentional. Both cleanup-discovery tools are read-only; they do not remove anything automatically.

## Organize and recover

`create_folder` creates missing parents and leaves existing directories alone. `copy_files` handles recursive copies, and `move_files` supports moves including across drives. They avoid overwriting collisions and return actual destination paths.

`rename_files` takes a new **name**, not a path. An existing destination name is refused; case-only renames are supported. Rename and move have safeguards around shared roots and FileHop workspace directories. Inspect per-item results rather than assuming the whole group moved or was renamed.

`trash_files` uses the OS Trash/Recycle Bin rather than permanent deletion. `trash_list` exposes eligible items from shared folders, and `restore_files` restores by original path (the newest matching trashed item). If that original path is occupied, restoration uses a unique name. Read the returned location instead of assuming an old link now points to the restored file.

Choose output locations using `workspace_folder` where appropriate: user-facing outputs, intermediates in scratch, and diagnostic logs have distinct purposes. Do not treat scratch previews or temporary speech files as permanent deliverables.

## Resume without repeating work

Use `activity_log` to find earlier outputs and partial failures. Use `context_read` to inspect review notes and decisions associated with a file. `context_write` adds/replies/resolves comments without changing file bytes; this works even when the underlying file is read-only.

Content edits made by FileHop participate in supported file history. If using another editor, capture `history_checkpoint` before and after meaningful changes. When the user needs both versions, `history_copy` writes a retained earlier state to a new file instead of replacing the current one.

For a continued human/agent task, attach sources, working files and outputs to a [review session](/docs/human-review-sessions/) and preserve the actual returned paths. A task attachment organizes work; it does not add filesystem permission or turn every external action into an audited FileHop operation.