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

---

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

| Tool | Description | |------|-------------| | mq_get_dashboard | Full overview: goals, today's tasks, wallet, streaks, replan status | | mq_list_goals / mq_create_goal / mq_update_goal | Goal management | | mq_get_plan / mq_generate_plan / mq_adjust_plan | Plan management | | mq_get_today_tasks / mq_get_optional_tasks | Fetch tasks | | mq_complete_task / mq_skip_task | Report task status | | mq_get_wallet / mq_list_rewards / mq_redeem_reward | Coin & reward system | | mq_add_assessment / mq_get_user_state | Track progress assessments | | mq_get_streak / mq_get_streak_milestones | Streak info | | mq_get_replan_status | Check if AI action is needed (offline catch-up) | | mq_send_notification | Send a message to configured Discord channel | | mq_register_webhook | Register agent webhook URL for push events | | mq_get_settings / mq_update_settings | Global settings |

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:

| Event | Pushed to agent when… | Agent action | |-------|----------------------|-------------| | task_completed | optional_completion_rate === 1.0 | Ask user: plan too easy? Consider replan | | cycle_ended | always | Replan immediately, notify user | | daily_check_ran | any goal skip_rate_3d > 0.5 | Ask user why; decide whether to replan | | assessment_recorded | always | Review plan; replan if significantly changed |

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

mochi-quest