A clean, local-first frontend for utility, chatting, roleplay, or storytelling with LLMs.
Project Status: Beta
SmileyChat is in Beta. The core features are stable, and we are now focusing on squashing bugs, improving performance, and refining the user experience. You may still encounter occasional bugs.
SmileyChat is a local-first frontend application designed for interacting with AI chatbots. Whether you are looking for casual chatting, immersive roleplay, or deep storytelling, SmileyChat provides a clean, accessible, and user-friendly experience for both beginners and experienced writers.
- Local Persistence: Your data belongs to you. All characters, chats, and personas are saved locally in standard JSON files. No cloud lock-in.
- Provider Support: Connect your favorite AI backends. We feature dedicated adapters for OpenAI-compatible APIs, OpenRouter, Google AI / Gemini, Anthropic / Claude, NovelAI, xAI, and KoboldCPP (with native instruct templates). Includes built-in support for response streaming.
- Character Cards & SillyTavern Sync: Easily import Tavern-style V1, V2, and V3 JSON or PNG character cards via drag-and-drop. Migrate or sync your local SillyTavern library (characters, chats, group chats, personas, presets, and lorebooks) directly from Settings. View and edit character details in a dedicated sidebar.
- Advanced Presets & Prompts: Full support for custom preset formats, SillyTavern preset imports, and comprehensive macro replacement (
{{char}},{{user}},{{last_message}}, etc.) to heavily customize AI behavior. - Personas & Dialogue Highlights: Create and manage multiple user personas with customizable dialogue highlight colors. Switch between them instantly and set custom visual statuses (Online, Away, Do Not Disturb).
- Composer Formatting & Hotkeys: Write effortlessly with built-in markdown, spoiler tags (
||spoiler||), and keyboard shortcuts (Ctrl+B,Ctrl+I,Ctrl+U,Ctrl+Shift+X,Ctrl+Shift+P,Alt+Q) in the message composer and editor. - Attachments & Multimodality: Support for image and file attachments during chats, integrating directly with multimodal providers.
- Context Management & Local Tokenizer: Profile-aware local token counting with automatic model detection (GPT-4o, Claude, Llama 3, Mistral, Gemma, DeepSeek) and manual overrides to ensure prompt stability and prevent token overflow.
- Diagnostics & Logging: In-app real-time diagnostics viewer, live SSE log streaming, granular subsystem filters, automatic secret scrubbing, and daily rotating log files.
- Extensible Plugin System: Customize and extend the core functionality using local ESM plugins.
Included as bundled plugins, SmileyChat provides powerful tools right out of the box:
- LoreBooks: Manage World Info with native support for creating, importing, and exporting LoreBooks to inject dynamic contextual information into your active chats.
- Chat Formatter: A dedicated formatter for cleaner chat presentation.
- Regex Replacer: Automatically format and replace text in messages using custom regular expressions.
- Chat Summarizer: Generate concise summaries of long conversations to save context tokens.
- Post Processing: Apply custom processing prompts to refine or alter the AI's final output.
- MCP Servers: Built-in support for Model Context Protocol integration.
SmileyChat runs locally on your machine and opens automatically in your default browser (typically at http://127.0.0.1:4173). To keep a launch headless, set SMILEYCHAT_OPEN_BROWSER=false in .env.
- Install Git.
- Clone the repository and run the startup script (it will offer to automatically install Bun if you don't have it):
git clone https://github.com/SmileyTatsu/SmileyChat.git
cd SmileyChat
SmileyChat.Windows.cmd(To update the app before starting, use SmileyChat.Windows.Update.cmd)
First, ensure Git, curl, and unzip are installed via your package manager. For Debian/Ubuntu, run:
sudo apt update
sudo apt install -y git curl unzipThen, clone the repository and run the startup script (it will offer to automatically install Bun if you don't have it):
git clone https://github.com/SmileyTatsu/SmileyChat.git
cd SmileyChat
./SmileyChat.Linux.sh(To update the app before starting, use ./SmileyChat.Linux.Update.sh)
Android is supported using Termux and a Bun compatibility shim. Read the full Android walkthrough.
Once configured, start or update SmileyChat with:
sh ./SmileyChat.Termux.shBy default, SmileyChat binds to 0.0.0.0, making it accessible to LAN devices, Tailscale peers, and Docker containers out of the box.
Safe-by-Default: Any non-loopback request will show a "set up access" page until you configure authentication. Edit the .env file (auto-created on first boot) to manage access. Most changes hot-reload in ~2 seconds.
# Interface the server binds to. 0.0.0.0 = all interfaces (default).
# Set 127.0.0.1 to refuse every connection except loopback.
SMILEYCHAT_HOST=0.0.0.0
# Set false to stop SmileyChat opening a local browser tab on startup.
SMILEYCHAT_OPEN_BROWSER=false
# Require a username/password from every non-loopback caller.
SMILEYCHAT_BASIC_AUTH_USER=
SMILEYCHAT_BASIC_AUTH_PASS=
# Restrict access by IP/CIDR instead of (or alongside) Basic Auth.
SMILEYCHAT_IP_ALLOWLIST=192.168.1.0/24,10.0.0.5For reverse proxy setups, Docker, Tailscale, or public access, please review our comprehensive Security Model Documentation.
Dive deeper into SmileyChat's features and technical architecture in the docs/ folder.
- Connecting AI Models
- Importing Characters
- Understanding Presets
- Formatting & Instruct Templates (Beta)
- Backup and Restore Data
- Accessing SmileyChat Remotely
- Using LoreBooks
- Troubleshooting
- Providers & AI Setup
- Built-In Model Catalogs
- Preset Macros
- SillyTavern Compatibility
- User Data & Storage
- Core Architecture
- Security Model
- Plugins System
- smileychat-plugins: Verified plugin registry, schemas, and contribution docs.
- smileychat-plugin-template: Starter template for building distributable plugins.
To run the app with Hot Module Replacement (HMR) for active development:
# Terminal 1: Frontend
bun run dev
# Terminal 2: Local API server
bun run dev:apiHelpful checks before submitting PRs:
bun run typecheck
bun test
bun run buildSee the Development Guide for more details.
- Post-Processing Default Prompts: The default pipeline prompts for the post-processing extension were adapted from closuretxt's recast-post-processing.
- License: GNU AGPL v3.0. Modified versions of SmileyChat must remain covered by AGPL-3.0. Third-party plugins using the documented API may use their own licenses.
- Community & Support: Join the SmileyCord Discord Server
- Inquiries: SmileyTatsu@waifu.club