wabit/coffee-bot repository overview

⁠☕ Coffee Bot

An AI-powered espresso shot analyzer that uses GPT-5.2 Pro to provide detailed, actionable recommendations for improving your shots.

⁠📚 Documentation

All documentation has been moved to the docs/ directory. Start here:

👉 docs/INDEX.md⁠ - Master index of all documentation

Quick links:

• docs/CLI_SETUP.md⁠ - 2-minute setup guide
• docs/ARCHITECTURE_CLI.md⁠ - How the CLI works
• docs/API_REFERENCE.md⁠ - Extension & architecture guide

⁠🚀 Quick Start

# 1. Run the setup script
./setup.sh

# 2. Add your OpenAI API key to .env
# Edit .env and set: OPENAI_KEY=sk-...

# 3. Run the app (CLI mode by default)
bun run dev

⁠🤖 Discord Bot Mode (Optional)

To run as a Discord bot instead of CLI, add Discord credentials to .env:

# 1. Create a Discord bot application:
#    - Go to https://discord.com/developers/applications
#    - Click "New Application"
#    - Name it "Coffee Bot" (or preferred name)
#    - Go to "Bot" section and click "Add Bot"
#    - Copy the "Token" under the bot name

# 2. Get your Discord Channel ID:
#    - Enable Developer Mode in Discord (User Settings → App Settings → Advanced → Developer Mode)
#    - Right-click your channel and select "Copy Channel ID"

# 3. Get your Discord Guild ID (Server ID):
#    - Right-click your Discord server name and select "Copy Server ID"

# 4. Add to .env:
DISCORD_TOKEN=your_bot_token_here
DISCORD_CHANNEL_ID=your_channel_id_here
DISCORD_GUILD_ID=your_guild_id_here

# 5. Invite bot to server:
#    - Go to OAuth2 → URL Generator
#    - Select "bot" scope
#    - Select permissions: "Send Messages", "Embed Links", "Read Message History"
#    - Copy the generated URL and open in browser to invite

# 6. Run:
bun run dev

The bot will auto-detect Discord mode and start listening for commands!

⁠✨ Features

• Interactive CLI Menu - Simple terminal interface
• AI-Powered Analysis - Uses GPT-5.2 Pro for deep shot analysis
• Teaching Focus - Explains why each recommendation matters
• Phase-by-Phase Breakdown - Analyzes bloom, extraction, etc.
• Taste Prediction - Predicts flavor profile with reasoning
• Complete Logging - Tracks all advice & confirmations
• Context Tracking - Remembers your bean type & grind settings
• Type-Safe - Zero any types, full TypeScript
• Discord Ready - Bot integration available for later

⁠📋 Installation

See docs/CLI_SETUP.md⁠ for detailed setup instructions.

Or use the automated setup:

./setup.sh

⁠📁 Project Structure

coffee-bot/
├── src/              - Application code
├── __tests__/        - Test suites
├── docs/             - All documentation
├── config/           - Configuration
├── data/             - Runtime data (auto-created)
├── logs/             - Shot logs (auto-created)
├── setup.sh          - Setup script
├── package.json      - Dependencies
└── tsconfig.json     - TypeScript config

⁠🛠️ Technology Stack

• Runtime: Bun (TypeScript-first, super fast)
• Language: TypeScript (strict, no any)
• AI: OpenAI GPT-5.2 Pro
• Storage: JSON files
• Testing: Bun's built-in test runner

⁠📞 Need Help?

See the full documentation in docs/:

• docs/CLI_SETUP.md⁠ - Detailed setup guide
• docs/ARCHITECTURE_CLI.md⁠ - How it works
• docs/QUICK_REFERENCE.md⁠ - Commands & tips
• docs/API_REFERENCE.md⁠ - Extension guide
• docs/DISCORD_DEFERRED.md⁠ - Discord bot (for later)

⁠🚀 Running

# Start the CLI app
bun run dev

# Run tests
bun test

⁠📄 License

MIT

Ready? → Run ./setup.sh or see docs/CLI_SETUP.md⁠

• Check bot has "Send Messages" permission in the channel
• Look for error logs in console

⁠OpenAI API errors

• Verify OPENAI_KEY is set correctly
• Check API key has credits/quota remaining
• Confirm model name is valid

⁠🐳 Docker Deployment

⁠Production Deployment

1. Create your config file:

   cp config.example.json config.json
   # Edit config.json with your actual credentials
   

   Copy

2. Run with docker-compose:

   docker-compose up -d
   

   Copy

3. Monitor logs:

   docker-compose logs -f coffee-bot
   

   Copy

4. Stop the bot:

   docker-compose down
   

   Copy

⁠Configuration

The bot uses a config.json file mounted into the container. Example:

{
  "gaggimate": {
    "host": "gaggimate.local",
    "port": 80
  },
  "openai": {
    "key": "sk-proj-YOUR_KEY_HERE",
    "model": "gpt-4"
  },
  "discord": {
    "token": "YOUR_DISCORD_BOT_TOKEN",
    "channelId": "YOUR_CHANNEL_ID",
    "guildId": "YOUR_GUILD_ID"
  },
  "polling": {
    "intervalSec": 60
  },
  "debug": false
}

Required fields:

• gaggimate.host - IP/hostname of your GaggiMate machine
• openai.key - OpenAI API key
• discord.* - Discord bot credentials (if using Discord mode)

⁠Docker Hub

Images are automatically built and pushed to Docker Hub on every merge to main:

docker pull YOUR_DOCKER_HUB_USERNAME/coffee-bot:latest
docker run -v ./config.json:/app/config.json -v ./data:/app/data YOUR_DOCKER_HUB_USERNAME/coffee-bot

⁠Network Configuration

The bot expects to reach your GaggiMate machine on the same network. Make sure:

• GaggiMate hostname/IP in config.json is correct
• Both containers/machines are on the same network or can reach each other
• No firewall blocking port 80 from bot to GaggiMate

⁠🚀 Continuous Deployment

GitHub Actions automatically:

1. Builds the Docker image on push to main
2. Pushes to Docker Hub
3. Tags with branch, git SHA, and "latest"

Setup required:

1. Create a Docker Hub account
2. Add GitHub secrets:
   • DOCKER_HUB_USERNAME - Your Docker Hub username
   • DOCKER_HUB_PASSWORD - Your Docker Hub password (or access token)
3. Update IMAGE_NAME in .github/workflows/docker-build.yml

⁠Future Enhancements

• Upgrade to two-way conversational bot (with cost controls)
• Support multiple grinder profiles
• Track taste preferences and adapt recommendations
• Export shot history to CSV/PDF
• Web dashboard for historical analysis
• Integration with other espresso machines

⁠License

MIT

⁠coffee-coach