Starship with bash: customize the status command line with a workday hour counter

I am a big fan of of Starship Cross-Shell prompt see https://starship.rs/

You can add to the command line very fancy information besides the default stuff that is also extremely useful.

You can add a workday hour counter to your Starship prompt by creating a small script and then telling Starship to display its output using a custom command module.

This counter will calculate and display the hours and minutes that have passed since your workday began.

Here’s how to set it up in three simple steps.

To set the work start dynamically with a command, you need command (workstart) that saves your start time to a temporary file.

This setup is persistent across all your terminal windows for the rest of the day.

Step 1: Create the workstart Command

We will create a shell function. This is more efficient than a separate script and integrates directly into your shell. We will create a shell function. This is more efficient than a separate script and integrates directly into your shell.

Add the following code at the end of .bashrc

# --------------------------------------------------
# Workday Counter Functions
# --------------------------------------------------

# File to store the start timestamp
WORKDAY_START_FILE="$HOME/.workday_start_time"

# Command to start the workday timer
function workstart() {
  # Save the current time (in seconds since epoch) to the file
  date +%s > "$WORKDAY_START_FILE"
  echo "Workday started at $(date -d @$(cat $WORKDAY_START_FILE) +'%H:%M:%S'). Your Starship prompt is now active."
}

# (Bonus) Command to stop and reset the timer
function workstop() {
  if [ -f "$WORKDAY_START_FILE" ]; then
    rm "$WORKDAY_START_FILE"
    echo "Workday stopped. Counter removed from prompt."
  else
    echo "Workday was not started."
  fi
}

# (Bonus) Command to check the start time
function workstatus() {
  if [ -f "$WORKDAY_START_FILE" ]; then
    # Check if the timestamp is from today
    local start_seconds=$(cat $WORKDAY_START_FILE)
    local today_start_seconds=$(date -d "00:00:00" +%s)
    if [ "$start_seconds" -lt "$today_start_seconds" ]; then
       echo "Workday not started today. (Found stale timestamp from a previous day)."
    else
       echo "Workday started at $(date -d @$start_seconds +'%r')."
    fi
  else
    echo "Workday not started yet. Run 'workstart' to begin."
  fi
}

Step 2: Create the Counter Script

First, you need a script that calculates the elapsed time. We’ll place this script inside a .config/starship/ directory in your home folder to keep things organized.

Create the directory if it doesn’t exist:

mkdir -p ~/.config/starship

Create and open the script file:

nano ~/.config/starship/workday_counter.sh

#!/bin/bash

# File where the start time is stored
START_TIME_FILE="$HOME/.workday_start_time"

# 1. Check if the start file exists. If not, exit silently.
if [ ! -f "$START_TIME_FILE" ]; then
  exit
fi

# 2. Read the start time from the file
START_SECONDS=$(cat "$START_TIME_FILE")

# 3. Validate the timestamp: Ignore if it's from a previous day.
# Get the timestamp for the beginning of today (00:00:00)
TODAY_START_SECONDS=$(date -d "00:00:00" +%s)
if [ "$START_SECONDS" -lt "$TODAY_START_SECONDS" ]; then
  # The saved time is from a previous day, so exit silently.
  exit
fi

# 4. Calculate elapsed time
NOW_SECONDS=$(date +%s)
ELAPSED_SECONDS=$((NOW_SECONDS - START_SECONDS))

if [ $ELAPSED_SECONDS -lt 0 ]; then
  ELAPSED_SECONDS=0
fi

# 5. Format and print the output
HOURS=$((ELAPSED_SECONDS / 3600))
MINUTES=$(((ELAPSED_SECONDS % 3600) / 60))

Step 3: Make the Script Executable

chmod +x ~/.config/starship/workday_counter.sh

Step 4: Configure Starship to Display It

At the end of the Starship configuration file ~/.config/starship.toml add:

# Workday Hour Counter Module
[custom.workday]
description = "Displays the elapsed time since the workday started"
# The full path to your script
command = "~/.config/starship/workday_counter.sh"
# The shell to use
shell = "bash"
# Show the module only when the command succeeds
when = "true"
# Format the output
format = "🏢 [$output]($style) "
# Style the module
style = "bold yellow"

How to Use Your New Commands

Your setup is complete. Here is your new workflow:

When you start work: Open your first terminal of the day and simply run the command:

workstart

Your prompt will immediately update and the counter will begin. It will stay active in all subsequent terminals you open.

When you finish work: You can run the workstop command to remove the counter from your prompt:

workstop

To check your start time: At any point, you can run:

workstatus

The counter will automatically disappear the next day because the script will see the old timestamp, ignore it, and wait for you to run workstart again.