|
1 | | -# Timetracker (TT) ⏱️ |
| 1 | +# Time Tracker TUI ⏱️ |
2 | 2 |
|
3 | | -A simple command-line time tracking application written in Rust. |
| 3 | +A beautiful terminal-based time tracker built with Go and the Charmbracelet ecosystem. Track your completed tasks with automatic duration calculation and enjoy a stunning interface. |
4 | 4 |
|
5 | | -## Features |
| 5 | + |
| 6 | + |
| 7 | + |
6 | 8 |
|
7 | | -- Track your time spent on activities throughout the day |
8 | | -- Categorize activities by projects |
9 | | -- Record time when you start and finish tasks |
10 | | -- Generate detailed reports of your time usage |
11 | | -- Define different activity types (work, break, ignored) |
12 | | -- Export reports to CSV format |
13 | | -- Automatic handling of date ranges |
| 9 | +## ✨ Features |
14 | 10 |
|
15 | | -## Quick Start |
| 11 | +- 🎯 **Retrospective time tracking** - Log completed tasks with automatic duration calculation |
| 12 | +- 🎨 **Beautiful TUI interface** - Styled with Charmbracelet's Lipgloss |
| 13 | +- ⚡ **Simple workflow** - Start → Work → Complete tasks → View reports |
| 14 | +- 📊 **Real-time summaries** - Work/break/total time with project breakdowns |
| 15 | +- 🔄 **Task extension** - Extend the last task if you're still working on it |
| 16 | +- 💾 **Persistent storage** - JSON-based data storage with automatic backups |
| 17 | +- 🎨 **Color-coded activities** - Visual distinction between work, breaks, and ignored time |
16 | 18 |
|
17 | | -### Installation |
| 19 | +## 🚀 Installation |
18 | 20 |
|
19 | | -1. Make sure you have Rust installed (https://rustup.rs/) |
20 | | -2. Clone this repository |
21 | | -3. Build and install the project: |
22 | | - ``` |
23 | | - cargo install --path . |
24 | | - ``` |
25 | | -4. This will install the `tt` command to your PATH |
26 | | -5. Alternatively, run `./build.sh` |
| 21 | +### Prerequisites |
| 22 | +- Go 1.19 or later |
27 | 23 |
|
28 | | -### Basic Usage |
| 24 | +### Quick Install |
| 25 | +```bash |
| 26 | +# Clone the repository |
| 27 | +git clone https://github.com/pergatore/tt |
| 28 | +cd tt |
29 | 29 |
|
30 | | -1. Start your day: |
31 | | - ``` |
32 | | - tt hello |
33 | | - ``` |
| 30 | +# Install dependencies |
| 31 | +go mod tidy |
| 32 | + |
| 33 | +# Run the application |
| 34 | +go run main.go |
| 35 | +``` |
| 36 | + |
| 37 | +### Build Binary |
| 38 | +```bash |
| 39 | +# Build for your platform |
| 40 | +go build -o tt main.go |
| 41 | + |
| 42 | +# Move to PATH (optional) |
| 43 | +sudo mv tt /usr/local/bin/ |
| 44 | + |
| 45 | +# Or install with go install |
| 46 | +go install |
| 47 | +``` |
| 48 | + |
| 49 | +## 🎮 Usage |
| 50 | + |
| 51 | +### Key Commands |
34 | 52 |
|
35 | | -2. Add tasks as you complete them: |
| 53 | +#### Navigation |
| 54 | +- `↑/k, ↓/j` - Move up/down |
| 55 | +- `←/h, →/l` - Move left/right |
| 56 | +- `Enter` - Select/confirm |
| 57 | +- `Esc` - Go back |
| 58 | +- `q` - Quit application |
| 59 | + |
| 60 | +#### Actions |
| 61 | +- `s` - **Start day** (creates initial timestamp) |
| 62 | +- `a` - **Complete task** (log what you just finished) |
| 63 | +- `r` - **View report** (detailed today's summary) |
| 64 | +- `x` - **Extend last task** (continue working on previous task) |
| 65 | +- `?` - **Toggle help** (show all commands) |
| 66 | + |
| 67 | +### Workflow Example |
| 68 | + |
| 69 | +1. **Start your day** |
36 | 70 | ``` |
37 | | - tt add "Education: CKA Labs" # This will add CKA labs to the Education project |
38 | | - tt add "Lunch **" # This will add a break |
39 | | - tt add "Meeting: Standup" # This will add Standup to the Meeting project |
40 | | - tt add "Twiddlin' thumbs ***" # This will add a task that doesn't count toward working time (i.e commuting) |
| 71 | + Press 's' → Creates "Start" entry at current time |
41 | 72 | ``` |
42 | 73 |
|
43 | | -3. Generate a report for today: |
| 74 | +2. **Work on tasks** (time passes naturally) |
| 75 | + |
| 76 | +3. **Complete tasks as you finish them** |
44 | 77 | ``` |
45 | | - tt report |
| 78 | + Press 'a' → "Meeting: Standup" → Optional comment |
| 79 | + Duration automatically calculated from last entry |
46 | 80 | ``` |
47 | 81 |
|
48 | | -4. Edit your entries: |
| 82 | +4. **View your progress** |
49 | 83 | ``` |
50 | | - tt edit |
| 84 | + Press 'r' → Beautiful report with time breakdown |
51 | 85 | ``` |
52 | 86 |
|
53 | | -## Activity Types |
54 | | - |
55 | | -- **Work activities**: Regular activities that count toward working time. |
56 | | - Example: `tt add "admin"` |
| 87 | +### Task Types |
57 | 88 |
|
58 | | -- **Break activities**: Activities that count toward break time, marked with `**` at the end. |
59 | | - Example: `tt add "lunch **"` |
| 89 | +The application supports three types of activities: |
60 | 90 |
|
61 | | -- **Ignored activities**: Activities that are not counted in reports, marked with `***` at the end. |
62 | | - Example: `tt add "commuting ***"` |
| 91 | +- **Work tasks**: `"Meeting: Standup"`, `"Development: Bug fixes"` |
| 92 | +- **Break activities**: `"Lunch **"`, `"Coffee break **"` (end with `**`) |
| 93 | +- **Ignored time**: `"Commuting ***"`, `"Personal call ***"` (end with `***`) |
63 | 94 |
|
64 | | -## Project Notation |
| 95 | +### Project Format |
65 | 96 |
|
66 | | -You can group activities by projects using the `project: task` notation: |
| 97 | +Use the `Project: Task` format to categorize your work: |
67 | 98 |
|
68 | 99 | ``` |
69 | | -tt add "Education: CKA Labs" |
70 | | -tt add "Sprint-2: bug fix" |
| 100 | +Education: CKA Labs |
| 101 | +Sprint-2: Bug fix #123 |
| 102 | +Admin: Email cleanup |
| 103 | +Meeting: Daily standup |
71 | 104 | ``` |
72 | 105 |
|
73 | | -## Commands |
74 | | - |
75 | | -### `hello` |
| 106 | +## 📊 Interface Overview |
76 | 107 |
|
77 | | -Marks the beginning of your day: |
78 | | -``` |
79 | | -tt hello |
| 108 | +### Main Dashboard |
80 | 109 | ``` |
| 110 | +⏱️ Time Tracker |
81 | 111 |
|
82 | | -### `add` |
| 112 | +Latest: Education: CKA Labs (45min ago) |
83 | 113 |
|
84 | | -Adds a completed task: |
85 | | -``` |
86 | | -tt add [task description] |
87 | | -``` |
| 114 | +Recent Activities: |
| 115 | + 09:00-09:30 0h30 Meeting: Standup |
| 116 | + 09:30-10:15 0h45 Education: CKA Labs |
| 117 | + 10:15-12:00 1h45 Development: Bug fixes |
88 | 118 |
|
89 | | -Add with a comment: |
90 | | -``` |
91 | | -tt add "project: task" --comment "details about the task" |
92 | | -``` |
| 119 | +Today's Summary: |
| 120 | + Work: 2h30 |
| 121 | + Break: 0h30 |
| 122 | + Total: 3h00 |
93 | 123 |
|
94 | | -### `report` |
| 124 | +• Task completed: Education: CKA Labs (45min) |
95 | 125 |
|
96 | | -Generate a report of your activities: |
97 | | -``` |
98 | | -tt report |
| 126 | +Press ? for help, q to quit |
99 | 127 | ``` |
100 | 128 |
|
101 | | -Report for a specific date: |
102 | | -``` |
103 | | -tt report 2025-03-15 |
| 129 | +### Task Completion Flow |
104 | 130 | ``` |
| 131 | +✅ Task Completed |
105 | 132 |
|
106 | | -Report for a date range: |
107 | | -``` |
108 | | -tt report --from 2025-03-10 --to 2025-03-15 |
109 | | -``` |
| 133 | +What task did you just finish? |
| 134 | +Examples: 'Meeting: Standup', 'Lunch **', 'Commuting ***' |
110 | 135 |
|
111 | | -Filter by project: |
112 | | -``` |
113 | | -tt report --project "project-1" |
114 | | -``` |
| 136 | +Duration: 1h15 (since 09:30) |
115 | 137 |
|
116 | | -Export as CSV: |
117 | | -``` |
118 | | -tt report --csv-section per_day |
119 | | -tt report --csv-section per_task |
| 138 | +[Meeting: Daily standup____________] |
| 139 | +
|
| 140 | +Enter to continue • Esc to cancel |
120 | 141 | ``` |
121 | 142 |
|
122 | | -Additional options: |
123 | | -- `--details`: Show detailed breakdown even for multi-day reports |
124 | | -- `--comments`: Include comments in the report |
125 | | -- `--per-day`: Group activities by day |
126 | | -- `--no-current-activity`: Don't include current activity in the report |
127 | | -- `--month [this|prev|YYYY-MM]`: Show report for a specific month |
128 | | -- `--week [this|prev|number]`: Show report for a specific week |
| 143 | +## 📁 Data Storage |
129 | 144 |
|
130 | | -### `stretch` |
| 145 | +The application stores data in your system's standard configuration directory: |
131 | 146 |
|
132 | | -Extend the previous task to the current time: |
133 | | -``` |
134 | | -tt stretch |
135 | | -``` |
| 147 | +- **Linux/macOS**: `~/.config/timetracker/` |
| 148 | +- **Windows**: `%APPDATA%\timetracker\` |
136 | 149 |
|
137 | | -### `edit` |
| 150 | +### Files Created |
| 151 | +- `config.json` - Application configuration |
| 152 | +- `entries.json` - Your time tracking data |
138 | 153 |
|
139 | | -Edit your time log file in your default text editor: |
140 | | -``` |
141 | | -tt edit |
| 154 | +### Data Format |
| 155 | +```json |
| 156 | +[ |
| 157 | + { |
| 158 | + "timestamp": "2025-01-15T09:00:00Z", |
| 159 | + "name": "Start", |
| 160 | + "comment": "" |
| 161 | + }, |
| 162 | + { |
| 163 | + "timestamp": "2025-01-15T09:30:00Z", |
| 164 | + "name": "Meeting: Standup", |
| 165 | + "comment": "Sprint planning discussion" |
| 166 | + } |
| 167 | +] |
142 | 168 | ``` |
143 | 169 |
|
144 | | -### `config` |
| 170 | +## 🎨 Color Coding |
145 | 171 |
|
146 | | -View or modify configuration: |
147 | | -``` |
148 | | -tt config |
149 | | -tt config --filename |
150 | | -tt config --default |
151 | | -``` |
| 172 | +- 🔵 **Work activities** - Blue text |
| 173 | +- 🟠 **Break activities** - Orange text |
| 174 | +- ⚪ **Ignored activities** - Gray text |
| 175 | +- 🟢 **Current status** - Green text |
| 176 | +- 🔴 **Error messages** - Red text |
| 177 | +- 🟢 **Success messages** - Green text |
152 | 178 |
|
153 | | -## Configuration |
| 179 | +## 🏗️ Built With |
154 | 180 |
|
155 | | -The configuration file is stored at: |
156 | | -- Linux/macOS: `~/.config/timetracker/tt.json` |
157 | | -- Windows: `%APPDATA%\timetracker\tt.json` |
| 181 | +- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - Terminal UI framework |
| 182 | +- [Bubbles](https://github.com/charmbracelet/bubbles) - Common TUI components |
| 183 | +- [Lipgloss](https://github.com/charmbracelet/lipgloss) - Styling and layout |
158 | 184 |
|
159 | | -Settings include: |
160 | | -- Data file location |
161 | | -- Default editor |
162 | | -- Timezone settings |
| 185 | +## 🤝 Contributing |
163 | 186 |
|
164 | | -## Data File Format |
| 187 | +Contributions are welcome! Please feel free to submit a Pull Request. |
165 | 188 |
|
166 | | -Each entry follows this format: |
167 | | -``` |
168 | | -YYYY-MM-DD HH:MM[+/-HHMM] activity name [# comment] |
169 | | -``` |
| 189 | +1. Fork the repository |
| 190 | +2. Create your feature branch (`git checkout -b feature/amazing-feature`) |
| 191 | +3. Commit your changes (`git commit -m 'Add amazing feature'`) |
| 192 | +4. Push to the branch (`git push origin feature/amazing-feature`) |
| 193 | +5. Open a Pull Request |
170 | 194 |
|
171 | | -Example: |
172 | | -``` |
173 | | -2025-03-15 09:00+0100 Hello |
174 | | -2025-03-15 10:30+0100 Education: CKA Labs |
175 | | -2025-03-15 12:00+0100 Lunch ** |
176 | | -2025-03-15 13:00+0100 Sprint-69: implementing feature JIRA-069 |
177 | | -``` |
| 195 | +## 📝 License |
| 196 | + |
| 197 | +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. |
| 198 | + |
| 199 | +## 🙏 Acknowledgments |
| 200 | + |
| 201 | +- [Charmbracelet](https://charm.sh/) for the amazing TUI toolkit |
| 202 | +- [Conventional Commits](https://conventionalcommits.org/) for inspiration on task categorization |
| 203 | +- The Go community for excellent tooling and libraries |
| 204 | + |
| 205 | +## 🐛 Issues & Support |
| 206 | + |
| 207 | +If you encounter any issues or have questions: |
178 | 208 |
|
179 | | -## License |
| 209 | +1. Check the [Issues](https://github.com/pergatore/tt/issues) page |
| 210 | +2. Create a new issue with: |
| 211 | + - Your operating system |
| 212 | + - Go version (`go version`) |
| 213 | + - Steps to reproduce the problem |
| 214 | + - Expected vs actual behavior |
180 | 215 |
|
181 | | -This software is released under the GPL-3.0 License. |
| 216 | +--- |
182 | 217 |
|
183 | | -## Shoutout & Accolades |
184 | | -This is heavily inspired by a probably better tool [UTT](https://github.com/larose/utt) by [larose](https://github.com/larose) |
185 | | -This was mainly used as a learning journey for using rust and some added functionality I needed for my work, you can practically consider this unmaintained. |
| 218 | +**Happy time tracking! ⏰** |
0 commit comments