Regex Scripts¶

Regex scripts are text transformation rules that automatically find and replace patterns in your messages. They can clean up formatting, enforce style rules, or transform content at various stages of the pipeline.

What Can Regex Scripts Do?¶

• Remove unwanted formatting (asterisks, brackets, etc.)
• Convert text styles (e.g., italic markers to actual HTML italics)
• Enforce naming conventions
• Strip or transform specific patterns
• Add HTML formatting to AI output
• Clean up reasoning tags or other artifacts

Creating a Script¶

1. Open the Regex Scripts panel
2. Click New Script
3. Fill in:

Example: Remove Asterisks¶

Find: \*([^*]+)\* Replace: <em>$1</em> Flags: g

This converts *italic text* into <em>italic text</em>.

Placement¶

Placement controls which parts of the text the script runs on:

You can select multiple placements for the same script.

Memory placement is independent of target: it strips text as it's saved to long-term memory (vector search and the memory cortex), before storage and embedding, while the displayed message keeps the full text. Use it to keep tracker or HUD blocks out of recalled memory. Macros aren't available at ingestion, so memory scripts must use literal patterns.

Target¶

Target controls when in the pipeline the script runs:

• Use prompt target to modify what the AI sees
• Use response target to clean up AI output before it's saved
• Use display target for visual-only transformations (the underlying text stays unchanged)

Associative Regex Actions¶

Associative regex actions turn elements in replacement HTML into choices. This is useful for interactive scene cards, CYOA responses, suggested dialogue, loadout selectors, and similar interfaces.

Actions require a script with the Display target. In the replacement HTML, associate a clickable element with an action by giving it a data-regex-action value:

<button type="button" data-regex-action="enter-gate">Enter the gate</button>

Then add an action in the script's Actions section whose ID is enter-gate. An element's regular id attribute can also be used, but data-regex-action is recommended because it does not interfere with CSS or page IDs.

Each action has these fields:

Titles, subtitles, content, cost, and limit support the same capture references as the replacement string, including $1, $2, $&, and named captures such as $<location>.

Persistent state effects¶

Use Add state effect to let a choice update a persistent chat variable. State values are available to prompts and later regex scripts through {{getchatvar::key}}.

For example, an action matching a named route capture can set:

{
  "type": "set_state",
  "key": "adventure.route",
  "value": "$<route>"
}

The key is creator-defined and cannot contain captures. Values and drafts are resolved from the stored assistant message when the action is claimed. Actions containing composable effects are disabled in user messages and rejected by the server; editing the browser payload cannot choose a different key, value, draft, or fork point.

Effects are additive and backward compatible. Existing actions without an effects field continue to behave exactly as before. A state effect is committed with the action's normal one-shot claim, including batched multi-select claims.

Draft and fork effects¶

A draft effect places capture-resolved text in the composer without sending it. It can either replace the current draft or append to it, leaving the user free to edit before sending.

A fork effect creates and opens a chat branch at the assistant message that rendered the action. Combine it with state and draft effects to build a complete branching choice:

{
  "id": "take-rooftops",
  "type": "effects",
  "multi_select": false,
  "cost": "1",
  "limit": "3",
  "title": "Take the rooftops",
  "subtitle": "Create an editable branch",
  "content": "",
  "effects": [
    { "type": "set_state", "key": "adventure.route", "value": "$<route>" },
    { "type": "fork" },
    { "type": "draft", "mode": "replace", "content": "Let's take $<route>." }
  ]
}

The state update and fork are committed together. The new branch inherits the updated chat state, then opens with the draft waiting in its composer. Draft and fork effects require an Effects only action and cannot be multi-select. State effects may also be attached to existing Send or Append actions.

One-shot behavior¶

Each rendered regex match is a stateful action block. A normal action consumes the entire block when selected. Multi-select choices remain provisional until Send: click an option once to add it and click it again to remove it. At Send, the selected options are claimed together and become one-shot.

Used choices stay disabled when the user scrolls away, refreshes, or opens the chat on another client. This prevents an old scene card from triggering the same generation influence more than once. If normal and multi-select actions are mixed in one block, a normal Send action acts as the commit trigger: its content and all staged modifiers are claimed and sent together. A normal Append action is non-triggering and cannot replace staged selections from its own block.

How multi-select content is applied¶

Multi-select actions wait for the next Send signal:

• An option can be toggled on or off until Send begins.
• A new option is rejected when its cost would put the block above its limit.
• Clicking a normal Send action also counts as Send and batches that action with every staged modifier.
• Send modifiers are joined to the user's visible message, separated by blank lines.
• Append modifiers are stacked in a hidden prompt appendix attached to that user message.
• A visible Send modifier can enable Send even when the text box is empty.
• Append-only selections keep waiting until the user sends an actual message.

Importable examples¶

• Scene card with a single action transforms <scene>...</scene> output into a styled HTML card. Its button sends the captured choice immediately.
• Multi-select scene planner provides two visible selections and one hidden tone modifier, all stacked on the next Send.

The first example expects AI output shaped like this:

<scene>
  <location>Moonlit Courtyard</location>
  <description>A silver gate stands between ivy-covered walls.</description>
  <choice>Open the silver gate</choice>
</scene>

The multi-select demo expects:

<scene-options>
  <title>Crossing the Sleeping City</title>
  <budget>3</budget>
  <route cost="2">Take the rooftops</route>
  <companion cost="1">Bring Lyra</companion>
  <tone cost="1">Keep the scene tense and quiet</tone>
</scene-options>

Import either JSON file through Regex Scripts → Import.

Scope¶

Resolution order: Global scripts run first, then character-scoped, then chat-scoped. Within each tier, scripts run in sort order.

Advanced Options¶

Testing Scripts¶

Before saving, use the Test feature:

1. Click Test on your script
2. Enter sample text
3. See the result, including matched portions and the transformed output

This lets you verify your regex works correctly before it affects real conversations.

Import & Export¶

Scripts can be imported and exported as JSON. Lumiverse also supports importing SillyTavern-format regex scripts for easy migration.

Tips¶