English · 中文

An AI-native, desktop-first, Web-capable cross-platform app scaffold
An extensible Tauri 2 + Vue 3 foundation: desktop is primary, with Beta-level Web and mobile adaptation.
The stable core covers local data, tray integration, and a design system; sync, updater, Agent, MCP, and local inference are enabled according to maturity.

meow-starter is a modular, AI-native cross-platform app scaffold. It takes care of the repetitive engineering behind desktop and multi-runtime products—data access, system tray behavior, updates, and a design system—while exposing Agent, local inference, and MCP capabilities as pluggable modules that can be enabled only when a product needs them.

Core philosophy: keep the core small, make capabilities optional, and add them on demand. Without any Agent code it remains a clean desktop scaffold. A Preview capability becomes a product feature only after the downstream project explicitly configures and verifies it.

Turn something you want to learn into a small step you can finish, prove, and revisit.

Shixue is a personal learning record assistant built from meow-starter and the first public reference application in this ecosystem. It demonstrates how the general scaffold can be shaped into a focused product without bypassing its data, module, security, or release boundaries.

Explore the Shixue source, screenshots, and setup guide →

Shixue v0.2.3 publishes Windows installers, a Portable EXE, updater metadata, and signed updater payloads. Its Windows binaries are not Authenticode-signed, so code-signing identity, SmartScreen reputation, and end-to-end upgrade validation remain separate work. Every downstream app must configure and protect its own updater endpoint and signing key.

Android has local debug evidence, but that is not evidence of signing, real-device behavior, store acceptance, or production update delivery. See docs/delivery-path.md for the full boundary and next steps.

• Frontend: Vue 3.5 + TypeScript 5.6 + Vite 8, with system-aware dark mode
• Data layer: one domain interface; SQLite on Tauri and IndexedDB on Web
• System integration: system tray, single-instance behavior, and close-to-tray instead of quit
• Auto-update (Beta): signing, download, install, and relaunch code paths; requires a downstream endpoint and signing keys before release validation
• Design system: complete design tokens, six base components, and four themes
• Modularity: four gates—configuration, dynamic import, runtime capability, and native Cargo feature
• Sync foundation (Preview): opt-in outbox engine, collection allowlist, and HTTP transport without vendor lock-in
• Agent (Preview): Vercel AI SDK inline adapter and extension interfaces; off by default
• Secret safety (Preview): stored keys cannot be read back by the WebView; OpenAI and Anthropic calls use a fixed-target Rust proxy
• Local inference (Preview): Ollama/OpenAI-compatible presets that require verification on the developer's machine
• MCP (Preview): HTTP/SSE client adapter; the complete Agent tool loop is still being verified
• Engineering: GitHub Actions CI gates plus a three-desktop-platform draft-release template that stays blocked until real updater and signing configuration is supplied
• No Electron: application bundles are typically around 3–20 MB instead of roughly 300 MB

New to the project? Follow this path:

For AI agents: this repository has explicit module boundaries and a routed documentation set. Read the relevant document before changing a feature.

# Option 1: clone the repository
git clone https://github.com/Shiaoming123/meow-starter.git my-app
cd my-app && npm ci && npm run tauri dev

# Option 2: use degit for a clean copy without Git history (recommended)
npx degit Shiaoming123/meow-starter my-app
cd my-app && npm ci && npm run tauri dev

Web only:

npm run dev:web

Prerequisites: Node.js 22+, Rust 1.77.2+, and platform dependencies. macOS requires Xcode Command Line Tools, Windows requires MSVC and WebView2, and Linux requires webkit2gtk and related packages. See the Tauri prerequisites.

tauri dev is a developer workflow, not an end-user delivery format. Before calling a downstream app usable, follow the application development and delivery standard and verify a package or Portable executable that a non-developer can launch by double-clicking.

Missing any of these items can break the build or collide with another application's identity:

1. name in package.json
2. name and [lib] name in src-tauri/Cargo.toml (lib name = underscored package name + _lib)
3. productName and identifier in src-tauri/tauri.conf.json (⚠️ treat the identifier as immutable after release)
4. Replace public/meow-mark.svg, then run npm run tauri -- icon public/meow-mark.svg -o src-tauri/icons
5. Regenerate the updater signing key with npm run tauri:signer
6. Replace OWNER/REPO in plugins.updater.endpoints with the downstream repository
7. Update repository, homepage, and author metadata in package.json and src-tauri/Cargo.toml
8. Replace UI branding, the tray tooltip, and the keychain namespace in src-tauri/src/agent/secrets.rs
9. Keep versions synchronized across package.json, src-tauri/Cargo.toml, and src-tauri/tauri.conf.json

Each capability is a pluggable module controlled by src/modules/config.ts:

See docs/modular-architecture.md for the complete design. Disabled modules are not loaded by the default runtime path. Use the lockfile and actual build output—not this table—to assess dependency and bundle size.

src/modules/contract.ts is the static catalog for module platforms, runtime capabilities, dependencies, and native build requirements. The assembler filters this catalog before dynamic import and rejects loaded modules whose declarations differ from their contract before setup begins.

Native build configuration is a separate plane: a frontend toggle never enables a Cargo feature or grants a Tauri permission. After changing default module configuration, validate the intended target:

npm run check:modules          # desktop target (default)
npm run check:modules -- web   # Web target

This validates checked-in configuration consistency only. It does not change Cargo features or permissions, and it is not evidence of plugin behavior, installable packages, signing, or device behavior.

The Vue frontend communicates with the Rust runtime through invoke and listen. The module loader assembles enabled capabilities in dependency order. Agent, Ollama, cloud-provider, and MCP integrations live in the Preview extension layer and are not loaded on the default path.

The same Vue codebase targets Web / macOS / Windows / Linux / Android / iOS. Desktop is the primary validation target. Web uses IndexedDB and skips native-only modules, while mobile uses responsive layouts and degrades desktop-specific capabilities.

.
├── .github/               # CI gates and a three-desktop-platform release template
├── docs/                  # Documentation hub
│   ├── architecture.svg        # Architecture diagram
│   ├── application-standard.md # Product UI, defaults, and double-click delivery standard
│   ├── development.md          # Local development, verification, and exFAT guidance
│   ├── release-kit.md          # Release Kit and release maturity boundaries
│   ├── windows-distribution.md # Windows Portable and Authenticode guidance
│   ├── design-system.md        # Tokens, components, themes, performance, accessibility
│   ├── project-guide.md        # Project fit and product-type guidance
│   ├── modular-architecture.md # Four module gates and the compatibility contract
│   ├── ai-capabilities.md      # AI-native capability roadmap
│   ├── agent-integration.md    # Agent integration and security architecture
│   ├── local-inference.md      # Ollama and local inference
│   ├── web.md                  # Web runtime, persistence, and deployment
│   ├── sync.md                 # Account, cloud, and LAN sync boundaries
│   └── mcp.md                  # MCP integration guide
├── src/
│   ├── assets/themes/     # Theme tokens and global styles
│   ├── components/        # Icon.vue and reusable UI components
│   ├── modules/           # Configuration, loader, and capability modules
│   ├── agent/             # Agent runtime, providers, tools, memory, hooks, and UI
│   ├── storage/           # Domain ports plus IndexedDB, SQLite, and memory adapters
│   ├── sync/              # SyncProvider, outbox, and HTTP transport
│   ├── lib/               # db.ts and updater.ts
│   └── App.vue            # Demonstration application
├── src-tauri/
│   ├── src/lib.rs         # Application assembly and feature gating
│   ├── src/tray.rs        # System tray behavior
│   ├── src/db.rs          # SQLite migrations
│   ├── src/agent/         # Native secret and provider proxy boundary
│   ├── capabilities/      # Tauri permission allowlist
│   └── tauri.conf.json    # Tauri application configuration
├── agent.config.ts        # Agent model, provider, and tool configuration
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── CHANGELOG.md
└── LICENSE

The frontend accesses domain interfaces through src/lib/db.ts. Tauri SQLite migrations are defined in src-tauri/src/db.rs and run during startup; the Web runtime stores data in IndexedDB. See docs/web.md.

📌 Each migration must contain one SQL statement only because the underlying sqlx execute call does not support multiple statements.

The Todo example also exposes an optional, versioned JSON data port. await exportTodos() emits application-domain data, while await importTodos(json) validates the complete payload before appending records and returning the imported count. It does not export database files, keys, Agent state, or sync state. Import does not overwrite existing data, and repeated imports intentionally create duplicate records. Product UI should request explicit user confirmation before import.

src-tauri/src/tray.rs registers left-click window toggling and a right-click menu for showing or hiding the window, checking for updates, and exiting. Together with single-instance handling, reopening the app focuses the existing window.

src/lib/updater.ts wraps check() → downloadAndInstall() → relaunch(). Tauri verifies updater signatures. Configure a downstream application before its first release:

npm run tauri:signer
# Put the public key in plugins.updater.pubkey in tauri.conf.json
# Store the private key as the TAURI_SIGNING_PRIVATE_KEY GitHub secret
# Replace OWNER/REPO in plugins.updater.endpoints with the downstream repository

🔑 Losing the updater private key prevents future releases from updating existing installations. Back it up securely and never commit it.

A template placeholder endpoint is treated as unconfigured at build time, so the application does not request an invalid update URL.

The Agent module is off by default. To enable its dependencies:

npm run add:agent
# Set enabled: true in agent.config.ts, then configure providers and a default model

Cloud providers such as OpenAI and Anthropic, as well as local Ollama-compatible models, are supported by the extension layer. Cloud secrets are stored in the operating system keychain; the WebView can write, delete, and test whether a key exists but cannot read the plaintext value back. Rust injects secrets only for fixed official provider targets. See docs/agent-integration.md and docs/local-inference.md.

⚠️ The cloud proxy uses an allowlist: by default only api.openai.com and api.anthropic.com are allowed. Local Ollama or vLLM endpoints use the direct path. DeepSeek, Moonshot, Groq, and other OpenAI-compatible cloud services are rejected when configured with keychain-backed secrets until the allowlist is extended deliberately. See docs/agent-integration.md §3.4.1.

MCP is off by default. To add its dependencies:

npm run add:mcp
# Enable mcp in modules/config.ts and connect a server with connectMcpServer

See docs/mcp.md.

The design system provides restrained typography, spacing, radius, shadow, motion, and layer tokens; six base components; and four themes. Downstream products use self-hosted Manrope Variable for Latin text and numbers, Noto Sans SC Variable for Chinese, and a restrained iOS-inspired acrylic treatment. See the application standard and design system.

The two smoke commands are local acceptance checks and are not part of default CI or npm run verify. The Web smoke does not download a browser; it uses an installed Edge or Chrome and honors MEOW_BROWSER_PATH when automatic discovery fails. The Windows smoke temporarily disables updater artifacts, constrains installation and app data to src-tauri/target/meow-windows-package-smoke-*, terminates only the process it started, and removes only its validated temporary directory.

These checks do not prove code signing, hosted updater delivery, offline installation, graceful tray exit, store approval, or release readiness on any platform.

• The production Tauri CSP permits same-origin resources and Tauri IPC only. Declare each required external source precisely; do not relax it with wildcards.
• Treat the application identifier as immutable after release.
• API keys belong in the operating system keychain, not source code or localStorage; stored keys have no plaintext read command.
• Sync uses a collection allowlist. API keys, tokens, cookies, MCP credentials, and local paths must never enter the generic sync layer.
• A new plugin requires coordinated changes to Cargo.toml, lib.rs, and capabilities/default.json.

Issues and pull requests are welcome. Read CONTRIBUTING.md and the Code of Conduct. Report security vulnerabilities through SECURITY.md.

• 🐛 Bugs and feature requests → Issues
• 💬 Questions and ideas → Discussions
• ❤️ Support the project → GitHub Sponsors

MIT © 2026 Shiaoming123

Tauri · Vue.js · Lucide · Vercel AI SDK · Model Context Protocol