# MacCalendar: a SwiftUI menubar calendar with lunar dates and offline holiday data

> MacCalendar is a small SwiftUI macOS app that lives in the menu bar, showing the Chinese lunar calendar, solar terms, statutory holidays and entries from the system Calendar without needing a network connection. It is ad hoc signed, so installation ends with an xattr command rather than a normal app store flow.

**bylinxx/MacCalendar** — 完全免费&开源的小而美 macOS 菜单栏日历App(带小组件)，支持中国农历、节假日、放假安排、系统日程、个性化配置等

- Repository: https://github.com/bylinxx/MacCalendar
- Stars: 865 · Forks: 51
- Language: Swift
- License: not declared
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/bylinxx-maccalendar

## A menu bar app that never phones home

MacCalendar is a SwiftUI application for macOS that runs silently in the menu bar and opens its window on a right click or with the Command plus comma shortcut. The README describes it as free and open source, lightweight in resource use, and completely offline with no network access required. That last point is the defining constraint of the design rather than a marketing line. Every piece of information the app shows comes from data bundled inside the application or read from the local system.

The feature list is specific about what that offline behaviour buys you. The app shows the Chinese lunar calendar, the 24 solar terms, and most festivals whether they fall on the Gregorian or the lunar calendar. It carries the Chinese statutory holiday schedule, described in the README as covering arrangements from 2015 onwards. It also reads the system Calendar data, can filter what it displays by calendar type, and supports modifying and deleting entries it reads. On top of that it lets you choose which content appears in the menu bar itself, using an icon, a date, a time or a custom format, and it supports quick jumps to a given year or month.

The repository layout matches a native application rather than a script: a MacCalendar.xcodeproj directory, a MacCalendar directory for the app itself and a separate MacCalendarWidget directory for the desktop widget. The widget is the part that makes this more than a menu bar icon, and it comes with the same signing caveat as the app.

## Ad hoc signing makes the xattr step unavoidable

The installation section carries a warning marked as important, and it is the first thing any new user will meet. The software uses ad hoc signing and has not been signed with an Apple developer certificate. Before the first run the README says you must run:

```bash
xattr -cr /Applications/MacCalendar.app
```

Without it, macOS reports the application as damaged or refuses to verify the developer, and the desktop widget does not appear at all. If the command is not enough, the README points to System Settings, then Privacy and Security, where the Still Open button sits in the security section.

This is a real cost and it is not only a documentation annoyance. The command strips the extended attributes, including the quarantine flag, from the application bundle, which is what lets the unsigned build launch. On a managed Mac with Gatekeeper enforced by a configuration profile, that step may be reverted by the profile, and the README documents no enterprise deployment path, no notarization, and no script for fleet installation. Anyone provisioning this to a team will need to handle the trust question outside the project.

The licence situation is similarly undocumented. The licence field on the repository says unknown, and there is no licence file among the top-level entries, which are .github, the Xcode project, the two source directories and the README. The README asks for sponsorship through a Chinese donation platform, so the author does accept support, but there is no permission grant in the repository that you can point to in a compliance review.

## Two installation paths, both ending at the same xattr command

The README documents a manual install and a Homebrew install, and both end with the same quarantine-clearing step. The manual path is a download and a drag: fetch the latest dmg from GitHub Releases, open the downloaded image, drag the MacCalendar icon onto the Applications icon, then run `xattr -cr /Applications/MacCalendar.app` in a terminal to release the system isolation. After the first launch you open System Settings, then Desktop and Dock, then Widgets, and add the MacCalendar widget to the desktop. Updates are handled from inside the app through Preferences and a check for updates.

The Homebrew path introduces a tap first and installs from it:

```bash
brew tap bylinxx/tap
brew install maccalendar
```

The same README sequence follows afterwards, running `xattr -cr /Applications/MacCalendar.app` after the install completes, with updates again handled from the preferences window. The Homebrew route is the better one for a machine you control, since it gives you an uninstall path and a repeatable install command, and it still does not remove the quarantine problem because the tap serves the same ad hoc signed bundle.

Note what is not documented. There is no Homebrew formula in the repository, only a link to a tap owned by the author, so the formula itself lives outside the project and cannot be reviewed from the source tree. There is also no instruction about which architectures the dmg covers, no mention of an Apple Silicon versus Intel distinction, and no note about the minimum macOS version in the text, although the release badge advertises macOS 14.0 and later. Those details matter when you are the person who has to make it work on a colleague's machine.

## Holiday data comes from another repository entirely

The statutory holiday schedule in the app is not authored inside MacCalendar. The README credits NateScarlet/holiday-cn as the source of the Chinese statutory holiday data, and that repository name is the only provenance link given for the schedule the app renders. This matters for two reasons.

First, accuracy. Chinese statutory holiday arrangements are announced year by year and are adjusted each year, with working weekends shifted around public holidays. A calendar app that renders the wrong arrangement shows a user the wrong day off, which is a poor failure mode for something people consult precisely to know when they are off work. The README states coverage from 2015 onwards but says nothing about how the data is refreshed inside the app, so a user cannot tell from the documentation whether the schedule stays current without an app update.

Second, the boundary of the offline claim. The app itself does not need a network, which is convenient, but it also cannot correct itself when the upstream data changes unless a new build carries the correction. For lunar dates and the 24 solar terms this is not a problem, since those are computable from a calendar algorithm. For announced holiday arrangements it is. The menu bar also shows the current time, and a menu bar clock that cannot correct itself against a network time source is another edge case the README does not address.

## Where MacCalendar sits against the built-in alternatives

macOS ships with a Calendar application, and the Notification Center clock can show a calendar date on some configurations, so the honest question is what MacCalendar adds. The answer is the Chinese-specific layer: lunar dates, the 24 solar terms, the festival list and the statutory holiday schedule, plus a menubar-only presentation and a desktop widget that reads the system Calendar data directly. The README states the app can filter the system calendars it displays by type and can modify and delete entries, which means it sits on top of the existing EventKit data rather than keeping a separate store.

The difference in approach against a general-purpose menubar calendar is that this one is offline and Chinese-first, with no account, no sync service and no telemetry described anywhere in the README. The cost of that privacy posture is that the holiday data must ship with the binary, so freshness depends on the release cycle.

The limits are clear from the README's own list of what it does not do. This is a read-and-display calendar. There is no recurrence editing, no event creation workflow beyond what the README mentions, and no sharing or invitation handling described. If you need to book a meeting from your phone and see it in the menu bar, the standard Calendar application does that and MacCalendar only mirrors it.

## Maintenance and the pace of releases

The repository is not archived and the last push was on 2026-10-01, so the code is current. The release history is dense: v1.7.21 on 2026-10-01, v1.7.20 on 2026-09-28 and v1.7.19 on 2026-08-04. Three releases inside a quarter, with patch numbers in the low twenties, is the signature of a single developer shipping small increments, and it means the app will be replaced often rather than settled.

That pace has a practical side. Each new build is another ad hoc signed bundle that needs the quarantine flag cleared again if it is replaced by hand, and a Homebrew user will get the update through brew instead. The README documents no auto-update mechanism beyond a manual check in the preferences window, so a user who does not open that window stays on whatever version they installed.

The project also keeps its Chinese-language README and screenshots, with the interface documentation written for a Chinese audience and the holiday data source being a Chinese repository. An English-speaking user will get the gist from the feature list, but there is no translated documentation, no English FAQ and no English issue tracker guidance in the repository. The README does point to a sponsorship option for the author, and the widget and menubar behaviour are documented well enough to be reproducible from the description alone.

## Conclusion

MacCalendar suits a macOS user who wants the Chinese lunar calendar, the 24 solar terms and the statutory holiday schedule visible from the menu bar on a machine with no reliable network access. It does not suit anyone who needs a signed, notarised build, a documented licence, or a client that can administer the macOS Calendar database for them. Before adopting it, check that the app bundle you downloaded is the one you trust, that `xattr -cr /Applications/MacCalendar.app` clears the quarantine flag on your machine, and that the holiday data it reads still matches the arrangement your employer publishes.

## FAQ

### How do I install MacCalendar on macOS?

The README documents two paths: download the latest dmg from GitHub Releases, open it and drag MacCalendar into Applications, or run `brew tap bylinxx/tap` followed by `brew install maccalendar`. Both paths require running `xattr -cr /Applications/MacCalendar.app` afterwards because the build is ad hoc signed.

### Why does macOS say MacCalendar is damaged or cannot be verified?

The app uses ad hoc signing rather than an Apple developer signature, so macOS quarantines the bundle. The README says the fix is to run `xattr -cr /Applications/MacCalendar.app`, and if that is not enough, to use the Still Open button under System Settings, Privacy and Security.

### Does MacCalendar need an internet connection?

No. The README describes it as fully offline and needing no network access, with the Chinese lunar calendar, the 24 solar terms, the festival list and the statutory holiday schedule for 2015 onwards all included in the app.

### Where does MacCalendar get Chinese holiday data?

The README credits the NateScarlet/holiday-cn repository as the source of the Chinese statutory holiday data used by the app.

### How do I add the MacCalendar desktop widget and update the app?

After the first launch you open System Settings, then Desktop and Dock, then Widgets, and add the MacCalendar widget. Updates are checked from the preferences window, which the README points to as the way to update after either installation method.

## Sources

- [bylinxx/MacCalendar on GitHub](https://github.com/bylinxx/MacCalendar)
- [Issues](https://github.com/bylinxx/MacCalendar/issues)
- [README](https://github.com/bylinxx/MacCalendar/blob/main/README.md)
- [Releases](https://github.com/bylinxx/MacCalendar/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bylinxx-maccalendar