tima-timer 2.0.3
A modern cross-platform productivity timer for managing multiple projects (Flet-based)
License: MIT
Requires Python: >=3.8
Keywords: timer, productivity, time-management, project-management

# 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:

```bash
# 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:
```bash
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
| Key | Action |
|-----|--------|
| `Space` | Pause/Resume current project |
| `↑` / `Page Up` | Previous project |
| `↓` / `Page Down` | Next project |
| `Delete` | Delete selected project |
| `Ctrl+Z` | Undo last delete/rename |
| `?` | Show keyboard shortcuts help |
| `Q` / `Escape` | Quit application |

#### Project List
| Key | Action |
|-----|--------|
| `F2` | Rename selected project |
| `Click` | Select project |

#### Text Entry
| Key | Action |
|-----|--------|
| `Enter` | Add project (when focused on input field) |

### 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`:

```python
# 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.**