> ## Documentation Index
> Fetch the complete documentation index at: https://reaperagent.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# File Operations

> Reagent can move, copy, rename, and create folders for you — every change requires your approval.

<Note>
  File operations are now powered by dedicated, structured tools (no shell access). The user-facing approval flow is unchanged — same overlay, same "Allow remaining" affordance — but the tool surface underneath is `file_move`, `file_copy`, `file_rename`, `file_mkdir`, plus the read-only `file_read`, `file_list`, `file_stat`, `file_glob`, `file_grep`. Paths are scoped to your home directory, the REAPER scripts directory, and external drives (`/Volumes` on macOS, `/mnt` on Linux).
</Note>

Reagent can perform basic file operations on your machine: moving and copying files, renaming, and creating folders. Every action that changes your filesystem requires your explicit approval.

## What's Allowed

| Operation         | Example                                                    |
| ----------------- | ---------------------------------------------------------- |
| **Move**          | "Move all SFX files into a `bounced/` subfolder"           |
| **Copy**          | "Copy the dialogue takes to my project archive"            |
| **Rename**        | "Rename these stems to match the UCS convention"           |
| **Create folder** | "Make a new `wwise-import/` folder next to the project"    |
| **Inspect**       | Listing folders and reading file metadata happens silently |

Reagent **cannot** run scripts, install software, send network requests, or invoke shells via this feature. The set of allowed commands is intentionally narrow.

## The Confirmation Overlay

When the agent wants to make a change, you'll see an overlay describing exactly what it's about to do:

* The operation kind (move, copy, rename, create folder)
* The files affected
* Source and destination folders
* Any warnings the safety checks raised

You have three choices:

| Choice              | Effect                                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Allow**           | Approves this single change                                                                                  |
| **Allow remaining** | Approves this change *and* auto-approves every other file operation for the rest of the agent's current turn |
| **Deny** (X / Esc)  | Cancels this change and reports the denial back to the agent                                                 |

<Tip>Use **Allow remaining** when you've reviewed a batch operation and want the agent to keep going without prompting on each file. The approval clears automatically when the turn ends, when you send a new message, or when you stop the session.</Tip>

When a change is auto-approved, you'll still see an inline `auto-approved: ...` line in the chat so you can scan the activity afterwards.

## Safety Checks

Every file operation passes through three layers of validation before you ever see the confirmation overlay:

1. **Structural patterns** — chained commands, shell metacharacters, command substitution, and destructive flags are rejected outright
2. **Allowed commands only** — anything other than `mv`, `cp`, `rename`, `mkdir`, `ls`, `find`, or `stat` is blocked at the gate
3. **Resolved-path check** — the *resolved absolute path* of every file is checked against protected system locations (`/etc/`, `/usr/`, `/bin/`, `/sbin/`, `/System/`, `C:\Windows\`, etc.). Path-traversal escapes like `../../` are caught here too

If any check fails, the agent receives a denial and is instructed not to retry by invoking a different command — a denial is a hard stop, not a hint to find another way.

<Warning>
  Reagent's safety pipeline blocks the most common foot-guns, but you should still review each confirmation. If a path looks wrong or a destination surprises you, Deny and ask the agent to clarify.
</Warning>

## Common Workflows

```
Move every file matching *_v01.wav from the desktop into the project's bounced/ folder
```

```
Rename the selected items' source files to match this UCS pattern: ImpactWood_DOOR_*
```