schedulr 0.0.3

A smart terminal scheduler with natural language input and ASCII calendar visualization.

Schedulr - Smart Terminal Task Scheduler

A beautiful, feature-rich terminal-based task scheduler with natural language input, calendar visualization, system tray integration, and desktop notifications.

Features

Core Functionality

• Natural Language Input: Create tasks using human-friendly date/time expressions
• Beautiful Terminal Interface: Rich, colorful TUI built with Textual framework
• SQLite Database: Persistent storage for all your tasks
• Calendar View: Visual monthly calendar with task indicators
• Search & Filter: Quickly find tasks by title
• Task Statistics: Overview of pending, completed, and recurring tasks

Advanced Features

• System Tray Integration: Run in background with tray icon
• Desktop Notifications: Get notified when tasks are due
• Auto-start Support: Automatically launch on Windows startup
• Settings Management: Customizable preferences and themes
• Responsive Design: Adaptive layout for different terminal sizes

Table of Contents

• Installation
• Quick Start
• Usage
• Command Line Options
• Configuration
• Task Management
• Calendar View
• Settings
• System Tray Mode
• Auto-start Setup
• Development
• API Reference
• Troubleshooting
• Contributing
• License

Installation

Prerequisites

• Python 3.8 or higher
• Windows operating system
• Terminal with color support (recommended)

Install from PyPI (Recommended)

pip install schedulr

Install from Source

# Clone the repository
git clone https://github.com/MadushankaRajapaksha/-Schedulr- 
cd schedulr

# Install in development mode
pip install -e .

Verify Installation

schedulr --help

Quick Start

Launch the Application

# Launch the main interface
schedulr

# Or run as Python module
python -m schedulr

Create Your First Task

1. Launch Schedulr
2. Click the ➕ Add Task button or press the navigation button
3. Fill in the task details:
   • Task Title: What needs to be done
   • Date: When it should happen (YYYY-MM-DD format)
   • Time: Hour, minute, and AM/PM
4. Click ✅ Save Task

Example: Add a Meeting Task

📝 Task Title: Team Meeting
📅 Date: 2024-01-15
⏰ Hour: 14
⏰ Minute: 30
🕐 Time Format: PM

Usage

Basic Navigation

• 🏠 Home: View all tasks with search and statistics
• ➕ Add Task: Create new tasks with the modal form
• 📅 Calendar: Monthly calendar view with task indicators
• ⚙️ Settings: Configure application preferences

Keyboard Shortcuts

• Tab: Navigate between interface elements
• Enter: Activate buttons and submit forms
• Escape: Close modals or go back
• Arrow Keys: Navigate in calendar view

Search Functionality

Use the search bar in the Home view to filter tasks by title:

Search by task title: meeting

Shows all tasks containing "meeting" in their title.

Command Line Options

# Show help information
schedulr --help

# Run in system tray mode (recommended for notifications)
schedulr --tray

# Manage auto-start on Windows
schedulr --autostart add     # Enable auto-start
schedulr --autostart remove  # Disable auto-start
schedulr --autostart check   # Check auto-start status

System Tray Mode

# Start in background with notifications
schedulr --tray

Features in tray mode:

• Application runs in background
• Desktop notifications for due tasks
• System tray icon for quick access
• Right-click menu for basic controls

Configuration

Settings Options

Access settings through the ⚙️ button in the Calendar view:

Notification Settings

• Enable Notifications: Desktop alerts for due tasks
• Default Reminder Time: Minutes before due time to notify
• Sound Notifications: Audio alerts (when supported)

Display Settings

• Theme: Light, dark, or auto theme selection
• Time Format: 12-hour or 24-hour format
• Week Start: Monday or Sunday as week start
• Show Completed Tasks: Display finished tasks in lists

Task Settings

• Default Task Duration: Default time allocation for tasks
• Working Hours: Define your typical work schedule
• Auto-start: Launch application on system startup

Configuration File

Settings are stored in the application's database and persist between sessions.

Task Management

Creating Tasks

Tasks can be created through the ➕ Add Task modal with the following fields:

• Title: Task description (required)
• Date: Target date in YYYY-MM-DD format
• Time: Hour (0-23) and minute (0-59)
• AM/PM: Time period for 12-hour format

Task Status

Tasks have the following status levels:

• ⏳ Pending: Not yet completed
• ✅ Completed: Finished tasks
• 🔄 Recurring: Repeating tasks (future feature)

Task Operations

• View: Click on task cards to see details
• Edit: Modify task details (planned feature)
• Delete: Remove tasks (planned feature)
• Mark Complete: Change status to completed

Calendar View

Monthly Overview

The calendar view displays:

• Month Navigation: Previous/Next month buttons
• Task Indicators: Days with tasks are highlighted
• Today Highlighting: Current date is specially marked
• Task Preview: Brief task list on each calendar day

Calendar Navigation

• ◀ Prev: Go to previous month
• Next ▶: Go to next month
• Keyboard: Use arrow keys for quick navigation
• Click Days: Click on calendar days to view tasks

Task Indicators

• Highlighted Days: Days containing tasks
• Task Count: Shows number of tasks per day
• Task Preview: First 2 tasks shown, with "+X more" indicator

System Tray Mode

Background Operation

schedulr --tray

Tray mode features:

• Minimized Operation: Runs without visible window
• Background Monitoring: Continuously checks for due tasks
• Desktop Notifications: Alerts when tasks are due
• Quick Access: Right-click tray icon for menu options

Tray Menu Options

• Open Schedulr: Show the main application window
• Exit: Close the application and stop notifications

Notification System

• Due Task Alerts: Notified when tasks reach their scheduled time
• Customizable Timing: Set reminder time in settings
• Persistent Notifications: Remain visible for 10 seconds
• Task Context: Shows task title and type in notifications

Auto-start Setup

Windows Auto-start

Enable Schedulr to launch automatically when Windows starts:

# Enable auto-start
schedulr --autostart add

# Disable auto-start
schedulr --autostart remove

# Check status
schedulr --autostart check

Auto-start Process

1. Creates a batch file in Windows startup folder
2. Uses pythonw.exe to run without console window
3. Automatically starts in system tray mode
4. Begins monitoring for due tasks immediately

Development

Development Setup

# Clone repository
git clone <repository-url>
cd schedulr

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

# Run in development mode
python -m schedulr

Project Structure

schedulr/
├── __main__.py          # Entry point and CLI argument parsing
├── cli.py              # Main Textual TUI application
├── core.py             # Database operations and task management
├── screens.py          # Calendar screen and modal screens
├── notifier.py         # Background notification system
├── tray.py            # System tray integration
└── autostart.py       # Windows auto-start management

data.db                # SQLite database (created automatically)
README.md             # This file
pyproject.toml        # Project configuration and dependencies

Key Components

Database Layer (core.py)

• SQLite database management
• Task CRUD operations
• Data validation and error handling

User Interface (cli.py)

• Textual-based terminal interface
• Task display and management
• Search functionality
• Modal forms for task creation

Calendar System (screens.py)

• Monthly calendar visualization
• Task indicators and previews
• Navigation and date selection

Notification Engine (notifier.py)

• Background task monitoring
• Desktop notification delivery
• Configurable check intervals

Dependencies

[project]
dependencies = [
    "rich",           # Beautiful terminal formatting
    "typer",          # CLI framework
    "dateparser",     # Natural language date parsing
    "schedule",       # Task scheduling
    "plyer",         # Desktop notifications
    "pystray",       # System tray icon
    "Pillow",        # Image processing for icons
    "textual"        # Terminal user interface framework
]

API Reference

Core Classes

Database

from schedulr.core import Database

# Initialize database connection
db = Database(db_path="data.db")

# Create a new task
result = db.create_task(
    title="Team Meeting",
    date_time="2024-01-15 14:30:00",
    status="Pending"
)

# Get all tasks
tasks = db.get_all_tasks()

# Update task status
db.update_task(task_id=1, status="Completed")

# Delete a task
db.delete_task(task_id=1)

Notifier

from schedulr.notifier import Notifier

# Create notifier instance
notifier = Notifier(check_interval=60)  # Check every 60 seconds

# Start background monitoring
notifier.start()

# Stop monitoring
notifier.stop()

System Tray

from schedulr.tray import SystemTrayApp

# Create and run tray application
tray_app = SystemTrayApp()
tray_app.run()

Textual App Structure

Home Screen

Main application interface with:

• Navigation sidebar
• Task statistics
• Search functionality
• Task cards display
• Modal screens for task creation

Calendar Screen

Monthly calendar view featuring:

• Month navigation
• Day highlighting
• Task indicators
• Click-to-view task details

Troubleshooting

Common Issues

Application Won't Start

# Check Python version
python --version  # Should be 3.8+

# Verify installation
pip show schedulr

# Check for missing dependencies
pip install -r requirements.txt

No Notifications

# Check if running in tray mode
schedulr --tray

# Verify notification permissions
# Check Windows notification settings

Database Issues

# Reset database (WARNING: Deletes all tasks)
del data.db
schedulr

Display Problems

• Ensure terminal supports colors
• Try resizing terminal window
• Check font supports Unicode characters

Debug Mode

Run with verbose output for troubleshooting:

# Enable debug logging (if available)
set SCHEDULR_DEBUG=1
schedulr

Getting Help

1. Check the Issues page for known problems
2. Create a new issue with:
   • Python version (python --version)
   • Operating system
   • Steps to reproduce the problem
   • Full error messages

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests if applicable
5. Run the test suite
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Code Style

• Follow PEP 8 for Python code
• Use type hints for function parameters and return values
• Add docstrings to all public functions and classes
• Keep line length under 88 characters

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Textual for the beautiful TUI framework
• Rich for enhanced terminal formatting
• PyStray for system tray functionality
• Plyer for cross-platform desktop notifications

Support

• Documentation: This README and inline code documentation
• Issues: Bug reports and feature requests via Issues
• Discussions: Community discussions via Discussions

---

Made with ❤️ for developers who love terminal applications

⭐ Star this project | 🐛 Report Bug | 💡 Request Feature