Skip to main content
otter-cal powers the calendar popover on Otter Shell’s status bar clock. It prints a month grid and a bounded agenda list to stdout. Left-click the clock widget and that output shows up as a popover. Pipe it into any bar or launcher that displays text, or run it in a terminal.

​
Usage

otter-cal                                              # current month
otter-cal --month 2026-06                              # specific month
otter-cal --today 2026-06-05 --agenda ~/.config/otter-shell/agenda  # with agenda file
otter-cal --next 1                                     # next month

​
Agenda File Format

Each line has a date in YYYY-MM-DD format, a space, and the event description. One event per line: 
2026-06-15 Team retrospective
2026-06-20 Release day
Pass the file path with --agenda, or set agenda_path in the config file.

​
Bar Integration

The Otter Shell status bar clock runs a command on left-click. The default is otter-cal, which opens the calendar popover inline. Override it with clock_calendar_command in your bar configuration: 
clock_calendar_command = "otter-cal"
Replace the value with any command whose stdout the bar should display. A wrapper script that passes a custom --agenda path works fine.

​
Configuration

otter-cal reads ~/.config/otter-shell/otter-cal.conf: 
agenda_path = ""
  • agenda_path: absolute path to your agenda file. Empty runs without agenda data.