MiQi

# MiQi

<p align="center">
  <em>🐈‍⬛🪶 A lightweight, extensible personal AI agent framework with a modern desktop interface</em>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.11%20%7C%203.12-blue" alt="Python 3.11 | 3.12" />
  <img src="https://img.shields.io/badge/node.js-20+-green" alt="Node.js 20+" />
  <img src="https://img.shields.io/badge/status-alpha-orange" alt="Development Status: Alpha" />
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License" /></a>
</p>

---

## Overview

MiQi Desktop is an Electron-based desktop application that provides a modern graphical interface for the MiQi AI agent. It combines powerful AI agent capabilities with an intuitive user interface, supporting chat interaction, memory management, task scheduling, and more.
![interface](interface.png)

### Core Positioning

- 🎯 **Personal AI Agent** — not just a chatbot: persistent memory, learned skills, file operations, and scheduled tasks
- 🔧 **Highly Extensible** — MCP protocol for external tools, custom skills, and pluggable LLM providers
- 🖥️ **Native Desktop Experience** — Electron with system-level integration (WSL2 sandbox, filesystem operations)
- 🔒 **Local-First** — all data stored locally; non-destructive file editing with versioned snapshots
- 📋 **Typed Application Protocol** — typed AppServer with JSON Schema catalog, method stability tracking, and handler-boundary validation

### Tech Stack

| Layer | Technology | Version |
|-------|-----------|---------|
| Desktop Framework | Electron | 35.2 |
| Frontend UI | React + TypeScript | 19.1 / 5.8 |
| CSS | Tailwind CSS 4 | 4.x |
| Component Library | Radix UI + Lucide Icons | — |
| Python Runtime | Python (asyncio) | 3.11+ |
| Data Validation | Pydantic v2 | 2.12+ |
| CLI Framework | Typer | 0.20+ |
| Build (Desktop) | electron-vite + electron-builder | 3.1 / 26.0 |
| Build (Python) | PyInstaller + Hatchling | 6.20+ |

---

## Key Features

| Feature | Description |
|---|---|
| **Smart Chat** | Natural language conversation with streaming responses and tool-call progress |
| **Multi-Provider** | OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, and more — with provider resilience |
| **Typed Protocol** | Typed AppServer with method specs, JSON Schema catalog, and handler-boundary validation |
| **Memory System** | Long-term memory snapshots, self-improvement lessons, and cross-session recall |
| **Task Scheduler** | Cron-based scheduled tasks with timezone support |
| **Skill System** | Create, upload, and manage agent skills; SkillHub registry integration |
| **Plugin Ecology** | MCP servers, plugins, and marketplace with deterministic catalog |
| **Sandbox Execution** | bwrap-based sandbox with LANDLOCK filesystem rules, streaming I/O, and process lifecycle |
| **File Management** | Workspace FS with watch, fuzzy search, snapshot/versioning, and non-destructive editing |
| **Replay & Debug** | Deterministic replay of turns, timeline, and messages for inspection |
| **Session Management** | Browse, search, archive, import/export conversation history |
| **Desktop App** | 15+ feature pages with real-time streaming, typewriter animation, and context menus |

---

## Quick Start

### Prerequisites

- **Python 3.11+** — to run MiQi backend
- **Node.js 20+** — to run Electron frontend
- **uv** — Python package manager (recommended)

### Installation

```bash
# 1. Clone the repository
git clone http://git.miqroera.com/intership/miqi-desktop.git
cd miqi-desktop

# 2. Install Python dependencies
uv sync

# 3. Install frontend dependencies
cd apps/desktop
npm install
```

### Development Mode

```bash
# Start Electron dev server with hot-reload
cd apps/desktop
npm run dev
```

### Production Build

**One-step build** (recommended):

```bash
cd apps/desktop
npm run build:all    # Python backend → Frontend compile → Electron package
```

**Step-by-step build**:

```bash
cd apps/desktop

# 1. Build Python backend (generates dist/miqi-bridge.exe)
npm run build:bridge

# 2. Compile frontend
npm run build

# 3. Package as desktop application
npx electron-builder --win --publish never
```

The packaged `miqi-bridge.exe` is a self-contained binary (PyInstaller onefile) that includes Python and all dependencies — no system Python installation required on the target machine. It also supports a `--check` flag for environment validation:

```bash
miqi-bridge.exe --check
# Output: {"ok": true, "python_version": "3.12.10", "issues": []}
```

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    MiQi Desktop App                         │
├─────────────────────────────────────────────────────────────┤
│  Electron Frontend                                          │
│  ├── React 19 + TypeScript                                 │
│  ├── Tailwind CSS 4 + shadcn/ui                            │
│  └── 15+ Feature Pages (Chat, Agents, Skills, MCPs, ...)   │
├─────────────

... (truncated)