Transform your OpenWebUI experience with intelligent AI persona switching
Agent Hotswap is a powerful OpenWebUI filter that enables seamless switching between specialized AI personas with a simple command system. Each persona comes with unique capabilities, expertise, and communication styles, all built on a Master Controller foundation that provides universal OpenWebUI-native features.
- 🎛️ Master Controller System - Transparent foundation providing OpenWebUI capabilities to all personas
- 🚀 Instant Persona Switching - Simple
!commandsyntax for immediate role changes - 📦 Remote Persona Downloads - Automatically fetch and apply persona collections from repositories
- 🔒 Security-First Design - Trusted domain whitelist and validation system
- ⚡ Performance Optimized - Smart caching, pre-compiled patterns, and efficient loading
- 🎨 Rich Rendering Support - LaTeX math, Mermaid diagrams, HTML artifacts built-in
- 💾 Automatic Backups - Safe persona management with rollback capabilities
⚠️ FIRST STEP: After installation, use the!download_personascommand to get the complete persona collection. The system starts with basic defaults but the full experience requires downloading the official persona repository.
- 🚀 Quick Start
- 🏗️ Installation
- 🎯 Core Concepts
- 📥 Persona Management
- 🛠️ Configuration
- 💡 Usage Guide
- 🏗️ System Architecture
- 🔧 Troubleshooting
- 🚀 Advanced Features
- 🤝 Contributing
- Copy the complete filter code
- Add as a new filter in OpenWebUI
- Enable the filter and configure basic settings
!download_personas
This downloads the official persona repository with 50+ specialized AI assistants.
!list
!coder # Become a programming expert
!writer # Transform into a creative writer
!analyst # Switch to data analysis mode
!reset # Return to default assistant
- OpenWebUI instance with filter support
- Administrator access to add filters
- Internet connectivity for persona downloads
-
Access Filter Management
- Navigate to OpenWebUI Settings
- Go to Admin Panel → Filters
- Click "Add Filter"
-
Install Agent Hotswap
- Copy the complete filter code
- Paste into the filter editor
- Set filter name: "Agent Hotswap"
- Save and enable the filter
-
Initial Configuration
- Review default settings in the Valves section
- Adjust
keyword_prefixif desired (default:!) - Configure
trusted_domainsfor security - Enable
create_default_configfor automatic setup
-
First-Time Setup
!download_personasThis command will:
- Download the official persona collection
- Create backup of existing configuration
- Apply new personas with merge strategy
- Clear caches for immediate availability
The Master Controller is the invisible foundation that powers every persona interaction:
- LaTeX Mathematics:
$$E=mc^2$$rendering support - Mermaid Diagrams: Automatic flowchart and diagram generation
- HTML Artifacts: Interactive content creation capabilities
- File Processing: CSV, PDF, image upload handling
- Status Messages: Real-time feedback and progress indicators
- Always Active: Automatically loads with every persona
- Transparent: Users never see or interact with it directly
- Foundation Layer: Provides OpenWebUI-native capabilities to all personas
- Smart Persistence: Only removed on reset/default commands
Each persona consists of structured components:
{
"persona_key": {
"name": "🎭 Display Name",
"prompt": "Detailed system prompt defining behavior",
"description": "User-facing description of capabilities",
"rules": ["Rule 1", "Rule 2", "..."]
}
}- Name: Display name with emoji for visual identification
- Prompt: Comprehensive system prompt defining personality and expertise
- Description: User-facing explanation of capabilities
- Rules: Structured guidelines for behavior and responses
Agent Hotswap uses a prefix-based command system:
| Command Type | Syntax | Purpose |
|---|---|---|
| Persona Switch | !persona_key |
Activate specific persona |
| List Personas | !list |
Show available personas in table format |
| Reset System | !reset, !default, !normal |
Return to standard assistant |
| Download Personas | !download_personas [url] [--replace] |
Fetch remote persona collections |
Available Personas
| Command | Name | Command | Name |
|---|---|---|---|
!airesearcher |
🤖 AI Pioneer | !analyst |
📊 Data Analyst |
!archaeologist |
🏺 Relic Hunter | !architect |
🏗️ Master Builder |
!artist |
🎨 Creative Visionary | !astronomer |
🔭 Star Gazer |
!biologist |
🧬 Life Scientist | !blockchaindev |
🔗 Chain Architect |
!careercounselor |
🧑💼 Career Navigator | !chef |
🧑🍳 Culinary Genius |
!chemist |
🧪 Molecule Master | !coder |
💻 Code Assistant |
!consultant |
💼 Business Consultant | !cybersecurityexpert |
🛡️ Cyber Guardian |
!debug |
🐛 Debug Specialist | !devopsengineer |
⚙️ System Smoother |
!doctor |
🩺 Medical Informant | !economist |
📈 Market Analyst Pro |
!environmentalist |
🌳 Nature's Advocate | !ethicist |
🧭 Moral Compass |
!fashiondesigner |
👗 Style Icon | !filmmaker |
🎥 Movie Director |
!financialadvisor |
💰 Wealth Sage | !fitnesstrainer |
💪 Health Coach |
!gamedesigner |
🎮 Game Dev Guru | !gardener |
🌻 Green Thumb |
!geologist |
🌍 Earth Explorer | !historian |
📜 History Buff |
!hrspecialist |
🧑🤝🧑 People Partner Pro | !interiordesigner |
🛋️ Space Shaper |
!journalist |
📰 News Hound | !lawyer |
⚖️ Legal Eagle |
!lifecoach |
🌟 Goal Getter Guide | !linguist |
🗣️ Language Expert |
!marketingguru |
📢 Brand Booster | !mathematician |
➕ Math Whiz |
!mechanic |
🔧 Auto Ace | !musician |
🎶 Melody Maker |
!negotiator |
🤝 Deal Maker Pro | !novelist |
📚 Story Weaver |
!nutritionist |
🥗 Dietitian Pro | !philosopher |
🤔 Deep Thinker |
!photographer |
📸 Image Capturer | !physicist |
⚛️ Quantum Physicist |
!poet |
✒️ Verse Virtuoso | !projectmanager |
📋 Task Mastermind |
!psychologist |
🧠 Mind Mender | !publicspeaker |
🎤 Oratory Coach |
!researcher |
🔬 Researcher | !roboticsengineer |
🦾 Robot Builder |
!salesexpert |
🤝 Deal Closer Pro | !scriptwriter |
🎬 Screen Scribe |
!sociologist |
👥 Society Scholar | !sommelier |
🍷 Wine Connoisseur |
!teacher |
🎓 Educator | !travelguide |
|
!writer |
✍️ Creative Writer |
To revert to the default assistant, use one of these commands: !reset, !default, !normal
The download system enables automatic persona collection management:
!download_personasDownloads from the default repository with merge strategy.
!download_personas https://your-domain.com/personas.jsonDownload from a specific URL (must be in trusted domains).
!download_personas --replaceCompletely replaces local personas with remote collection.
- URL Validation - Verifies domain is trusted
- Content Retrieval - Downloads JSON configuration
- Structure Validation - Ensures proper persona format
- Backup Creation - Saves current configuration
- Merge/Replace - Applies new personas based on strategy
- Cache Invalidation - Refreshes system for immediate use
trusted_domains: "github.com,raw.githubusercontent.com,gitlab.com"
Only domains in this list can serve persona downloads.
- JSON Structure - Validates persona configuration format
- Required Fields - Ensures name, prompt, description are present
- Content Limits - 1MB maximum download size
- Timeout Protection - 30-second download timeout
- HTTPS-only downloads
- Content-type validation
- Malicious URL detection
- Safe fallback on errors
- Created before every download/apply operation
- Timestamped for easy identification
- Stored in
backups/subdirectory - Automatic cleanup (keeps 5 most recent)
/app/backend/data/cache/functions/agent_hotswap/backups/
├── personas_backup_2024-01-15_14-30-22.json
├── personas_backup_2024-01-15_14-25-18.json
└── ...
| Setting | Default | Description |
|---|---|---|
keyword_prefix |
! |
Command prefix for persona switching |
case_sensitive |
false |
Whether commands are case-sensitive |
persistent_persona |
true |
Keep persona active across messages |
show_persona_info |
true |
Display status messages for switches |
| Setting | Default | Description |
|---|---|---|
cache_directory_name |
agent_hotswap |
Directory name for config storage |
config_filename |
personas.json |
Filename for persona configuration |
create_default_config |
true |
Auto-create default personas |
default_personas_repo = "https://raw.githubusercontent.com/pkeffect/agent_hotswap/refs/heads/main/personas/personas.json"
trusted_domains = "github.com,raw.githubusercontent.com,gitlab.com"
download_timeout = 30
backup_count = 5debug_performance = false
status_message_auto_close_delay_ms = 5000- Smart Caching - Only reloads when files change
- Pattern Pre-compilation - Regex patterns compiled once
- Lazy Loading - Personas loaded on-demand
- Change Detection - File modification time tracking
!list
Displays a formatted table showing:
- Command syntax for each persona
- Display names with emojis
- Reset command options
!reset # Primary reset command
!default # Alternative reset
!normal # Another reset option
!coder # Switch to Code Assistant
!writer # Switch to Creative Writer
!analyst # Switch to Data Analyst
!teacher # Switch to Educator
!researcher # Switch to Researcher
- Automatic Introduction - Each persona introduces itself on activation
- Persistent Context - Persona remains active until changed
- Specialized Responses - Tailored expertise and communication style
- Master Controller Foundation - OpenWebUI capabilities always available
# Download default collection
!download_personas
# Download from specific URL
!download_personas https://example.com/personas.json
# Replace all personas
!download_personas --replace
# Custom URL with replace
!download_personas https://example.com/custom.json --replace/app/backend/data/cache/functions/agent_hotswap/
├── personas.json # Main configuration
├── backups/ # Automatic backups
│ ├── personas_backup_2024-01-15_14-30-22.json
│ └── personas_backup_2024-01-15_14-25-18.json
└── logs/ # Debug logs (if enabled)
{
"_master_controller": {
"name": "🎛️ Master Controller",
"hidden": true,
"always_active": true,
"priority": 0,
"prompt": "=== OPENWEBUI MASTER CONTROLLER ===\n...",
"description": "Universal OpenWebUI environment context"
},
"coder": {
"name": "💻 Code Assistant",
"prompt": "You are the 💻 Code Assistant...",
"description": "Expert programming assistance",
"rules": [...]
}
}- File Modification Detection - Only reloads when JSON changes
- Validation Caching - Remembers successful validations
- Pattern Compilation Cache - Stores compiled regex patterns
- Invalidation Triggers - Manual cache clearing on downloads
- Reduced I/O - Minimizes file system access
- Faster Switching - Pre-compiled patterns for instant detection
- Memory Efficiency - Lazy loading of persona data
- Change Tracking - Timestamp-based modification detection
# Compiled patterns for efficiency
prefix_pattern = re.compile(rf"{escaped_prefix}coder\b", flags)
reset_pattern = re.compile(rf"{escaped_prefix}(?:reset|default|normal)\b", flags)
list_pattern = re.compile(rf"{escaped_prefix}list\b", flags)- Command Preprocessing - Normalize case if needed
- Pattern Matching - Use pre-compiled regex for speed
- Priority Ordering - System commands checked first
- Fallback Handling - Graceful degradation on errors
Problem: !download_personas fails with domain error
Solution: Check trusted_domains configuration
- Ensure domain is in whitelist: "github.com,raw.githubusercontent.com"
- Verify HTTPS protocol is used
- Check network connectivity
Problem: Persona doesn't activate after switching
Solution: Check configuration and cache
1. Use !list to verify persona exists
2. Check personas.json syntax
3. Clear cache: restart OpenWebUI or modify config file
4. Review logs for validation errors
Problem: !coder or other commands don't work
Solution: Verify configuration
- Check keyword_prefix setting (default: "!")
- Ensure case_sensitive matches your usage
- Verify filter is enabled and active
- Test with !list first
debug_performance = trueProvides detailed timing and operation logs.
- Pattern compilation timing
- File loading performance
- Cache hit/miss ratios
- Command detection speed
- Delete config file: Remove
personas.json - Restart filter: Toggle off/on in OpenWebUI
- Reload defaults: System creates fresh configuration
- Re-download: Use
!download_personasto restore collection
- Locate backup: Check
backups/directory - Copy desired backup: Rename to
personas.json - Clear cache: Restart OpenWebUI or modify timestamp
- Verify: Use
!listto confirm restoration
Edit personas.json directly to add custom personas:
{
"custom_key": {
"name": "🎯 Your Custom Persona",
"prompt": "You are a specialized assistant for...",
"description": "Brief description of capabilities",
"rules": [
"1. First behavioral rule",
"2. Second behavioral rule"
]
}
}Structure for shareable persona collections:
{
"meta": {
"version": "1.0.0",
"author": "Your Name",
"description": "Collection description"
},
"personas": {
"specialist": {
"name": "🎯 Specialist",
"prompt": "...",
"description": "..."
}
}
}- Development Teams: Code review personas for different languages
- Content Creation: Writing personas for different styles/audiences
- Education: Teaching personas for different subjects/levels
- Analysis: Specialized personas for different data types
- Fork Repository - Create your own copy
- Clone Locally - Set up development environment
- Test Changes - Use OpenWebUI test instance
- Submit PR - Follow contribution guidelines
- Clear Purpose - Well-defined role and expertise
- Comprehensive Prompt - Detailed behavioral instructions
- User-Friendly Description - Clear capability explanation
- Appropriate Rules - Structured behavioral guidelines
- Validation - Passes JSON schema validation
- Functionality - Commands work as expected
- Performance - No significant slowdown
- Compatibility - Works with Master Controller system
Include the following information:
- OpenWebUI Version - Your OpenWebUI version
- Filter Configuration - Relevant valve settings
- Error Messages - Full error text and logs
- Reproduction Steps - How to recreate the issue
- Expected Behavior - What should happen instead
This project is licensed under the MIT License - see the LICENSE file for details.
- OpenWebUI Team - For the amazing platform
- Community Contributors - For persona collections and feedback
- Beta Testers - For early feedback and bug reports
- GitHub Issues - Report bugs and request features
- Discussions - Community support and questions
- Documentation - This README and inline code documentation
🎭 Transform your AI interactions with Agent Hotswap!
Seamless persona switching • Rich OpenWebUI integration • Secure & performant