Mio

A lightweight desktop voice assistant that listens, thinks, and responds aloud in real time.

What's New in v0.1.4

• Added a dedicated Notebook page for information Mio should know about the user.
• Included Notebook content in the assistant's context for both voice and text conversations.
• Added spoken offline responses using the built-in text-to-speech engine when the network is unavailable.
• Added keyboard-accessible Notebook navigation with Ctrl+Shift+N on Windows and Cmd+Shift+N on macOS.
• Added hover tooltips to icon-only actions and improved placeholder text contrast.
• Reduced excessive assistant orb hover glow and refined the landing page download links and open-source action.

Overview

Mio helps users interact with a digital assistant without interrupting their current workflow. It takes spoken or typed input, processes the request, and produces immediate spoken feedback. There is no complicated setup or cloud account requirement, just straightforward functionality that keeps conversation context stored safely on the local machine.

System Architecture

flowchart LR
  UIClient["React Interface"]
  MainProcess["Electron Backend"]
  LocalStore[("SQLite Database")]
  ExternalAI["Groq Cloud API"]

  UIClient -- "IPC Invocation" --> MainProcess
  MainProcess -- "Save History" --> LocalStore
  MainProcess -- "AI Processing" --> ExternalAI

  style UIClient fill:#1e1b4b,stroke:#6366f1,stroke-width:2px,color:#fff
  style MainProcess fill:#2e1065,stroke:#8b5cf6,stroke-width:2px,color:#fff
  style LocalStore fill:#0f172a,stroke:#3b82f6,stroke-width:2px,color:#fff
  style ExternalAI fill:#2e1065,stroke:#8b5cf6,stroke-width:2px,color:#fff

Loading

Installation

Clone the repository and install the dependencies:

git clone git@github.com:Charmingdc/mio
cd mio
npm install

To run the application locally in development mode, start the React renderer and the Electron process:

npm run dev:renderer
# In a separate terminal:
npm run dev:electron

To build and package the application for production release:

npm run dist

Usage

Once installed, the application lives in the system tray and runs quietly in the background.

1. Open the application window from the tray or start menu.
2. Click the settings icon in the top right.
3. Paste a Groq API key and save the configuration.
4. Press Ctrl+Space globally from any application to wake the assistant.
5. Speak a prompt. The assistant will transcribe the speech, process it, and read the response aloud.

To use text mode, click the small handle on the right side of the main window to open the chat text area.

Features

• Global Activation: A system-wide shortcut activates the assistant from any application, bringing it into focus instantly.
• Voice and Text Input: Users can speak directly into their microphone or open a slide-out drawer to type messages silently.
• Local Persistence: All conversation history and configuration details are stored in a local database rather than synced to a remote cloud server.
• Customizable Voices: Users can select different synthesized voices and adjust the pitch or reading speed to fit their preference.
• Personalized Context: Users can provide brief background information for Mio to consider when relevant.
• Adjustable Assistant Behavior: Users can choose the tone and response style that best fits them.

Voice Interaction Flow

The following diagram demonstrates what happens when a user triggers the assistant and speaks a command.

sequenceDiagram
  actor User
  participant UI as "React Interface"
  participant Core as "Electron Process"
  participant AI as "Groq AI Services"
  participant DB as "Local Database"

  User->>UI: Trigger shortcut and speak
  UI->>Core: Send audio buffer via IPC
  Core->>AI: Request transcription
  AI->>Core: Return text transcript
  Core->>AI: Request chat completion
  AI->>Core: Return response text
  Core->>DB: Persist conversation
  Core->>UI: Dispatch text to frontend
  UI->>User: Play synthesized speech

Loading

Internal API Documentation

The Electron main process exposes several IPC (Inter-Process Communication) endpoints that the React frontend calls to interact with the system and external services.

[IPC HANDLE] groq:chat

Description: Sends a list of conversation messages to the Groq AI service and returns the generated text response.

Request:

{
  "messages": [{ "role": "user", "content": "What is the weather?" }],
  "model": "llama-3.1-8b-instant",
  "apiKey": "gsk_..."
}

Response:

"The weather is sunny."

Errors:

• 401: Invalid Groq API key.
• 429: Rate limit exceeded. Try again shortly.

[IPC HANDLE] whisper:transcribe

Description: Takes a raw audio buffer and sends it to the Groq Whisper endpoint to convert speech into text.

Request:

{
  "audioData": [11, 22, 33, 44],
  "apiKey": "gsk_..."
}

Response:

"Transcribed text from the audio."

Errors:

• 401: Invalid Groq API key.
• 400: No speech detected.

[IPC SEND] window:minimize

Description: Instructs the operating system to minimize the application window to the taskbar.

Request:

{}

[IPC SEND] window:hide

Description: Hides the application window completely, leaving it running in the system tray.

Request:

{}

Technologies Used

Category	Technologies
Core
Frontend
State & Build
Storage

Contributing

Contributions are welcome. Developers can open an issue or submit a pull request with improvements, bug fixes, or new features.

Author Info

• LinkedIn: https://linkedin.com/in/adebayo-muis
• X (Twitter): https://x.com/charmingdc01

---