The complete guide to ReaAssist.

https://raw.githubusercontent.com/michaelbriggsaudio/mbriggs-reaper/main/index.xml

Tell me what tracks are in this session and suggest three useful cleanup tasks.

#What ReaAssist Is

ReaAssist is a workflow assistant for REAPER. It helps with the practical work around a session: routing, editing, automation, plugin setup, project organization, script generation, troubleshooting, and REAPER feature questions.

The short version: ask anything, automate everything. ReaAssist sits next to your session and helps with the technical side of production, all from inside the DAW.

ReaAssist can:

• Read useful session metadata such as tracks, items, FX chains, plugin names, routing, tempo, markers, regions, time selection, edit cursor, and selected objects.
• Answer questions about your current REAPER session.
• Generate Lua scripts that run inside REAPER.
• Add, configure, and automate plugins.
• Set up routing, sends, folders, markers, regions, edits, and other project structure.
• Configure known stock and third-party plugin parameters by name when the necessary parameter information is available.
• Generate JSFX only when you explicitly ask for a custom JSFX effect.
• Help diagnose failed or incorrect results when you tell it what happened.

The goal is not to replace your judgment. The goal is to make technical REAPER work faster and less tedious.

#What ReaAssist Is Not

ReaAssist is not a generative creative tool. It does not create audio, music, lyrics, melodies, samples, or finished creative ideas for you. It does not process or upload your audio files. It does not make artistic decisions on your behalf.

It can still help with production-related setup and workflow tasks, such as:

• Setting up virtual instruments or samplers.
• Building routing for recording or mixing.
• Creating plugin chains.
• Explaining REAPER features.
• Advising on workflow, microphone setup, or signal-chain concepts.
• Writing scripts that perform clearly described technical actions.

You remain responsible for the creative direction, for reviewing generated code, and for keeping backups of important projects.

#Who ReaAssist Is For

ReaAssist is built for working REAPER users who want faster access to the technical side of the DAW.

It is useful for:

• Engineers and producers who want to speed up routine session setup, editing, FX chains, and template work.
• Mixers and mastering engineers who want faster routing, gain staging, plugin setup, and REAPER workflow support.
• Power users and scripters who want a session-aware assistant for Lua, JSFX, and the REAPER API.
• Users who know what they want done but do not want to write every script or menu sequence by hand.

It is also useful as a learning aid. You can ask ReaAssist how a generated script works, why a REAPER feature behaves a certain way, or how to approach a routing or editing task.

#Requirements

ReaAssist requires:

• REAPER 7.0 or later.
• ReaImGui extension, installed through ReaPack from the ReaTeam Extensions repository.
• curl, which is built into current Windows, macOS, and Linux systems.
• At least one configured LLM provider, such as Claude, OpenAI/ChatGPT, Gemini, or a local/custom OpenAI-compatible server.

Optional:

• js_ReaScriptAPI, installed through ReaPack. This enables native file dialogs and more accurate window screenshots.

#Installation

#Install with ReaPack

ReaPack is the recommended installation method.

1. Install ReaPack from https://reapack.com if it is not already installed.

2. In REAPER, open Extensions > ReaPack > Import repositories....

3. Paste this repository URL:

   https://raw.githubusercontent.com/michaelbriggsaudio/mbriggs-reaper/main/index.xml
   

4. Open Extensions > ReaPack > Browse packages....

5. Find ReaAssist.

6. Right-click ReaAssist and choose install.

7. Run Script: ReaAssist.lua from REAPER's Action List.

For frequent use, bind ReaAssist to a toolbar button or keyboard shortcut.

#Manual Installation

Manual installation is available if you do not use ReaPack.

1. Download ReaAssist.lua.
2. Download the full Resources/ directory.
3. Put ReaAssist.lua and Resources/ in the same REAPER scripts folder.
4. Load ReaAssist.lua through REAPER's Action List.

The Resources/ folder must stay directly beside ReaAssist.lua. ReaAssist expects that layout when loading its UI, prompts, help text, plugin references, fonts, and support files.

#First Launch

On first launch, ReaAssist shows its intro and setup flow.

1. Review and accept the Terms of Use.
2. Add an API key for at least one supported provider, or configure a custom/local model server.
3. Choose a provider and model.
4. Decide whether to send a session snapshot with each message.
5. Type a request and press Enter or click Send.

You can change provider, model, API keys, and behavior later from Settings.

#Main Window Overview

The main ReaAssist window has three primary areas:

• Chat history: the conversation between you and the assistant.
• Message input: where you type requests and attach files.
• Controls: provider/model selection, options, settings, help, update status, and generated-code actions.

The welcome screen presents starter areas for session work, track and project management, mixing and effects, custom Lua and JSFX, and general REAPER questions. These are entry points, not limits. You can type your own request at any time.

Generated code appears inside the assistant response. When ReaAssist detects runnable Lua code, action buttons appear below the code block. When it detects JSFX code, JSFX-specific save and install actions appear.

#Writing Good Requests

ReaAssist works best when requests are specific about the target, action, and desired result.

Good requests:

• "Build a rock vocal chain on the selected track: high-pass at 80 Hz, 4:1 compression, presence boost at 3 kHz, and a plate reverb send."
• "Add ReaComp to the selected vocal track and set a gentle 3:1 ratio with about 3 dB of gain reduction."
• "Rename every selected item using the track name plus the item start time."
• "Create a marker at each region start and name it after the region."
• "Set up a sidechain compressor on the bass, keyed from the kick track."
• "Write a Lua script that selects muted items on all visible tracks."

Less effective requests:

• "Fix my mix."
• "Make this sound professional."
• "Do something cool."
• "Make this better."

If a result is wrong, tell ReaAssist what happened in concrete terms:

• "It added the plugin to the wrong track."
• "The script ran, but it selected every item instead of only muted items."
• "The parameter names did not match this plugin."
• "It created the JSFX file, but the effect does not appear in the FX Browser."

That feedback helps ReaAssist correct the next attempt.

#Session Awareness

When session awareness is enabled, ReaAssist can include REAPER project metadata in requests so answers and scripts are grounded in the current session.

Depending on the request and settings, context may include:

• Track names, numbers, colors, folders, mute/solo/arm state, and selection.
• Items, takes, selected items, time selection, and edit cursor.
• FX chains and plugin names.
• Routing and sends.
• Tempo, markers, regions, and project-level state.
• Preferred-plugin mappings and cached plugin parameter data.

Session awareness helps ReaAssist understand requests like:

• "Compress the vocal."
• "What FX are on track 3?"
• "Add delay to the selected guitar track."
• "Make markers for each section."

The assistant only knows what ReaAssist sends in text form. It does not listen to your audio, inspect waveform content, or open/upload your .RPP project file.

#Providers and Models

ReaAssist supports Claude, OpenAI/ChatGPT, Gemini, and custom OpenAI-compatible model servers.

Each provider offers different model choices. ReaAssist organizes model selection around practical tiers such as fast, balanced, and smart/full models.

ReaAssist itself is free. You bring your own provider key and pay the selected provider directly for usage, according to that provider's pricing. API keys are stored locally on your machine.

General guidance:

• Use a balanced model for everyday REAPER questions and normal script generation.
• Use a smart/full model for complex multi-step scripts, plugin-heavy work, or unusual requests.
• Use a fast/mini model for quick questions, explanations, and simple edits.
• If a complex task fails, try a stronger model before changing advanced reasoning or thinking controls.

Model availability, pricing, and naming can change over time. Check your provider account for current billing and usage details.

#Local and Custom Models

ReaAssist can use local or self-hosted models through OpenAI-compatible tools such as LM Studio, Ollama, llama.cpp, vLLM, and similar servers.

Local/custom model servers are useful when:

• You want all chat traffic to stay on your machine or local network.
• You need to work offline.
• You are experimenting with local models.
• You want to connect to a private server, proxy, or internal provider.

For best results with local models:

• Use a model strong enough to write correct Lua and follow structured instructions.
• Keep tasks focused.
• Review generated code carefully.
• Expect lower reliability from small local models on complex scripting or plugin-parameter work.
• Use stronger cloud models when correctness matters more than offline operation.

#Privacy and Data

ReaAssist does not upload audio files. It does not send .RPP project files. It does not send API keys to the ReaAssist author.

For normal chat requests, ReaAssist sends text to the provider you choose. That text can include:

• Your typed message.
• Conversation history needed for the current chat.
• Optional project/session metadata.
• Files you explicitly attach, such as images, PDFs, or text files.

All normal chat communication goes between your machine and your selected provider or custom model server.

For fully offline use, configure a local model server. With a local server, chat data stays on your machine or local network, subject to how that server is configured.

#Feedback Reports

ReaAssist includes optional feedback buttons below assistant replies.

Clicking thumbs-up or thumbs-down does not send anything immediately. It opens a preview-and-send dialog.

Inside the dialog, you can:

• Choose thumbs-up or thumbs-down.
• Add issue tags for a thumbs-down report.
• Add an optional text comment.
• Expand the preview to inspect the exact report data that would be sent.
• Expand privacy details.
• Press Send to upload the report, or Cancel to discard it.

Feedback reports can include:

• The current chat session visible in the chat.
• Your rating, tags, and comment.
• App version, REAPER version, OS, provider, and model.
• A diagnostic report with app, REAPER, operating system, and ReaImGui versions, installed extensions, preferences, plugin cache status, recent errors, and recent token/cache/cost details.

Before sending, ReaAssist automatically removes or hides:

• API keys.
• Authorization: headers.
• Bearer tokens.
• Home-directory paths such as C:\Users\<user>.

Review the preview before sending. Chat text may still include project names, track names, plugin names, or other text you typed.

Feedback reports are sent to the ReaAssist project maintainer through https://d.reaassist.app. A random installation ID is generated only on the first successful send so duplicate reports from the same install can be deduplicated. The ID is not linked to your identity.

If a feedback send fails, the dialog remains open and shows the error. ReaAssist does not silently queue, retry, or save the report in the background. If you cancel after a failed send, the data is discarded.

#Running Generated Code

When ReaAssist returns a Lua code block, the app shows code action buttons below the block.

Available actions include:

• Run Code: execute the code inside REAPER.
• Undo: revert the last action with REAPER's undo system.
• Backup: save a timestamped .rpp-bak project backup.
• Copy: copy the code to the clipboard.
• Save: save the code as a .lua file that can be added to the Action List.
• Edit: switch the generated code into editable mode before running or saving.

Executed code is wrapped in a REAPER undo block, so normal REAPER undo can revert many actions. You should still keep backups, especially before running code that edits many tracks, items, plugins, files, or project settings.

#Safety Scanner

Before running generated code, ReaAssist scans for potentially dangerous Lua patterns.

The safety scanner looks for operations such as:

• File deletion or renaming through os.remove or os.rename.
• Shell execution through os.execute or io.popen.
• File writes through io.open in write or append mode.
• Loading external code through require, dofile, loadfile, loadstring, or load.
• Debug-library access.

When the scanner finds risky patterns, ReaAssist replaces the normal Run button with a Review Before Running confirmation. The modal lists the detected risks. You must explicitly accept before the code can run.

Auto-run is blocked when the safety scanner requires review.

This scanner is a hard gate, not a guarantee that code is harmless. Always skim generated code before running it.

#Auto-Run and Backups

The main screen includes options for execution behavior.

Auto-run code:

• Runs returned code automatically when ReaAssist determines it is eligible.
• Should be used carefully.
• Is blocked by safety scanner findings and other validation gates.

Auto-backup:

• Saves a project backup before running code.
• Is recommended when using auto-run or running broad edit scripts.

Show details:

• Shows provider/model details, token counts, prompt-cache hits, estimated cost, and session totals.
• Cost estimates are approximate.

#JSFX Creation

JSFX generation is opt-in.

ReaAssist creates JSFX only when you explicitly ask for a custom JSFX effect, such as:

• "Write a JSFX stereo widener."
• "Create a custom delay JSFX and add it to track 1."
• "Make a JSFX utility that swaps left and right channels."

Generic effect requests do not automatically become JSFX. For example, "add a reverb" or "I need a delay" routes through stock or preferred plugin workflows unless you explicitly request a custom JSFX.

JSFX actions can include:

• Copy JSFX code.
• Save the JSFX file.
• Add To Selected Track(s), which saves the JSFX and inserts it on selected tracks.
• A companion Lua script when needed to install the generated JSFX on a target track.

Generated JSFX files are saved under REAPER's Effects/ReaAssist/ folder with unique names. ReaAssist avoids overwriting existing files.

If a new JSFX does not appear in the FX Browser immediately, rescan REAPER's effects or restart REAPER.

#File Attachments

Use the + button below the prompt to attach files.

Attachment options include:

• Attach File: choose an image, PDF, or text file.
• Screenshot: capture the REAPER window as an image attachment.
• Paste Image: attach an image from the clipboard.
• Drag and drop: drop files onto the ReaAssist window.

Supported formats include:

• PNG
• JPG
• GIF
• WebP
• PDF
• Text files

ReaAssist supports up to 10 attachments per message.

Use attachments when the assistant needs to inspect:

• A screenshot of an error.
• A plugin window or settings page.
• A routing diagram.
• Notes or a text file.
• A PDF that you want summarized or interpreted.

Attached files are sent to the selected provider or custom model server as part of the request.

#Preferred Plugins

Preferred Plugins let you choose which plugin ReaAssist should use for generic effect types.

For example:

• EQ -> your preferred EQ.
• Compressor -> your preferred compressor.
• Reverb -> your preferred reverb.
• Delay -> your preferred delay.

After configuration, a request such as "add an EQ to the vocal" can use your chosen EQ instead of asking every time.

Preferred Plugins supports:

• Autocomplete from installed plugin names.
• Arrow-key navigation in the match list.
• Enter or click to select.
• Tab and Shift+Tab to move between type and plugin fields.
• Comma-separated aliases for a type, such as EQ, equalizer, tone.
• Per-row rescan.
• Rescan All.
• Clear All with confirmation.

When you save a preferred plugin, ReaAssist scans parameter information for uncached plugins so future parameter changes can be more precise.

Preferred-plugin mappings and cached parameter data live together in FX_Cache.json in the script folder. Back up that file if you want to preserve your setup across machines or manual reinstalls.

#Plugin Resolve Prompts

When a request needs a generic plugin type and no preferred plugin is configured, ReaAssist shows a resolve prompt titled Choose a plugin to use....

From that prompt, you can:

• Type a plugin name and choose from autocomplete results.
• Use a stock fallback plugin when available.
• Install ReEQ instantly for EQ requests.
• Cancel if no fallback is available.

Using a plugin from the resolve prompt can save it as your preference for that type, so ReaAssist does not need to ask again.

#Stock Fallbacks

All fallback plugins ship with a stock REAPER install. JSFX fallback entries use source files from REAPER's Effects/ folder.

#FX Parameter Cache

The FX Parameter Cache stores scanned plugin parameter data.

Cached parameter data helps ReaAssist:

• Set plugin parameters by name.
• Avoid repeated plugin scans.
• Generate more reliable plugin-configuration scripts.
• Work faster on repeated requests involving the same plugins.

The cache page shows cached plugins and actions for each row:

• Rescan: quickly re-scan a plugin's parameters.
• Deep: run a slower scan for plugins that report parameter values late.
• Remove: drop that plugin from the cache.

Use Deep scan when a normal scan returns unclear values, which can happen with some VST3 plugins.

The cache page also includes Clear All. This clears parameter data but does not remove preferred-plugin mappings.

#On-Demand Context

ReaAssist can request additional context mid-conversation when needed. This can happen even when Send session snapshot is off.

Available on-demand context includes:

• Project snapshots.
• REAPER API reference sections.
• MIDI reference notes.
• Theme and UI reference notes.
• Plugin guidance.
• Preferred-plugin settings.
• FX search results.
• FX chain listings.
• Live parameter scans for installed plugins.

This lets ReaAssist keep normal requests lighter while still pulling more detail for code generation, plugin work, MIDI edits, routing, or other tasks that need extra context.

#Prompt Caching and Cost

Supported providers can cache repeated request content between turns. This can reduce cost during longer conversations because the same background instructions and reference material do not always need to be billed at full price again.

With Show details enabled, ReaAssist displays:

• Model name.
• Token counts.
• Cache hits.
• Estimated cost for the exchange.
• Running session total.

Cost estimates are approximate and may differ from your provider's final billing. Provider pricing and cache behavior can change.

#Settings Reference

Settings includes:

• API Keys: add, update, or remove provider keys.
• Provider and model selection.
• Custom provider configuration.
• Theme selection.
• UI scale selection.
• Send session snapshot.
• Always include REAPER API reference.
• Check for updates.
• Preferred Plugins.
• FX Param Cache.
• Reset Window Size.
• Factory Reset.

Factory Reset clears keys, preferences, settings, theme, scale, and window geometry. Use it only when you want to return ReaAssist to a fresh state.

#Theme, Scale, and Window Recovery

ReaAssist includes:

• Auto theme.
• Dark theme.
• Light theme.

Auto theme follows the operating system's light/dark appearance when supported.

UI Scale options:

• 75%
• 85%
• 100%
• 125%
• 150%
• 200%

When changing scale, ReaAssist shows a confirmation popup with a 10-second countdown. Choose Keep Scale to confirm or Revert Now to undo. If you do nothing, the scale reverts automatically. This prevents the UI from getting stuck at an unusable size.

The window is clamped to the monitor work area, including multi-monitor setups.

If the UI becomes unreachable, hold Shift while launching ReaAssist. Shift-launch recovery resets:

• UI scale to 100%.
• Theme to Auto.
• Saved window geometry.

Shift-launch recovery requires js_ReaScriptAPI.

#Updates and Repair

ReaAssist can check for updates and repair missing or mismatched installed files.

The update system checks installed files against the official release file list. It can:

• Check for a newer version.
• Compare local files against the expected release checksums.
• Download missing or outdated files.
• Clean up files that were removed from the package.
• Relaunch ReaAssist after update or repair when needed.

You can enable automatic update checks on startup. You can also run a manual check from Settings or the footer update control when available.

If repair fails because a file is locked or unavailable, close REAPER, reopen it, and try again. If the problem persists, reinstall ReaAssist through ReaPack.

#Keyboard Shortcuts

#Prompt Examples

#General Session Questions

• "What information do you have about my current REAPER session?"
• "What FX are on the selected track?"
• "Which tracks are armed?"
• "Summarize my routing."
• "What changed in this session since the last request?"

#Editing

• "Split selected items at the edit cursor."
• "Fade in the first item on each selected track."
• "Select all muted items."
• "Move selected items 10 ms earlier."
• "Create crossfades between overlapping selected items."

#Track and Project Management

• "Create a folder track for the selected drum tracks."
• "Color all vocal tracks blue."
• "Rename selected tracks using their first item name."
• "Create markers at every region start."
• "Set the project tempo to 120 BPM."

#Mixing and Effects

• "Build a rock vocal chain on the selected track: high-pass at 80 Hz, 4:1 comp, presence boost at 3 kHz, plate verb send."
• "Add a compressor to the selected vocal track."
• "Add a quarter-note delay to the selected guitar track."
• "Set up a sidechain compressor on the bass from the kick."
• "Add an EQ to every selected track."
• "Create a parallel reverb send for the selected tracks."
• "Make my drum bus compressor pump harder by lowering the threshold 2 dB and using a faster attack."

#Plugin Configuration

• "Set Pro-Q 4 on the vocal to cut 250 Hz by 3 dB."
• "Set the Pro-Q 4 high shelf to +3 dB at 8 kHz on the vocal."
• "Add ReaComp to the bass with a 4:1 ratio and medium attack."
• "Set the limiter ceiling to -1 dB."
• "Make the selected track's delay wetter."
• "List every track using Pro-Q 4 and tell me which ones are bypassed."

#Lua Scripting

• "Write a Lua script that selects items shorter than 100 ms."
• "Write a script that creates a marker every 8 bars."
• "Write a script that disables all bypassed FX on selected tracks."
• "Write a script that exports selected track names to a text file."
• "Write a Lua script that prefixes every folder track's name with [BUS]."

Review scripts before running, especially scripts that write files or make broad project changes.

#JSFX

• "Create a JSFX stereo widener and add it to selected tracks."
• "Write a JSFX utility that swaps left and right channels."
• "Create a simple JSFX gain trim with input and output meters."
• "Make a JSFX delay with tempo sync and feedback."

Ask explicitly for JSFX when you want custom DSP code.

#Troubleshooting

#Code buttons do not appear

Make sure ReaImGui is installed and up to date through ReaPack.

#ReaAssist will not launch

Check that:

• REAPER is version 7.0 or later.
• ReaImGui is installed.
• Resources/ is directly beside ReaAssist.lua.
• The install was not partially copied or interrupted.

If installed through ReaPack, try reinstalling or synchronizing packages.

#API key errors

Open Settings and verify:

• The key is pasted correctly.
• The correct provider is selected.
• Billing or account access is active with the provider.
• The chosen model is available to your account.

#Local model server errors

Check that:

• The local server is running.
• The base URL is correct.
• The local server uses an OpenAI-compatible chat API.
• The selected model name matches what the server exposes.
• Firewall or network settings are not blocking localhost access.

#Gemini free tier limits

The Gemini free tier may reject large requests or hit lower rate limits. Enable billing on the Google account for full access, or use a smaller request/model when appropriate.

#Screenshots do not work

Install js_ReaScriptAPI through ReaPack for accurate window capture.

#JSFX does not appear in the FX Browser

Try:

• Restarting REAPER.
• Rescanning effects.
• Checking REAPER's Effects/ReaAssist/ folder.
• Confirming the JSFX was saved successfully.

#UI is too large or off-screen

Hold Shift while launching ReaAssist to reset UI scale, theme, and saved window geometry. This requires js_ReaScriptAPI.

#Plugin parameters are wrong

Try:

• Rescanning the plugin in FX Param Cache.
• Using Deep scan for plugins that report delayed values.
• Rewording the request with exact parameter names visible in the plugin.
• Choosing a stronger model for complex plugin work.

#Generated code did the wrong thing

Use Undo if possible. Then tell ReaAssist exactly what happened and what should have happened. Include track numbers, item names, plugin names, or screenshots when useful.

#Support and Contact

For ReaAssist questions, bug reports, suggestions, and plugin feedback, use:

[email protected]

For audio work inquiries, including production, mixing, recording, or mastering, use:

[email protected]

When reporting a ReaAssist issue, include:

• ReaAssist version.
• REAPER version.
• Operating system.
• Provider and model.
• What you asked ReaAssist to do.
• What happened instead.
• Screenshots or copied error text when available.

Do not send API keys, private project files, or audio files unless explicitly requested and appropriate.

#Limitations

ReaAssist has important limitations:

• It cannot hear or analyze audio unless you provide relevant text or supported attachments.
• It does not upload audio files.
• It does not inspect .RPP project files as project documents.
• Generated code can be wrong.
• Plugin parameter names and values can vary by plugin version and format.
• Smaller local models may be less reliable than stronger cloud models for complex scripting.
• Safety scanning reduces risk but cannot prove code is safe.
• Cost estimates are approximate.

Use backups and review generated code before running it.

#Disclaimer and Terms of Use

ReaAssist is provided as-is. Review generated code before running it. Keep project backups. Follow your provider's terms, pricing, and usage policies.

You are responsible for deciding whether generated scripts, plugin changes, routing changes, or project edits are appropriate for your session.

#Author and License

ReaAssist is created by Michael Briggs, an audio engineer and producer based in Denton, Texas.

• Production, mixing, and recording: https://michaelbriggs.audio
• Mastering: https://michaelbriggsmastering.com

See LICENSE.txt for license terms. In summary, ReaAssist may be downloaded, installed, and used through official distribution channels authorized by Michael Briggs. Redistribution, resale, sublicensing, repackaging, or presenting modified or unmodified copies as your own requires prior written permission.

ReaAssist bundles ReEQ under Resources/ReEQ/. ReEQ is distributed under its own MIT license; see Resources/ReEQ/LICENSE.txt.