A dead-simple terminal time tracker.
One key to start. One key to switch. One key to stop.
Install · Usage · Reports · Contributing
Most time tracking tools are either clunky web apps that demand your attention, or over-engineered CLIs with a dozen subcommands and flags. You just want to press one key when you sit down, and another key when you switch tasks. That's it.
Fuso is a terminal-native time tracker that lives in your terminal and gets out of your way. No accounts. No cloud. No config files to learn. You open it, press s, and you're tracking. Press 3 to switch to "Meeting." Press s again to stop. Done.
Your data is yours - plain JSON files in ~/.fuso/.
Idle — one keypress to start tracking.
Tracking time with live category breakdown and per-category totals.
Weekly and monthly reports with CSV export.
- One-key workflow —
sto start/stop,1–9to switch categories,pto switch projects - Minimalist TUI — only what matters is on screen, nothing else
- Offline & private — all data stored locally in
~/.fuso/as plain JSON - Suspend-safe — if your laptop sleeps or hibernates, the timer stops automatically at the last known time (works in WSL too)
- CSV export — weekly and monthly reports, ready for timesheets or invoicing
- Zero config — sensible defaults on first run, customize via the built-in settings screen
- Ruby 3.2+ (Ruby 4.0+ recommended)
- A terminal with 256-color support
gem install fusoThat's it. Now run fuso from anywhere.
yay -S fusoOr with any other AUR helper. See the AUR package page.
git clone https://github.com/AfonsoNeto/fuso-tui.git
cd fuso-tui
bundle install
bundle exec exe/fuso- Launch
fuso - Press
sto start tracking - Press
1–9to switch between categories - Press
sto stop - Press
rto view reports
That's it. No flags, no subcommands, no YAML.
Imagine you're a developer working on two projects. You open Fuso in the morning:
→ Press s to start tracking "Development" on "Project Alpha"
→ A meeting starts — press 3 to switch to "Meeting"
(Development time is saved automatically)
→ Meeting ends — press 1 to switch back to "Development"
→ Need to help a colleague — press 4 for "Support"
→ End of day — press s to stop
→ Press r then e to export your timesheet as CSV
Every category switch is a single keypress. No interruptions. No context switching away from your terminal.
| Scenario | How Fuso Helps |
|---|---|
| Freelancer billing | Track hours per project/category, export CSV for invoicing |
| Team standups | Glance at yesterday's breakdown before standup |
| Focus tracking | See where your time actually goes vs. where you think it goes |
| Contractor timesheets | Monthly reports with weekly breakdown, ready for submission |
| Key | Action |
|---|---|
s / Space |
Start or stop the timer |
1–9 |
Switch to category by number |
p |
Cycle through projects |
m |
Open settings (manage projects & categories) |
r |
Open reports |
q / Ctrl+C |
Quit (active session is saved automatically) |
| Key | Action |
|---|---|
↑ / ↓ |
Navigate list |
Tab |
Switch between projects and categories |
a |
Add new item |
d |
Set selected item as default |
x |
Delete selected item |
Esc |
Back to main screen |
| Key | Action |
|---|---|
Tab |
Toggle between weekly and monthly view |
← / → |
Navigate between weeks or months |
e |
Export current view as CSV |
Esc |
Back to main screen |
Press r to open the report view. Use Tab to switch between weekly and monthly breakdowns. Navigate with ← / →.
Press e on the report screen to export. Files are saved to ~/.fuso/exports/:
~/.fuso/exports/fuso_weekly_2026-W25.csv
~/.fuso/exports/fuso_monthly_2026-06.csv
The monthly CSV includes a weekly breakdown with columns for each week-ending date, matching a standard timesheet format.
You can also view reports without the TUI:
fuso report weekly # Current week summary
fuso report monthly # Current month summaryAll data lives in ~/.fuso/:
~/.fuso/
├── config.json # Projects, categories, defaults
├── sessions.json # All time entries, keyed by date
├── heartbeat # Active tracking timestamp (auto-cleaned)
└── exports/ # Exported CSV files
Everything is plain JSON. You can read it, edit it, back it up, or sync it however you want.
If your laptop goes to sleep, hibernates, or suspends — or if you close the lid and come back later — Fuso won't count the sleep time as work.
While the timer is running, Fuso writes a heartbeat timestamp to ~/.fuso/heartbeat every 10 seconds. When it wakes up and notices the gap is too large (>60s), it saves the session at the last known heartbeat time and stops the timer.
This works everywhere: native Linux, WSL, macOS — no D-Bus, no systemd, no OS-specific APIs needed.
- Ruby — simple, readable, gets the job done
- Charm Ruby —
bubbletea(Elm Architecture TUI),lipgloss(styling),bubbles(components)
Contributions are welcome! Whether it's bug fixes, new features, documentation improvements, or just ideas — all are appreciated.
# Clone the repo
git clone https://github.com/AfonsoNeto/fuso-tui.git
cd fuso-tui
# Install dependencies
bundle install
# Run the test suite
bundle exec rake test
# Launch the app
bundle exec exe/fusoThe project uses Minitest. All tests run in an isolated temporary directory so your actual ~/.fuso/ data is never touched.
bundle exec rake testlib/fuso/
├── app.rb # Main Bubbletea model (Elm Architecture)
├── config.rb # Config loading & persistence
├── session.rb # Time entry recording & queries
├── heartbeat.rb # Suspend detection via heartbeat file
├── styles.rb # Lipgloss style definitions
└── views/
├── main_view.rb # Timer screen (idle + tracking)
├── settings_view.rb # Project/category management
└── report_view.rb # Weekly & monthly reports + CSV export
- Keep it minimal. Every feature should earn its screen space.
- Follow the Elm Architecture pattern (
init→update→view). - Add tests for new functionality.
- No external services, no network calls, no accounts.
This project is licensed under the MIT License.