⏰ TimSum

Beautiful Timewarrior summaries in your terminal

Transform your time tracking data into stunning, colorful terminal displays

Installation • Usage • Themes • Contributing

---

✨ Features

🚀 Lightning Fast Terminal-native performance with instant summaries 🎨 Beautiful Themes Catppuccin palettes + unlimited custom themes ⏱ Flexible Ranges From daily snapshots to complete history

💻 Clean Installation Isolated virtual environment, zero conflicts 🎯 Consistent Colors Tags maintain colors across all views 📊 Rich Formatting Elegant tables powered by Rich library

---

🚀 Installation

🏠 Local Installation (Recommended)

Perfect for personal use - installs in your home directory without touching system files.

git clone https://github.com/yourusername/timsum.git
cd timsum
bash install.sh

💡 Pro tip: The installer will guide you through local vs system-wide options

🌐 System-Wide Installation

For system administrators or multi-user setups.

git clone https://github.com/yourusername/timsum.git
cd timsum
sudo bash install.sh

📝 PATH Setup

Add to your shell configuration (~/.bashrc or ~/.zshrc):

export PATH="$HOME/.local/bin:$PATH"

---

🎮 Usage

Quick Start

# Weekly summary with Mocha theme
timsum --theme mocha --range :week

# Monthly overview with custom theme
timsum --theme kanagawa --range :month

# Complete history with Latte theme
timsum --theme latte --range :all

🎛 Command Options

Option	Description	Examples
--theme	Color theme	mocha, latte, frappe, macchiato, kanagawa
--range	Time period	:day, :week, :month, :all

---

⚙️ Configuration

📄 Config File

TimSum reads configuration from:

Installation	Config Path
Local	~/.config/timsum/timsum.conf
System	/etc/timsum/timsum.conf

Example configuration:

[timsum]
theme = mocha
range = :week

🔄 Override: Command-line arguments always take precedence

---

🎨 Custom Themes

🎪 Built-in Themes

There are 22 Built-in themes but you can add your own. (See Below)

🎭 Create Your Own

1. Choose your theme directory:

Installation	Theme Directory
Local	~/.config/timsum/themes/
System	/etc/timsum/themes/

2. Create a JSON theme file:

{
  "base": "#1f1f28",      // Background color
  "text": "#dcd7ba",      // Primary text
  "accent": "#7e9cd8",    // Headers & totals  
  "highlight": "#ff9e3b"  // Emphasis & highlights
}

3. Save and use:

# Save as ~/.config/timsum/themes/mytheme.json
timsum --theme mytheme --range :week

🌸 Example: Kanagawa Theme

# Create the theme
cat > ~/.config/timsum/themes/kanagawa.json << 'EOF'
{
  "base": "#1f1f28",
  "text": "#dcd7ba",
  "accent": "#7e9cd8",
  "highlight": "#ff9e3b"
}
EOF

# Use it immediately
timsum --theme kanagawa --range :month

---

🛠 Development

🏗 Setup

git clone https://github.com/yourusername/timsum.git
cd timsum

# Create development environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run locally
python timsum.py --theme mocha --range :week

🧪 Testing

# Test with different themes
python timsum.py --theme latte --range :day
python timsum.py --theme frappe --range :month
python timsum.py --theme macchiato --range :all

---

🤝 Contributing

We love contributions! Here's how to get started:

🐛 Found a Bug?

Open an issue with details and steps to reproduce.

💡 Have an Idea?

Start a discussion about new features.

🔧 Ready to Code?

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to your branch: git push origin feature/amazing-feature
5. Open a Pull Request

📋 Style Guide: We follow PEP 8 for Python code

---

📚 Roadmap

✅ Completed

• Config file support
• Custom theme system
• Consistent tag coloring
• Virtual environment installation

🚧 In Progress

• 📊 Export to CSV/JSON
• 🖥 Interactive TUI mode

---

📜 License

Released under the MIT License - see LICENSE for details.

---

🙏 Acknowledgements

Built with amazing open-source projects

Inspired by terminal productivity tools like tldr, glances, and bat

---

Made with ❤️ for the terminal

⬆ Back to top