Loading...
Claude 5-hour conversation block tracker with visual countdown, expiration warnings, and color-coded indicators to prevent unexpected session terminations.
#!/usr/bin/env bash
# Block Timer Tracker for Claude Code
# Monitors Claude's 5-hour conversation block limit with countdown
# Read JSON from stdin
read -r input
# Extract session start time and current timestamp
session_start=$(echo "$input" | jq -r '.session.startTime // ""')
current_time=$(date +%s)
# Calculate elapsed time in seconds
if [ -n "$session_start" ]; then
start_epoch=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$session_start" +%s 2>/dev/null || echo "$current_time")
elapsed=$((current_time - start_epoch))
else
elapsed=0
fi
# 5-hour block = 18000 seconds
BLOCK_LIMIT=18000
remaining=$((BLOCK_LIMIT - elapsed))
# Convert to hours:minutes:seconds
hours=$((remaining / 3600))
minutes=$(((remaining % 3600) / 60))
seconds=$((remaining % 60))
# Calculate percentage remaining
if [ $BLOCK_LIMIT -gt 0 ]; then
percent=$((remaining * 100 / BLOCK_LIMIT))
else
percent=0
fi
# Color codes based on time remaining
if [ $percent -gt 50 ]; then
# Green: > 2.5 hours remaining
COLOR="\033[38;5;46m"
ICON="✓"
elif [ $percent -gt 20 ]; then
# Yellow: 1-2.5 hours remaining
COLOR="\033[38;5;226m"
ICON="⚠"
elif [ $percent -gt 0 ]; then
# Red: < 1 hour remaining
COLOR="\033[38;5;196m"
ICON="⚠"
else
# Expired
COLOR="\033[38;5;160m"
ICON="✗"
fi
RESET="\033[0m"
# Progress bar (20 chars)
bar_filled=$((percent / 5))
bar_empty=$((20 - bar_filled))
bar=""
for ((i=0; i<bar_filled; i++)); do bar+="█"; done
for ((i=0; i<bar_empty; i++)); do bar+="░"; done
# Format time display
if [ $remaining -gt 0 ]; then
time_display=$(printf "%dh %02dm %02ds" $hours $minutes $seconds)
else
time_display="EXPIRED"
fi
# Build statusline
echo -e "${COLOR}${ICON} Block: [${bar}] ${time_display} (${percent}%)${RESET}"
# Warning messages (stderr for alerts)
if [ $percent -le 10 ] && [ $percent -gt 0 ]; then
echo "⚠ WARNING: Less than 30 minutes remaining in conversation block!" >&2
elif [ $remaining -le 0 ]; then
echo "✗ BLOCK EXPIRED: Start new conversation to continue." >&2
fi{
"format": "bash",
"position": "right",
"colorScheme": "traffic-light",
"refreshInterval": 1000
}Time showing as 0h 00m 00s or EXPIRED immediately on start
Check session.startTime exists in JSON input. Verify date parsing: date -j -f '%Y-%m-%dT%H:%M:%SZ' '2025-10-23T10:00:00Z' +%s. On Linux use -d instead of -j flag.
Progress bar showing all filled or all empty incorrectly
Verify BLOCK_LIMIT=18000 (5 hours in seconds). Check percent calculation: echo $((remaining * 100 / BLOCK_LIMIT)). Ensure remaining time calculated correctly from session start.
Warning messages not appearing when time low
Warnings output to stderr (>&2) for alerts. Check stderr visible in terminal. Test: bash statusline.sh 2>&1 | grep WARNING. Ensure percent calculation under 10 triggers warning.
Colors not displaying, showing escape codes instead
Terminal may not support ANSI colors. Test: echo -e '\033[38;5;46mGreen\033[0m'. Enable color support in terminal settings. For screen/tmux ensure TERM=screen-256color or xterm-256color.
Countdown refreshing too slowly or appearing static
Decrease refreshInterval to 1000ms (1 second) in configuration. Verify script executes on each refresh. Check system clock accurate: date. Test manual execution shows changing countdown.
Loading reviews...