⏱️ TimeTrakk

A beautiful terminal-based time and project tracker designed specifically for Android Termux. Track your productivity with style!

✨ Features

• 📁 Project Management: Create, edit, and delete projects
• ▶️ Timer Control: Start and stop timers with live updates
• 📊 Time Tracking: View all your time entries in beautiful tables
• 📈 Statistics: See your productivity stats and project breakdowns
• 🎨 Beautiful UI: Modern terminal interface with colors and emojis
• 💾 SQLite Database: Persistent data storage
• 📱 Termux Optimized: Designed specifically for Android Termux

🚀 Installation

Prerequisites

Make sure you have Python 3.7+ installed in Termux:

pkg update && pkg upgrade
pkg install python python-pip

Install TimeTrakk

1. Clone or download the project:

   git clone <repository-url>
   cd TimeTrakk

2. Install dependencies:

   pip install rich==13.7.0

3. Make the script executable:

   chmod +x timetrakk.py

📱 Installing Termux

Step 1: Download Termux

Recommended: F-Droid (Best option)

1. Download F-Droid from f-droid.org
2. Install F-Droid on your Android device
3. Open F-Droid and search for "Termux"
4. Install Termux from the official repository

Alternative: Google Play Store

1. Open Google Play Store
2. Search for "Termux"
3. Install the official Termux app
4. Note: Play Store version may be outdated

Step 2: First Time Setup

1. Open Termux on your Android device
2. Grant permissions when prompted
3. Update packages:

   pkg update && pkg upgrade

Step 3: Install Required Packages

# Install Python and pip
pkg install python python-pip

# Install additional useful packages
pkg install git nano

# Verify installation
python --version
pip --version

Step 4: Configure Termux (Optional but Recommended)

# Enable storage access (for file sharing)
termux-setup-storage

# Install additional Termux addons
pkg install termux-api

📱 Android Termux Setup

Step 1: Install in Termux

# Navigate to your home directory
cd ~

# Create TimeTrakk directory
mkdir TimeTrakk
cd TimeTrakk

# Copy all TimeTrakk files to this directory
# (via USB, cloud storage, or email)

# Install Rich library
pip install rich==13.7.0

# Make executable
chmod +x timetrakk.py

Step 2: Create One-Click Launcher

# Create shortcuts directory
mkdir -p ~/.shortcuts

# Create simple launcher
echo '#!/bin/bash
cd ~/TimeTrakk
python timetrakk.py' > ~/.shortcuts/timetrakk

# Create notification launcher
echo '#!/bin/bash
termux-notification --title "⏱️ TimeTrakk" --content "Launching..." --icon "timer"
sleep 0.5
cd ~/TimeTrakk
python timetrakk.py' > ~/.shortcuts/timetrakk-notify

# Make both executable
chmod +x ~/.shortcuts/timetrakk
chmod +x ~/.shortcuts/timetrakk-notify

Step 3: Add to Home Screen

1. Long press on your Android home screen
2. Select "Widgets"
3. Find "Termux Widget" and add it
4. Tap the widget and select your shortcut:
   • timetrakk (simple launch)
   • timetrakk-notify (with notification)

🎯 Usage

Starting the App

Option A: Direct launch

cd ~/TimeTrakk
python timetrakk.py

Option B: Use launcher

~/timetrakk

Option C: Use simple version (no dependencies)

python timetrakk_simple.py

Main Menu Options

1. 📁 Manage Projects

   • Create new projects with names and descriptions
   • Edit existing project details
   • Delete projects (and their time entries)

2. ▶️ Start Timer

   • Select a project to track time for
   • Live timer display with real-time updates
   • Press Ctrl+C to stop the timer

3. ⏹️ Stop Timer

   • Stop the currently running timer
   • Add optional notes to the time entry
   • Automatically saves the entry to database

4. 📊 View Time Entries

   • See all your time entries in a beautiful table
   • Shows date, project, start/end times, duration, and notes

5. 📈 Statistics

   • View total time tracked
   • See breakdown by project
   • Track your productivity patterns

6. ❌ Exit

   • Safely exit the application
   • Prompts to stop timer if one is running

📱 Termux Tips

Optimizing for Termux

1. Font Size: Adjust Termux font size for better readability:

   • Go to Termux Settings → Appearance → Font Size
   • Recommended: 14-16pt

2. Color Scheme: Use a dark theme for better contrast:

   • Go to Termux Settings → Appearance → Color Scheme
   • Recommended: "Dracula" or "Monokai"

3. Keyboard Shortcuts:

   • Ctrl+C: Stop timer
   • Ctrl+D: Exit (alternative)
   • Arrow keys: Navigate menus

File Locations

• Database: timetrakk.db (created in app directory)
• Logs: Check Termux logs if issues occur

🛠️ Technical Details

Dependencies

• Rich: Beautiful terminal formatting and UI components
• SQLite3: Database storage (built-in with Python)
• Datetime: Time handling and calculations

Database Schema

Projects Table:

• id: Unique identifier
• name: Project name (unique)
• description: Optional project description
• created_at: Timestamp of creation
• color: Project color (for future use)

Time Entries Table:

• id: Unique identifier
• project_id: Reference to project
• start_time: Timer start timestamp
• end_time: Timer end timestamp
• duration: Duration in seconds
• notes: Optional notes for the entry

🎨 Customization

Colors and Styling

The app uses Rich library for styling. You can customize colors by modifying the style attributes in the code:

• bold magenta: Main headers
• bold cyan: Section headers
• bold green: Success messages
• bold red: Error messages
• yellow: Timestamps and warnings
• white: Regular text

Adding Features

The modular design makes it easy to add new features:

1. Add new menu options in show_main_menu()
2. Create corresponding methods for functionality
3. Update the main loop in run()

🐛 Troubleshooting

Common Issues

1. Import Errors:

   pip install --upgrade rich

2. Database Issues:

   rm timetrakk.db  # Reset database (WARNING: loses all data)

3. Display Issues:

   • Check Termux font settings
   • Ensure terminal supports Unicode characters
   • Try different color schemes

4. Widget Issues:

   # Recreate shortcuts directory
   mkdir -p ~/.shortcuts
   chmod +x ~/.shortcuts/timetrakk

Getting Help

If you encounter issues:

1. Check that all dependencies are installed
2. Verify Python version (3.7+)
3. Check Termux permissions
4. Review the error messages

📄 License

This project is open source. Feel free to modify and distribute.

🤝 Contributing

Contributions are welcome! Some ideas:

• Add export functionality (CSV, JSON)
• Implement project categories/tags
• Add time goals and reminders
• Create backup/restore features
• Add data visualization charts

---

Happy Time Tracking! ⏱️✨