Mayva

Getting started

Getting started

Clone, install, run. Five minutes from zero to a morning brief.

Updated · 2026-05-28

This is the fastest path to a working Mayva instance on macOS. Linux works for everything except voice; Windows works for everything except voice.

Prerequisites

You’ll need:

  • Node 20+ and pnpm 9 (brew install pnpm or corepack enable)
  • Docker (for the local Postgres / Redis dev stack)
  • A Claude Code login (the LLM hop rides your existing auth)
  • Optional: a Whoop account if you want the health-aware brief

Clone and install

git clone https://github.com/corporatethings/mayva.git
cd mayva
pnpm install

This installs every package in the monorepo. The first install pulls a few hundred MB — subsequent ones are instant thanks to pnpm’s content-addressed store.

Bring up the dev stack

pnpm db:up         # docker-compose up postgres + redis
pnpm migrate       # apply SQL migrations
pnpm seed          # optional: a small synthetic dataset

The DB lives in a docker volume named mayva_pgdata. To start completely over, pnpm db:down && docker volume rm mayva_pgdata.

Configure Whoop (optional)

pnpm whoop:auth

Opens your browser, hits Whoop’s OAuth, drops the refresh token into the local DB. From that point on, whoop-sync runs every 15 minutes and your morning brief is health-aware.

If you skip this step, the morning brief still works — it just shows NO SIGNAL on the recovery gauge.

Run the dashboard

pnpm -C packages/desktop dev

Electron window opens at the Today tab. Hero shows recovery (or NO SIGNAL), suggestions widget on the right, this morning’s brief below.

Trigger the morning brief manually

pnpm brief

That runs the brief worker once, against your current data. Should complete in 5–10 seconds. The output lands in the morning_brief table; the dashboard auto-refreshes.

Try voice

pnpm voice

Hold-to-talk overlay appears. Speak a task like “schedule a 30-minute deep work block at 4pm tomorrow.” Release. The agent transcribes locally with whisper.cpp, classifies the intent, inserts the row, and confirms via say.

What now?

  • Read Architecture for the big picture.
  • Read Memory model to understand the four layers.
  • Read Workers to see how to add your own.
  • Or just edit packages/workers/src/scheduled/morning-brief.ts and rerun pnpm brief. The prompt is right there in the file.