# pomodoro-timer

A work timer based on the Pomodoro Technique.

## Description

A simple, shell-based Pomodoro timer that uses `timer`, Kitty terminal, Rofi, libnotify, and speech synthesis to provide visual and audio feedback for work and break sessions.

## Features

- ⏱️ **Pomodoro Technique**: 45-minute work, 10-minute break cycles
- 🎨 **Terminal UI**: Floating Kitty terminal window
- 📋 **Rofi Menu**: Easy session selection
- 🔔 **Notifications**: Desktop and voice notifications
- ⚙️ **Custom Times**: Set custom durations
- 🎯 **Quick Access**: Simple keybinding integration

## Installation

### Via Overlay

```nix
{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    launch-timer  # The main program is named launch-timer
  ];
}
```

### Direct Reference

```nix
{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    inputs.m3ta-nixpkgs.packages.${pkgs.system}.launch-timer
  ];
}
```

### Run Directly

```bash
nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#launch-timer
```

## Usage

### Basic Usage

```bash
# Launch timer selection menu
launch-timer
```

This opens a Rofi menu with three options:

1. **work** - 45-minute work session
2. **break** - 10-minute break session
3. **custom** - Custom time duration

### Session Options

#### Work Session

```bash
# Select "work" from menu
# Starts 45-minute timer
```

#### Break Session

```bash
# Select "break" from menu
# Starts 10-minute timer
```

#### Custom Time

```bash
# Select "custom" from menu
# Enter time in format: 25m, 1h, 30s

# Examples:
# 25m  - 25 minutes
# 1h   - 1 hour
# 30s  - 30 seconds
```

### Time Formats

Supported formats:

| Format | Example | Description |
|---------|----------|-------------|
| `Xm` | `25m` | X minutes |
| `Xh` | `1h` | X hours |
| `Xs` | `30s` | X seconds |

## Configuration

### Keybinding Integration

Add to Hyprland config:

```nix
{pkgs, ...}: {
  wayland.windowManager.hyprland.settings = {
    bind = [
      # Launch Pomodoro timer with SUPER + T
      "SUPER, T, exec, ${pkgs.launch-timer}/bin/launch-timer"
    ];
  };
}
```

### Custom Defaults

Modify the script for custom defaults:

```bash
# Change work duration
start_timer "60m" "work"

# Change break duration
start_timer "15m" "break"
```

## Requirements

### Dependencies

- `timer` - Terminal timer utility
- `kitty` - Terminal emulator
- `rofi` - Application launcher
- `libnotify` - Desktop notifications
- `speechd` - Text-to-speech synthesis

### System Requirements

- Linux (primary)
- Desktop environment with notification support
- Audio output for speech synthesis

## Platform Support

- Linux (primary)
- macOS (not supported)
- Windows (not supported)

## Behavior

### Timer Window

- Opens as floating Kitty window
- Window class: `floating-pomodoro`
- Window title: `floating-pomodoro`

### Notifications

When session ends, you'll receive:

1. Desktop notification: "work session ended!" or "break session ended!"
2. Voice announcement: "work session ended" or "break session ended"

### Input Validation

For custom times:

- Valid: `25m`, `1h`, `30s`, `1h30m`
- Invalid: `25`, `abc`, `1.5h`

## Build Information

- **Version**: 0.1.0
- **Type**: Shell script
- **License**: MIT
- **Main Program**: `launch-timer`

## Troubleshooting

### Kitty Not Found

Ensure Kitty is installed:

```nix
{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    kitty
  ];
}
```

### No Notifications

Ensure notification daemon is running:

```bash
# Check for notification daemon
ps aux | grep -i notify

# Start notification daemon
# Depends on your DE: dunst, mako, etc.
```

### Speech Not Working

Check if speech synthesis is working:

```bash
# Test speech
spd-say "Hello"

# Check if speech-dispatcher is running
ps aux | grep speech-dispatcher
```

## Related

- [Adding Packages](../guides/adding-packages.md) - How to add new packages
- [Quick Start](../QUICKSTART.md) - Getting started guide