SillyTavern Development Expert

Expert guidance for developing frontend interfaces and background scripts for SillyTavern using the Tavern Helper framework.

When to Use This Skill

Use this skill when users request:

✅ Frontend interfaces - Interactive UI in message floors (status bars, game systems, multimedia displays)
✅ Background scripts - Automation, chat enhancement, external service integration
✅ Character card features - Enhanced gameplay, visual effects, data visualization
✅ MVU variable framework - Message floor variable management and display
✅ SillyTavern UX improvements - UI tweaks, workflow automation, custom tools

Core Concepts

Project Types

Projects live in src/项目名/ folders:

Frontend Interface (index.ts + index.html):

Runs as sandboxless iframe in message floor (foreground)
Has visual UI with styles and interactions
Preferred stack: Vue 3 + Pinia + Vue Router

Script (index.ts only):

Runs as sandboxless iframe in background
No visual UI, code-only
jQuery operates on parent SillyTavern page: window.$ = window.parent.$

Data Persistence: Tavern Variables

Use getVariables() / replaceVariables() for persistent storage:

global - Shared across entire tavern
character - Bound to specific character card
chat - Bound to specific chat file
message - Bound to specific message floor
script - Bound to specific script
extension - Bound to specific extension

MVU Variable Framework

Separate Tavern Helper script enhancing message floor variables:

Set variables in world info
Auto-update variables from AI output
Provides display_data and delta_data for visualization
Must initialize: await waitGlobalInitialized('Mvu')

See references/mvu_framework.md for detailed API.

Quick Start

1. Choose Project Type

Determine frontend interface or script based on whether UI is needed.

2. Select Tech Stack

For frontend interfaces:

Simple UI: Vue 3 + Tailwind CSS
Complex game: PixiJS + @pixi/react
React preference: React + hooks

For scripts:

DOM manipulation: jQuery + jQueryUI
State management: Pinia + Zod
Animations: GSAP

See references/tech_stack.md for full dependency list and usage patterns.

3. Development Workflow

# Install dependencies (pnpm only)
pnpm install

# Development build
pnpm run build:dev

# Watch mode (auto-rebuild)
pnpm run watch

# Production build
pnpm run build

4. Live Preview

Option 1: Soft link (recommended)

ln -s /path/to/dist/项目名/index.html /root/web-dev/preview.html

Option 2: Copy

cp /path/to/dist/项目名/index.html /root/web-dev/

Access: https://dev.piepia.space/preview.html

Use browsermcp to test in real browser environment.

Development Best Practices

TypeScript Required

// ✅ Correct: TypeScript with Zod validation
import { z } from 'zod';

const Settings = z.object({
  volume: z.number().min(0).max(1).default(0.5),
  autoPlay: z.boolean().default(true),
}).prefault({});

type Settings = z.infer<typeof Settings>;

Use Third-Party Libraries

// ✅ jQuery for DOM
$('#button').on('click', handler);

// ✅ GSAP for animations (including typewriter)
gsap.to('#text', {
  duration: 2,
  text: { value: "New text", delimiter: "" },
  ease: "none"
});

// ✅ Zod for validation
const result = Schema.safeParse(data);
if (!result.success) {
  console.error(z.prettifyError(result.error));
}

Correct Loading/Unloading Timing

// ✅ Correct: jQuery ready handler
$(() => {
  toastr.success('Loaded');
  // Initialization logic...
});

// ✅ Correct: Cleanup on unload
$(window).on('pagehide', () => {
  toastr.info('Unloaded');
  // Cleanup: remove listeners, stop timers...
});

// ❌ Wrong: DOMContentLoaded doesn't fire on network load
document.addEventListener('DOMContentLoaded', () => {
  // Won't execute when loaded via $('body').load(url)!
});

Reload on Chat Change

let chat_id = SillyTavern.getCurrentChatId();

eventOn(tavern_events.CHAT_CHANGED, new_chat_id => {
  if (chat_id !== new_chat_id) {
    chat_id = new_chat_id;
    window.location.reload();
  }
});

Frontend Interface Development

index.html Rules

<head>
  <!-- Keep empty - webpack auto-injects styles/scripts -->
</head>
<body>
  <!-- Static content only -->
  <div id="app"></div>

  <!-- ❌ NO <link rel="stylesheet" href="./index.css"> -->
  <!-- ❌ NO <script src="./index.ts"> -->
  <!-- ❌ NO <img src=""> empty placeholders -->
</body>

Styling Approaches

// Method 1: Tailwind CSS (simple styles)
import './tailwind.css'; // Content: @import 'tailwindcss';

// Method 2: Vue component styles (recommended)
// Component.vue
<template>...</template>
<style lang="scss" scoped>
  .my-class { color: red; }
</style>

// Method 3: Global SCSS
import './index.scss';

iframe Adaptation

// ✅ Use width + aspect-ratio (NOT vh)
.container {
  width: 100%;
  aspect-ratio: 16 / 9;
}

// ❌ Avoid forcing parent height
.bad {
  min-height: 500px; // Not recommended
  overflow: auto;    // May cause scrollbars
}

// ✅ Fit container width, no horizontal scroll
body {
  max-width: 100%;
  overflow-x: hidden;
}

// ✅ Card style: transparent background (unless explicitly requested)
.card {
  background: transparent;
}

Vue Development Template

See references/vue_template.md for complete Vue 3 + Pinia + Vue Router setup.

PixiJS Multimedia Interface

See references/pixijs_usage.md for game-like interfaces with heavy multimedia assets.

Script Development

jQuery Scope

// ⚠️ $ operates on SillyTavern page, not iframe
$('body'); // Selects SillyTavern <body>

// Select iframe elements
$('body', document); // document = script iframe

Using Vue in Scripts

// 1. Create mount point with jQuery
const $app = $('<div>').attr('id', 'my-app').appendTo('body');

// 2. Create Vue app
const app = createApp(App);
app.use(createPinia());

// 3. Mount to jQuery element
app.mount($app[0]); // Note [0] to get DOM element

// 4. Cleanup
$(window).on('pagehide', () => {
  app.unmount();
  $app.remove();
});

Teleporting Styles to SillyTavern Page

// Script styles only apply to iframe - manually teleport to parent

export function teleport_style() {
  $(`<div>`)
    .attr('script_id', getScriptId())
    .append($(`head > style`, document).clone())
    .appendTo('head'); // Appends to SillyTavern <head>
}

export function deteleport_style() {
  $(`head > div[script_id="${getScriptId()}"]`).remove();
}

$(() => teleport_style());
$(window).on('pagehide', () => deteleport_style());

Script Settings UI

See references/script_patterns.md for Pinia + Zod settings management pattern.

Registering Script Buttons

// Triggered when user clicks button in Tavern Helper script library
eventOn(getButtonEvent('Reload'), () => {
  window.location.reload();
});

eventOn(getButtonEvent('Clear Data'), () => {
  if (confirm('Clear all data?')) {
    replaceVariables({}, { type: 'script', script_id: getScriptId() });
    toastr.success('Data cleared');
  }
});

API Priority

Priority order: Tavern Helper API > STScript Commands > SillyTavern Native API

// ❌ Don't: STScript
await triggerSlash('/setvar key=score 100');
const score = await triggerSlash('/getvar score');

// ✅ Do: Tavern Helper API
replaceVariables({ score: 100 }, { type: 'chat' });
const score = getVariables({ type: 'chat' }).score;

// ✅ Do: toastr instead of /echo
toastr.success('Hello');

// ✅ Do: Tavern Helper functions
const messages = getChatMessages(); // Instead of SillyTavern.chat
replaceWorldbook(data);             // Instead of /setentryfield

Reason: Tavern Helper API provides:

✅ Type safety (full TypeScript support)
✅ Higher abstraction (semantic operations)
✅ Better error handling
✅ Better performance (less string parsing)

Resources

references/

Detailed documentation loaded as needed:

tech_stack.md - Complete dependency list and usage patterns
api_reference.md - Tavern Helper API documentation
stscript_commands.md - All 264 STScript commands with examples
type_definitions.md - TypeScript type system overview
vue_template.md - Vue 3 + Pinia + Router setup
script_patterns.md - Common script development patterns
pixijs_usage.md - PixiJS multimedia interface guide
mvu_framework.md - MVU variable framework API
best_practices.md - Development do's and don'ts

assets/

Template files for quick project initialization:

frontend-template/ - Vue 3 frontend interface boilerplate
script-template/ - Background script boilerplate
tailwind.css - Tailwind CSS import file

Common Patterns

Reactive Data + Tavern Variable Sync

const data = ref({ score: 0, hp: 100 });

// Load initial values
data.value = getVariables({ type: 'chat' });

// Auto-save (remove Vue Proxy with klona)
watchEffect(() => {
  replaceVariables(klona(data.value), { type: 'chat' });
});

Listening to Tavern Events

import { tavern_events, eventOn } from '@types/iframe/event';

// AI message received
eventOn(tavern_events.MESSAGE_RECEIVED, (message_id) => {
  console.log('New message', message_id);
});

// Message updated
eventOn(tavern_events.MESSAGE_UPDATED, (message_id) => {
  console.log('Message updated', message_id);
});

Calling LLM

// Simple generation (with chat history + character card)
const result = await generate({
  prompt: 'Summarize the conversation',
  quietPrompt: 'Summarize in 50 words or less',
});

// Raw generation (no chat history)
const result = await triggerSlash(`
  /genraw instruct=off Why is the sky blue?
`);

Error Handling with Zod

const UserInput = z.object({
  name: z.string().min(1),
  age: z.number().int().positive(),
});

const result = UserInput.safeParse(data);

if (!result.success) {
  toastr.error(z.prettifyError(result.error));
  return;
}

const { name, age } = result.data; // Type-safe

Forbidden Practices

❌ Node.js libraries (fs, path, http, etc.) ❌ <link> / <script> tags in index.html for local files ❌ DOMContentLoaded for load timing ❌ vh units in frontend interface styles (use aspect-ratio) ❌ Direct code execution in global scope (use $(() => {})) ❌ Saving Vue reactive data directly (use klona() first)

Output Requirements

When developing features for users:

Confirm project type - Frontend interface or script?
Choose tech stack - Vue (recommended) / React / PixiJS?
Data persistence plan - Which variable type?
Provide complete code:
- Clear TypeScript types
- Use recommended libraries
- Follow best practices
- Include error handling
Test with preview - Build and preview on dev.piepia.space via browsermcp
Code documentation - Comment key logic, explain special usage

Working Directory

Current directory: /root/tavern_helper_template