vimalender

README

vimalender

A vim-style terminal calendar built with Go, Bubble Tea, and Lip Gloss.

Navigate, create, move, search, and customize events entirely from the keyboard with familiar vim motions.

Demo:

https://github.com/user-attachments/assets/5c1090b0-922f-4f04-b4ba-83717fbde6fb

Installation

go install

Requires Go 1.25+. Installs the binary to your $GOPATH/bin (or $GOBIN):

go install github.com/Sadoaz/vimalender@latest

Make sure $GOPATH/bin is in your PATH, then run:

# bash/zsh
export PATH="$HOME/go/bin:$PATH"

# fish
fish_add_path ~/go/bin

vimalender

From source

git clone https://github.com/Sadoaz/vimalender.git
cd vimalender
go build -o vimalender .
go install .
./vimalender

If you usually run the installed binary from ~/go/bin, remember to run go install . after local changes.

Highlights

• Week, month, and year views
• Vim-style navigation plus help overlay with live key rebinding
• Multi-day events, including recurring multi-day events and 24h+ all-day spans at the top of week view
• Visual selection, copy, cut, paste, delete, and grouped move
• Recurring move/delete flows with o = one occurrence and a = all occurrences
• Search with persistent match navigation
• In-app .ics import and export flows available from Settings
• In-app color customization for event color, consecutive-event color, event background, and UI accent

Views

Vimalender has three main views:

View	Key	Description
Week	default	Multi-day column grid with time gutter. Shows 1-9 day columns.
Month	M	Full month grid with event dots and first event title per cell. ISO week numbers.
Year	Y	4x3 grid of 12 mini-month calendars with event-day highlighting.

Press Enter in month or year view to open the week view at the selected day.

Keybindings

Press ? any time in the main UI to open the help panel. It shows the current bindings, supports Enter to rebind a selected action, and Backspace to reset that binding to default.

Navigation (Week View)

Key	Action
h / l	Previous / next day
j / k	Move cursor down / up
J / K	Move cursor down / up by one visible row
H / L	Previous / next overlapping event
Ctrl+D / Ctrl+U	Jump quarter page down / up
Tab	Cycle through overlapping events at cursor
1-9	Set number of visible day columns
c	Jump to now (today on far left, cursor at current time)
g	Go to time -- type e.g. 14:30, 1430, 9 and press Enter
G	Go to day -- type day of month (1-31) and press Enter
M	Switch to month view
Y	Switch to year view
S	Open settings menu
u	Undo last action
Ctrl+R	Redo
q	Quit

Events

Key	Action
a	Create new event at cursor position
Enter	Open detail view for event under cursor
m	Enter move mode
e	Edit event in $EDITOR (falls back to vi)
dd	Delete event (vim-style double-key)
x	Cut selected event
yy	Copy selected event
p	Paste clipboard at cursor
u	Undo last action (create, delete, move, edit)
Ctrl+R	Redo

For recurring events:

• delete prompts: (o)ne occurrence or (a)ll
• move prompts: preview first, then Enter, then (o)ne or (a)ll

Importing .ics

Open Settings with S, then choose Import events.

• type or paste a relative or absolute .ics path
• press Tab to complete matching folders and .ics files
• press Enter to import supported VEVENT entries into your local calendar
• unsupported recurrence rules, exceptions, and malformed events are skipped with reasons shown in the overlay
• duplicate prevention is not automatic, so importing the same file again creates new events

Exporting .ics

Open Settings with S, then choose Export events.

• type or paste a relative or absolute .ics path
• press Tab to complete matching folders and .ics files
• press Enter to export your stored events to that file

Create Flow

1. Press a to start creating at cursor
2. j/k to set duration by visible row, J/K to fine-tune by 1 minute, Ctrl+D/Ctrl+U to resize faster, Enter to confirm
3. Type title, Enter
4. Type description, Enter (skippable via settings)
5. r/R to cycle recurrence, Enter to save (skippable via settings)

Create spans can cross midnight and multiple days.

If a logical event is at least 24 hours long, it renders as a top all-day span in week view instead of as timed blocks in the grid.

Search

Key	Action
/	Start search (searches title and description)
n / N	Jump to next / previous match
Ctrl+N / Ctrl+P	Alternative next / previous match
Esc	Clear search highlights

Search matches against event title and description. Navigate matches with n/N. When events are changed or deleted, the search list is refreshed so stale matches are removed.

Visual Mode

Press V in week view to start a visual time-range selection.

Key	Action
h / j / k / l	Expand the selection
Ctrl+D / Ctrl+U	Expand faster
J / K	Expand by exactly 1 minute
y	Copy selected events
x	Cut selected events
d	Delete selected events
m	Move selected events together
Esc / V	Leave visual mode

Recurring selections are occurrence-aware:

• selecting one recurring occurrence does not automatically select the entire series
• visual recurring move previews first, then Enter, then o or a
• o means only the selected occurrences
• a means the whole recurring series

Move Mode

Enter with m on any event. The event stays pinned to its visual column during move preview.

Key	Action
j / k	Move event down / up by visible row
J / K	Move event down / up by 1 minute
h / l	Move event to previous / next day
g	Jump move preview to a typed time
G	Jump move preview to a typed day of month
Enter	Confirm move preview
Esc	Cancel move

For recurring events, Enter opens the (o)ne / (a)ll prompt after you have already previewed the new position.

Detail View

Press Enter on any event to view full details (title, description, date, time, duration, notes). Press e to edit in external editor, Esc/q to go back.

Month & Year Views

Key	Action
h / l	Move one day left / right
j / k	Move one week down / up
H / L	Move one month back / forward
J / K	Move one year back / forward (year view only)
c	Jump to today
Enter	Open week view at selected day

Recurrence

Events support seven recurrence patterns:

Pattern	Description
None	One-time event
Daily	Every day
Weekdays	Monday through Friday
Weekly	Same weekday each week
Biweekly	Same weekday every 2 weeks
Monthly	Same day of month
Yearly	Same month and day

Recurring events can have an optional end date. Virtual occurrences are shown with a ↻ prefix.

Supported recurring workflows include:

• moving one occurrence or the whole series
• deleting one occurrence or the whole series
• recurring multi-day events
• recurring visual selections by occurrence

Overlapping Events

Events can overlap in time. Overlapping events are displayed side-by-side in sub-columns within the same day. Use H/L or Tab to navigate between them. When scrolling with j/k, the cursor automatically selects new events as they appear. The status bar shows [N/M: title] to indicate which overlapping event is selected.

Settings

Open with S. Navigate with j/k, change values with h/l or Enter.

Setting	Default	Description
Default zoom	30 min/row	Default week-view zoom level
Event color	#1a5fb4	Main border/accent color for events
Consecutive event color	#26a269	Alternating border color for back-to-back event chains
Accent color	#00a8ff	Main UI accent (WEEK, headers, help, prompts, etc.)
Event background	#1c1c2e	Dark background fill for event blocks
Show keybinding hints	Off	Show shortcut hints in the status bar and menus
Show event borders	On	Left color bar style vs full background
Show descriptions	On	Show event descriptions below title in grid
Quick create	Off	Skip recurrence picker during create
Skip description	Off	Skip description step during create

Color rows open an inline hex editor:

• type or paste a hex value like #00a8ff
• Enter saves
• Ctrl+R resets to the default
• Esc cancels

Title and description input also support Ctrl+W to delete the previous word.

Customization

settings.json is autogenerated with helpful customization fields.

• keybindings contains the active binding for each action key
• keybinding_help explains what each binding does
• ui_colors controls accent-related UI colors
• ui_color_help explains each color key

You can either edit the JSON file directly or use the in-app help/settings flows.

Data Storage

All data is stored locally in ~/.local/share/vimalender/:

File	Content
events.json	All events (dates, times, recurrence, exceptions)
settings.json	User preferences, colors, keybindings, and last cursor position

Writes are atomic (write-to-temp-then-rename) for crash safety. Cursor position is restored on next startup.

External Editor

Press e on any event to open it in $EDITOR (or vi). The editor shows a structured file with Title, Desc, Start, End, Repeat, Until fields, followed by a --- separator and freeform notes. Changes are parsed back on save.

The generated template also places notes in a more convenient editing position.

Requirements

• Terminal with 256-color or truecolor support
• Minimum terminal size: 80x24
• Go 1.25+ (build only)