The complete guide to ReaAssist.

#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 about your session and automate the technical work. 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 upload your audio files or process them through an AI audio model. Generated REAPER scripts can still edit item properties, fades, pitch, routing, FX, and other project settings when you ask for that. ReaAssist 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.

#Prompt Examples

The most useful ReaAssist prompts usually combine a target, a desired action, and the kind of report or cleanup you want afterward.

#Session Review

• "Audit this session for cleanup issues: armed tracks, muted tracks, hidden tracks, empty tracks, bypassed FX, and unusual routing. Give me a short checklist before writing code."
• "Compare the selected tracks' FX chains, sends, colors, and folder placement, then suggest what should be standardized."
• "Find every selected track that routes to more than one destination and explain the signal flow."
• "Look at the selected vocal tracks and tell me which ones have missing compression, EQ, tuning, or reverb sends based on their FX chains."

#Editing and Analysis

• "Select the item under my mouse cursor, move the edit cursor to its start, and report its track, take name, start time, and length."
• "Find selected audio items that peak above -1 dBFS, color them red, and copy a peak/LUFS report to the clipboard."
• "Pitch-shift the selected melodic audio items up 2 semitones, leave drum tracks unchanged, and report which items were edited."
• "Create 5 ms fades on selected items that do not already have fades, then tell me how many items were changed."
• "Analyze the selected audio items and make a table with item name, track name, peak level, peak position, and integrated LUFS."

#Track and Routing Automation

• "Create a drum bus from the selected drum tracks, route them to it, color it, name it, and preserve any existing sends."
• "Build a stem-print setup for the selected tracks: create matching print tracks, route each source to its print track, name them clearly, and leave the originals muted."
• "Add subtitles to the current markers and regions using their names, then refresh the SWS notes window."
• "Add track notes to the selected tracks summarizing each track's role, routing, and FX chain."

#Mixing and Effects

• "Build a parallel drum crush return for the selected drum tracks with ReaComp, route the tracks to it, and label/color the return."
• "Set up sidechain compression on the bass from the kick, including the send and the ReaComp detector input settings."
• "Create a shared plate reverb return for the selected vocal tracks, add sends at -18 dB, and name/color the return."
• "Find tracks that have a limiter or clipper in the FX chain and make a report of where they are, including bypass/offline state."

#Plugin Configuration

• "On all selected vocal tracks, find Pro-Q 4 or ReaEQ and add a gentle high-pass around 80 Hz without changing existing bands."
• "Normalize ReaComp settings across the selected backing vocal tracks: 3:1 ratio, 10 ms attack, 100 ms release, and auto makeup off."
• "List every track using Pro-Q 4 or ReaEQ, include whether each instance is bypassed or offline, and copy the report to the clipboard."
• "For selected guitar tracks, create a quarter-note delay return, send the tracks to it, and leave the existing insert FX alone."

#MIDI

• "In the active MIDI take, find overlapping notes, shorten or remove the duplicates safely, and report how many overlaps were fixed."
• "For selected MIDI items, humanize selected notes by up to 8 ticks and 6 velocity steps while preserving note lengths."
• "Transpose the selected MIDI items from C major to D major, update any marker or region names that mention the old key, and report how many notes were changed."
• "Set all selected notes in the active MIDI take to velocity 96, keep their timing unchanged, and report the note count."
• "Create a MIDI cleanup script for selected takes: remove muted notes, delete notes shorter than 1/128, and sort the events afterward."

#Lua Scripting

• "Write a Lua script that exports selected item metadata to the clipboard: track name, item name, GUID, start time, length, peak level, and LUFS if available."
• "Write a script that saves the current selected items by GUID so I can restore that same selection later after editing the project."
• "Write a script that lists the selected FX in the focused FX-chain window and copies their names and indexes to the clipboard."
• "Write a script that creates a mix prep report from selected tracks: color, folder depth, sends, receives, FX chain, mute/solo state, and SWS track notes."

Review scripts before running, especially scripts that write files or make broad project changes. For routing, pitch, batch edit, or cleanup scripts, save the project or make a backup first.

#JSFX

• "Create a JSFX stereo utility with width, balance, mono, mid/side solo, mono-safe bass below 120 Hz, and output trim."
• "Create a JSFX gain trim with input/output meters, phase invert, clip indicator, and a simple output ceiling."
• "Make a tempo-synced tremolo JSFX with selectable wave shape, stereo phase offset, smoothing, depth, and output level."

Ask explicitly for JSFX when you want custom DSP code.

#Requirements

ReaAssist requires:

• REAPER 7.0 or later.
• ReaImGui extension. ReaAssist auto-installs the pinned version on first launch if it is not already present, or you can install it through ReaPack from the ReaTeam Extensions repository.
• SWS Extension. ReaAssist auto-installs the pinned version on first launch if it is not already present, or if the installed version is older than the supported floor.
• OSARA for Screen Reader Mode. Install OSARA with REAPER closed, then reopen REAPER before running Screen Reader Mode. If OSARA is missing, the Screen Reader Mode action shows native setup instructions and opens the official OSARA download page.
• curl, which is built into current Windows, macOS, and Linux systems.
• At least one configured LLM provider, such as Claude, ChatGPT, Gemini, DeepSeek, or a local/custom OpenAI-compatible server.

Optional:

• js_ReaScriptAPI extension. ReaAssist auto-installs the pinned version on first launch on Windows, macOS, and Linux x86_64, alongside the required extensions. Enables native file dialogs and more accurate window screenshots. On platforms without an upstream binary (legacy macOS, Linux ARM, Linux x86), ReaAssist runs without it and uses non-native fallbacks.

#Installation

There are two supported install paths. Both end up with the same files in the same place; pick whichever is easier for you.

#Direct Download

This is the recommended path if you do not already use ReaPack. The installer script downloads ReaAssist, registers it as a permanent REAPER action, and handles the rest, including dependency setup.

1. Download ReaAssist_Installer.lua to your computer. Any location is fine, like your Downloads folder or Desktop.

   Screen reader users should install OSARA first with REAPER closed, then download ReaAssist_Installer_Screen_Reader_Mode.lua.

2. In REAPER, open Actions > Show Action List.

3. Click the New Action button and select Load ReaScript.

4. Find the downloaded installer file and open it.

5. Click Run. That's it, the installer takes care of the rest.

On first launch ReaAssist fetches its supporting files automatically (about 5 MB). If required extensions are missing or out of date, ReaAssist offers to install the pinned versions directly from their upstream releases. Restart REAPER once when prompted, then re-run ReaAssist from the Action List.

The installer file itself can be deleted after step 5; ReaAssist updates itself automatically on subsequent launches.

#Install with ReaPack

If you already use ReaPack for other REAPER scripts and extensions, you can install ReaAssist through it.

1. Install ReaPack 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 ReaAssist.lua from REAPER's Action List.

   Screen reader users should install OSARA first with REAPER closed, then choose ReaAssist_Screen_Reader_Mode.lua from the Actions list.

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

#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.

#Screen Reader Mode

Screen Reader Mode is a dedicated ReaAssist action built to help blind and visually impaired users work with ReaAssist through OSARA and a keyboard-first, screen-reader-friendly workflow. It uses the same ReaAssist engine, providers, settings, privacy rules, generated-code safety checks, and update system as the visual ReaAssist window, but presents the workflow through accessible controls and spoken status updates instead of the main visual chat interface.

Screen Reader Mode is meant for real daily use, not only emergency recovery. You can enter prompts, choose providers and models, configure API keys, manage custom providers, use custom instructions, attach files or screenshots, review responses, read or save generated code, run safe generated actions, undo recent runs, report issues, and open Help without needing the visual ReaAssist UI.

#Requirements for Screen Reader Mode

Screen Reader Mode requires OSARA, the REAPER accessibility extension. Install OSARA with REAPER closed, then reopen REAPER before launching Screen Reader Mode.

If OSARA is missing, the Screen Reader Mode action shows native setup instructions and opens the official OSARA download page. Install OSARA, restart REAPER, then run Screen Reader Mode again.

Screen Reader Mode also uses the same required ReaAssist dependencies as the main window: REAPER 7.0 or later, ReaImGui, SWS Extension, and at least one configured provider key or local/custom OpenAI-compatible provider. ReaAssist installs or repairs its required dependencies during startup when possible.

#Opening Screen Reader Mode

For a new direct-download install:

1. Close REAPER and install OSARA.
2. Download ReaAssist_Installer_Screen_Reader_Mode.lua.
3. In REAPER, open Actions > Show Action List.
4. Click New Action, choose Load ReaScript, and load the downloaded installer.
5. Click Run.

The Screen Reader Mode installer downloads ReaAssist, registers both the ReaAssist visual-mode action and the Screen Reader Mode action, sets Screen Reader Mode as the default ReaAssist launch mode, and opens Screen Reader Mode.

For a ReaPack install or an existing ReaAssist install:

1. Close REAPER and install OSARA if it is not already installed.
2. Install or update ReaAssist through ReaPack.
3. Open Actions > Show Action List.
4. Search for ReaAssist_Screen_Reader_Mode.lua.
5. Run the Screen Reader Mode action.

For frequent use, bind the Screen Reader Mode action to a REAPER keyboard shortcut or toolbar button from the Action List. The direct-download Screen Reader Mode installer already enables Always open ReaAssist in Screen Reader Mode. If you installed another way and want the visual-mode ReaAssist.lua action to open Screen Reader Mode by default, open Screen Reader Mode settings and enable Always open ReaAssist in Screen Reader Mode. To go back to the visual interface as the default, use the Screen Reader Mode settings option that opens the visual interface, or turn off Always open ReaAssist in Screen Reader Mode.

#First Launch in Screen Reader Mode

On first launch, accept the Terms of Use, then configure an API key or custom provider. The main Screen Reader Mode window includes:

• Prompt field.
• Provider, model, and thinking controls.
• Prompt & Chat tools.
• Example prompts.
• Attachments.
• Auto-run generated actions.
• Auto-backup session.
• Settings.
• Help.
• Report Issue.
• Credits, Donate, and Close.

Use Tab and Shift+Tab to move through controls. Most controls include short spoken descriptions. If the focus hints feel repetitive, open Settings and enable concise focus hints.

#Sending Prompts

For a short prompt, use the main Prompt field or press F2 for the New Prompt dialog. F5 sends from the main screen, Prompt & Chat screen, or Attachments screen when a prompt is ready.

For longer or multiline prompts, open Prompt & Chat. That screen lets you paste a prompt from the clipboard, append clipboard text, clear the prompt, copy or save the prompt, and open a draft file in your system text editor. After editing the draft file, load it back into ReaAssist and send when ready.

Example Prompts opens starter prompts similar to the visual welcome cards. Choosing one loads it as the current prompt so you can edit it or send it.

#Attachments

Open Attachments to queue files or images for the next request. You can:

• Copy a file path in Explorer, Finder, or your file manager, then choose Add File Path.
• Choose Add Clipboard Image when an image is available on the clipboard.
• Choose Add Screenshot when screenshot capture is available.
• Remove the last attachment or clear the attachment queue.

Attachments are sent with the next request only. ReaAssist does not upload audio files or .RPP project files.

#Reading Responses and Running Code

When a response arrives, Screen Reader Mode announces it and opens a response screen with the available actions first. Use the on-screen controls or the shortcut keys below.

If the response contains plain text, use Read Full Response, Speak Response, Copy Chat, or Save Chat when available.

If the response contains generated Lua, JSFX, or a structured edit, review the summary and code or edit details before running it. Screen Reader Mode exposes the same safety model as the visual ReaAssist window:

• Lua can be read, copied, saved, added to REAPER's Actions list, or run in REAPER.
• JSFX can be read, copied, saved, or added to selected tracks when the JSFX action is available.
• Structured edits can be reviewed and run after ReaAssist validates them.
• Risky actions may require a confirmation screen before they run.
• Undo is available after a generated run or structured edit when REAPER can undo it.

Auto-run can run validated generated actions automatically when enabled. Auto-backup can save a project backup before an auto-run change. For important sessions, keep Auto-backup enabled and save the project before broad edits.

#Settings and Tools

Screen Reader Mode settings include provider and model preferences, API keys, local/custom providers, custom instructions, preferred plugin mappings, FX parameter cache tools, language, text size, contrast, concise focus hints, automatic diagnostics, update checks, and reset options.

Use API Keys to add, test, or clear provider keys. Use Custom Providers for local or self-hosted OpenAI-compatible endpoints. Use Custom Instructions for durable workflow preferences. Use Preferred Plugins and FX Cache when you want ReaAssist to understand the plugins you prefer and the parameter data available for them.

#Help, Reports, and Recovery

Press F1 or choose Help for the compact in-app Screen Reader Mode help page. Use Read Online Manual from Help to open this manual in your browser.

Use Report Issue for bugs that need maintainer attention. The accessible report screen lets you paste or load a description, add contact information if you want a reply, copy or save the redacted preview, and send the report only after reviewing it. Manual reports are not sent until you choose Send.

If Screen Reader Mode traps focus or you need to close it quickly, press F4, Ctrl+Q, Alt+F4 on Windows, Escape twice, or tab to Close. If the visual ReaAssist window is ever opened accidentally, Ctrl+Q closes it.

#Screen Reader Mode Shortcuts

These shortcuts work while the Screen Reader Mode window has focus. Some screen readers may reserve function keys or modifier combinations; if a shortcut is intercepted, tab to the matching on-screen control.

#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 include four pieces: the target, the action, any constraints, and the report or confirmation you want afterward.

Good requests:

• "On the selected vocal tracks, add or update a high-pass EQ around 80 Hz, leave existing EQ bands alone, and tell me which tracks were changed."
• "Create a drum bus for the selected drum tracks, preserve their existing sends, color the bus red, and summarize the new routing."
• "For selected MIDI items, transpose from C minor to D minor, keep drum tracks unchanged, and report how many notes were edited."
• "Find selected audio items that peak above -1 dBFS, color them red, and copy a peak/LUFS report to the clipboard."

Less effective requests:

• "Fix my mix."
• "Make this sound professional."
• "Do something cool."
• "Make this better."
• "Change the song key."

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.

#Custom Instructions

Custom Instructions let you save stable preferences that ReaAssist should consider with every request. Use them for repeatable workflow habits, default safety rules, naming conventions, preferred plugins, or project standards you otherwise find yourself typing over and over.

You can open Custom Instructions from Settings > Custom Instructions or from the main window Options menu. The page has an enable switch, a text editor, character and approximate token counts, and example instruction cards you can copy or adapt.

Good Custom Instructions are specific and durable:

• "Work only on selected tracks or items unless I say to edit the whole project."
• "Ask before deleting tracks, items, takes, automation, or files."
• "Preserve existing routing, sends, and receives unless I ask to rebuild them."
• "For broad edits, summarize the plan before generating code."
• "Keep originals intact when rendering, freezing, gluing, or committing edits."

Avoid putting one-off task details in Custom Instructions. For example, the key of the current song, a temporary track name, or a single mix note usually belongs in the current chat request instead. Custom Instructions are best for preferences that should still be true next week.

When enabled, Custom Instructions are sent to your selected provider with each request. Keep them concise: longer instructions add tokens, can increase cost, and can compete with the current request for attention. ReaAssist stores the text locally with your other app data.

#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 hear, understand, or judge audio content, and it does not open or upload your .RPP project file. Generated scripts can still use REAPER and supported extensions to read project metadata or run measurements such as peak, RMS, and LUFS on selected items.

#Providers and Models

ReaAssist supports Claude, ChatGPT, Gemini, DeepSeek, 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.

#Quick model guide

These are the current recommendations. Model availability and naming can change, so the in-app model picker is the source of truth if this page ever differs from what you see in ReaAssist.

The model and thinking dropdowns mark each provider's recommended row with a * on the left. Hover any row to see what that combination is best for. The same explainer briefly appears as a muted line below the chips after you change the selection. These recommendations come from internal benchmarks of multi-step REAPER scripting tasks; they favor latency and reliability for everyday work, so for most prompts a strong base model with no extra thinking outperforms a smaller model running deeper thinking.

Check your provider account for current billing and usage details.

#Getting an API Key

An API key is a private token that proves a request is paid for by your account. ReaAssist uses it to talk to the provider directly from your machine; the key is stored locally and is never sent to the ReaAssist author. You need at least one provider key — or a configured local model — before ReaAssist can answer anything.

ReaAssist stores provider and custom-endpoint keys in REAPER's persistent settings using reversible XOR obfuscation tied to the REAPER install path. This is not encryption and not storage in Windows Credential Manager, macOS Keychain, or a Linux Secret Service vault. The path binding prevents casual copying to another install, but a person or process that can read your REAPER settings and the ReaAssist source can recover the keys. Protect access to your computer and REAPER configuration accordingly; clear saved keys from ReaAssist before sharing a portable install or configuration backup.

Sign in to the provider with your normal account, then open its API key page:

• Anthropic (Claude): https://console.anthropic.com/settings/keys

  Click Create Key, name it, and copy the value.

• ChatGPT: https://platform.openai.com/api-keys

  Click Create new secret key, name it, and copy the value.

• Google (Gemini): https://aistudio.google.com/apikey

  Click Create API key and copy the value.

• DeepSeek: https://platform.deepseek.com/api_keys

  Create a new API key and copy the value.

Each provider only shows the full key once at creation time, so copy it before closing the dialog. If you lose it, create a new one.

To use it in ReaAssist:

1. Open Settings and go to API Keys.
2. Paste the key into the row for the matching provider.
3. Save, then pick that provider and a model in the main window.

Most providers require a paid account or prepaid credit before keys will work. If requests come back unauthorized or quota-exceeded, check the provider's billing page.

#ChatGPT API Complimentary Token Option

Last checked: 2026-07-10.

Eligible users may be able to use ReaAssist's ChatGPT/OpenAI option at very low cost, or effectively free for typical daily use, by opting into OpenAI's API input/output sharing program. The tradeoff is privacy: prompts, project context, model responses, and explicitly attached files may be shared with OpenAI, and eligibility/limits are controlled entirely by OpenAI. You still need a positive API balance, which currently requires a minimum $5 prepaid credit purchase, but if you stay within the complimentary daily limits that credit may not be used.

OpenAI currently offers some eligible API users complimentary daily token usage when they opt into sharing API inputs and outputs with OpenAI. If available on your account, this can make ReaAssist's ChatGPT/OpenAI option very inexpensive, and in some cases effectively free for typical daily use.

For the OpenAI models available in ReaAssist, assuming a typical Tier 1 API account, OpenAI's shared-traffic allowance is currently listed as up to 2.5 million tokens per day for GPT-5.4 mini, GPT-5.6 Luna, and GPT-5.6 Terra, and up to 250,000 tokens per day for GPT-5.6 Sol. These are shared daily quota groups controlled by OpenAI, not guaranteed ReaAssist-only allowances.

There is an important privacy tradeoff: prompts, text-based project context sent to the model, model responses, generated code, and any files you explicitly attach may be shared with OpenAI to help improve their models. ReaAssist does not send audio files or .RPP project files, but it may send relevant REAPER project context such as track names, plugin names, settings, prompts, generated code, screenshots, PDFs, images, or text files if you include them. For many ordinary ReaAssist prompts this may be low-sensitivity data, but avoid sharing confidential, client, personal, or proprietary information unless you are comfortable with OpenAI processing it under this program.

Eligibility is determined entirely by OpenAI, and not all users may qualify. You need an OpenAI API account with a positive API balance, and OpenAI's prepaid billing minimum is currently $5. The setting must be enabled from OpenAI's Data Controls page, and only eligible shared traffic on enabled projects receives the complimentary tokens.

Based on recent ReaAssist testing, eligible users using GPT-5.4 mini may see roughly 75-85 ReaAssist prompts per day covered by OpenAI's 2.5M shared-traffic daily token allowance. Smaller tasks may allow more than 100 prompts per day, while larger plugin or context-heavy tasks may be closer to 45-60 prompts per day. GPT-5.6 Luna and Terra share the same 2.5M group, but there is not yet enough ordinary daily-use data to publish a separate reliable prompt-count estimate for them.

These are rough estimates, not guarantees. Actual usage depends on the selected model, prompt complexity, project size, included context, attachments, retries, OpenAI's current limits, and whether the user remains eligible. GPT-5.6 Sol uses the smaller 250K daily allowance, so comparable ReaAssist usage may be closer to roughly 8 prompts per day.

For normally billed usage, GPT-5.6 prompt-cache writes cost 1.25 times the uncached input rate, while cache reads receive the discounted cached-input rate. ReaAssist uses GPT-5.6's explicit cache controls to cache stable instructions and reference material without repeatedly writing changing prompts, project context, or attachments. The first eligible request may therefore cost more while the stable prefix is written; repeated matching requests during the cache lifetime can be much less expensive. Cache behavior and prices are controlled by OpenAI and may change.

If a request would push you over the remaining daily complimentary-token quota, OpenAI may bill the entire request at normal rates. Model coverage, daily limits, eligibility rules, billing behavior, and the availability of this program are controlled by OpenAI and may change. Return to the Data Controls page on the OpenAI Platform site regularly to confirm that you are still eligible.

To check eligibility:

1. Open OpenAI's data controls page.
2. Look for the API input/output sharing option and the complimentary-token eligibility message.
3. Enable sharing only for the project you want to use with ReaAssist, if you are comfortable with the privacy tradeoff.
4. After using ReaAssist, verify covered usage on the Chat Completions usage page by grouping by service tier.
5. Look for usage labeled data sharing incentive tier - input/output tokens.

OpenAI's help article on API input/output sharing has the current program 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.

#Test Connection

When configuring a custom provider, click Test Connection to verify the endpoint is reachable. By default it sends a lightweight request to the server's models list endpoint to confirm the URL is reachable and authentication is accepted.

Above the button, the Test with a real chat/completions request checkbox switches the test to a real one-token chat completion that mirrors the request body ReaAssist uses in normal use. Use this when a model lists correctly but real prompts fail (different auth scope between the models list and chat completions, configured id is not actually a chat model, etc.). The checkbox is off by default because some reasoning models still run their full thinking pass even when the output cap is one token, so opting in can cost a short inference call per click.

#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.

When you use the hosted OpenAI provider, ReaAssist also sends OpenAI a stable, pseudonymous safety_identifier with each chat request. ReaAssist creates it by applying SHA-256 to a domain-separated random per-install identifier stored locally. It does not contain your name, email address, file paths, project names, chat text, or API key, and it is not sent to custom OpenAI-compatible servers or other providers. OpenAI documents this field as an abuse-prevention and usage-policy signal for individual application users in its Safety checks guide.

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 offers two ways to send feedback to the project maintainer: the in-chat thumbs dialog under each assistant reply, and the Report an Issue form on the Help page. Both are opt-in. Nothing is sent until you press Send, and both show a preview of the exact bytes first.

#In-chat thumbs feedback

ReaAssist includes optional thumbs-up and thumbs-down buttons below assistant replies. Clicking one 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.

#Report an Issue

For issues that need more than a thumbs reaction (something crashed, the wrong code ran, a feature is not working as expected), open Feedback / Report an Issue from the Help page. The form collects everything the maintainer needs in one place.

Inside the form, you can:

• Describe what happened, what you expected, and what actually happened (required).
• Add an optional Name and Email if you want a reply.
• Expand the preview to inspect the exact bytes that would be sent.
• Expand privacy details.
• Press Send to upload, or close the form to discard it.

The Report an Issue form attaches one of the following, depending on the Enable Advanced Log toggle on the Help page:

• With the log enabled (default): the entire Advanced Log file, redacted before sending. The log captures full API request/response traffic, FX scan events, and exchange summaries.
• With the log disabled or empty: the current chat session as a fallback.

Name and Email, if you fill them in, are sent as-is so the maintainer can reply. They are saved locally between visits and are never sent unless you press Send. Failed sends keep the form filled with a Try Again button. ReaAssist does not silently queue, retry, or save the report in the background.

#Redaction

Before sending, ReaAssist automatically removes or hides:

• API keys.
• Authorization: headers.
• Bearer tokens.
• ?key=, ?token=, ?secret=, ?password=, and similar URL query secrets.
• Home-directory paths such as C:\Users\<user>, /Users/<user>, and /home/<user>.
• Install paths in the diagnostic report (log file path is reduced to its filename).

The Report an Issue form additionally redacts custom-provider endpoint URLs from the Advanced Log, so LAN IPs and self-hosted hostnames stay private when you send a bug report.

Review the preview before sending. Redacted text is replaced with placeholders such as ***, <user>, or <custom-endpoint-1>. Chat and log text may still include project names, track names, plugin names, or other text you typed.

#Where it goes

Feedback reports, bug reports, and automatic diagnostics are sent to the ReaAssist project maintainer through https://d.reaassist.app. A random installation ID is generated on first diagnostic/report use so duplicate reports from the same install can be deduplicated. The ID is not linked to your identity. Basic automatic diagnostics are structured and anonymous; Extended diagnostics are sent only if you enable them in Settings.

Raw automatic-diagnostic JSON and any Extended diagnostic chat/log/report attachments are retained for up to 90 days, then deleted automatically. ReaAssist keeps normalized aggregate metrics after that so reliability, cost, latency, and outcome trends can still be measured without retaining the raw diagnostic payload. Manual feedback and bug reports are kept as support records until the maintainer deletes them after they are resolved; those reports include contact information only when you choose to provide it. Private analysis-export links expire after 24 hours, and their generated bundle files are deleted after 30 days.

If a manual feedback or bug-report send fails, the dialog or form remains open and shows the error. ReaAssist does not silently queue, retry, or save those manual reports in the background. If you cancel after a failed send, the data is discarded. Automatic diagnostics use a separate next-launch queue and send only when ReaAssist is idle.

#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.

#Structured Track Edits

Structured track edits are built in for supported track and routing requests. They run locally and offline through a structured executor instead of generated Lua. This path is narrower than normal script generation, but it is stricter: the model must return a small JSON plan, ReaAssist validates it, and ReaAssist applies the supported operations directly.

The first public scope supports:

• Creating or resolving tracks.
• Setting track volume, pan, mute, solo, and master/parent-send state.
• Creating folders.
• Adding supported stock FX.
• Setting supported stock-FX parameters.
• Creating sends.

Supported stock FX for this path are ReaEQ, ReaComp, ReaDelay, ReaVerbate, ReaGate, and ReaLimit. Unsupported plugins, MIDI work, item editing, JSFX, file work, and broader scripting requests continue through the normal Lua workflow.

Structured edits still require Auto-run, still use Auto-backup when enabled, and fail closed when the plan does not match the request safely. If ReaAssist blocks a structured edit, it reports that no changes were made unless it explicitly says that part of the edit had already started and you should use REAPER Undo.

#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 Data/FX_Cache.json. 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.
• Custom Instructions.
• Language selection.
• Chat font size.
• 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.

#Language and Localization

ReaAssist starts in English. You can change the interface language from Settings. The selected language localizes the main window, settings, dialogs, status labels, buttons, menus, and in-app Help.

Language packs are downloaded on demand from reaassist.app and stored in Data/Lang. After a pack is cached, ReaAssist reuses it locally and refreshes it when a newer pack is available. If you keep ReaAssist in English, no language pack is required.

Available translated languages:

• Spanish
• French
• German
• Italian
• Portuguese
• Dutch
• Polish
• Swedish
• Czech
• Romanian
• Turkish
• Russian
• Ukrainian
• Chinese (Simplified)
• Chinese (Traditional)
• Japanese
• Korean
• Vietnamese
• Indonesian

For Chinese (Simplified), Chinese (Traditional), Japanese, and Korean, ReaAssist may ask to download an optional language font so CJK text renders correctly. Optional fonts are stored in Data/Lang/fonts and verified before use. If you cancel the prompt or a download fails, ReaAssist keeps the current language and you can try again later.

Downloading a language pack or optional font only fetches static files for localization. It is separate from provider requests and does not upload your project, prompts, API keys, or audio files.

#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.

ReaAssist also checks required extensions such as ReaImGui and SWS Extension during startup. If a required extension is missing or too old, ReaAssist can install or update the pinned version from the upstream release. After extension installs or updates, restart REAPER so the newly installed binaries load.

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

These shortcuts apply to the main visual ReaAssist window. For the accessible workflow, see Screen Reader Mode Shortcuts.

#Troubleshooting

#Code buttons do not appear

Make sure ReaImGui is installed and up to date. ReaAssist auto-installs required extensions on first launch when missing; if you uninstalled one manually, relaunch ReaAssist and accept the install prompt, or update via ReaPack (Extensions > ReaPack > Browse Packages).

#ReaAssist will not launch

Check that:

• REAPER is version 7.0 or later.
• ReaImGui and SWS Extension are 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

Accurate window capture requires js_ReaScriptAPI. ReaAssist auto-installs it on first launch on supported platforms; if it was skipped or you uninstalled it, install through ReaPack. Platforms without an upstream binary use a non-native capture fallback.

#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, understand, or judge audio content. It can run supported REAPER/SWS measurements such as peak, RMS, and LUFS on selected items when a script uses those APIs.
• 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.