calfw: a calendar view inside the Emacs buffer

One buffer showing schedules from several systems

calfw is a calendar framework for Emacs that displays a calendar view in the Emacs buffer, and the framework word is doing real work. The central abstraction is a list of calfw-source objects, collected through two named argument variables. The contents sources define schedule contents, and the annotation sources provide date annotations such as moon phases. Holidays come from the standard calendar-holiday-list function, so calfw reuses the holiday data already in Emacs rather than shipping its own.

The result is that a single calendar buffer can show entries drawn from several different scheduling systems, each plugged in as a source. That is the point of the design, and it is why the add-ons exist as separate files rather than being built into the core.

There are four views, month, one week, two week and day. The buffer navigates like calendar.el, so the muscle memory transfers, and pushing SPC opens a detail buffer for the item under the cursor, and pushing it again closes the buffer, which the readme describes as a pop-up like Quicklook on macOS. A lot of information items are displayed in the buffer, and the toolbar buttons can be clicked with the mouse, so the package is usable without learning the key bindings at all.

The repository layout is small and flat, with calfw.el holding the core, calfw-howm.el, calfw-ical.el, calfw-org.el and calfw-cal.el holding the four sources, calfw-compat.el for backwards compatibility, a Makefile, a CHANGELOG.md and a LICENSE. The primary language is Emacs Lisp and the licence is GPL-3.0.

The key bindings are the calendar.el bindings with a view switch

The navigation table is essentially calendar.el's, which is the single best decision in the package, because a calendar view that invents its own motion keys is a calendar view nobody wants to learn.

Left, b and h go to the previous day, and right, f and l to the next day. Up, p and k go to the previous week, and down, n and j to the next week. The caret moves to the week begin and the dollar sign to the week end. Home and end jump to the first and last date of the current month, and page up and page down move between months. The angle brackets move the current view backward or forward, which is how you step from a one week view to a month view without changing modes. t goes to today and g prompts for an absolute date in YYYY/MM/DD form. TAB moves to the next item within a day, which is how you walk through several entries on the same date.

The view changes have their own letters, and they are unusual enough to be worth noting. M is month view, W is one week, T is two week and D is day. The two week view is the one that has no equivalent in calendar.el, and it exists because the week and month views are both too coarse for a working week with several entries a day.

Then there are the operational keys. r refreshes the data and re-draws the contents, SPC opens the detail buffer, RET or a click jumps to the entry, which means howm or orgmode depending on the source, and q buries the buffer. The fact that jumping is source aware is the detail that makes the framework work, because a click on an Org entry should take you to the Org entry and a click on a howm entry should take you to howm.

Loading it and the compatibility shim for old cfw: names

Installation is the usual Emacs Lisp arrangement. The file goes on your load path, and you require it from your.emacs.

(require 'calfw)

The interesting part is the commented block underneath, which is about the old naming scheme. The package used to be called cfw and used the cfw: prefix for its variables and functions, and the readme explains that the old scheme is still supported. If you uncomment the calfw-compat require, the old names keep working, and the setq of calfw-compat-mark-obsolete to nil suppresses the obsolete messages that would otherwise be printed on every load. That is a thoughtful piece of migration design rather than a straight rename, and it means an existing config that refers to cfw: functions does not break the first time you update.

Once loaded, the command calfw-open-calendar-buffer opens the calendar, and the readme notes you can navigate the date as in calendar.el.

The Makefile shows the project's own quality bar, which is unusual and worth naming. Building a file runs checkdoc over it to verify the docstrings, runs package-lint to check packaging conventions, runs a checkindent step that reformats the file in a temporary directory and diffs the result so that an incorrectly indented file fails the build. Only then does it byte compile and remove the artefact. The comment at the top says the Makefile was taken from radian, so the project inherited a rigorous Emacs Lisp build recipe rather than writing one.

The repository also carries calfw.juth, which is a Japanese translation of the readme, and a CHANGELOG.md.

The Org mode source and the two settings that change its behaviour

The Org mode add-on is the most developed of the four sources, and the readme spends most of its length on it. Loading it is one line.

(require 'calfw-org)

After that, M-x calfw-org-open-calendar opens the calendar. The first customisation is calfw-org-agenda-schedule-args, which lets you choose which agenda items appear.

(setq calfw-org-agenda-schedule-args '(:timestamp))

Setting it to :timestamp restricts the view to items carrying a date stamp or a date range that matches the selected date. If you leave it as nil, the default customisation variable org-agenda-entry-types is used instead, which means you inherit Org's own filtering behaviour. That is a sensible default and a sensible escape hatch, and the readme links to the Org mode documentation on custom agenda commands for the deeper version of the same idea.

The second customisation is calfw-org-overwrite-default-keybinding, which makes the calendar buffer behave like an Org agenda buffer.

(setq calfw-org-overwrite-default-keybinding t)

When it is non-nil, a set of Org style keys is rebound inside the calendar. g refreshes the data and re-draws, j prompts for a date, k captures an Org entry, x closes calfw and the other buffers it opened, d and v d switch to the day view, v w to the one week view and v m to the month view. Being able to capture an entry with k without leaving the calendar is the feature that makes the calendar a working surface rather than a read only display.

The readme also points at org-gcal.el, a separate program that synchronises schedule items between Org and Google Calendar and collaborates with calfw, and at the related blog posts describing that integration.

The iCalendar source and how the other add-ons attach

The iCalendar source is the shortest of the four and connects to a plain iCalendar URL.

(require 'calfw-ical)
(calfw-ical-open-calendar "http://www.google.com/calendar/ical/.../basic.ics")

That covers the common case of a private Google Calendar iCal feed. The readme also names a separate add-on, calfw-gcal.el, which talks to the Google Calendar API directly and can edit entries, rather than reading a feed, and the point of separating the two is that one is read only and the other is not.

The howm source is the other one with real configuration. It installs its schedules and then binds a key.

(eval-after-load "howm-menu" '(progn
  (require 'calfw-howm)
  (calfw-howm-install-schedules)
  (define-key howm-mode-map (kbd "M-C") 'calfw-howm-open-calendar)
))

If you use Elscreen there is a second entry point, calfw-howm-elscreen-open-calendar, bound the same way. And there is an inline form you can place in a howm menu file, %here%(calfw-howm-schedule-inline), which renders the schedule right in the menu rather than in a separate buffer, with a screenshot showing it embedded that way.

The diary source, calfw-cal.el, displays diary schedules and is the smallest of the four, and the readme's summary of the add-ons is worth keeping in mind. calfw-howm.el displays howm schedules, calfw-ical.el displays schedules in the iCalendar format such as Google Calendar, calfw-org.el displays Org schedules, and calfw-cal.el displays diary schedules.

Where calfw is the wrong tool

Three cases argue against it. The first is someone who wants to manage events rather than see them. calfw is a display framework. It shows what Org, howm, an iCal feed or the diary contains, and the jump behaviour takes you to the owning system, so editing happens there. If your requirement is a calendar you can create and change events in, an application with a real event store is the right shape, and calfw is at best a viewer for it.

The second case is a user outside Emacs. The package is a set of Emacs Lisp files with an Emacs Lisp install path, a build recipe that runs emacs --batch, and bindings that live in Emacs keymaps. There is no port, and the value of the package is precisely that it lives inside a text editor where your notes and tasks already are.

The third case is a team that wants a shared calendar service with a web or mobile interface. calfw assumes a single user, one local Emacs, and locally available sources, and the iCalendar integration is a read of a feed URL rather than a multi user collaboration layer.

There is a smaller limitation that follows from the design and is worth stating plainly. The two week view has no equivalent in calendar.el, and the view letters M, W, T and D are memorable only if you remember that T is two week rather than a more obvious choice. And because the sources are read on each refresh, a large calendar with several sources will re-read everything when you press r, which is a design consequence of a display layer that stays in sync by polling rather than subscribing.

On the state of the project, the last push was on 2026-10-02, the repository publishes no GitHub releases, and the CHANGELOG.md is the version history. The licence is GPL-3.0, and the compatibility shim means an installation that predates the rename continues to work with the old cfw: names.

Editorial conclusion

calfw suits an Emacs user whose schedules already live in Org mode, howm, an iCalendar feed or the diary, and who wants them rendered together in a buffer with the same navigation keys they use in calendar.el. It does not suit someone who wants to manage events, since calfw displays rather than edits, and it does not suit a user outside Emacs. Before you configure it, decide which sources you need and require the matching add-on, and note that the last push was on 2026-10-02.

Frequently asked questions

Official sources

1. Issues
2. kiwanami/emacs-calfw on GitHub
3. License: GPL-3.0
4. README