nixpkgs/pkgs/crunch/README.md

# crunch

Voice-notified reminders and AI crunch jobs via systemd transient timers. Schedules tasks that fire through `talk` (ElevenLabs TTS) — no NixOS rebuild needed, survives reboots.

## Usage

### Simple voice reminders

```bash
crunch at "14:30" "Müll rausbringen"
crunch at "2026-07-03 10:00" "Zahnarzttermin"
crunch in "30m" "Build checken"
crunch daily "09:00" "Daily standup"
crunch weekly "Mon 09:00" "Weekly review"
crunch weekly "Montag 09:00" "Weekly review"    # German day names
```

### AI crunch jobs

Runs a prompt through `pi` or `opencode` in print mode, pipes result to `talk`:

```bash
crunch ai pi in "1h" "Fasse die neuesten Commits zusammen"
crunch ai opencode daily "08:00" "Review offene Issues und gib 3 Key-Points"
crunch ai pi weekly "Mon 09:00" "Generiere Weekly Summary aus git log"
```

### Custom script jobs

Runs any shell script on schedule. Script stdout → `talk`:

```bash
crunch script daily "08:00" ~/scripts/basecamp-daily.sh
crunch script in "2h" ~/scripts/deploy-check.sh -- --verbose
crunch script weekly "Mon 09:00" ~/scripts/weekly-report.sh
```

Example script:

```bash
#!/usr/bin/env bash
# ~/scripts/basecamp-daily.sh
TODOS=$(basecamp todos --today 2>/dev/null) || exit 0
echo "$TODOS" | pi -p "Erstelle Summary als ~/reports/daily.md. Antworte mit Top 3."
```

### Management

```bash
crunch list                          # List active jobs
crunch cancel crunch-mll-rausbringen-12345   # Cancel a job
crunch purge                         # Remove fired one-shot jobs
```

## Command Reference

```
crunch at <time> <message>                    One-shot (14:30 or "2026-07-03 14:30")
crunch in <duration> <message>                One-shot after delay (30m, 2h, 1h30m)
crunch daily <time> <message>                 Recurring daily
crunch weekly <day> <time> <message>          Recurring weekly (Mon/Montag)
crunch ai <engine> <type> <time> <prompt>     AI crunch (pi|opencode)
crunch script <type> <time> <script.sh> [args]  Custom script → talk
crunch list                                    List active jobs
crunch cancel <name>                           Cancel a job
crunch purge                                   Remove fired one-shot jobs
```

## Day Names

Supports English and German:

| English | German | systemd |
|---|---|---|
| Mon, Monday | Mo, Montag | Mon |
| Tue, Tuesday | Di, Dienstag | Tue |
| Wed, Wednesday | Mi, Mittwoch | Wed |
| Thu, Thursday | Do, Donnerstag | Thu |
| Fri, Friday | Fr, Freitag | Fri |
| Sat, Saturday | Sa, Samstag | Sat |
| Sun, Sunday | So, Sonntag | Sun |

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `ELEVENLABS_API_KEY` | ✅ | — | Required by `talk` |
| `VOICE_NOTIFY` | ❌ | `1` | `0` silences talk globally |
| `TALK` | ❌ | `talk` | Override path to talk binary |

## How It Works

```
┌─────────────────────────────────────────────┐
│  systemd --user transient timer fires       │
│                                             │
│  crunch _say "message"                      │
│    └─ talk "message"  (TTS via ElevenLabs)  │
│                                             │
│  crunch _ai pi "prompt"                     │
│    └─ pi -p "prompt" | talk  (AI → TTS)    │
│                                             │
│  crunch _script ~/script.sh                 │
│    └─ bash ~/script.sh | talk  (pipe → TTS)│
└─────────────────────────────────────────────┘
```

Uses `systemd-run --user` to create transient `.timer` + `.service` units. No NixOS rebuild needed — jobs are created and managed at runtime.

## Prerequisites

- `talk` package installed and in PATH
- `pi` and/or `opencode` for AI crunch mode
- `loginctl enable-linger <username>` — **critical** for timers to fire when logged out
- `ELEVENLABS_API_KEY` in environment (or agenix secrets)

## NixOS Installation

```nix
# home-manager
home.packages = [ pkgs.m3ta.crunch pkgs.m3ta.talk ];
```

Verify lingering is enabled:

```bash
loginctl show-user $(whoami) | grep Linger=yes
# If not:
sudo loginctl enable-linger $(whoami)
```