hallelujahIM: an English input method for macOS that suggests words and fixes spelling as you type

The typing problem hallelujahIM targets

Most macOS users type English with the system keyboard, which offers no word completion and no correction. If you write English as a second language, you also hit the gap between knowing the word and recalling its spelling. hallelujahIM is aimed at that gap. The README describes an offline dictionary with word frequencies derived from Google's 1/3 million most frequent English words, plus a built-in spelling correction feature: if you remember the rough shape or sound of a word, the input method shows the most likely candidates. Two more features widen the audience. Pinyin input maps a pinyin string to an English word, so typing suanfa surfaces algorithm. Fuzzy phonetic input accepts cerrage or kerrage and offers courage. The project also carries a Text-Expander, so a short key like yem can expand to a phrase you defined. This is a tool for people who type English on a Mac and want suggestions to appear where they are already typing, not in a separate lookup window.

How the candidate engine and the grid panel actually work

The repository layout tells you most of the architecture. hallelujahIM is an Objective-C++ input method bundle built with Xcode (hallelujah.xcodeproj, hallelujah.xcworkspace) and CocoaPods (Podfile, Podfile.lock). FMDB wraps SQLite for prefix-matching queries against the word database. The dictionary directory feeds those tables; cedict.json, converted from cc-cedict, becomes the cedict_pinyin table used for pinyin-to-English lookup. Phonetic matching is assembled from two libraries the README credits: talisman supplies the phonex algorithm, and MDCDamerauLevenshtein ranks the phonetically similar words by Damerau-Levenshtein edit distance. Pinyin mode is a different engine entirely: librime, with rime-prelude, rime-luna-pinyin, rime-stroke, rime-essay and OpenCC supplying the scheme, dictionaries, stroke lookup and simplified/traditional conversion. That mode is off by default and must be enabled in preferences.

The candidate panel is drawn by the input method itself, not by the system. The README names the two components, CandidatePanel and CandidatePanelState, and describes the interaction: candidates appear in a grid whose column count is configurable from 5 to 9 (default 7), the first press of the down arrow expands the full grid, then all four arrows navigate, left and right wrap within the current row, and pressing up on the first row collapses it again. Space, Enter or a number key commits the highlighted candidate. Column widths are recalculated against the rows currently on screen, so expanding or collapsing is a deliberate re-layout, and scrolling to the next screen re-fits the widths while navigation within a screen does not shift columns. The phonetic transcription and Chinese gloss of the highlighted word are drawn on a bottom line of the panel and hidden when there is no translation. The README states this replaced the earlier standalone translation window.

Installing hallelujahIM on macOS and trying it

The README is explicit that you should not use the repository's Clone or download button; you download a pkg from the releases page instead. Which release depends on your macOS version. For macOS 26.6.2 (Tahoe) and newer, the README points to the latest release. For macOS 10.12 through 15.x, it points to the v1.7.2 tag. For macOS 10.9 through 10.11, it points to v1.1.1, which is marked deprecated and requires installing the app file manually.

Open the downloaded pkg and the README says it installs, registers and activates the input method automatically. Two caveats follow. On macOS 14 and later you must add the input source manually in Input source settings, and after a reboot you may need to go to Settings, Keyboard, Text Input and add it there. If the input method does not work at all, the README suggests logging out and back in, then removing and re-adding Hallelujah in Input source.

Because the package is not distributed through the App Store and is not Developer ID signed or notarized, Gatekeeper blocks it. The README gives the workaround per system version. On macOS 14 and earlier, right-click the pkg and choose Open. On macOS 15 (Sequoia) and later, right-click Open no longer works: go to System Settings, Privacy & Security, scroll to the blocked-item notice and click Open Anyway. Alternatively, remove the quarantine attribute in Terminal before double-clicking:

xattr -d com.apple.quarantine ~/Downloads/hallelujah-*.pkg

After installation, preferences are reachable from the input method's Preferences item or directly through a local HTTP server on port 62718:

open http://localhost:62718/index.html

The README shows the web preference page with toggles for pinyin input, the raw-input candidate position and the grid column count. The Text-Expander entries are added and removed on that same page, using a JSON mapping such as {"yem":"you expand me"} quoted in the README, after which typing yem offers you expand me as a candidate.

Mode switching is done with the right Command key, which cycles smart English, pinyin and traditional English. The README notes that pinyin mode is skipped in the cycle while the Enable pinyin (Rime) input option is off. In traditional English mode keystrokes pass straight through to the system. Committing a candidate with Space appends a space by default, which can be turned off in the configuration page; Enter commits without appending a space.

Where hallelujahIM gets in your way

The signing situation is the first real cost. The README states plainly that the program is not distributed through the App Store and has no Developer ID signature or notarization. That is why every installation path starts with a Gatekeeper bypass, and the bypass differs between macOS 14 and macOS 15 and later. If your environment forbids installing unsigned packages, or if you manage Macs under a policy that blocks Open Anyway, this project is not deployable regardless of how well the candidate engine works.

The second cost is the platform split. The README lists Windows support through a PIME-based port at a separate repository, Linux support through fcitx5-hallelujah maintained by a different contributor, and Android and iOS builds marked as test versions. Only the macOS codebase lives here. Anyone reading this repository as a cross-platform input method will be disappointed; the Windows, Linux and mobile versions are separate projects with their own release and maintenance cycles.

The third cost is the candidate panel's own navigation semantics. Expanding and collapsing deliberately re-flows the column widths, and the README says scrolling to the next screen re-fits them again. That means the grid is not a stable spatial map: a word's column can move when the visible rows change. For someone who learns the position of a candidate and reaches for it by number, that is a real behavioural difference from a fixed list.

Finally, the README documents no rollback path for an installed pkg, and it does not describe how to remove the input method cleanly. The troubleshooting it does offer is limited to logging out, removing the input source and re-adding it.

How it compares with Squirrel and the Rime stack

The closest reference point in the README is Squirrel, the macOS front end for Rime. The two projects are not the same kind of tool. Squirrel is a Chinese input method; hallelujahIM's primary mode is English, with pinyin-to-English lookup and an optional pinyin-to-Chinese mode layered on top. The relationship is closer than a shared category: hallelujahIM embeds librime plus rime-prelude, rime-luna-pinyin, rime-stroke, rime-essay and OpenCC to run its pinyin mode, and the README credits Squirrel's implementation as the reference for how the pkg installer is built. So if your need is Chinese input on macOS, Squirrel is the natural choice and hallelujahIM's pinyin mode is a secondary feature that is off by default. If your need is English input with offline frequency-ranked candidates, phonetic correction, pinyin-to-English and Text-Expander macros, Squirrel does not address that at all. The README also credits SwiftType for the grid panel's navigation semantics, which is a narrower debt than it sounds: the interaction model is borrowed, the panel itself is implemented here in CandidatePanel and CandidatePanelState.

One more comparison worth naming: the README lists a third-party review on sspai by a user called 北堂岚舞, framed around the problem of not being sure how to spell an English word and having the input method complete it from pinyin. That framing is the honest scope of the project.

Maintenance, licence and what upgrading costs you

The repository is not archived, and the last push was on 2026-09-24. The most recent releases in that window are build-f9a07e5 on 2026-09-24, which the release notes describe as making the grid candidate panel the only layout, build-e8c5290 on 2026-09-24, which fixes fitting the candidate panel to its gloss in both layouts, and build-ef7b367 on 2026-09-18, which adds configurable pinyin input and raw-input candidate position. Read together, the two 2026-09-24 releases are a removal: a second panel layout was dropped. If you had configured around that other layout, the upgrade changes your candidate panel whether or not you wanted it to.

The licence is GPL-3.0, stated in the README and in the LICENSE and COPYING.md files at the repository root. For an end user installing a pkg on a personal Mac this has no practical effect. For anyone embedding this code in a product, the copyleft terms of GPL-3.0 are the governing constraint, and the README separately advertises paid customisation consulting through WeChat and Gmail. That is a description of what the documentation says, not legal advice; if you are shipping something, read the licence text yourself.

The dependency surface is a maintenance cost in its own right: CocoaPods with FMDB, GCDWebServer, talisman, MDCDamerauLevenshtein, librime and its data packages, OpenCC, and the cedict and cmudict-derived dictionaries. Each of those can move independently of this repository. The README does not state a release cadence or a support window for older macOS tracks, which is why the version-specific links to v1.7.2 and v1.1.1 matter more than the latest tag for anyone on an older machine.

Editorial conclusion

hallelujahIM suits macOS users who type English all day and want offline autocomplete, spell correction and pinyin-to-English lookup inside the text field rather than in a separate window. It is the wrong tool if you need a signed, notarized installer, if you are on Windows or Linux and want the same codebase, or if you expect a maintained API surface: the README points Windows users to a separate PIME-based repository and Linux users to fcitx5-hallelujah. Before installing, verify your macOS version against the three release tracks the README lists, and check whether your system is one where you must add the input source manually after login.

Frequently asked questions

Official sources

1. dongyuwei/hallelujahIM on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases