A Start

Since november 2024 I have been building a TUI (Terminal User Interface) for Toggl. In reality this post has been long overdue for a long time now, as a lot of progress has been made, modules have been refactored or entirely removed. There is a silver lining to this though, as there will be a lot ground to cover.

The idea for this project originated some time in early 2024, when Toggl decided to stop development and deprecated the Linux app and a need arose for a desktop tool that would allow me to visually edit tracker entries. In some ways I also wanted data ownership, which gave me permanent access to my trackers; allowing me to build custom tools to analyse the data or for expanding scope of the tool.

Initially I started building an wrapper for the API, which I also wanted to use for an Ulauncher extension I had built previously. This allowed me to segregate the backend and frontend logic into separate components so I could reuse it for different applications.

Tech Stack

Around the same time the idea for this project shot into my head I found Textual and it poked out to me as interesting foundational framework for the application. It sat dormant in my mind for while initially considering using PyQt, which I had utilised extensively before, but as it was a tool I use while working there was a need to permanently have it open in one of my Kitty tabs, so using something new was up on the drawing board.

With the main tool out of the way I chose some proven Python libraries: SQLAlchemy for all the database needs and HTTPx for external requests were added and through the pain of dealing with date and time so much I have grown to like Whenever a lot. Hoping will allow me to deal with these issues much more effectively, as there are just so many traps one can fall into when dealing with time and a solid package that mitigates most of these problems was needed on the menu.

Project Structure

Excalidraw was used to design an user interface with various features. Creating a bunch of layouts allowed me to easily flesh out the application design and primarily work on the integration logic. These layouts changed drastically, as I kept working on the application and learning about the possible functionality of Textual.

In this case Toggl uses a multi entity structure which I can use as the foundation of my design. This allowed me to create a simple structure of widgets which could be abstracted into a few classes, which could manage most of the UI logic.

As mentioned previously the project has a different repository as the backend therefore its easy to split up and differentiate between each of the modules. Most of the project frontend uses semantics set by Textual, which follows a very similar system to the web developer world. A simplified description would be that you compose a layout with a bunch of containers/widgets and that gets delivered to a DOM allowing you to query it and update depending on events within the code. Even though the workflow is designed to be similar to a web development; compared to other frameworks I have used this has felt like the most native library to Python.

Technical Challenges

Since most the project is developed through the terminal, all of your visuals will be designed through Unicode characters and that has brings a hurdle of challenges. In some was this simplified the design, as very complex interfaces are possible, but take a lot of finesse to achieve. This in turn reduces the resolution of the project, as the amount of characters available to the user is determined by the terminal emulators font size. For example my full screen Kitty window is 274 columns wide and 55 rows tall. This limitation provides an interesting opportunity for design and can still lead to eye please and functional design, as long as you are careful enough with your layouts.

Design

With my previous professional direction being in architectural design I wanted to make sure the visuals of the applications are striking. Luckily a lot of elements from my drafting days show up here. Textual CSS(TCSS) has a builtin hatch property which you can use, if used correctly it leads to very interesting effects. One of my favourites is to use vertical or horizontal hatching to provide some sort grip for the user to use similar to physical products in the real world.

Camera lens grip in the physical world.	Hatched container in a Textual user interface.

At the time of this writing most terminal emulators don't support variable text size it's difficult to keep consistent traditional graphic design and UI/UX rules. You still have access various font styles such as bold, italics and underlines, but that is lacking since you can't really grow hierarchy this way. The best way to approach this is to use colour and line weights. For the latter you can use box-drawing characters to creating division and use limited weights in order to generate some sort of ladder of importance. Access is available to ASCII fonts such as Figlet, but I find if not sparingly used the aesthetic and functional charm of the application degrades very quickly.

Colour becomes utterly important here, as you need to elegantly convey what the user is doing at a point in time. Textual added themes around a month into the development of this application, which has made much easier to deal with these issues. My findings were, as long as you follow a few key rules your designs end up being much more striking and effective in the long run. As always you can break these rules, as with any design advice, with this in mind be wary as too many broken rules will lead back to chaos.

Variable	Rule
$primary	Widget Has Focus
$secondary	Widget Is Hovered
$accent	Important or Passively Active Element e.g. Current Time, Date or Cursor.

Timeline

Visual interactivity is important to me as well, which might be counter intuitive with the choice of medium. A Timeline widget ticked these boxes for me, as I could visually see overlaps, adjust and block out time slots easily. Similar to many other calendar applications in that way.

A big issue was plaguing me here was dealing with the start and end times of trackers, as you can not rely on pixel precision when drawing the entries, so you have to round the values to the nearest accuracy. In most cases this is fine, but if the user wants to deal with more fine grained details of a tracker it becomes cumbersome. Implementing scaling is required here, so the user can at least get 30 second intervals between applications. As all float values get truncated to the nearest integer the positioning can often misalign if not calibrated correctly.

Timeline Scaling Functionality

Timeline Entry Extents

)

DB Operations

Since the goal is to add offline capability at some point in the future, which means database handling needs to be at its most capable, in order to remain consistent across the local and remote APIs. Even just dealing with fleeting cache, this can cause a bunch of issue across the board for the user; for example I am using multiple Toggl clients which need to keep data in sync. In most cases adding a simple manual synchronisation feature to an application can avoid this, but this not a user friendly feature, as the user is not notified explicitly whether certain data is out sync and needs to know if they have kept their data in sync.

Time Oh Time

Since the application is primarily dealing with time a lot of issues popped up surrounding that domain. Time-zone's can be a pain to crack and therefore are terrible to deal with; the variance here being that different countries will have varying ways of handling those time zones. In some cases the jump for daylight saving time will be causing issues in a lot of regards. You would could expect users to set their timezone correctly as well, but that is also incorrect in a lot of ways. In previous projects my a lot of errors come from the DST switch, where the client will interpret times differently compared to the backend server. For further reading I would recommend this read this gist about various fallacies that programmers face when dealing with time.

The Future

In reality I have been close to finishing this project for a while now, but burnout and other issues been plaguing progress for a while. Two months of coding was the initial goal, but scope creep-ed further with me wanting more features and a better baseline for future additions. Even though it was ultimately delayed and I surprised myself how much could be achieved in two months.