Skip to main content
File operations don’t need REAPER, except for prompts about “my project”: Reagent needs REAPER connected to find where the project is saved.

What Reagent Can Do

  • Move, copy and rename files and folders.
  • Create folders.
  • List folders and find files by name.
  • Read and search text files, such as scripts, CSVs and REAPER project files.
File operations can’t:
  • Delete files or folders (though a move or copy that overwrites replaces what was there; see Built-in Safeguards).
  • Run shell commands, scripts or other programs.
  • Reach folders outside the allowed locations.
  • Open audio, images or other binary files as text. For audio, see Audio Analysis.
File changes don’t update your REAPER project. If you move or rename a file that an open project uses, the project still points to the old location, so REAPER may not find the media. To rename items in REAPER, ask Reagent to rename the takes instead. For UCS names, use the UCS Renamer skill.
To point Reagent at an exact folder, drag it into the message box, or click + > Attach folder. Reagent gets its path. Its contents aren’t uploaded.

Reading and Searching

Folder listings, file names, matching lines from searches and the text of files Reagent reads are sent to the AI model as part of the conversation. Privacy & Security explains what the model receives.
  • Name the folder. Otherwise Reagent may search your whole home folder, which is slower. For content searches, name a scripts or documents folder, not a whole sound library.
  • Point to the part you need. Reagent reads long files a part at a time, so name the section or column.
  • Mention both capitalizations. Finding by name is case-sensitive: “creak” doesn’t find “Creak”, and “.wav” doesn’t find ”.WAV”.
Listing, finding and searching all skip:
  • Hidden files and folders (names that start with a dot). A folder listing includes them if you ask.
  • Anything named build, out, dist, target, node_modules, .git, .svn, .hg, .next, .turbo or .cache, in any capitalization. If your renders live in a folder called Out or Build, name that folder directly and Reagent can list and search inside it.

Where Reagent Can Reach

File operations only work in the locations below. A path that ends up outside them, even through a symbolic link (a link to another location) or .. (the parent folder), is refused, and nothing changes.
  • Your home folder and everything in it, such as Desktop, Documents, Music and Downloads.
  • Your REAPER Scripts folder, where Reagent installs the Bridge.
  • Drives under /Volumes: external drives, and network shares you’ve mounted in Finder.
The rest of your startup disk is out of reach, for example /Applications, /Library and /Users/Shared.The first time Reagent works in a protected folder such as Desktop, Documents or Downloads, macOS may ask for access. Allow it, or file actions there fail. See File Access Problems.
A refused step reads “Something went wrong”, and its Show details says “Path is outside the allowed roots”. Move or copy the files somewhere allowed, then ask again.

Approvals

Listing, finding, reading and searching never ask. Changes follow your permission mode. Auto-review asks only before a move or copy set to overwrite, or a batch that contains one.

The Approval Card

Related changes usually arrive as one batch of up to 100 items on one card. The card shows:
  • A single move, copy, rename or new folder: the full paths.
  • A batch: the first four items, then “+N more operation(s)”.
  • An overwrite: “Will overwrite the destination if it exists.” for one item, or “Some operations can overwrite destinations.” for a batch.
Allow runs every item in the batch. Deny changes nothing. See Permissions.

Built-in Safeguards

These checks run in every mode, when the action runs rather than on the card. A path problem shows as an error after you click Allow, and nothing changes.
  • No overwrites unless Reagent asks. A move or copy stops if the destination exists, unless Reagent set it to overwrite.
  • Renames never overwrite. A rename stops if the new name is taken. macOS and Windows treat door.wav and Door.wav as the same file, so a rename that only changes capitalization is usually refused too. Rename to a temporary name first, then to the new name.
  • The whole batch is checked first. Before a batch of moves, copies or renames changes anything, Reagent checks that each source exists, each destination is free (or set to overwrite), no two items go to the same place, and no folder goes inside itself. If any item fails these checks, nothing changes.

Stopping and Undoing

An overwrite can’t be undone. What was at the destination, even a whole folder and everything in it, is deleted permanently before the new item takes its place. It isn’t merged, or moved to the Trash or Recycle Bin. Check the card’s overwrite warning before you click Allow.
  • No undo. REAPER’s undo doesn’t reverse file changes. Ask Reagent to move or rename things back, and remove unwanted copies or new folders yourself (Undoing Changes).
  • Items run one at a time. If one fails, for example on a full disk or denied access, the batch stops there and finished items stay changed.
  • Stopping doesn’t roll back. Stopping Reagent halts a batch of moves before the next item. A batch of copies or renames, or a folder copy already under way, may still run to the end.
  • Moves to another drive are two steps. Reagent copies each item, then deletes the original. If you stop one, the item it was working on may end up in both places. If it was overwriting, what was at the destination may already be deleted.