Rhythm - Time-Block Schedule Tracker

A lightweight CLI tool that tracks your daily schedule from org-mode files, showing what you should be doing right now and what's coming next.

Features

• 📅 Parse org-mode formatted schedule files
• ⏰ Show current active time block
• 🔜 Display upcoming activities
• 🌍 Timezone support
• 📊 Progress tracking through time blocks
• 🎯 JSON output for integration with other tools
• ✅ Filters out completed/closed tasks

Installation

Prerequisites

• Dart SDK 3.8.1 or higher

Quick Install

# Clone the repository
git clone <your-repo-url> rhythm
cd rhythm

# Run the installation script
./install.sh

# Complete installation with:
sudo cp rhythm_cli/rhythm /usr/local/bin/rhythm

Manual Installation

cd rhythm_cli
dart pub get
dart compile exe bin/rhythm_cli.dart -o rhythm
sudo cp rhythm /usr/local/bin/rhythm

Usage

Basic Usage

# Show current schedule (reads from ~/.config/rhythm/schedule.org)
rhythm

# Use a specific schedule file
rhythm -f my-schedule.org

# Show schedule for a specific time
rhythm --now 14:30

# Output in JSON format
rhythm --json

# Use a different timezone
rhythm --tz America/New_York

Output Examples

Human-readable output:

Now: Deep Work Block 1 (09:00–11:00) • Next: Email & Admin 11:00–11:30

Between blocks:

Between phases • Next: Lunch Break 13:00–14:00

JSON output:

{
  "current": {
    "title": "Deep Work Block 1",
    "timeRange": "09:00–11:00"
  },
  "next": {
    "title": "Email & Admin",
    "timeRange": "11:00–11:30"
  },
  "progress": 0.75
}

Schedule File Format

Rhythm uses org-mode format for schedule files. Create your schedule at ~/.config/rhythm/schedule.org:

* Morning Routine <2025-09-03 Tue 06:30-07:30>
Wake up, exercise, breakfast

* Deep Work Block 1 <2025-09-03 Tue 09:00-11:00>
Focus on most important project

* Email & Admin <2025-09-03 Tue 11:00-11:30>
Process inbox and messages

* Lunch Break <2025-09-03 Tue 13:00-14:00>
Meal and rest

* DONE Morning Review <2025-09-03 Tue 08:30-09:00>
This will be skipped (marked as DONE)

Format Rules

• Use single asterisk * for time blocks (sub-headings are ignored)
• Timestamps: <YYYY-MM-DD Day HH:MM> or <YYYY-MM-DD Day HH:MM-HH:MM>
• Mark completed items with DONE or CLOSED keywords
• Overnight spans are supported (e.g., 23:00-01:00)

Integration Ideas

Shell Prompt

Add to your .zshrc or .bashrc:

# Show current task in prompt
current_task() {
  rhythm 2>/dev/null | head -n 1
}
PS1='$(current_task) $ '

Status Bar (tmux)

# In .tmux.conf
set -g status-right '#(rhythm --json | jq -r ".current.title // \"No task\"")'

Desktop Notifications

Create a cron job to notify on task changes:

*/15 * * * * rhythm | notify-send "Schedule Update"

Development

Run Tests

cd rhythm_cli
dart test

Run Without Installing

cd rhythm_cli
dart run bin/rhythm_cli.dart

Tips

• Keep your schedule file in version control
• Use templates for recurring daily patterns
• Set up aliases for quick schedule checks
• Integrate with your workflow tools

License

MIT