Wailschat
A desktop AI chat application built with Wails v2 (Go backend + Vue 3 frontend) that connects to OpenAI-compatible LLM APIs with MCP tool calling support.
Ask AI about Wailschat
Powered by Claude Β· Grounded in docs
I know everything about Wailschat. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
WailsChat

A desktop AI chat application built with Wails v2 (Go backend + Vue 3 frontend) that connects to OpenAI-compatible LLM APIs with MCP tool calling support.

Features
- Multiple LLM Providers: Support for OpenAI, Claude, DeepSeek, and other OpenAI-compatible APIs
- Streaming Responses: Real-time SSE streaming for smooth chat experience
- Multimodal Support: Send images to vision-capable models like GPT-4 Vision
- Multiple Sessions: Create and manage multiple chat sessions with drag-and-drop reordering
- Local Storage: All data stored locally in SQLite database
- Customizable Settings: System prompts, themes, fonts, and chat width
- Dark/Light Theme: Built-in theme switching support
- Built-in Tools (Read/Write/Execute): AI models can read local files, write files, and execute shell commands directly
- MCP Tool Calling: AI models can use external tools via Model Context Protocol
- LaTeX Rendering: High-quality mathematical formula rendering using KaTeX
- Mermaid Diagrams: Render flowcharts, sequence diagrams, and more
- Performance Statistics: Token usage, response times, and generation speed tracking
- Keyboard Shortcuts: Configurable shortcuts for common actions
- Custom CSS: Full CSS customization with highest priority
- Resizable Sidebar: Drag to resize sidebar (200-500px)
- Window State Persistence: Remembers window position, size, and maximized state
Image Input Features
- File Selection: Click the image button to select images from your computer
- Clipboard Paste: Directly paste images from clipboard using Ctrl+V
- Multiple Images: Send multiple images in a single message
- Image Preview: Preview selected images before sending with ability to remove them
- Vision Model Support: Compatible with GPT-4 Vision and other vision-capable models
MCP Tool Calling Features
- MCP Server Management: Configure local (stdio) and remote (HTTP) MCP servers
- Tool Discovery: Automatic tool discovery from connected servers
- Real-time Status: Connection status monitoring with connect/disconnect controls
- Exponential Backoff Retry: Automatic reconnection with retry (up to 5 attempts)
- Environment Variables: Support for custom environment variables in stdio mode
- Auth Token: Optional Bearer token for HTTP transport servers
- Tool Call Display: Collapsible panels showing tool arguments and results
- Error Handling: Graceful error handling with detailed error messages
- Iterative Tool Calls: Support for multiple tool call iterations (up to 10) in a single response
Built-in Tools (Read/Write/Execute)
AI models can directly use these built-in tools to interact with your local filesystem and execute commands:
file_read
Read the contents of a local file, or list the entries of a directory.
- Parameters:
path(required, accepts file or directory path),max_size(optional, default 100KB, max 1MB, file only) - Directory mode: When a directory path is provided, returns a non-recursive listing showing type (
[DIR]/[FILE]), name, size, and modified time - Security: Path validation prevents directory traversal attacks
- Use cases: Reading source code, configuration files, logs, text files; browsing directory structure
file_write
Create a new file or overwrite an existing file with text content.
- Parameters:
path(required),content(required),create_dirs(optional) - Security: Dangerous extensions (.exe, .bat, .sh, .ps1, etc.) are blocked
- Use cases: Writing code, creating scripts, saving generated content
shell_exec
Execute a shell command and return the output.
- Parameters:
command(required),timeout(optional, default 300s, max 1800s) - Security: Dangerous commands (rm, shutdown, dd, etc.) are blacklisted
- Use cases: Running build commands, compiling code, running tests, git operations
Security Features:
- Path validation prevents access outside allowed directories
- Dangerous file extensions blocked for write operations
- Command blacklist prevents destructive operations
- Configurable timeout prevents runaway processes
- Results are truncated (10KB max) to prevent context overflow
Enabling Built-in Tools: Built-in tools are disabled by default. Enable them in Settings β Tools tab.
LaTeX Mathematical Rendering
- KaTeX Integration: High-quality math formula rendering
- Display & Inline Math: Support for both display (
$$...$$) and inline ($...$) math - Alternative Delimiters: Also supports
\[...\]and\(...\) - Error Resilience: Failed LaTeX renders as plain text with error styling
- Unicode Support: Proper handling of Unicode punctuation in markdown
Mermaid Diagram Support
- Flowcharts: Create flowcharts using Mermaid syntax
- Sequence Diagrams: Visualize interactions between participants
- Class Diagrams: Object-oriented class hierarchies
- State Diagrams: State machine visualization
- ER Diagrams: Entity-relationship diagrams
Example:
```mermaid
graph TD
A[Start] --> B{Decision}
B -->|Yes| C[Action 1]
B -->|No| D[Action 2]
C --> E[End]
D --> E
```
Live Development
To run in live development mode, run wails dev in the project directory. This will run a Vite development
server that will provide very fast hot reload of your frontend changes. If you want to develop in a browser
and have access to your Go methods, there is also a dev server that runs on http://localhost:34115. Connect
to this in your browser, and you can call your Go code from devtools.
MCP Server Examples
Stdio Mode (Local Process)
# File system server
npx -y @modelcontextprotocol/server-filesystem /path/to/directory
# SQLite server
npx -y @modelcontextprotocol/server-sqlite /path/to/database.db
# GitHub server
npx -y @modelcontextprotocol/server-github
HTTP Mode (Remote Server)
https://api.github.com/mcp
https://custom-mcp-server.example.com
Configure MCP servers in Settings β MCP tab.
Building
To build a redistributable, production mode package, use wails build.
Project Structure
main.go- Application entry point with Wails configurationapp.go- Main application logic with Wails bindings and MCP tool callingwindow_state.go- Window position/size/maximized state persistenceinternal/- Backend packagesdb/- SQLite database with migrations (V1-V15)llm/- OpenAI-compatible API client with streaming and tool calling supportmodel/- Data models including MCP typesmcp/- MCP protocol implementation (JSON-RPC 2.0 client)tools/- Built-in tool implementations (file_read, file_write, shell_exec)provider/- Provider CRUD servicesession/- Session CRUD servicemessage/- Message CRUD servicesettings/- Settings key-value servicefonts/- Cross-platform system font enumeration
frontend/- Vue 3 frontend with TypeScriptsrc/components/- UI componentsChatInput.vue- Message input with image supportChatWindow.vue- Chat area with message listMessageBubble.vue- Message display with MCP tool call UIMarkdownMessage.vue- Markdown rendering with LaTeX and MermaidSettingsModal.vue- Settings interface with 6 tabsSidebar.vue- Session sidebarSessionList.vue- Session list with drag-and-drop
src/stores/- Pinia state managementsrc/utils/- Utilities including markdown.ts
build/- Build configurations and assets
Database
The application uses SQLite for local storage, located at:
- Windows:
%LOCALAPPDATA%/wailschat/wailschat_data.db - macOS:
~/Library/Application Support/wailschat/wailschat_data.db - Linux:
~/.config/wailschat/wailschat_data.db
Database Schema
providers- API provider configurationssessions- Chat sessions linked to providers (with sort_order for ordering)messages- Chat messages with images, performance stats, and MCP tool datasettings- Application settings (theme, fonts, shortcuts, etc.)mcp_servers- MCP server configurationsschema_version- Current migration version (V15)
Technical Details
MCP Tool Calling Architecture
- Server Configuration: Configure MCP servers in Settings β MCP tab (stdio or HTTP)
- Server Connection: MCP servers connect on app startup (if enabled) or manually via UI
- Tool Discovery: Tools are fetched via
tools/listand cached - Tool Injection: MCP tools are converted to OpenAI function calling format
- LLM Interaction: LLM returns tool calls in streaming response
- Tool Execution: Tools executed via
tools/callwith JSON arguments - Result Integration: Tool results added to context, LLM continues streaming
- Iteration: Up to 10 tool call iterations supported per message
LaTeX Rendering Pipeline
- Protection: LaTeX blocks replaced with HTML comment placeholders
- Markdown Processing: Standard markdown processing (code highlighting, bold fixes)
- Restoration: Placeholders replaced with KaTeX-rendered HTML
- Error Handling: Failed renders show original LaTeX with error styling
Key Technologies
- Backend: Go 1.21+, Wails v2, modernc.org/sqlite (CGO-free)
- Frontend: Vue 3, TypeScript, Tailwind CSS, Pinia
- MCP Protocol: JSON-RPC 2.0 with stdio/HTTP transport support
- Math Rendering: KaTeX for LaTeX, highlight.js for code syntax
- Diagrams: Mermaid.js for diagram rendering
- Build System: Vite, Wails build system
Development Commands
# Development mode with hot reload
wails dev
# Production build
wails build
# Frontend development only
cd frontend && npm run dev
# Frontend type checking
cd frontend && npm run type-check
# Go dependency management
go mod tidy
Troubleshooting
MCP Connection Issues
- Check command syntax for stdio servers
- Verify environment variables are correctly set
- Test connection using the Test button in Settings β MCP
- Check logs for detailed error messages
LaTeX Rendering Issues
- Verify LaTeX syntax is valid
- Check KaTeX compatibility of LaTeX commands
- Ensure proper delimiters (
$$...$$for display,$...$for inline)
General Issues
- Clear database: Delete the SQLite file and restart
- Check API keys: Verify provider API keys are valid
- Update dependencies: Run
npm installandgo mod tidy
License
This project uses the official Wails Vue-TS template as a base.
