miaw-ai-desktop

What is miaw-ai-desktop?

miaw-ai-desktop is an Electron-based, Windows-first desktop app that provides a simple floating chat interface for “Miaw”. The project focuses on recreating the existing Miaw React UI and preserving a compatible command surface (including Tauri-compatible client shims) so the app can interact with supported back-end commands for chat, history, images, and screenshots.

The repository also documents local configuration via an .env file, supports a LiteLLM-compatible OpenAI endpoint as the default model provider, and includes build instructions for development, production, and Windows EXE packaging.

Key Features

• Floating chat window UI (Electron shell) intended to mirror the existing React-based Miaw interface, including a setup card when the backend is not available.
• Tray icon and global shortcut support (Ctrl+Shift+Space) to show/hide the chat overlay.
• Tauri client shims for @tauri-apps/api modules (core, event, window, dpi) so the front-end can reuse existing internal calls.
• Command surface for chat streaming and conversation management, including ask_ollama, cancel_generation, reset_conversation, plus conversation history operations like save_conversation, persist_message, list_conversations, load_conversation, and delete_conversation.
• Image and screenshot commands, including saving/removing image commands and screen capture commands (capture_screenshot_command, capture_full_screen_command).
• Window/event hooks and misc utilities such as notify_frontend_ready, notify_overlay_hidden, and open_url; plus get_model_config.

How to Use miaw-ai-desktop

1. Clone the repository and copy the provided environment template: copy .env.example to .env.
2. Edit .env to point to your model provider. The documented defaults use a LiteLLM-compatible OpenAI endpoint with values such as:
   • THUKI_PROVIDER=litellm
   • THUKI_API_BASE_URL=http://127.0.0.1:4000
   • THUKI_API_KEY= (empty in the example)
   • THUKI_SUPPORTED_AI_MODELS=gemma-3-4b-it
3. Run locally for development:
   • npm install
   • npm run dev (Alternatively, the repo notes Bun commands.)
4. For production packaging, build the frontend first (npm run build) and then run Electron without the Vite dev server (npm run start). Windows distribution commands are also provided (dist:portable, dist:win).

Use Cases

• Local floating chat for quick prompts: use the global shortcut (Ctrl+Shift+Space) to bring up the overlay and interact via the app’s chat commands.
• Managing chat sessions: save, list, load, and delete conversation history using the app’s built-in history command surface.
• Working with image-related workflows: trigger commands that save or remove images and perform cleanup of orphaned images when using the chat UI’s image features.
• Capturing content from the desktop: use screenshot commands to feed visual context through the same command surface exposed to the UI.
• Setting up a local model proxy: configure the app to use a LiteLLM-compatible OpenAI endpoint at the base URL specified in .env, enabling the default model provider behavior.

FAQ

Does the project support macOS? The repository notes “macOS-only permission/onboarding commands return safe Windows defaults,” which indicates the current build is Windows-first and that macOS-specific behavior is handled conservatively for Windows.

How does the app connect to an AI model provider? By default, the model provider is configured to use a LiteLLM-compatible OpenAI endpoint. You set THUKI_PROVIDER, THUKI_API_BASE_URL, THUKI_API_KEY, and the supported models via .env.

Is search implemented? The repository states that “Search is stubbed to SandboxUnavailable so the existing UI renders the setup card,” meaning search is not fully functional in the current implementation.

Are desktop window dragging and movement fully native? No. Drag-to-move is “not fully native yet,” and “window movement is still a follow-up task.”

How are production builds packaged for Windows? The repo provides Windows build commands including npm run dist:portable for a portable EXE and npm run dist:win for a Windows installer. It also notes icon regeneration for miaw.ico from public/miaw-logo.png to keep branding in sync.

Alternatives

• Desktop “floating chat” clients that integrate with local LLM servers: these typically focus on a similar always-available UI, but may not reuse Miaw’s existing command surface or Tauri-compatible client calls.
• Generic chat clients for OpenAI-compatible APIs (local or remote): useful if you only need a standard chat UI and don’t require the specific command set for conversation/history, image commands, and screenshot commands.
• Building from a React-based overlay with Electron: if you want full control over shortcuts, tray behavior, and model connectivity, a custom integration may be more flexible than using a prebuilt Miaw-focused app.
• Other Tauri/Electron cross-platform wrapper approaches: if your primary goal is to preserve an existing command surface and front-end calls, a different wrapper strategy may better match your target platforms and window behavior needs.