DEV Community

Cover image for I shipped super-time-tracker-ui, a local web UI for my CLI time sheets
Cris Mihalache
Cris Mihalache

Posted on

I shipped super-time-tracker-ui, a local web UI for my CLI time sheets

The short version

If you live in the terminal but still wish your time sheets had a real interface, I built the thing for you. It's called super-time-tracker-ui and it's now on npm.

npm install -g super-time-tracker-ui
stt-ui
Enter fullscreen mode Exit fullscreen mode

That's it. The stt-ui command boots a local server and opens your browser to a full time tracking dashboard. No accounts required, no cloud required, no setup wizard.

super-time-tracker-ui

Why I made it

I have a CLI called super-time-tracker that stores everything in a plain JSON file at ~/.super-time-tracker/db.json. The CLI is great for quick check ins and check outs, but reviewing a month of work in a terminal is rough. Pie charts in ASCII only get you so far.

super-time-tracker

So instead of bolting a clunky reporting command onto the CLI, I made a web UI that reads the exact same database file. Same data, two front ends. Track from the terminal, review in the browser, and they stay in sync because they're literally pointing at the same file. When the UI loads, it even migrates and dedupes the database on the fly so old data keeps working.

What it actually does

The home screen is the tracker. You check in with a description and inline @tags, watch the live timer, and check out when you're done. Entries pile up under the active sheet and you can do real work on them:

  • Edit, move between sheets, split, and merge entries
  • Archive things you want out of the way without deleting them
  • Bulk move or bulk delete a whole selection at once
  • Resume a past entry with one click
  • Attach, edit, and delete timestamped notes on any entry

Sheets work like separate timesheets. Create them, rename them, archive them, switch between them with keyboard shortcuts. Tag filtering supports both "match any" and "match all" modes.

The reporting dashboard

This is the part the CLI could never do well. There's a proper analytics view with:

  • A tag pie chart so you can see where the hours actually went
  • Daily bar charts and weekday breakdowns
  • An activity heatmap, the GitHub contributions style grid
  • Trend cards that compare periods
  • A month in review summary
  • Flexible date range picking with handy shortcuts
  • Focus goals and gentle nudges

The reporting dashboard

You can set a weekly focus target, define your working hours, and pick a focus sheet. If you forget to log anything for a while, the app nudges you. If you're slacking on your target, it lets you know without being annoying about it. It's the accountability buddy that doesn't judge.

A built in Pomodoro timer

There's a real Pomodoro view with configurable work and break cycles. It ties into the tracker, so a focus session and a tracked entry can move together. Desktop notifications fire when a phase ends, so you can stop staring at the countdown.

AI descriptions, your key, your call

Writing entry descriptions gets boring. The app can generate a concise description for you from your current text and any notes you attached. You bring your own API key and pick the provider:

  • OpenAI
  • Claude
  • Google AI

Keys live in your own preferences and the request goes straight to the provider you chose. Skip this entirely if it's not your thing. Nothing depends on it.

Optional cloud sync

By default everything is local and offline. But if you want your sheets on more than one machine, there's optional Supabase sync. Sign in, then push and pull manually or let it sync automatically. Turn it on only if you want it.

The little things that make it pleasant

  • A command palette so you can jump anywhere fast
  • Keyboard shortcuts everywhere, with customizable quick actions
  • Light, dark, and system themes plus a few accent palettes
  • Desktop and in app notifications
  • It's a PWA, so you can install it and use it offline
  • Display knobs for time format, duration format, week start day, compact lists, seconds in the timer, and a live timer in the tab title

Backup, restore, import, and markdown export for your data

Under the hood

It's a Next.js 16 app on React 19, styled with Tailwind 4. The npm package ships a standalone build plus the stt-ui launcher. The launcher frees the port if a previous instance is still running, waits for the server to come up, then opens your default browser. You can override the port, the bind host, or tell it to skip opening a browser.

PORT=8080 stt-ui
STT_UI_HOSTNAME=0.0.0.0 stt-ui
stt-ui --no-open
Enter fullscreen mode Exit fullscreen mode

You'll need Node 20 or newer.

Try it

npm install -g super-time-tracker-ui
stt-ui
Enter fullscreen mode Exit fullscreen mode

Then open http://127.0.0.1:3000 and start tracking. It's MIT licensed and the source lives on GitHub. If you find a bug or want a feature, open an issue. I'd love to hear how you use it.

Happy tracking.

Top comments (1)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.