fuzzy-clock.el/readme.org

fuzzy-clock.el

• What is this?
• Quick Start
• Why?
• Fuzziness Levels
• Configuration
• Commands
• Customization
• Documentation
• Installation
  • Manual Installation
  • Package Manager
• Requirements
• Testing
• License
• Inspiration
• Philosophy

What is this?

Fuzzy Clock displays time in Emacs the way humans naturally think about it.

Instead of 14:32, you see "Half past two".

Instead of obsessing over every minute, you see "Afternoon".

Quick Start

;; Load and enable
(require 'fuzzy-clock)
(fuzzy-clock-mode 1)

Look at your mode-line. You should see something like "Three o'clock" or "Afternoon".

Why?

Humans don't think in precise time. We think in approximations:

• "Let's meet around three"
• "I'll be there in half an hour"
• "See you this afternoon"

Fuzzy Clock eliminates the mental overhead of constantly converting 14:32 to "about half past two". It shows time the way you already think about it.

More importantly, it changes your relationship with time. When your mode-line says "Afternoon" instead of 14:32, you stop obsessing over every passing minute.

Fuzziness Levels

Fuzzy Clock supports 11 levels of fuzziness, from precise to very abstract:

Level	Type	Example
1	Every 5 minutes	"Quarter past three"
2	Every 15 min	"Half past three"
3	Half hour	"Three o'clock"
4	Hour (default)	"Three o'clock"
5	Part of day	"Afternoon"
6	Day of week	"Tuesday"
7	Part of month	"Early October"
8	Month	"October"
9	Part of season	"Early Fall"
10	Part of year	"Early 2025"
11	Year	"2025"

Choose your fuzziness level:

;; Maximum precision (still natural language)
(setq fuzzy-clock-fuzziness 'five-minutes)

;; Default: hour precision
(setq fuzzy-clock-fuzziness 'hour)

;; Deep focus: eliminate time anxiety
(setq fuzzy-clock-fuzziness 'part-of-day)

;; Weekly planning
(setq fuzzy-clock-fuzziness 'day-of-week)

;; Monthly view
(setq fuzzy-clock-fuzziness 'part-of-month)

;; Seasonal perspective
(setq fuzzy-clock-fuzziness 'part-of-season)

;; Long-term planning
(setq fuzzy-clock-fuzziness 'part-of-year)

Configuration

Basic configuration:

(require 'fuzzy-clock)

;; Set fuzziness level (default: 'hour)
(setq fuzzy-clock-fuzziness 'hour)

;; Set update interval in seconds (default: 60)
(setq fuzzy-clock-update-interval 60)

;; Enable mode-line display
(fuzzy-clock-mode 1)

Recommended for deep focus:

(setq fuzzy-clock-fuzziness 'part-of-day)
(setq fuzzy-clock-update-interval 3600)  ; Update once per hour
(fuzzy-clock-mode 1)

Commands

Command	Description
M-x fuzzy-clock-mode	Toggle fuzzy clock in mode-line
M-x fuzzy-clock-show	Show fuzzy time once in minibuffer
M-x fuzzy-clock-display-buffer	Show fuzzy time in dedicated buffer

Customization

Use Emacs' built-in customization interface:

M-x customize-group RET fuzzy-clock RET

Two variables:

• fuzzy-clock-fuzziness — Fuzziness level
• fuzzy-clock-update-interval — Update frequency in seconds

Documentation

For comprehensive documentation including:

• The philosophy of fuzzy time
• Detailed explanation of each fuzziness level
• When to use each level
• Advanced configurations
• Complete API reference

See: doc/fuzzy-clock.org

The documentation follows Steve Losh's "teach-don't-tell" philosophy. It will teach you how to think about fuzzy time, not just how to configure it.

Installation

Manual Installation

1. Clone this repository or download fuzzy-clock.el
2. Add to your load-path:

(add-to-list 'load-path "/path/to/fuzzy-clock.el")
(require 'fuzzy-clock)

Package Manager

Not yet published to MELPA. Manual installation required.

Requirements

• Emacs 24.4 or later
• No external dependencies

Testing

Tests use Buttercup via Eldev:

# Run all tests
eldev test

License

See LICENSE file.

Inspiration

Inspired by the KDE fuzzy clock widget.

Philosophy

This package embodies a simple idea: software should adapt to humans, not the other way around.

We evolved to think about time in approximate, contextual terms. Digital clocks force precision we don't need and can't use.

Fuzzy Clock lets you be human again.