Kopi: Track Your Coffee Brewing & Consumption

Everyone who skimmed over the content on this website has probably noticed that I’m somewhat of a coffee enthusiast. Not only do I take pleasure in drinking coffee, but I’m also enjoying the process of grinding beans, steaming milk, and preparing fresh espresso every day.

I usually drink around two cups of coffee per day: One that is a milk-based drink (e.g. a Cappuccino) in the morning, and another one that is a black coffee in the afternoon, with enough time for the caffeine to be largely gone by the time I go to bed. I don’t drink coffee due to the effects that caffeine has, but rather despite them. For me, having a cup of coffee is an enjoyable and calming ritual. Whenever I find good decaf beans that a roasted to my liking I don’t hesitate to buy a bag. However, obviously, there’s a bigger selection of regular, caffeinated coffee beans.

To understand which combinations of roasts, flavors, and preparation methods I like and which ones not so much, I began writing down the coffee that I consumed. At first, I only had a list of coffee beans that I would rate, which I eventually integrated into this website. However, to be able to understand how changing individual variables, like the grind coarseness, affect the result and to identify what changes led to a more enjoyable cup of coffee for me, I began writing down many of these details.

I ended up with a load of different documents, from physical notebook pages, over digital pages on AnyType, all the way to plain text documents on my computer. Each of these documents would contain one set of info, like my grinder’s coarseness setting over time, the type of milk that I would use for individual cups, water temperatures, and the amount of ground coffee per shot/pour.

To consolidate all this information I began looking for a tool – preferably a command-line tool – that would allow me to track all this data in a single place. I wanted to have a tool that uses an open data format to store this information, so I’m not locked into a proprietary solution, and that doesn’t use the cloud to store my data or track my usage.

Unfortunately, most apps are either privacy nightmares or implement very limited functionality, usually more dedicated towards the actual brewing process using specific methods. Also, I don’t feel like having to hack all the information that goes into one cup of coffee into my smartphone. But more on that later.

Long story short, I set out to build a coffee journal tool that would prioritize the collection of in-depth information over fancy user interfaces, brew timers, and similar features.

Meet Kopi

Kopi is a command-line (CLI) coffee journal (or habit tracker), designed for coffee enthusiasts. It lets you track coffee beans, equipment usage, brewing methods, and individual cups.

From Malay kopi (“coffee”) and Hokkien 咖啡 (ko-pi); the latter is also derived from the former.
– Wiktionary

The tracked data offers insights into bean and roast preferences, caffeine and dairy consumption, and equipment usage patterns. This helps users refine their coffee choices while managing caffeine intake for a more enjoyable and responsible experience.

Kopi focuses on meticulously tracking every step of the coffee preparation process. Unlike standard coffee or caffeine tracking apps, it requires more detailed input to function effectively. If you only want to track the cups of coffee you drink without monitoring the beans/roasts and the preparation methods used, Kopi may not be the best fit for you. Think of Kopi as a coffee journal that lets you rate individual roasts and analyze how different roasts, brewing methods, and drink types influence your preferences.

Kopi stores everything locally and does not send any data to third-party services unless explicitly mentioned before an operation (e.g. requesting current exchange rates from the ECB, for price input/conversions of individual coffee bags). Kopi does not employ analytics libraries/services.

Kopi follows a structured three-step workflow for tracking coffee consumption, essential for its functionality and insights. The first step is typically done once — during setup or when equipment changes. The second step is performed regularly, while the third step, tracking actual consumption, is done for every cup.

Steps

Step 1: Add equipment

Coffee equipment is the first piece of information that Kopi requires. Most coffee enthusiasts will usually have at least two pieces of coffee equipment at their disposal:

• A coffee grinder
• A coffee maker

This equipment needs to be added to Kopi before tracking coffee brewing and consumption. To do so, the following command is used:

▲ kopi equipment add

Note: If you don’t have coffee brewing equipment and typically get your coffee from a barista, add their brewing method as a dummy entry. For espresso-based drinks, add an espresso maker; for pour-overs or AeroPress, add a coffee maker. However, keep in mind that Kopi is not designed for tracking individual cups from various coffee shops—there are better tools for that. Instead, Kopi is aimed at coffee enthusiasts who want to document their coffee experiences, ideally using their brewing methods.

Step 2: Open a bag of coffee

Coffee bags are the second key element in tracking brewing and consumption. Every cup requires a designated bag of coffee. Previously opened bags can be used until their beans are depleted, at which point a new bag must be opened. Multiple bags can be open at the same time, but only one can be selected per cup. For blends, a dedicated bag must be prepared and then opened.

To open a new bag of coffee the following command is used:

▲ kopi bag open

Step 3: Drink a cup of coffee

To track a cup of coffee, the following command is used:

▲ kopi cup drink

Insights

A wide range of insights can be extracted from the data that has been tracked over time. The kopi insights command aggregates the information and displays it. It supports multiple output formats and custom periods. For more information check the output of kopi insights --help.

Ranking

The database calculates an overall ranking for each coffee based on ratings from individually tracked cups. Use the kopi coffee ranking command to view the ranking:

(ltr: Rank, coffee name, roaster, score calculated from individually rated cups)

“This is awesome, but how can I track coffee cups that I enjoy in cafés or on the go? Does Kopi have a …

Mobile App

What have been the cool kids on the block a decade ago – namely mobile apps – are now being looked down upon as an annoyance that nobody asked for, let alone wants. More and more people want fewer apps rather than more or even try to get rid of their smartphones altogether for good old mobile phones, and rightfully so. While I don’t agree with the advocates around the dumbphone movement, I nevertheless support the argument that not everything in our lives requires a mobile app.

And as if rejecting smartphones and mobile apps wasn’t already the new black enough, many people push even further in their efforts to go back to the basics: Why not replace all those fancy calendars and to-do apps with just a pen and paper? Even the people who make a living off others watching their videos (predominantly) on smartphones have hopped on the pen-and-paper trend, rejecting modern, digital tools for good old notebooks and mechanical pencils.

Kopi follows this trend and therefore rejects having a dedicated smartphone app. But fear not, you can nevertheless use Kopi without your computer, using only a mobile device!

May I introduce:

The Kopi “mobile app”!

Kopi’s “mobile app” is indeed pen and paper. Whenever you are not on your computer and hence unable to track a cup of coffee directly within the Kopi CLI, you can jot it down on a piece of paper.

“Wait, what? Are you kidding?”

Not at all. You can simply write down your coffee consumption, and as soon as you get to it, take a photo of your notes and import it into Kopi, using the kopi import command. Leveraging modern large language models, Kopi uses – buzzword incoming! – “AI” to scan your notes and import them in the structured and open format that it uses internally. Depending on the amount of information that you jotted down, Kopi will ask you a few more questions (using its interactive TUI wizard) to fill in the blanks. However, in the (not-so-distant) future, Kopi will learn to auto-complete most missing information, resulting in even less paperwork for you.

How does it work? (a.k.a the technical mumbo-jumbo)

Kopi uses Ollama as a backend for its import feature. At the moment, it requires a running Ollama instance somewhere on your computer or reachable via network, and it performs the optical character recognition (OCR) using the llama3.2-vision (11b) model. Even without a dedicated GPU, Kopi can process a photo within around a minute on somewhat older yet decent hardware.

In my tests, I was able to get responses from Ollama running on my AMD Ryzen 9 5950X workstation usually within less than a minute. On my AMD Ryzen 7 5800U laptop, however, performance was significantly worse and wait times amounted to around twenty minutes. Bear in mind, though, that these numbers refer to imports running on solely the CPU, without any GPU involvement. With a supported GPU imports should be instant.

As soon as the LLM performs the OCR and returns with a structured JSON response, Kopi will complete the provided information with everything that it requires to import the data. At this stage, the completion is being done by selectively asking the user questions about the required details. However, in the future Kopi will try to look up the information on its own, so that the user will have an easier time importing handwritten logs of their coffee consumption into Kopi.

Where do we go from here?

The import feature is not only intended for the continuous use of Kopi while on the go, but also for first-time users who would like to move from a purely pen and paper-driven workflow to a Kopi-supported one. Existing journal entries can be ingested by Kopi, ideally without much subsequent work from the user, allowing the tool to display insightful metrics based on pre-existing data.

In addition, the visual recognition capabilities can hopefully be enhanced for Kopi to be able to not only import scans of structured hand-written notes but also photos of bags of coffee – making it easier to import new consumable coffee bags into the database – and maybe one day even cups of coffee with their data extracted primarily from photos.

Additionally, alternative LLM backends might be something worth exploring, for everyone who would prefer using a paid cloud service over a self-hosted solution.

Status

Kopi is still in its early stages. Some features might not be working as expected and others might very well be missing. If you depend on your coffee journal, do not use Kopi at this stage, as things might change and, in the worst case, randomly break. If you’re feeling adventurous or you’re looking to contribute to the project, I would be happy for you to give Kopi a try, and let me know what you think of it!