ASCII Clock ⏰

A beautiful, fully functional clock using ASCII art that runs in your terminal or as a standalone GUI widget. Perfect for keeping time visible in a side terminal while you work!

Why Use This? 💡

Perfect for developers who want to:

• Keep time visible in a terminal split alongside your code
• Track how long you've been working with the built-in stopwatch
• Have a cool-looking clock that doesn't take up much space
• Customize everything - colors, numbers, seconds, 12/24 hour format
• Launch instantly from anywhere with a simple command: aclock terminal

Features ✨

• Real-time analog clock with hour, minute, and optional second hands
• Beautiful ASCII rendering with proper aspect ratio correction for a round clock face
• Digital time display in a stylish bold ASCII border
  • 12-hour format with AM/PM (default) or 24-hour format (toggle with t)
• Color-coded hands: Hour (red), Minute (cyan), Second (green)
• Hour markers: Toggle between major markers (12, 3, 6, 9) or all 12 numbers
• Built-in stopwatch: Start/stop with w key, displays total time on exit
• Resizable on the fly: Auto-resize to fit your terminal/window + manual zoom controls
• Two modes: Terminal (curses) and GUI widget (tkinter)
• Interactive controls: All features accessible via single keystrokes

Quick Install 🚀

The easiest way - install globally with UV:

# Clone this repository
git clone https://github.com/yourusername/ascii-clock.git
cd ascii-clock

# Install globally with UV (one command!)
uv tool install .

That's it! Now you can use these commands from anywhere:

aclock terminal          # Launch the clock! ⏰
termclock terminal       # Alternative command
ascii-clock terminal     # Full command name

Alternative: Development Install

If you want to modify the code:

uv pip install -e .

Verify Installation

aclock --help           # Should show help menu
aclock terminal         # Launch the clock!

Usage Examples 📖

Basic Usage

# Just launch it!
aclock terminal

# Or use alternative commands
termclock terminal
ascii-clock terminal

Common Workflows

Developer working in a split terminal:

# In your side terminal, launch a clock with all features
aclock terminal --numbers --seconds

# Press 'w' to start the stopwatch when you begin a task
# Press 'n' to hide numbers if you want more space
# Press 't' to switch between 12/24 hour format
# Press 'q' when done - see total time worked!

Minimal clock for small terminal:

# Small, simple clock
aclock terminal --size 10

Desktop widget mode:

# Always-on-top GUI widget
aclock gui --on-top --numbers

All Options

Terminal Mode:

aclock terminal [OPTIONS]

Options:
  --size N        Clock radius (5-50, default: 20)
  --seconds       Show seconds hand by default
  --numbers       Show all 12 hour numbers
  --24hour        Use 24-hour time format

GUI Mode:

aclock gui [OPTIONS]

Options:
  --size N        Clock radius (5-50, default: 20)
  --seconds       Show seconds hand by default
  --numbers       Show all 12 hour numbers
  --24hour        Use 24-hour time format
  --on-top        Keep window always on top

Controls

Key	Action
+ / -	Increase/decrease clock size
s	Toggle seconds hand
n	Toggle hour numbers (1-12)
t	Toggle 12/24 hour format
w	Toggle stopwatch
q / Esc	Quit

Stopwatch: When you quit, the total elapsed time will be displayed in your terminal!

Development 🛠️

Setup

# Clone the repository
git clone https://github.com/yourusername/ascii-clock.git
cd ascii-clock

# Install in development mode
uv pip install -e .

Code Formatting

This project uses Black for code formatting:

uv run black .

Running Tests

uv run pytest

Contributing 🤝

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests

License 📄

MIT License - see LICENSE file for details.

Acknowledgments 🙏

Built with:

• Python 3.8+
• UV for package management
• curses for terminal rendering
• tkinter for GUI mode

---

Enjoy your ASCII clock! ⏰✨

If you find this useful, consider giving it a ⭐ on GitHub!