Mochi Quest 🍡

An open-source, AI-powered personal growth coaching system.

Mochi Quest lets you describe your goals — lose weight, learn English, become a Googler — and an AI coach builds a personalized plan, assigns daily tasks, tracks your progress, and dynamically adjusts when things get too hard or too easy.

Agent-agnostic: works with Claude, GPT, Gemini, or any MCP-capable AI agent.

Features

• Goal clarification — AI interviews you to understand your situation, constraints, and current level before building a plan

• Cycle-based planning — AI plans a full cycle (7–14 days) with a per-day task menu; daily allocation runs instantly from the DB (no LLM latency)

• Dynamic replan — triggers automatically at cycle end, when skip rate is high, or when all optional tasks are done (too easy)

• Multi-goal balance — set a weight per goal; daily tasks are allocated proportionally within your daily limit

• Coin + reward system — earn coins from tasks, redeem for self-defined rewards; AI adjusts pricing if a reward conflicts with your goals

• Streak tracking — per-goal streaks + global streak (all goals done = global +1); milestone bonuses at 7/30/100/365 days

• Web dashboard — local UI for checking off tasks, viewing plan roadmap, wallet, and streaks

• Real-time updates — SSE pushes events to the UI instantly

• Background daemon — node-cron daily check at 4am (configurable): streak update, task allocation, cycle-end detection, replan flagging

• Push notifications — server POSTs typed events to the agent's webhook URL (pre-filtered); agent uses Discord to ask the user questions or report results

Related MCP server: agent-runtime-mcp

Architecture

┌──────────────────────────────────────────┐
│               AI Agent Layer              │
│   Claude / GPT / Gemini / any MCP agent  │
│   ┌──────────────────────────────────┐   │
│   │          SKILL.md                │   │
│   │  coaching behavior & decisions   │   │
│   └──────────────────────────────────┘   │
└──────────────────┬───────────────────────┘
                   │ MCP (stdio)
┌──────────────────▼───────────────────────┐
│         MCP Server  (Node.js)            │
│  Goals · Plans · Tasks · Wallet · Streaks│
│  ┌─────────────────────────────────────┐ │
│  │    SQLite  (~/.mochi-quest/data.db) │ │
│  └─────────────────────────────────────┘ │
│  REST API :3030  ←──── Web UI (React)    │
│  node-cron (4am daily check, daemon)     │
└──────────────────────────────────────────┘

One command (mochi-quest start) runs the MCP server, REST API, and scheduler together.

Quick Start

Prerequisites

• Node.js 20+

• pnpm 9+

• An MCP-capable AI agent (Claude Code, Cursor, etc.)

Install

git clone https://github.com/YOUR_USERNAME/mochi-quest.git
cd mochi-quest
pnpm install

Build

# Build server
cd packages/server && pnpm build

# Build web UI
cd packages/web && pnpm build

Run

# Start everything (MCP + REST API + scheduler + built Web UI)
node packages/server/dist/index.js start

# Or as a background daemon
node packages/server/dist/index.js start --daemon

The web dashboard is available at http://localhost:3030.

Docker

docker compose up -d --build

The Docker server stores SQLite data in the mochi_quest_data volume and serves the built Web UI, REST API, scheduler, and MCP entrypoint from one container.

Full deployment notes: docs/deployment.md.

Connect to your AI agent

Add the MCP server to your agent's config:

Claude Code (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "mochi-quest": {
      "command": "node",
      "args": ["/path/to/mochi-quest/packages/server/dist/index.js", "mcp"]
    }
  }
}

Then install skills/mochi-quest/ as a skill (or paste the SKILL.md body into your system prompt).

MCP Tools

Full tool reference: packages/skill/SKILL.md

Project Structure

mochi-quest/
├── packages/
│   ├── server/          # MCP Server + REST API (Node.js + TypeScript)
│   │   └── src/
│   │       ├── db/      # SQLite schema & queries
│   │       ├── mcp/     # MCP tool implementations
│   │       ├── api/     # REST API routes (Hono)
│   │       └── scheduler.ts  # node-cron daily check + notifications
│   ├── web/             # Web dashboard (React + Vite + Tailwind)
│   │   └── src/
│   │       ├── pages/   # Dashboard, Goals, Tasks, Wallet, Settings
│   │       ├── components/
│   │       ├── hooks/   # useSSE for real-time updates
│   │       └── lib/     # API client + types
│   └── skill/
│       └── SKILL.md     # AI coaching behavior definition
└── docs/
    └── spec.md          # Full system specification

How It Works

Planning vs Execution

The AI generates a cycle-based plan (7–14 days) during planning sessions — a day-by-day schedule where each day has specific tasks, plus an optional pool for the whole cycle. The server allocates daily tasks by day_in_cycle with no LLM call, so the UI loads instantly.

Event-driven Replan

Every meaningful state change emits a typed event through a unified pipeline:

emitEvent(type, data)
  ├── writeLog()           → DB audit log
  ├── emitSseEvent()       → Web UI badge (real-time)
  └── notifyAgentWebhook() → Agent HTTP endpoint (pre-filtered)

The server pre-filters before pushing — the agent only receives actionable signals:

The agent registers its webhook URL via mq_register_webhook or the settings page. As offline catch-up, mq_get_replan_status() at session start returns any pending replans from while the webhook was offline.

Multi-goal Task Allocation

Each goal has a daily_task_weight (1–5). Tasks are allocated proportionally:

weights = [3, 2, 1]  →  budget = 6  →  tasks = [3, 2, 1]

Adjust weights any time: "Focus more on English this week."

Data Storage

All data is stored locally in ~/.mochi-quest/data.db (SQLite). No cloud sync, no accounts.

Notifications (Daemon Mode)

node packages/server/dist/index.js start --daemon

The built-in scheduler runs a daily check at the configured notification time (default: 08:00) and sends a native OS notification when there are pending tasks.

• macOS: Notification Center

• Windows: Toast Notification

• Linux: libnotify (notify-send)

Roadmap

• Integration adapters (Fitbit, Garmin, Duolingo, LeetCode)

• Habitica sync (push tasks to Habitica, webhook completion back)

• Server-driven replan (server calls LLM directly in daemon mode)

• Apple Health companion app

• Auto-start installer (mochi-quest setup)

Contributing

Pull requests welcome. Please open an issue first to discuss larger changes.

License

MIT