Skip to main content
Reagent writes a ReaScript (a Lua script that controls REAPER) when its REAPER tools don’t cover a job, such as FX parameters, routing, track settings, automation and envelopes.

Before You Start

You need REAPER open with the Bridge running and the SWS extension installed. If REAPER wasn’t connected when you sent a message, connect it and send the message again. The Run script and Save to REAPER Actions buttons need the connection too.

How It Works

Runs it now. When you describe a change that no built-in tool covers, Reagent runs a script. It asks for your approval first, unless you use Full access.
Drafts it for review. When you ask to see, review or draft a script, Reagent shows a Create script block with the code. Nothing runs until you click Run script.
Checks your scripts first. Before Reagent drafts a new script, it searches your REAPER Scripts folder, ReaPack scripts included, and reads the code of the ones that look similar. If one already does the job, Reagent offers it instead, and can run it if it’s in REAPER’s action list. If one does part of the job, Reagent asks whether to add the rest to it or write a new script. The search appears in the reply as a row such as 2 similar scripts.

Approval and Undo

In Default permissions and Auto-review, the Run script approval card shows the script’s description, not its code. To read the code first, open the summary line above the card and click Show code. The block reads Running… while it waits for you, but nothing has run yet.
Approve with Allow on the card. The play button on the block runs the script straight away, outside the card, and Allow would then run it again.
Whether Reagent ran a script or you clicked Run script, REAPER records all its changes as one undo point, named after the script’s description.
If a script stops with an error partway through, the changes it made before the error can still be in your project. Check the project before you continue.

The Script Block

Scripts appear inside the reply’s summary line, such as Created a script, Ran a script or Ran 3 tools. A Run script block with a Success result, the Hide code toggle, syntax-highlighted Lua code, and the Run, Copy and Save buttons in the top-right corner of the code Each block shows Create script for a draft or Run script for a script Reagent ran, then a description and a Show code toggle. A script Reagent ran also shows Running…, then Success, Failed or Cancelled. What the script printed, or its error, appears below the code. Three buttons sit at the top right of the code: To change a draft, ask Reagent to revise it or copy the code. Before you edit a saved file yourself, see Change an Existing Script.

Save as a REAPER Action

To make a saved action one undo point, ask Reagent to add an undo block (reaper.Undo_BeginBlock and reaper.Undo_EndBlock) before you save it. Reagent normally leaves undo code out of the scripts it runs.
1

Click Save to REAPER Actions

A form opens with a name from the script’s description, such as Reagent: Toggle SFX Mutes. Edit it if you like, then click Save or press Enter. Cancel or Esc closes it without saving.The Save as REAPER Action form with the name "Reagent: Split selected item at cursor position" filled in, and Save and Cancel buttons
2

Assign a shortcut (optional)

Reagent saves a .lua file and adds it to the Main section of REAPER’s action list. REAPER then opens its shortcut dialog, so switch to REAPER if you don’t see it. Assign a key, or close the dialog to skip. Back in Reagent, the form shows the action’s name, such as Script: reagent_toggle_sfx_mutes, with a copy button.
Reagent saves the file in the reagent folder next to the Bridge, inside the Scripts folder that REAPER path shows in Settings > Connectors. The file is named after the action in lowercase with underscores, starting with reagent_, such as reagent_toggle_sfx_mutes.lua. If that name exists, Reagent adds a timestamp to the new file’s name instead of replacing the old file. To find the action later, search the action list for the file name.

Change an Existing Script

Reagent can search and read the scripts in your REAPER Scripts folder. Name or describe one:
Reagent normally looks for the script first and reads it. You can also paste code and ask Reagent to explain or change it. Reagent changes a script in place only if it’s a .lua file in the reagent folder of your Scripts folder, where Reagent saves scripts (see Save as a REAPER Action). The draft then reads Change script and is linked to that file. For a script anywhere else, such as a ReaPack script or one of your own in another folder, Reagent drafts a changed copy. Saving it adds a new script and action, and the original stays as it was, so a ReaPack update can’t undo your change and the original keeps working. A linked block shows the file’s path above the code. A block you save stays linked for the rest of the chat. Before you save, hover over the save button and check its name:
  • Save changes: the block is linked. It overwrites the file straight away, with no form or shortcut dialog. If the file no longer exists, it saves a new file and action.
  • Save to REAPER Actions: the block isn’t linked, and saving creates a new file.
Save changes replaces the whole file with the code in the block. If you’ve edited the file outside Reagent since, those edits are overwritten.
Saving over the original doesn’t add it to the action list. If it wasn’t an action before, add it in REAPER with Actions > Show action list… > New action… > Load ReaScript…, then pick the file.

Scripts, REAPER Preferences and Themes

Reagent changes the REAPER preferences on its list, and REAPER’s theme, with its own settings tool, which records each change so you can revert it, not with a script. If a script Reagent runs sets one of those preferences, for example with set_config_var_string or an SWS setter, or changes the theme with OpenColorThemeFile, SetThemeColor or ThemeLayout_SetParameter, Reagent stops the script before it reaches REAPER, and the error tells it to use that tool instead. The chat shows Preferences and themes change through REAPER settings — script not run. The check reads the script as written, so it can miss a script that makes these changes less directly, for example one that builds a function’s or a preference’s name while it runs, or calls a preference setter through pcall. Scripts can still set any other preference, and scripts you run yourself with the play button aren’t checked. See REAPER Preferences and REAPER Themes.

Reagent vs. the Action List

If a script works in Reagent but not as a saved action, or the other way round, check:
  • Lua functions. From Reagent, require, dofile, setmetatable and coroutine aren’t available, and only a few io and os functions are. As a saved action, a script gets everything REAPER normally gives a Lua script.
  • print() output. From Reagent, it appears below the code when the script finishes without an error. As a saved action, Reagent doesn’t show it.

Ask About the REAPER API

Ask Reagent which REAPER API functions do a job, or what a function’s parameters are:
Reagent answers API questions, and can check before it writes a script, by searching REAPER’s ReaScript documentation by exact function name or description, such as “get item fade length”. It gets back each function’s signature, parameters and return values. The search doesn’t guarantee a working script. It covers REAPER’s own API only, not extensions such as SWS. It’s a fixed copy of the documentation that doesn’t know your REAPER version. The search runs on reaperagent.com and sends the search text Reagent writes and search settings. It doesn’t include your project file or your script’s code. Reagent’s search service shares the search text with Voyage AI to find matching functions, as listed on the subprocessors page. See Documentation Searches.

Example Workflows

Prompts for common REAPER tasks.

Privacy & Security

What Reagent sends to which services, and what scripts can reach on your computer.