44485c4c72
- Update package description and fix mainProgram typo - Rewrite documentation to describe project switching, not process viewing - Add PROJECT_FOLDERS configuration and usage examples - Update all references across docs (README, guides, module overviews)
221 lines
3.9 KiB
Markdown
221 lines
3.9 KiB
Markdown
# 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
|