If you are a developer, your life has a lot of suffering. Here is a package to bring some sunlight into the abyss that is your soul. Raise a hand if the following scenario is familiar to you.

After a long session of coding, you finally run the script that trains your machine learning model (or data processing, or some other batch operation). You do not know when it will finish. You want to open a beer, sit on the couch, relax and watch Netflix while your code is running. But something is eating you inside. An uncontrollable urge compels you to check the computer. Maybe the code threw an exception. Maybe it completed the execution and waiting idle. There is no way to know that, right? WRONG! From now on, you are in control! Use headsup to be notified when your code completes execution (or practically at any stage of your code).

You have two options:

1.   headsup.local
2.   headsup.remote

headsup.local allows you to play a cool sound file when you call the headsup() method. Simple? Because it should be simple!

headsup.remote on the other hand, allows you to communicate the status of your code with the Heads up server, which you can tap into using the browser your laptop or your mobile phone. You will simply be given a heads up when your code reaches a certain stage in execution.

headsup.remote notification also allows you to receive messages via Telegram app. To enable that, you must send a text message to headsupbot via Telegram. This will introduce you to the bot. After that, you can start watching handles. Give /help command to the bot to learn more about the usage.

To start watching a handle, visit:


Use the package manager pip to install heads-up.

pip install heads-up


headsup() gives a voice notification when called.

>>> from headsup.local import headsup
>>> headsup()

It is possible to change the sound to play. Check out the parameters.

>>> headsup(loop=True) # sound the notification repeatedly.
>>> headsup(soundname='soundfile.wav') # set the soundname parameter to customize the notification. 


watch() retrieves an identifier from the headsup server and prints the instructions to start watching the identifier. Call it before the execution of your long-running code.

>>> from headsup.remote import watch, notify
>>> watch_code = watch()

Your watch code: MBOL
Visit the following URL:
Alternatively, give this code to headsupbot on Telegram app to start watching.

You can also summon a QR code and scan it to start watching switfly.

>>> watch(QR=True, QRInline=True)

notify(watch_code, message_text) gives a notification to everyone watching the provided watch_code. Call it at a point where you want to get a notification such as after the end of your long-running code.

>>> notify("MBOL", "Code execution complete!")

Heads-up server successfully notified. All watchers should receive a headsup!


You can also get a heads-up via Telegram app. To do so, you will need Telegram app installed on your phone, and introduce yourself to headsupbot simply by sending a message. Otherwise, headsupbot will not be able to notify you.

Here are several commands that you can use while interacting with headsupbot:

  >>> /hi       # greet the bot
  >>> /help      # display usage instructions
  >>> /status   # show the list of handles that you are actively watching 
  >>> /stop     # remove all handles from your watch list
  >>> Enter a 4-character code (case sensitive) to start watching it. 
      If you enter the same code again, you will stop watching it. 


If you want to implement your own client, you can still use the heads-up service API.

To request a unique watch code, simply send a POST request to the following URL with two empty parameters; room and status:

  curl -d '{"room":"","status":""}' -H "Content-Type: application/json" -X POST

To notify the clients that are watching a particular code, send a POST request to the following URL with the same two parameters, only this time, assign values to those parameters:

  "room": 4-character watch code. 
  "status": A string that contains the headsup message you want to send
  curl -d '{"room":"1234","status":"Complete"}' -H "Content-Type: application/json" 
       -X POST


You can contact the developer team (me) on

To download the Python client, please visit:

To start watching a handle, visit: