Coffee Coach AI
Documentation

How Coffee Coach AI works

A full reference for every major system in the app.

How Live Coaching Works

The data pipeline

Coffee Coach AI reads RoasTime's live log folder:~/Library/Caches/roast-incomplete/ on macOS or%LOCALAPPDATA%\roast-incomplete\ on Windows. RoasTime writes a live log roughly every 5 seconds during an active roast.

Every 15 seconds, Coffee Coach AI assembles a coaching request containing:

  • The current telemetry snapshot
  • A rolling window of recent telemetry history (up to 800 samples, so the AI sees the full roast curve, not just the latest reading)
  • Your bean's context: name, origin, process, target roast level
  • Your RoastIQ operator profile: a compact summary of your patterns from past sessions
This is why advice can say “RoR is flattening earlier than your last three roasts of this bean.” The AI sees the shape of this roast and knows your history with this coffee.

Timing

  • Telemetry is read from RoasTime every 3 seconds and accumulated. Every 15 seconds, that telemetry history is sent to your AI model for a coaching call.
  • If no action is needed, a reassurance notification arrives approximately every 2 minutes so you know Coffee Coach AI is still watching
  • No coaching fires during preheat. It begins when the Bullet transitions to the active roast phase

Bean identification

When RoasTime detects a new session, Coffee Coach AI prompts you to confirm or name the bean being roasted. This context is included in every coaching prompt, so advice is always specific to the coffee in the drum.

Privacy & Data

Does Coffee Coach AI collect my data?

No. Coffee Coach AI has no backend servers, no Coffee Coach account, and no server-side database. We cannot access your API key, roast logs, prompts, AI responses, RoastIQ profile, or notes.

Your roast data stays yours. We never receive, store, sell, or inspect your roast data. We could not anyway: nothing is sent to us or transmitted to us, and we have no visibility into your data at all, ever.

What leaves my computer?

Only the AI request needed for coaching leaves your computer: roast telemetry, bean context, and the relevant local RoastIQ context. It travels from Coffee Coach AI through your own OpenRouter account to the AI model provider you choose, subject to those services' policies.

Your API key is stored securely on your device in the macOS Keychain or Windows Credential Locker. Local app data remains in your local Coffee Coach AI database unless you remove it.

RoastIQ

RoastIQ is the system that makes Coffee Coach AI improve with use. It is not machine learning, and no model weights ever change. The app maintains a compact rolling text profile on your computer.

How it builds your profile

After each roast, a single API call distills a short pattern from the session's coaching events, telemetry, and analysis. These patterns are merged into a capped rolling profile stored in a local SQLite database.

The profile updates automatically when:

  • A live roast ends
  • You generate a post-roast analysis
  • You import a historical CSV
  • You rate a session thumbs up or thumbs down

How it improves coaching

The profile is injected into every live coaching system prompt. After 5–10 sessions, advice noticeably reflects your machine, your bean preferences, and your roasting style.

Privacy. The profile lives on your computer. The only data that leaves is the coaching prompt sent through your own OpenRouter account to the model provider you choose. It is never sent to Coffee Coach AI.

Importing a Roast

Coffee Coach AI can import any roast you previously exported from RoasTime as a CSV.

Steps

  1. 1In RoasTime: File → Export → CSV
  2. 2In Coffee Coach AI: click the menu bar or system tray coffee cup → Import CSV
  3. 3Select the CSV file

What importing does

  • Adds the roast to Roast History with full telemetry
  • Generates a post-roast analysis automatically (requires an OpenRouter key)
  • Updates your RoastIQ profile so historical roasts inform future live coaching

Imported sessions show a CSV badge in the Roast History list.

Importing your last 5–10 roasts of the same bean is the fastest way to give RoastIQ meaningful context from day one.

Settings

Access: menu bar or system tray coffee cup → Settings

Credentials & Connectivity

OpenRouter API KeyPaste your sk-or-v1-… key. It is validated against OpenRouter and stored in the macOS Keychain or Windows Credential Locker.
Choose your modelAny text/chat model on OpenRouter. Recommended models are marked with an asterisk (*). The list loads live from OpenRouter. Click Refresh model listif a recently released model isn't showing.

RoasTime Capture & Diagnostics

Live LogsUpdates every ~3 seconds. Shows IBTS, RoR, power, fan, drum, and session phase as Coffee Coach AI reads them. Blank until preheat begins. Compare these to RoasTime to confirm the pipeline is working.
Live coaching pipelineUpdates every 15 seconds. Shows why the model was or was not called: Telemetry present, coaching call sent or Preheat phase, skipping coaching.
Verbose telemetry loggingWrites detailed pipeline output to a local log file. Use it when troubleshooting and reveal it in Finder or File Explorer from Settings.
OCR Calibration (advanced)macOS only. Corrects region mappings when the optional screen-reading fallback is needed. Windows reads the RoasTime log directly and does not require calibration.

Roast History & Logs

Access: menu bar or system tray coffee cup → Roast History

Session list (left column)

All recorded sessions, newest first. CSV-imported sessions show a CSV badge. Rated sessions show a thumbs up (green) or thumbs down (orange).

Session detail (right panel)

Coaching eventsEvery notification sent during the roast, timestamped.
Telemetry samplesThe full IBTS, RoR, power, fan, and drum curve.
Post-roast analysisIf generated, appears here in formatted text.
RatingThumbs up or thumbs down, fed back into RoastIQ.
NotesFree text for cup notes or changes to try next time.
Generate Analysis buttonCalls your OpenRouter model for a full post-roast report at any time.