An unofficial brewing companion for xBloom Studio. Snap a photo of a coffee bag, let AI read the label (and look the bean up online), design a pour-over recipe, and send it straight to your xBloom — it appears in the xBloom app, ready to brew. Save recipes, log how each brew tasted, and let the AI dial them in.
Phone-first. Built to use standing next to the machine.
Unofficial project — not affiliated with xBloom. It uses a community reverse-engineered API that may break at any time. Please read DISCLAIMER.md before using.
- 📷 Photo → recipe — vision model reads the bag (front + back), designs a pour-over tailored to the beans using brewing science.
- 🔎 Smart lookup — sparse bag? Paste the product URL or let it search the web for the roaster's origin/process/notes. Sources are shown so you can verify.
- 📝 Your notes — tell the AI your preferences ("brighter, 18g dose").
- ☕ One-tap to xBloom — recipe syncs to your xBloom app instantly. Edits re-push in place.
- 🧠 Taste feedback loop — "too bitter / sour / weak" → AI adjusts grind, temp, and ratio using real extraction theory. One-tap "brighter / sweeter" variations too.
- 📖 Brew log — rate each brew and keep tasting notes per recipe.
- 📥 Import — pull recipes already on your xBloom account in to tweak.
- 🎨 Light & dark — light by default, toggle persisted.
- 📱 PWA — Add to Home Screen for an app-like feel.
This is a self-hosted template: you run your own copy with your own accounts. Your xBloom credentials live only in your deployment.
Then, in your new Vercel project:
- Storage → Neon — add the Neon integration. It sets
DATABASE_URLautomatically. (Tables are created on first use.) - AI Gateway — enable it and add
AI_GATEWAY_API_KEY(used for the vision model + web search). Make sure the gateway has credits. - Confirm
XBLOOM_EMAILandXBLOOM_PASSWORDare set. - Settings → Deployment Protection → On.
⚠️ Important: this keeps your deployment private to you. Anyone who can reach the app brews into your xBloom account.
Requires Node 20+ and pnpm.
git clone https://github.com/hgstrm/pourpilot.git
cd pourpilot
pnpm install
cp .env.example .env.local # fill in the values (see below)
pnpm devOpen http://localhost:3000.
pnpm xbloom:test # pushes a sample recipe, lists to confirm
XBLOOM_CLEANUP=1 pnpm xbloom:test # same, then deletes the test recipe| Var | Required | What |
|---|---|---|
XBLOOM_EMAIL |
yes | Your xBloom account email (server-side only) |
XBLOOM_PASSWORD |
yes | Your xBloom account password (server-side only) |
AI_GATEWAY_API_KEY |
yes | Vercel AI Gateway key (vision + web search) |
DATABASE_URL |
yes | Neon Postgres connection string (or POSTGRES_URL) |
AI_MODEL |
no | Model id, default openai/gpt-4o (must support vision + web search) |
Credentials are used server-side only — the browser never sees your xBloom password, and it's never written to the database.
photo(s) ─▶ /api/analyze ─▶ read bag (vision) ─▶ research (web search, if sparse)
│
▼
design recipe (AI)
│
review & tweak ◀──────────────────────────────────┘
│
├─ save ─▶ Neon Postgres (recipes, brews)
└─ send ─▶ /api/push ─▶ xBloom cloud API (RSA-encrypted) ─▶ xBloom app
- Framework: Next.js (App Router) + TypeScript, deployed on Vercel.
- AI: Vercel AI Gateway via the AI SDK; structured output validated with Zod; native web search tool for bean lookups.
- Storage: Neon serverless Postgres.
- xBloom client (
src/lib/xbloom/client.ts): logs in, RSA-encrypts the payload, and creates/edits/lists/deletes recipes.
The xBloom API integration is based on the reverse-engineering work in denull0/xbloom-agent — huge thanks. Go star it.
Issues and PRs welcome — see CONTRIBUTING.md. Be kind (Code of Conduct).
MIT · See DISCLAIMER.md for important notes about the unofficial xBloom API.