MiQi

🐈‍⬛🪶 A lightweight, extensible personal AI agent framework with a modern desktop interface

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.

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

# 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

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

Production Build

One-step build (recommended):

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

Step-by-step build:

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:

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, ...)   │
├─────────────────────────────────────────────────────────────┤
│  Bridge (IPC Communication)                                 │
│  ├── stdin/stdout JSON-line protocol                        │
│  ├── State synchronization + Log forwarding                 │
│  └── BridgeRuntimeLoop (persistent asyncio event loop)      │
├─────────────────────────────────────────────────────────────┤
│  AppServer (Typed Protocol Layer)                            │
│  ├── ProtocolRegistry (typed method specs)                  │
│  ├── Typed Envelopes (Pydantic v2)                          │
│  ├── JSON Schema Draft 2020-12 Catalog                      │
│  └── Handler Typed Validation                               │
├─────────────────────────────────────────────────────────────┤
│  MiQi Runtime Engine                                        │
│  ├── RuntimeSession / TaskRunner / TurnRunner               │
│  ├── HistoryRuntime + LedgerRuntime (SQLite persistence)    │
│  ├── ContextRuntime (compaction, token budgeting)           │
│  ├── ThreadRuntime (fork, rollback, import/export)          │
│  └── ReplayRuntime (deterministic replay inspection)        │
├─────────────────────────────────────────────────────────────┤
│  Execution & Sandbox                                        │
│  ├── ToolOrchestrator (approval → sandbox → execute)       │
│  ├── PermissionEngine + ApprovalPolicy + HookRuntime        │
│  ├── bwrap Sandbox (LANDLOCK, streaming, cancellation)      │
│  └── Workbench Process Runtime (command/exec, process/*)    │
├─────────────────────────────────────────────────────────────┤
│  Tools & Integrations                                       │
│  ├── Built-in Tools (filesystem, shell, web, papers, ...)   │
│  ├── MCP Client (external tool servers)                     │
│  ├── Plugin Manager + Skill Loader                          │
│  └── Office Document Tools (docx, pptx, xlsx)               │
└─────────────────────────────────────────────────────────────┘

Launch the application
Go through the setup wizard:
- Environment Check — validates Python and dependencies (bundled exe auto-detects; dev mode checks system Python)
- WSL2 Setup — (Windows only) auto-detects and installs WSL2 for sandbox support
- LLM Provider — configure API keys and default model
Start chatting with the AI agent

Protocol Method Families

Family	Scope	Methods
`turn/*`	Turn	start, interrupt, steer
`thread/*`	Thread	list, get, rollback, fork, delete, compact/start, inject_items
`fs/*`	Filesystem	readFile, writeFile, createDirectory, getMetadata, readDirectory, remove, copy, watch, unwatch
`fuzzyFileSearch/*`	Filesystem	sessionStart, sessionUpdate, sessionStop
`command/exec`	Process	exec, exec/write, exec/resize, exec/terminate
`process/*`	Process	spawn, writeStdin, resizePty, kill, list, get, snapshot
`replay.*`	Debug	turns, timeline, messages
`config/*`	Session	get, batchWrite
`model/*`	Session	list, get
`feature/*`	Session	list, set
`permission/*`	Session	listProfiles, getProfile
`plugin/*`	Session	list, install, uninstall, enable, disable, configure
`skills/*`	Session	list, get, create, upload, delete, setExtraRoots
`mcp/*`	Session	listServers, getServer, status
`agent/*`	Session	list, get, spawn, kill
`protocol/*`	Connection	catalog, method_names, schema

Configuration

The application configuration file is located at ~/.miqi/config.json:

{
  "providers": {
    "openai": { "apiKey": "sk-..." },
    "anthropic": { "apiKey": "sk-ant-..." }
  },
  "agents": {
    "defaults": {
      "model": "claude-sonnet-4-6",
      "temperature": 0.1,
      "maxToolIterations": 100
    }
  },
  "tools": {
    "restrictToWorkspace": true
  }
}

Environment Variables

Variable	Description
`MIQI_PYTHON_PATH`	Custom Python interpreter path
`MIQI_AGENTS__DEFAULTS__MODEL`	Override default model

Development Guide

Project Structure

miqi-desktop/
├── miqi/                         # Python backend
│   ├── runtime/                  # Runtime engine (AppServer, Session, Turn, Thread, Replay, Agent, MCP, ...)
│   ├── agent/                    # Agent logic, tools, memory, trace, context compression, smart routing
│   ├── bridge/                   # Electron bridge service (IPC protocol)
│   ├── bus/                      # Internal message bus (async in/out queues)
│   ├── execution/                # Tool orchestrator, permissions, approval, hooks, sandbox policy
│   ├── providers/                # LLM provider implementations + resilience
│   ├── protocol/                 # Typed commands, events, permissions (runtime-frontend protocol)
│   ├── channels/                 # Chat channel adapters (Feishu, Slack, Discord, Telegram, ...)
│   ├── sandbox/                  # bwrap sandbox manager
│   ├── skills/                   # Built-in skills (cron, paper-research, feishu-report, ...)
│   ├── session/                  # Session management (Manager, SQLite store)
│   ├── config/                   # Configuration loader and schema
│   ├── cli/                      # CLI commands (agent, gateway, trace, config)
│   ├── cron/                     # Cron scheduler service
│   ├── context/                  # Context fragments, thread store
│   ├── heartbeat/                # Heartbeat service
│   ├── plan/                     # Plan tracker and tool
│   ├── documents/                # Office document tools (docx, pptx, xlsx)
│   ├── observability/            # OpenTelemetry integration
│   ├── server/                   # Server assets and configuration
│   ├── templates/                # Templates
│   ├── tui/                      # Terminal UI (Textual-based)
│   └── utils/                    # Utility functions
├── apps/
│   └── desktop/                  # Electron frontend
│       ├── src/main/             # Main process (BridgeManager, IPC handlers)
│       ├── src/renderer/         # Renderer (React pages and components)
│       └── src/preload/          # Preload scripts (contextBridge API)
├── tests/                        # Test suite (~150+ test files)
│   ├── runtime/                  # Runtime unit and integration tests (~70+ files)
│   ├── bridge/                   # Bridge protocol and audit tests (~20+ files)
│   ├── execution/                # Sandbox, permissions, orchestration tests
│   ├── providers/                # LLM provider tests
│   ├── protocol/                 # Protocol commands/events/permissions tests
│   └── agent/tools/              # Tool-level tests
├── docs/                         # Documentation (MkDocs)
├── plan/                         # Implementation plans (not in VCS deliverables)
└── scripts/                      # Build and utility scripts

Code Standards

Python: Ruff for linting (line-length 100)
TypeScript: ESLint for linting
Commit Messages: Conventional Commits format

Testing

# Python backend tests (~1800+ tests)
uv run pytest

# Skip sandbox/subprocess tests for quick feedback
uv run pytest -m "not sandbox and not subprocess"

# Frontend tests
cd apps/desktop
npm run test

E2E Tests

# Electron E2E (full desktop app + bridge + LLM)
cd apps/desktop
npm run build && npx playwright test --config=playwright.config.ts --project=electron

Platform	E2E Coverage	Notes
Linux (Ubuntu CI)	Full suite ✓	bwrap sandbox + all specs
Windows (WSL CI)	Full suite ✓	WSL bwrap sandbox + all specs (needs `MIQI_RUN_SANDBOX_E2E=1`)
macOS (CI)	Non-sandbox only	bwrap not available; sandbox specs excluded via `--grep-invert`

macOS known limitation: The "restart recall" E2E test (session-context-recall.spec.ts) is skipped only when process.env.CI && process.platform === 'darwin' (local macOS runs still exercise the test). After a full app restart on macOS ARM64 CI runners, session history (chat messages) fails to render in <main> even though the sidebar session title loads correctly and the bridge reports running / initialized. This is likely a bridge IPC timing issue or APFS/SQLite WAL checkpoint race on cold start — needs native debugging. The non-restart session-switch recall test still validates #490 behavior on macOS.