caffeinate-me 0.2.0

A whimsical caffeine companion for coffee-loving developers

Caffeinate Me ☕

A whimsical caffeine companion for coffee-loving developers.

caffeinate-me started as a single-function script and has grown into a full CLI tool with a rich quote library, coffee-type info, a local consumption tracker, brewing timers, and achievements.

---

Installation

The recommended way to install caffeinate-me is with pipx, which installs the CLI into an isolated environment and puts it permanently on your PATH — no virtual environment to activate, works in any terminal.

Install pipx (if you don't have it):

# macOS
brew install pipx

# Linux / WSL
sudo apt install pipx

# or via pip
pip install --user pipx

Install caffeinate-me from PyPI:

pipx install caffeinate-me

Or install from source:

git clone https://github.com/brett-buskirk/caffeinate-me.git
cd caffeinate-me
pipx install .

That's it — caffeinate-me is now available everywhere. Dependencies like rich are installed automatically inside the isolated environment.

Requires Python 3.9+.

---

Usage

Default — show a random quote

caffeinate-me

╭────────────────────────── ☕ Caffeinate Me ──────────────────────────────╮
│                                                                           │
│   ) ) )                                                                   │
│  ( ( (                                                                    │
│  ......                                                                   │
│  |    |]                                                                  │
│  \    /                                                                   │
│   `---'                                                                   │
│                                                                           │
│   "Coffee is my rubber duck. Time for another cup!"                       │
│                                                                           │
│   Recommended: ☕ Pour Over  •  100mg caffeine  •  Strong intensity       │
╰───────────────────────────────────────────────────────────────────────────╯

---

Mood-based quotes

caffeinate-me --mood energetic   # motivational / programmer quotes
caffeinate-me --mood sleepy      # sarcastic / dark-humor quotes
caffeinate-me --mood stressed    # programmer stress-relief quotes
caffeinate-me --mood zen         # wholesome / mindful quotes

Coffee-type info + recommendation

caffeinate-me --type espresso     # show espresso details + a quote
caffeinate-me --type cold-brew    # show cold-brew details + a quote

Available types: espresso, americano, latte, cappuccino, cold-brew, pour-over, french-press, mocha, macchiato, flat-white

Intensity filter

caffeinate-me --intensity mild      # recommend a lighter coffee
caffeinate-me --intensity strong    # recommend a strong coffee
caffeinate-me --intensity espresso  # espresso-level strength

Plain text (no emoji)

caffeinate-me --no-emoji

---

Consumption Tracker

Log each coffee and build up your stats over time.

caffeinate-me --log                  # log a coffee alongside your quote
caffeinate-me --log --type espresso  # log a specific type
caffeinate-me --stats                # view stats and achievements

Stats view

    ☕ Your Coffee Stats
┌───────────────┬──────────┐
│ Today         │ 3 cup(s) │
│ This Week     │ 14 cup(s)│
│ All Time      │ 42 cup(s)│
│ Daily Average │ 2.1      │
│ Favourite     │ Espresso │
└───────────────┴──────────┘

🏆 Achievements  (3/7)
☕  First Cup      — Logged your very first coffee!
🔥  Triple Shot    — Had 3 coffees in one day!
🌅  Early Bird     — Had coffee before 6 AM!
·   Night Owl      — Had coffee after 10 PM!
...

Achievements

Icon	Name	How to unlock
☕	First Cup	Log your very first coffee
🔥	Triple Shot	3+ coffees in one day
🌅	Early Bird	Coffee before 6 AM
🦉	Night Owl	Coffee after 10 PM
🏆	Week Warrior	Coffee every day for 7 consecutive days
💯	Century Club	100 coffees total
🎨	Variety Seeker	Try 5 different coffee types

Export your data

caffeinate-me --export json   # JSON format
caffeinate-me --export csv    # CSV format

Data is stored locally in ~/.caffeinate_me/tracker.json.

---

Brewing Timer

caffeinate-me timer french-press   # 4-minute countdown
caffeinate-me timer espresso       # 30-second countdown
caffeinate-me timer --list         # show all brew times

Cold brew (12+ hours) skips the live timer and prints a reminder instead.

---

Python API

The core function is still available for use in your own code:

from caffeinate_me import caffeinate_me

print(caffeinate_me())
# "sudo make me a coffee. Time for another cup!"

print(caffeinate_me(mood="zen"))
# "Coffee is a warm hug in a mug. Time for another cup!"

print(caffeinate_me(no_emoji=True))
# "Maybe just a nap instead?"

---

Quote Library

115 quotes across 8 categories:

Category	Flavour
motivational	Uplifting, get-things-done energy
sarcastic	Dry wit and coffee snob energy
programmer	Developer-specific coffee struggles
wholesome	Warm and fuzzy coffee feelings
dark_humor	Because sometimes coffee isn't enough
morning	Dawn-patrol, first-cup vibes
afternoon	3 PM slump survival
evening	Night-owl, deadline-fuelled motivation

---

Project Structure

src/caffeinate_me/
├── __init__.py      — package entry, re-exports caffeinate_me()
├── core.py          — caffeinate_me() function (backward-compatible)
├── quotes.py        — 130+ quote library with categories
├── coffee_types.py  — coffee type info and time-of-day recommendations
├── tracker.py       — local JSON consumption tracker + achievements
├── timer.py         — brewing countdown timer (rich live display)
├── art.py           — ASCII coffee cup art
└── cli.py           — CLI entry point (argparse + rich)

tests/
├── test_core.py
├── test_quotes.py
├── test_tracker.py
└── test_coffee_types.py

---

Contributing

Pull requests are welcome! The easiest way to contribute is to add new coffee quotes. See the categories in src/caffeinate_me/quotes.py and submit a PR.

Run the tests before submitting:

pytest

---

License

MIT. See LICENSE.

---

Coffee responsibly. This tool is for entertainment purposes only.