Moumantai (冇問題 / no problem) is an open-source, self-hosted runtime for personal apps that can be owned, adapted, and used across the devices around you.

Describe an app once: its data, capabilities, and interfaces. The server holds the state and application logic, then projects the appropriate face onto the browser, phone, watch, or embedded display in front of you. Code defines the reliable behavior; an LLM-powered agent adds language, interpretation, and judgment within those boundaries.

The result is an app, not a prompt: durable software that can be reused, inspected, shared, and remixed.

You drive; the agent helps.

Quick start · Architecture · Plugin apps · Agent backends · Clients · Develop

_{Talk to one agent; your mini apps render natively on every screen.}

Key features

• Yours, end to end — self-host the runtime and own the app's source, data, behavior, appearance, and deployment.
• Schema. Tools. Faces. — a deliberately familiar CRUD core: the schema owns state, tools mutate, and faces read. Direct UI and agent calls meet at the same tool boundary.
• Code for the known, an agent for the fuzzy — taps and forms stay deterministic; an LLM-powered agent brings language, flexibility, and judgment when useful.
• Bring your own agent and model — the agent supplies orchestration and tool use; the model supplies inference. Choose the combination that fits the task, provider, and budget.
• Polyphenic apps, native surfaces — one app wears many faces, specialized for each device and context. Thin clients map the same typed protocol to the toolkit that fits — from browsers and phones to watches and embedded panels — while the server carries the heavy compute.
• Apps, not prompts — code and interfaces are reused rather than regenerated on every request, saving tokens and making smaller or less expensive models practical. The result can be inspected, shared, forked, and personalized.
• Build, preview, promote — a coding agent can draft or edit an app in isolation, validate it, and preview it on paired devices; nothing goes live until you choose to promote it.

Moumantai is early and evolving; expect rough edges and changing APIs. Trying it, reporting what breaks, and contributing improvements are all welcome.

Quick start

Runs the server + PWA locally — the fastest path to a working app. Native clients are opt-in (see Running on your devices).

1. Set up. Clone with the plugin-apps submodule:

git clone --recurse-submodules https://github.com/xiang-deng/moumantai.git
cd moumantai
# Already cloned without --recurse-submodules? Run: git submodule update --init

Then install the toolchain — install mise (winget install jdx.mise · brew install mise · curl https://mise.run | sh), activate it in your shell (mise activate pwsh|bash|zsh), open a fresh shell, and run:

mise install && uv sync   # Node 22, Python 3.12, JDK 17, task, buf, uv
npm install               # links the TS workspaces (server, pwa, protocol)

2. Configure the server. An interactive wizard sets up the workspace (Moumantai Home — config, secrets, per-app data) and your LLM credential. Its first prompt asks where the workspace lives (default ~/.moumantai/; see Where your data lives):

By default the wizard expects a Claude credential — one of:

Prefer another agent harness, model, or provider? See Agent backends.

3. Start the server and the PWA in two terminals:

task server:dev   # Terminal A — WebSocket on ws://localhost:3000
task pwa:dev      # Terminal B — Vite on http://localhost:5174

4. Pair this browser. Pairing is on by default — the server only accepts allowlisted devices. Open an enrollment window:

task server:cli -- device pair   # opens a 5-minute enrollment window

Open http://localhost:5174; the PWA shows a pairing code. Back in the device pair prompt, type approve <code> — the browser connects within seconds. (Local-only? Disable with pairingRequired: false via task server:cli -- config edit, but keep it on for any networked server.)

5. Try it. In chat, type:

The spend-tracker plugin app picks it up via the agent, runs its add_expense tool, and re-renders the Summary face. Swipe up/down to switch faces within an app, left/right to switch apps.

6. Make it your own. The bundled spend-tracker shows the idea. From here you can:

• Install an existing app — from a local path, a git URL, or a registry id:

  task server:cli -- app install <path|url|id>
  task server:cli -- app list

• Edit one directly — work in TypeScript using the same schema, tool, face, and validation rules used by the coding agent.

• Use the coding agent — describe an app or change in the PWA's dev tab, preview its isolated draft, then promote it when ready.

Both are covered in full under Plugin apps.

Where your data lives

The server keeps all runtime state in one directory — Moumantai Home: config.json, secrets in .env, chat history, and each app's SQLite database. The setup wizard's first prompt picks where it goes:

• ~/.moumantai/ — the default; best for everyday use.
• <checkout>/.moumantai/ — project-local and gitignored; best for development and keeping multiple checkouts / worktrees isolated.

Not sure which home is active (common with multiple clones)? task server:cli -- workspace path prints it and which rule selected it. The full resolution order and the workspace set/reset commands live in server/CLAUDE.md.

Credentials are stored on the server and never sent to clients or plugin apps. The active agent backend uses them to authenticate with the provider you configure; prompts and relevant app context may be sent to that provider.

Architecture

Moumantai is a server-authoritative application runtime. The server owns state, execution, and coordination; plugin apps, agent backends, and clients connect through explicit contracts.

The design follows a few strict boundaries:

• Tools mutate; faces read; parameters steer presentation.
• The server is authoritative; clients render and report intent.
• Agent backends request actions; the server validates and executes them.
• Device specialization happens on the server, outside plugin business logic.
• Apps do not depend on a particular client, agent harness, or model.

Implementation detail lives with each boundary: the server, app examples, protocol, and client READMEs.

Plugin apps

An app is a small TypeScript plugin: a Drizzle schema, defineTool tools, and defineFace faces. Example apps ship in the apps/ submodule and serve as working references.

Install or remix an existing app

Install from a local path, git URL, or registry id; installed source remains available to inspect and change:

task server:cli -- app install <path|url|id>
task server:cli -- app list

Edit directly

Write or modify the TypeScript yourself. Humans and coding agents follow the same rules in CLAUDE.md and the build-moumantai-app / edit-moumantai-app skills. Validate app changes with task apps:typecheck.

Use the coding agent

Enable dev mode (MOUMANTAI_DEV_MODE=1, or devMode: true in .moumantai/config.json) and describe an app or change in the PWA's dev tab. The agent works through an isolated draft: draft → validate → preview → promote or discard. Nothing touches the live app until you choose to promote it.

Dev mode is off by default; restart the server after enabling it.

Agent backends

The server integrates intelligence through an agent backend contract. A backend connects its agent harness and chosen model to app context, tools, and faces; the server keeps ownership of tool execution and state.

Select the backend in .moumantai/config.json. Provider/model selection and authentication details are covered in server/CLAUDE.md.

Clients

Clients are independent implementations of the shared protocol. Each maps the same component vocabulary to the toolkit and interaction model that fits its platform.

Per-client setup lives in each client's README: PWA · Android · Wear OS · ESP32.

Running on your devices

The PWA has three deliberately different modes:

For secure remote access, start the server and PWA in separate terminals, then expose each loopback service through Tailscale Serve:

task server:dev
task pwa:serve:tailscale TAILSCALE_HOST=<host>.<tailnet>.ts.net

tailscale serve --bg --https=443 http://localhost:4173
tailscale serve --bg --https=8443 http://localhost:3000

Open https://<host>.<tailnet>.ts.net. The PWA connects to wss://<host>.<tailnet>.ts.net:8443; both endpoints remain inside the tailnet with TLS. A plain http://<host>:<port> URL may be reachable but is not an installable secure context.

Native clients are opt-in, and each connects to the same server and must be paired the same way — task server:cli -- device pair, then approve the code shown on the device (see Quick start).

cp .mise.local.toml.example .mise.local.toml

Develop

Every workspace exposes its commands through Task. Use task --list-all for the complete, current inventory.

Run and verify

Regenerate shared outputs

Start with CLAUDE.md — codebase rules and dev workflow. Subsystem-specific rules live in <dir>/CLAUDE.md files (auto-loaded by Claude when working in that subtree). One gotcha worth knowing up front: hot-reload does not propagate to transitive imports — touch an app's index.ts or restart the server after editing its parts.ts / schema.ts (details in server/CLAUDE.md).

Repository layout

moumantai/
├── server/             # Node WebSocket server + agent + protocol handling
├── clients/
│   ├── pwa/            # Progressive Web App client (React + Vite)
│   ├── android/        # Phone client (Kotlin + Compose M3)
│   ├── wear-os/        # Watch client (Kotlin + Wear Compose)
│   └── esp32/          # HMI panel firmware (ESP-IDF + LVGL)
├── shared/
│   ├── protocol/       # Wire protocol SSOT (.proto + generated TS/Kotlin/C bindings)
│   └── tokens/         # Design tokens (YAML, codegen targets each client)
├── apps/               # Plugin apps (submodule of moumantai-apps; loaded at runtime)
├── scripts/            # Codegen + dev helpers
└── docs/               # Architecture / design docs

The TypeScript pieces (server/, clients/pwa/, shared/protocol/) are npm workspaces. Native clients (clients/android, clients/wear-os, clients/esp32) are independent — each uses its own native build tool.

Troubleshooting

Documentation

Contributing

Contributions are welcome — including via coding agents. Start with CLAUDE.md (codebase rules and dev workflow), use the issue and PR templates under .github/, and follow the Code of Conduct.

Security

Found a vulnerability? Please report it privately — see SECURITY.md.

License

MIT