Tima

Pronounced like "timer" - because that's what it is

A sleek desktop productivity timer that keeps you focused on what matters

Tima is a modern, minimalist activity timer designed to help you cycle through multiple projects with customizable time allocations. Perfect for time-boxed work sessions, research rotations, or managing multiple concurrent projects.

Features

Core Functionality

• Multi-Project Management - Track multiple projects simultaneously with individual timers
• Customizable Durations - Set default time allocations or customize per-project
• Pause & Resume - Flexible control over individual project timers
• Auto-Cycling - Automatic notifications and project switching when time expires
• Persistent State - All projects and timer states are saved automatically

User Experience

• Modern Dark UI - Easy on the eyes with a sleek, contemporary design
• Two-Panel Layout - Timer and status on left, project list on right
• Keyboard Shortcuts - Full keyboard navigation for power users
• Visual Indicators - Clear status indicators for current, paused, and running projects
• Undo Support - Restore accidentally deleted or renamed projects
• Import/Export - Easily share project lists via text files

Project Controls

• Add, rename, and delete projects on the fly
• Individual pause/resume for each project
• Reset timers to default duration
• Navigate between projects with arrow keys
• Clear visual feedback for all actions

Installation

Quick Install

No system dependencies required! Just install and run:

# Using uv (recommended)
uv pip install tima-timer

# Or using pip
pip install tima-timer

Tima uses Flet (Flutter for Python), so everything you need is included - no tkinter, no Qt, no external dependencies!

Running

After installation, simply run:

tima

The modern Flet UI will launch automatically!

Usage

Getting Started

1. Launch Tima - Run tima from your terminal
2. Add Projects - Type project names in the input field and click ADD (or press Enter)
3. Start Working - The timer automatically starts with your first project
4. Stay Focused - Watch the countdown and receive alerts when time expires

Managing Projects

Adding Projects

• Type the project name in the input field
• Press Enter or click the ADD button
• New projects start with the default duration (1 hour)

Renaming Projects

• Click to select a project in the list
• Press F2 to open the rename dialog
• Type the new name and press Enter to save

Deleting Projects

• Select a project in the list
• Press Delete
• Use Ctrl+Z to undo if needed

Pausing/Resuming

• Press Space to pause/resume the current project
• Or use the Timer menu for more options

Keyboard Shortcuts

Global Controls

Project List

Text Entry

Menu Options

Access the menu via the ⋮ button in the top-right corner:

• Import Projects - Load project list from a text file
• Export Projects - Save project list to a text file
• Settings - Configure default time allocation for new projects
• Keyboard Shortcuts - Display all available keyboard shortcuts
• Exit - Close the application

All project operations (rename, delete, pause/resume, reset) are available via keyboard shortcuts.

Configuration

Default Duration

• Click the menu (⋮) → Settings
• Enter hours and minutes
• New projects will use this duration
• Existing projects keep their current settings

Data Persistence

All data is automatically saved to ~/.tima/tima_projects.json including:

• Project names and order
• Individual project timer states
• Pause states
• Current project index
• Default duration setting

Color Scheme

The application uses a modern dark theme with carefully chosen colors:

• Dark background for reduced eye strain
• Purple primary accent for active elements
• Color-coded status indicators (green for running, orange for paused, red for ended)

Technical Details

Architecture

• Built with Flet (Flutter for Python) for modern, cross-platform UI
• Modular design: Separated UI, business logic, and data layers
• JSON-based data persistence
• Async timer system using Python's asyncio
• Undo stack implementation for reversible operations
• Material Design components

File Structure

tima/
├── src/tima_timer/
│   ├── app_flet.py             # Flet UI implementation
│   ├── models.py               # Data models and state
│   ├── timer_logic.py          # Business logic
│   └── __init__.py             # Package entry point
├── ~/.tima/
│   └── tima_projects.json      # User project data (auto-saved)
├── MIGRATION.md                # Migration documentation
└── README.md                   # This file

Platform Support

• ✅ Windows: Full support with native sound notifications
• ✅ macOS: Full support
• ✅ Linux: Full support (no system dependencies!)
• 🔮 Web/Mobile: Flet supports web and mobile deployment (not yet configured for this project)

Tips & Tricks

1. Focus Mode - Pause all non-essential projects to focus on one task
2. Daily Rotation - Set up recurring daily projects and cycle through them
3. Research Sessions - Perfect for managing multiple research papers or study topics
4. Sprint Planning - Use for time-boxed development sprints across features
5. Meeting Prep - Allocate time for preparing multiple meeting topics

Customization

Want to change the default settings? Edit these values in src/tima_timer/app_flet.py:

# Color scheme (lines 17-28)
COLORS = {
    'bg': '#1e1e2e',           # Dark background
    'primary': '#6c63ff',       # Primary accent color
    # ... customize other colors
}

# Default duration is stored in user data and can be changed via Settings menu

Troubleshooting

Timer not ticking?

• Ensure you have projects added
• Check if the current project is paused (look for [PAUSED] indicator)

Sound notifications not working?

• Windows: Ensure C:/Windows/Media/Alarm04.wav exists
• macOS/Linux: Console notification will appear (audio support coming soon)

Projects not saving?

• Check write permissions in the application directory
• Verify tima_projects.json is not corrupted

License

This project is open source. Feel free to use, modify, and distribute as needed.

Contributing

Contributions are welcome! Some ideas for enhancements:

• Cross-platform sound notifications (beyond Windows)
• Statistics and time tracking reports
• Project categories and tags
• System tray integration
• Light theme option
• Custom alert sounds per project
• Web version deployment
• Mobile apps (iOS/Android)

Stay focused. Stay productive. Use Tima.