# 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](https://pipx.pypa.io), 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):

```bash
# macOS
brew install pipx

# Linux / WSL
sudo apt install pipx

# or via pip
pip install --user pipx
```

**Install caffeinate-me from PyPI:**

```bash
pipx install caffeinate-me
```

**Or install from source:**

```bash
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

```bash
caffeinate-me
```

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

---

### Mood-based quotes

```bash
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

```bash
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

```bash
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)

```bash
caffeinate-me --no-emoji
```

---

## Consumption Tracker

Log each coffee and build up your stats over time.

```bash
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

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

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

---

## Brewing Timer

```bash
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:

```python
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](src/caffeinate_me/quotes.py) and submit a PR.

Run the tests before submitting:

```bash
pytest
```

---

## License

MIT. See [LICENSE](LICENSE).

---

*Coffee responsibly. This tool is for entertainment purposes only.*
