ReCast runs in the background and fixes English/Hebrew keyboard-layout mistakes
as you type. It switches layouts and replaces the mistyped word, corrects English
spelling (recieve → receive), and offers word completion and custom abbreviations.
Everything runs locally, with dictionaries embedded in the executable. Your
clipboard is never touched.
ReCast checks words when you finish them with Space, preserving trailing punctuation. It uses the current keyboard layout, dictionary matches, and word frequency to decide whether to rewrite them. Each word gets one rewrite or none; capitalization and the terminator are preserved. Same-layout corrections keep an unchanged prefix on screen and rewrite only the remaining suffix, reducing visible deletion. Cycling suggestions also preserves all text shared by consecutive offers; undo still restores exactly what you typed. Enter accepts an already selected suggestion and clears typing context. It never starts an automatic rewrite or replays Enter, because that key may send a message or execute a command instead of inserting a line break. A confident English or Hebrew spelling fix can also correct a wrong-layout word in the same replacement. Combined Hebrew repairs preserve source punctuation and protect known English words, common names, ALL CAPS, and saved exceptions. A confident English spelling repair takes precedence.
Spelling also checks missing, extra, or wrong first letters in longer words,
including combined opening mistakes (xocmputer → computer) and additional
mistakes later in the word (ommunicaton → communication). Missing, repeated,
extra, swapped, and wrong letters are checked throughout the word. A single
stray ending letter can recover the unchanged base (computerx → computer).
Words of eight or more letters can use the three-edit budget; six-letter words
can recover multiple cheap slips. Shorter tokens keep their existing limits.
These fixes also work when typed in the Hebrew layout.
Three-letter ordering slips such as tounge → tongue and probeml → problem
use the two-edit budget. The reviewed short transpositions teh and hte become
the in English; valid Hebrew readings remain protected when typing in Hebrew.
Layout correction also recognizes English contractions and possessives such as
don't, I'm, and keyboard's, preserving capitalization and punctuation.
Layout correction recognizes unlisted Hebrew words with supported
one- through four-letter prefixes, such as במקלדת, ושלמקלדת, and וכשהמקלדת,
when the stem is a ranked dictionary word and the English reading is not a known word or common name.
Conservative spelling keeps its existing single-edit limit.
Spelling corrects recognized apostrophe forms by checking their stem and preserving
the suffix (recieve's → receive's). Valid forms and saved word exceptions remain
protected; arbitrary internal punctuation and digits are not spelling inputs.
Spelling correction protects frequency-attested dictionary words, curated
technical terms, ALL CAPS, and tokens containing
digits or internal punctuation. It uses word frequency and weighted typo costs;
the previous finished word can resolve close candidates using bounded phrase
evidence. Keeping the original token also competes with a replacement: frequency
evidence, short unknown words, and trusted compound components can prevent an
otherwise unique suggestion from winning. Reviewed nonword misspellings remain
repairable even when the broad layout dictionary contains them; valid rare words
and regional variants are not added to that reviewed list. Regular inflections
reuse those reviewed errors only when the corrected form has dictionary and
frequency evidence (langauges → languages, accomodating → accommodating).
Long dictionary derivatives missing from the frequency sample can use a discounted
rank from a common dictionary stem, restricted to a doubled-letter repair or
transposition (mispelling → misspelling). Correction details identify this
inferred rank separately from observed frequency ranks. Unfamiliar names or
jargon can still get unwanted fixes. When competing candidates remain too close,
ReCast leaves the word unchanged. Undo, ignored words,
and Conservative spelling give you control.
Navigation, mouse clicks, and focus changes cancel stale corrections where detected.
Enable English and Hebrew keyboards in your OS settings. Their order does not matter.
The release workflow produces these self-contained downloads; check GitHub Releases for available builds:
| File | Platform |
|---|---|
recastLinux |
Linux x86-64 |
ReCast.exe |
Windows x86-64, Windows 10+ |
recastMac |
macOS, Intel and Apple Silicon |
ReCast.app.zip |
macOS app bundle, Intel and Apple Silicon |
LICENSES.txt |
Application and bundled English dictionary notices |
SHA256SUMS |
Download checksums |
For a source build, install Rust/Cargo, clone this repository, and run the commands below from its root. No separate dictionary installation is needed.
For a downloaded app, extract ReCast.app.zip, move the app to /Applications,
and open it from Finder. To build and install the app from source:
make appSetup opens on first launch or whenever a requirement is missing. It checks Accessibility and both keyboards, links to System Settings, and offers Check again. Keyboard capture uses an active session event tap authorized by Accessibility, so a separate Input Monitoring grant is not required. If ReCast is missing from Accessibility, click +, then Cmd+Shift+G, and enter the exact path shown in setup. Show ReCast in Finder reveals that copy. Quit and reopen ReCast if permission changes require a relaunch.
For a release smoke test, use a fresh macOS account, install the downloaded app
in /Applications, and grant only Accessibility. Leave Input Monitoring off.
Enable English and Hebrew keyboards, reopen ReCast, and verify correction, undo,
and completion in TextEdit. Quit and reopen once more to check that access persists.
Automated tests cannot verify macOS privacy grants for a downloaded app.
Use Settings > General > Start at login in the menubar app for autostart. Alternatively,
make service installs a bare binary with a launchd LaunchAgent;
make service-uninstall removes that service. Terminal-launched binaries may have
permissions attributed to the terminal rather than ReCast.
After the keyboard listener is ready, Practice correction and undo opens once
in the tray app or Linux control window. Close it to skip, or reopen it from
Help > Practice correction and undo in the tray or the Linux controls.
On macOS and Windows, practice shows one step at a time and checks both installed
keyboards. Windows offers a link to Language settings; the checklist updates when
you return. The exercise uses a real local text field: try layout correction,
undo it, then complete keyb with Right Shift. Successful steps are confirmed by
the keyboard engine. Practice does not train word exceptions or personalization,
consume the first-correction hint, or change correction counts. Saved word rules
and your enabled settings still apply. Linux practice requires a desktop that
can identify the active application; its field is disabled otherwise.
ReCast reads keyboards through evdev and writes corrections through uinput.
Your user needs access to both devices. Add yourself to the input group, then
log out and back in before installing the user service:
sudo usermod -aG input "$USER"
# After logging back in, from the repository:
make serviceThis builds and installs ~/.local/bin/recast and starts a systemd user service.
Ensure ~/.local/bin is on your PATH.
systemctl --user status recast
journalctl --user -u recast -f
systemctl --user restart recast
make service-uninstallLayout backends support Hyprland, Sway, KDE, GNOME on X11, and X11. GNOME Wayland additionally needs the optional ReCast Shell extension for live layout queries and switching. GNOME/KDE Wayland focused-app detection uses the optional AT-SPI helper. See Linux desktop integration for dependencies, setup, supported controls, and limitations. Missing live layout or required focus information pauses edits; saved GSettings values never confirm a switch.
macOS compares the current layout's actual key output with ReCast's physical mapping. Linux accepts standard US and Hebrew XKB layouts and rejects unknown variants, including Dvorak, Colemak, and dead-key layouts. Localized KDE layout names that cannot be verified are also declined. Custom remaps that keep a standard layout name cannot be detected by the Linux name check. Status reports unsupported variants; select compatible layouts to resume. Disconnected keyboards are detected automatically; ReCast waits for reconnection.
Run ReCast.exe for the tray app. Settings > General > Start at login registers it in the per-user
Run key. The checkbox also recognizes and toggles the Scheduled Task installed
from source, preserving its recovery settings. To build, install, and register a
logon Scheduled Task from source:
.\deploy.ps1 -Target serviceThe default install directory is %USERPROFILE%\.local\bin.
Use -Target service-uninstall to remove the task, or -Target help for all targets.
The gestures below are defaults. In Settings, choose Double-tap action (undo / convert), Completion (single tap), and Spelling suggestions (single tap) to use Left/Right Ctrl or Left/Right Shift, or disable any gesture. Double-tap actions also offer Either Ctrl. Changes save and apply immediately; help, status, and practice show your current bindings. Completion and spelling suggestions need separate keys from each other, the double-tap action, and extra single-tap undo. Disable or move the conflicting binding first. Only bare taps shorter than 300 ms count; double taps must finish within 500 ms of each other. Holding a modifier or using it in a chord keeps its normal behavior. Completion and spelling-suggestion Shift taps may overlap the release of the last typed letter. Rapid suggestion taps while an offer is landing queue one additional step; typing, cursor movement, or a focus change cancels that step. On every platform, suggestion search runs off the keyboard capture thread, so slow lookups do not hold up your next keystroke. Rapid taps during a search are queued; typing, adding spaces, navigation, or changing shortcuts cancels stale results before they can edit your text. If a layout query or requested switch temporarily fails before editing starts, the same gesture can retry the tracked word without retyping it. After cursor movement, an explicit request can complete, correct, or convert the keys typed since that movement. Previously existing text stays untouched; clicking or starting in a newly focused target allows the first freshly typed word to be corrected automatically. No warmup word or Ctrl double tap is needed. Keyboard navigation and deletion into untracked text still suspend automatic correction until a word boundary, protecting incomplete editing fragments.
| Action | Gesture or control |
|---|---|
| Request spelling alternatives | Tap Left Shift before or after Space; on macOS, preview choices in a quiet caret strip, repeat to advance, type or Space to accept. Windows/Linux cycle replacements directly. |
| Complete an English or Hebrew word | Tap your completion key (Right Shift by default) before or after Space. On macOS, preview choices; repeat to advance, type or Space to accept. Windows/Linux cycle replacements directly. |
| Reconsider an unchanged word | Tap Ctrl twice immediately, before or after its Space |
| Rescue selected text (supported controls) | Select text in an editable field, then tap Ctrl twice; repeat to restore it |
| Convert an unchanged last word to the other layout | Tap Ctrl twice within half a second, even for unknown words |
| Undo the latest correction or completion | Tap Ctrl twice immediately, or use the optional single-Ctrl undo shortcut |
| Allow an ignored word again | Choose Allow again beside it in Recent corrections, or edit Settings > Word rules |
| Enable/disable or pause | Tray/menubar, Linux control window, or terminal dashboard |
| Inspect or ignore a correction | Open Recent corrections… in the tray, then choose Details or Ignore word; in the Linux window, expand a correction and choose Ignore this word. Allow again reverses ignoring. Save failures appear beside the action. |
| Inspect live activity | Help > Start live log… in the tray/menubar, or Live log… in the Linux control window |
| Review gestures | Help > Typing shortcuts in the tray, or Typing shortcuts in the Linux control window |
Double-Ctrl undoes the latest automatic correction, abbreviation expansion, or completion, restoring the original text or prefix. If the last word was unchanged, it converts the word to the other keyboard layout, even if neither reading is a dictionary word. Conversion works before or after Space and preserves the separator. Repeating a manual conversion converts the word back without changing saved exceptions or training spelling replacements. Up to 32 extra spaces preserve correction undo and explicit suggestions, and are restored with the original word. Enter or moving the cursor ends the opportunity to act on a finished word. On supported macOS text fields and Windows native Edit/RichEdit controls, undo also survives up to 32 characters typed after a correction. Those characters are preserved verbatim; the text before the caret must still match. Linux and unsupported controls retain undo across spaces only.
On macOS, completion and spelling alternatives appear only on explicit request in a compact, passive strip near the caret. The original sentence and keyboard layout stay unchanged while you browse. Each page includes your original text; choosing it makes no edit and does not train learning or count a correction. Typing (including punctuation) or Space accepts the highlighted alternative and preserves that input. Enter cancels the preview and reaches the application once, unchanged; it never accepts, erases or replays a possible send/execute action. Escape, Backspace, navigation, command chords, clicks, focus changes, pause and disable dismiss the preview. Holding Shift for capitals still works. The strip follows your configured keys, including Left Shift when assigned to completion. The active choice has a filled highlight, with cycling, acceptance, and dismissal hints below it. Choices size to their text; long labels truncate to fit the screen. Near the bottom edge, the strip opens above the caret to keep your text visible.
The strip anchors to an accessible caret, or below an accessible single-line search field such as Spotlight. If neither is available, macOS leaves text untouched instead of opening an unanchored window. Unsupported individual accessibility notifications do not prevent the strip; application switches still dismiss it. Spotlight replacements validate the typed suffix and update its search field directly, preserving earlier query text and discarding only its selected inline autocomplete suffix. If safe field access is unavailable, no Backspaces are sent. Windows and Linux retain their existing direct replacement cycling; passive native candidate strips are not implemented there. Native appearance and accessibility support vary by application.
The optional single-Ctrl shortcut only undoes corrections. It never converts unchanged words or removes saved exceptions. If it shares the action key, the single-tap action waits half a second so double taps take priority. The double-tap action can still be remapped or disabled in Settings.
Selected-text rescue converts physical English/Hebrew key positions, without dictionary checks. The first English or Hebrew letter determines the source layout; select one language at a time for predictable results. Spaces, line breaks, digits, and unmapped characters are preserved. Converted text stays selected, and double-Ctrl again restores the exact original, including case. It leaves the clipboard and keyboard layout untouched. macOS requires writable Accessibility selected-text and range attributes. Windows supports native Edit and RichEdit controls with UI Automation selection access. Linux uses the optional AT-SPI helper in supported editable controls. Password, read-only, and unsupported controls are skipped. Selections are limited to 64 KiB of UTF-8 text. Selection undo restores the original text; it does not promise to restore rich formatting. Linux AT-SPI replacement requires multiple calls: an interruption after insertion can leave both texts rather than risk deleting the original. See the integration limits. App exclusions, pause/disabled state, and Secure Input still apply.
Holding Shift for capitals or Ctrl for shortcuts does not trigger these gestures.
Settings > Shortcuts > Undo only can additionally enable a single tap of
Left Ctrl or Right Ctrl. The configured double-tap action remains available unless disabled. Holding Ctrl or using
it in a chord never triggers the extra shortcut; the same cursor/focus safeguards
apply to both gestures.
Extra spaces preserve undo. Supported native controls also preserve undo across
a bounded typed suffix, as described above. Enter or cursor movement ends the undo
opportunity. Undo restores the original text and, when changed, the previous layout.
One undo suppresses that word
for the session; undo counts are saved in learned.txt, and two occasions make the
exception survive restarts. Allowing the word again clears its saved exception.
On macOS, an undo gesture completed while a correction is landing waits for that
correction to finish; later typing or cursor movement still cancels the queued undo.
macOS prefers a verified native range replacement when the field supports it,
preserving surrounding text and formatting. Other fields use paced keyboard events.
During the destructive part of a macOS rewrite, keyboard events and mouse button
events wait briefly until the replacement is complete, then replay in their original
order. This keeps continued typing from canceling a partly erased word. Unsafe queued
input clears correction and undo context; bare modifier taps and spaces retain it.
The macOS/Windows tray opens a native Settings window with General, Shortcuts, Applications, and Word rules sections. General offers language preference, spelling, completion, spelling sensitivity, and Start at login. Sensitivity ranges from no automatic spelling edits to Conservative (one edit), Balanced (two), and Flexible (three); shorter words still have stricter limits. The status submenu suggests Conservative spelling when many corrections have been undone. The Linux control window offers language preference and live controls for spelling, completion, and all four spelling sensitivity levels. The enabled/disabled switch survives restarts.
Settings uses visible General, Shortcuts, Applications, and Word rules navigation. On smaller windows, settings scroll without shrinking controls. General includes example previews using the current correction settings without typing, changing the keyboard layout, or learning. Previews exclude prior words and application restrictions; choose Preview again after changing settings. The tray exposes the last detected application's mode and temporary pause directly below status. Practice offers one-click enablement of an available, separate Ctrl for immediate undo without changing existing bindings automatically. If both Ctrl keys are occupied (including Either Ctrl for the double-tap action), practice explains which bindings need separating in Settings > Shortcuts. For immediate undo, assign a Ctrl key different from the double-tap action; sharing a key retains the half-second wait needed to distinguish taps.
recast # Linux: background daemon; macOS/Windows: tray app
recast -f # Linux: stay in the foreground
recast -g # Terminal dashboard (Linux/Windows)
recast -w # Control window (Linux only)
recast --stop # Linux/macOS; on Windows, quit from the tray
recast --status # Running state and configuration diagnostics
recast --explain "recieve" --layout en # Preview a correction without typing
recast --explain "יקךךם" --layout he # Preview visible Hebrew-layout text
recast --explain "baye" --layout en --context "data" # Preview with preceding text
recast --write-config # Create a commented config without overwriting one
recast --help # All options and environment settingsThe tray and Linux control window also offer Pause in [application] until I switch away for the last detected external app. Switching to another identified app ends this temporary pause automatically; Resume in [application] ends it early. Unknown focus and ReCast's own controls preserve the pause. Saved app modes remain unchanged and apply when correction resumes.
The Linux control window offers Pause for 30 minutes / Resume and Recent corrections. Expand a correction to see its captured decision evidence, then choose Ignore this word to save an exception. On macOS and Windows, Recent corrections… opens a window with separate Original and Replacement columns, timestamps, Details, and Ignore. It shows a snapshot of up to 20 corrections, up to five per page depending on window height. Choose Refresh to include newer corrections; rows stay stable while you inspect or ignore a word. Closing Settings, history, or practice leaves ReCast running in the tray. Undone corrections remain visible and marked. Details include both layout readings, dictionary/form matches, frequency ranks, and spelling scores and competing candidates when spelling was evaluated. Evidence is captured when the decision is made, stays in the bounded in-memory history, and is not recomputed using later settings. Inspecting a correction does not add a word rule.
--explain accepts one visible word with optional trailing punctuation and requires
an explicit en or he layout. It reports the replacement, planner operation,
layout evidence, spelling candidates, and protection or rejection reasons,
using this invocation's settings and saved lists. It never captures keys, changes
the OS layout, types text, or stops a running instance. Supply up to 16 preceding
visible words with --context to inspect a contextual decision. The supplied
words stay in memory for that invocation and never train personalization.
Punctuation and newlines end the supplied context just as they do while typing.
Without --context, the preview has no prior-word history. Live application
checks are unavailable; unsupported characters produce an error.
In the terminal dashboard, e/Space toggles correction, p pauses for 30 minutes,
r reloads lists, and q quits. Closing the control window or quitting the dashboard
ends ReCast. On macOS, use the menubar instead of the dashboard.
Starting ReCast normally replaces an existing instance. If a service manager would
immediately restart the old copy, ReCast explains how to stop that service first.
--keep-others bypasses replacement, but concurrent copies can correct text twice.
--status queries each running copy for its live settings, memory, listener health,
active application mode, and pause/disabled reason, including on Windows. An older
or unresponsive copy is reported as running with live status unavailable. If no
copy is running, it prints clearly labeled offline configuration diagnostics.
| OS | Configuration directory |
|---|---|
| Linux | ~/.config/recast/ (or $XDG_CONFIG_HOME/recast/) |
| macOS | ~/Library/Application Support/recast/ |
| Windows | %APPDATA%\recast\ |
Live UI settings save to config.toml and apply immediately. Manual edits to that
file require a restart. Environment variables override the file; the UI explains
when an override prevents a change. Run recast --write-config for every supported
setting, including layout backends and injection timings.
The file accepts flat key = value lines and # comments, without tables or arrays.
Keys are environment names lowercased without RECAST_; for example,
RECAST_SPELL_DIST=1 is spell_dist = 1.
# Example overrides; everything else uses its default.
prefer = "balanced" # balanced (default), english, or hebrew
spell_dist = 1 # Single-edit spelling fixes (default ceiling: 3)
complete = true # Completion and abbreviations (default: true)
split = true # Merged-token last-word correction (default: true)
personal = false # Persistent personalization (default: false)When two words run together, ReCast can recognize a common prefix of at least
three letters and replace the entire merged token with its corrected final word.
For example, hellorecieve becomes receive, and helloakuo becomes שלום.
Trailing punctuation and the final word's capitalization are preserved. Undo
restores the entire original token. Recognized whole tokens take priority. Set
split = false or RECAST_SPLIT=0 to disable this fallback.
Spelling defaults to words of at least 4 characters and suggestions ranked within
75,000 for English words of at least eight letters (20,000 for shorter words).
Cheap two-edit repairs can use the full rank limit from eight letters; more
speculative two-edit repairs of long words are limited to rank 15,000. Completion
defaults to prefixes of at least 2 characters and rank 100,000.
Short layout switches accept ranks up to 30,000, or 50,000 after at least two
confirmed words in the target language; short = false restricts them
to ranks up to 500. Homograph overrides accept alternate readings ranked up to
5,000, requiring a tenfold frequency advantage without language history;
freq = false disables the frequency tie-break between valid readings in both layouts.
Choose Balanced, Prefer English, or Prefer Hebrew from Language
preference in the tray/menubar, Settings > General, or the Linux window.
In the terminal dashboard (recast -g), press b to cycle through these modes.
Changes save and apply immediately. For a command-line launch, use
RECAST_PREFER=english recast (or hebrew / balanced); services use
prefer = "english" in config.toml after a restart. recast --status shows
the active preference; --explain includes its decision checks.
Balanced retains the existing symmetric rules. A preference adds checks only to automatic switches into the other language: exact targets of 2–3 letters must rank within 500, longer targets within 5,000. A recognized preferred-language word stays unchanged without an established run in the other language. After two confirmed words in that language, the limits relax to 5,000 and 20,000 respectively. Combined layout and spelling repairs require at least five target letters and rank within 5,000 (20,000 with an established run). Supported Hebrew prefixes can use their ranked dictionary stem. Unranked targets are left unchanged. These conservative heuristics trade some automatic corrections for fewer unwanted switches; they are not measured confidence probabilities. Switching toward the preferred language retains all Balanced protections. Explicit conversion, completion, abbreviations, and spelling within the current language work as usual. Automatic learned layout replacements also pass the preference checks.
An absent config uses defaults. Invalid values produce diagnostics and fall back; an unreadable config stops startup so exclusions are not silently discarded.
| File | Purpose |
|---|---|
config.toml |
Settings; optional until created or saved from the UI |
abbrev.txt |
Custom abbr = expansion rules; # comments allowed |
ignore.txt |
Words to leave alone, one per line; # comments allowed |
learned.txt |
Undo counts used for persistent exceptions |
state.txt |
Saved enabled/disabled state |
welcomed |
Marker for the one-time correction hint |
setup-complete |
macOS setup marker; missing requirements still reopen setup |
practice-offered |
Marker for the optional first-run practice window |
personal/ |
Opt-in personalization files, rules.txt rule counts, and usefulness.txt usage counts |
abbrev.txt and ignore.txt reload within about two seconds of edits.
Settings > General > Advanced settings opens the config file in your editor,
creating it if needed without overwriting existing content. Settings > Word
rules opens the native editors for ignored words, learned exceptions, and
abbreviations. Reload lists is available in that section.
For abbreviations, add rules to abbrev.txt:
btw = by the way
addr = 1 Main Street, Tel Aviv
Rules expand when you finish the word and take priority over automatic corrections.
Right Shift also offers an expansion. Capitalization follows your input:
Btw becomes By the way. No abbreviations ship enabled; complete = false
disables both abbreviations and word completion.
The separate spelling-suggestion gesture (Left Shift by default) requests
alternatives in the current language, including short misspellings (hte → the)
and valid English words (form / from). It works with automatic spelling and
completion disabled and stays in the word's language. On macOS it previews choices
without editing until typing or Space accepts; Enter cancels. Windows/Linux keep
direct cycling. Accepted replacements use the existing undo gesture.
Requests stay bounded to four choices and preserve capitalization and trailing
punctuation. Choosing an alternative to a valid dictionary word does not train
an automatic replacement for that word.
Word completion uses the active English or Hebrew layout. Two-letter prefixes
use exact matches. Longer prefixes can recover a missing, extra, wrong, or swapped
letter; prefixes of 6–20 characters can recover two such errors when their first
two letters are intact. Cycling and undo always restore your original prefix. Prefix
length limits count characters in either language. English apostrophe prefixes
such as don' can complete to don't; saved apostrophe words are also candidates.
Saved words in ignore.txt and persistent undo exceptions are also completion candidates, including names
and technical terms absent from the bundled dictionary.
Completion presents four choices, then restores the original prefix. Keep tapping
to reach the next page instead of repeating the same four choices forever. After
the final page, the sequence starts again. Undo always restores the original prefix.
Bundled technical vocabulary is available even without a general-language frequency
rank. Long, exact prefixes can also complete specific dictionary words beyond the
ordinary rank cutoff; short and edited prefixes retain their confidence limits.
Opening quotes and brackets are preserved around corrections and completions.
Completion and spelling suggestions also work on the last finished word while
the cursor remains after its tracked spaces. Every choice and undo preserves
those spaces; typing the next word accepts the choice without requiring another
Space. Hebrew completion can attach supported prefixes to ranked dictionary
stems or saved words even when the combined form has no separate dictionary entry.
On macOS and Windows, open Settings > Applications and choose the last detected app or a saved app. Use last application refreshes that list after switching apps. On Linux, use Application modes in the control window:
- Full correction follows the global spelling/completion settings.
- Layout only keeps layout correction and undo, with spelling, abbreviations, completion, and personalization disabled in that app.
- Manual only disables automatic rewrites and personalization while retaining explicit conversion, spelling suggestions, completion, and undo. Useful for terminals and code editors.
- Off excludes the app from processing.
Choose a saved application and set its mode to Full correction to restore it. Changes save together and apply immediately; an in-flight replacement is canceled if its app mode changes. You can also edit these values and restart:
# Exact IDs, comma-separated and case-insensitive; no wildcards.
exclude_apps = "Alacritty, org.keepassxc.KeePassXC"
layout_only_apps = "code, org.gnome.TextEditor"
manual_only_apps = "Alacritty" # explicit gestures only
undo_shortcut = "right_ctrl" # optional single-tap undo; none (default), left_ctrl, right_ctrl
# Shortcut defaults; these settings are global, not per-application.
action_shortcut = "ctrl" # ctrl, left_ctrl, right_ctrl, left_shift, right_shift, none
completion_shortcut = "right_shift" # left_ctrl, right_ctrl, left_shift, right_shift, none
correction_shortcut = "left_shift" # explicit spelling alternatives; same choices, separate key
# macOS uses bundle IDs; Windows uses executable filenames including .exe.A conflicting shortcut configuration keeps action/undo bindings first, then completion, and disables conflicting completion or spelling-suggestion gestures at startup. Diagnostics report the disabled gesture. Abbreviation expansion is unaffected.
Excluded apps receive no corrections, expansions, completion, undo rewrites, word logging, or learning. Global events still track key releases. Off takes precedence over Manual only, then Layout only, if an app appears in multiple lists. With any application restrictions configured, an unknown active application also suspends processing. On native GNOME/KDE Wayland, correction requires the optional AT-SPI helper and an accessible focused control. Application rules use the executable basename there; Hyprland, Sway, and X11 retain their existing application identifiers. After returning to an allowed app, finish the current word with Space/Enter to resume.
The compact tray menu contains Status, Pause, Recent corrections, Language preference, Settings, Help, and Quit. Status includes the current application mode, recovery details, and correction counts. Pause correction groups temporary pauses and Disable until I enable it again, which persists across restarts. The icon distinguishes active, paused, disabled, and attention states by shape. macOS uses a monochrome template icon that adapts to the menubar appearance. The Linux window uses the same status wording and groups pause controls.
The status submenu and Linux window explain Active, Disabled, Paused,
Excluded application, Secure Input, unavailable keyboard capture, and unknown
application identity, with a suggested recovery action. Routine corrections stay
silent. --status exposes the same status from the running process.
Open Settings in the tray/menubar and select the Word rules section, or
expand Settings > Word rules in the Linux control window.
Choose Ignored words, Learned exceptions, or Abbreviations. Add or
remove words one per line; write abbreviations as shortcut = expansion.
Learned exceptions shows saved exceptions from repeated undos; single-undo
session exceptions are not listed. Other lists still apply when you remove a word.
Save applies changes immediately. Cancel leaves the rules unchanged. Correction pauses while the editor is open and returns to its previous enabled or paused state when you close it. Invalid entries and failed saves keep your edits open. If rules changed on disk while you were editing, copy your edits and reopen the editor before saving, so newer changes are not overwritten.
ReCast processes global keyboard events locally: no telemetry, remote dictionaries, or update checks. Recent corrections stay in memory. Undo counts and explicitly ignored words are saved locally; debug logging and personalization are off by default. Synthetic input replaces text without using the clipboard.
The live log starts only when you choose Help > Start live log… in the tray/menubar or press Start logging in the Linux control window. It shows timestamps, correction and undo text, and Accessibility, listener, or keyboard setup issues as they appear. Closing its window stops recording and clears the entries; Stop live log stops it while keeping the window open for review. Entries stay in memory only, up to 500 lines. A new session clears earlier entries. Leave it off when typing sensitive text.
Live status uses an authenticated connection on localhost only. Its random access token is stored under the user's cache directory (owner-only on Unix); status responses contain configuration and application identity, never typed words or recent corrections. Nothing is sent to a remote service.
On macOS, ReCast suspends processing while the OS reports Secure Input. Linux and Windows have no equivalent check: exclusions can protect a whole app, but cannot identify individual password fields in an allowed browser or application.
RECAST_DEBUG=1 prints checked words and may expose sensitive text in service logs.
Set rule_stats = true in config.toml (or RECAST_RULE_STATS=1) to save
automatic correction and undo counts in personal/rules.txt. Rows cover layout,
missing-space split, spelling or learned replacement, abbreviation, and combined
layout plus spelling. They contain no typed words, application names, or key
timings. Manual conversions and completion taps are excluded. Counts update on
successful text replacements and flush about every 30 seconds. This setting is
independent of personalization and is off by default.
The same setting saves aggregate usefulness counters in personal/usefulness.txt:
completion sessions, extra cycling taps, accepted choices, first-choice acceptance,
abandoned offers, automatic corrections, and correction undos. One session begins
with a successfully inserted offer; acceptance requires finishing the chosen word.
Returning to the original prefix, continuing to edit, undo, or losing context ends
an offer as abandoned. Unresolved offers are not counted as accepted or abandoned.
These counters contain no words or application IDs, flush about every 30 seconds,
and appear in recast --status. The counts support acceptance and undo ratios;
they do not automatically retune ranking. --clear-personal-data removes them.
RECAST_PERSONAL=1 saves word/correction data and aggregate key timings under
personal/; on Linux/Windows, this may include password-field text. Personal files
are user-only on Unix. Automatic corrections train word frequency and replacement
pairs only after subsequent typing retains the result; undo, deletion, and detected
focus changes cancel pending learning. Completion offers do not train replacement
pairs merely by being displayed: only a retained choice, finished with Space or
Enter, can train word frequency or a manual spelling repair.
Completion ranks exact and edited prefix matches together, penalizing each edit
tenfold (a hundredfold for two-error recovery) and accounting for the taps needed
to reach each choice. Frequency and context
lead; saved keystrokes add at most a 60% ranking benefit, so long words cannot
dominate merely by having a long suffix. One-letter completions retain their
frequency weight. Otherwise equal capped scores prefer the shorter word.
For three-letter prefixes,
typo recovery runs only when no exact offer exists. Configured abbreviations still
come first. Retained word frequency influences ranking when personalization is on.
Completion and manually requested spelling offers use bundled English and
Hebrew phrase priors immediately, even with personalization off. Curated weights
are supplemented by 994 measured pairs from two public Leipzig news samples,
each containing 10,000 sentences. Measured pairs require at least five occurrences,
conditional frequency of 5%, and association of at least three times the independent
word-frequency expectation. Weights remain bounded to four; counts and pinned source
checksums are in src/phrase_counts.tsv. Explicit completion and manual spelling
offers also use 560 additional English pairs from src/intent_counts.tsv, with
the same evidence thresholds and raw dictionary/top-20,000 frequency trust.
For example, for after task ranks force ahead of forget. Eligible weights
are prepared at build time and cached for the previous finished word; overlapping
phrase sources use their maximum weight. Automatic rewriting keeps its existing
phrase evidence policy. Personalization additionally boosts pairs retained at least
twice in the current typing context; these pair counts remain in memory. Focus changes, cursor
moves, deletion, undo, and Enter clear phrase context; punctuation ends the
previous-word link. Disabling personalization discards learned pair counts while
keeping the public phrase priors available.
The same context retains at most 16 visible words in memory and supplements the
one-word priors with a local, smoothed 4-gram model. It scores a candidate against
up to three preceding words, backing off when longer contexts are sparse. The
interpolation returns counts lost to pruning or phrase boundaries to the shorter
context. A history with no retained continuations contributes no new evidence.
Longer-context likelihood is compared with the previous-word distribution, so it
adds evidence without counting the one-word phrase prior twice. This preserves
useful phrase evidence when extra history is sparse: baye after the data or
we store all the data can still resolve to base, as it does after data.
The model contains 59,644 measured 1-to-4-grams from the same pinned public news
samples, stored in about 1.2 MB of read-only executable data. Context counts
must occur at least four times before influencing ranking. Relative likelihood
adjustments are bounded; mixed-script transitions do not borrow evidence from
the other language. Neither context nor the model requires a network service.
Tap the completion shortcut (Right Shift by default) before Space to request an English or Hebrew spelling suggestion when the prefix has no exact completion. Repeated taps cycle alternatives and return to the original text. Phrase context ranks these manual offers; automatic spelling retains its confidence gates. Existing words are not reconsidered by the manual spelling list. Explicit abbreviations retain priority. Finishing a selected spelling repair of the same or shorter length can train its correction pair when personalization is enabled; unaccepted offers and longer prefix completions do not.
Same-layout automatic English spelling applies context to every eligible candidate before deciding, allowing sentence evidence to reconsider a previously confident guess. Context adjusts each candidate's cost by at most eight units in either direction. The winner must still lead both keeping the original and the next candidate by at least four units. Context never widens edit-distance or frequency limits. Word protection, ALL CAPS, ignored words, and undo exceptions still apply. This also supports a combined layout and spelling repair, with independently accepted alternate-layout matches taking precedence over contextual intent. Recent correction details include the phrase weight and cost adjustment.
Hebrew spelling corrections and manual offers search one letter insertion, deletion,
substitution, or transposition, favor missing/extra ו and י, enforce final-letter
positions, and recognize the layout planner's supported prefix stacks. Candidates
need a ranked dictionary word or stem. Existing words and saved exceptions are
preserved; the spelling enable, minimum-length, and rank settings still apply.
Balanced and Flexible spelling also recover two cheap edits in plain stems with
at least six letters, preserving the first two stem letters. The total edit cost
cannot exceed 180, and the target rank cannot exceed half the configured limit
or 10,000, whichever is smaller. Supported prefixes do not count toward that
minimum stem length. For example, אינטררנטט becomes אינטרנט and מעכרותת
becomes מערכות. Conservative spelling keeps one-edit search; explicit correction
requests can offer these long-stem repairs regardless of automatic settings.
Automatic Hebrew corrections require at least four letters and a 20-point lead
over both the next candidate and keeping the original; phrase context contributes
at most eight points to candidate ranking. Neighboring physical keys and repeated
letters receive lower costs. These cheap repairs use the configured spelling rank
ceiling; speculative single edits retain a ceiling of 30,000. Inferred prefixes receive
a score surcharge rather than inheriting the stem's full confidence. Correction
details show candidates, costs, frequency rejections, prefix evidence, learned
discounts, and the keep-original comparison.
Manual spelling search normalizes niqqud and Hebrew
or ASCII quotes for lookup, preserving them attached to their original letters
in offered repairs. A decorated letter cannot be deleted. Automatic Hebrew spelling
accepts plain letters only. Live keyboard capture
still supports the existing unshifted Hebrew keymap; this does not add niqqud input
capture or new Linux injection mappings.
Ambiguous candidates remain available through the completion gesture. Hebrew
repairs preserve the current layout and punctuation, replace only the changed
suffix, and support the same undo and retained-correction learning as English.
Before a combined layout and spelling repair, both language assessments compete under their existing confidence gates. A candidate rejected by its own confidence gate can still veto an ambiguous switch. Reading source letter keys as alternate-language punctuation adds uncertainty; English punctuation is preserved when evaluating a Hebrew repair. Exact layout decisions retain their existing word, frequency, and history guards. Exact matches and alternate-layout typo repairs that pass these checks without context take precedence over contextual intent and learned replacements. For unresolved alternatives, a supported phrase in the preceding word's language can resolve the language choice without bypassing either speller's acceptance gates. Scores are heuristics, not confidence percentages.
The completion gesture checks both layouts. Current-language exact matches, known words, and explicit abbreviations retain priority; exact alternate-layout matches remain reachable on later pages. An exact alternate-layout prefix match can precede weak current-layout offers. Acceptance by the completion tap switches layout and inserts the completion together. Cycling back or undo restores the original text and requests the original layout. A refused initial layout switch cancels insertion. No automatic layout change happens from these completion suggestions before the gesture.
With personalization enabled, repeatedly retained English and Hebrew correction pairs also adjust the ranking cost of transpositions, neighboring-key substitutions, and missing letters (including extra letters in Hebrew). Each language trains its own counts. The discount is capped at 15 score units, does not widen edit-distance or frequency limits. A retained automatic correction contributes one vote; an explicitly selected and retained spelling repair contributes three. Merely displaying an offer contributes nothing. Undo withdraws three votes, saturating at zero, weakening the rejected pair and its learned edit-class evidence. Ordinary word frequency still counts each retained word once.
Learned exact layout pairs switch in either direction, including in layout-only
mode. Accepted exact alternate-layout matches and independently confident
alternate-layout typo repairs are chosen before learned pairs are considered.
Otherwise, learned pairs compete with independently inferred actions and preserving
the original token. Configured
abbreviations take precedence, unknown
layouts remain untouched, and single-letter inputs never trigger learned repairs.
Repeated Hebrew spelling pairs stay in Hebrew. Learning requires personal = true.
Learned replacements require at least two retained votes, twice the votes for all
competing replacements combined, and a lead of at least two votes. Ties and weak
leads do not trigger a learned replacement. Correction-pair votes halve every
30 days, including their contribution to learned typo costs. New observations do
not reset the aging period. The local personal/confusions.txt file stores the
decay timestamp in a fourth column; existing three-column files remain readable
and start aging when first loaded by this version.
Before the contextual intent comparison, ReCast accepts exact alternate-layout matches and alternate-layout spelling repairs that independently pass its existing tolerance and bilingual confidence checks. Context cannot veto or change these accepted matches. Source-word, frequency, edit, language-preference, and focus protections remain in force. Remaining eligible layout, spelling, and learned actions share one intent comparison with keeping the original. Equivalent visible actions are deduplicated. Spelling retains its minimum margin over both the original and same-language or other-language alternatives, normalized against each model's acceptance threshold. Learned evidence uses its decayed support advantage; layout eligibility retains its frequency and recent-language checks. Conflicting actions or a lead below four policy-cost units leave the text unchanged. Existing pipeline eligibility and language-preference gates still apply. These scores are heuristics, not calibrated confidence percentages. Completion remains an explicit shortcut action and uses the same contextual evidence for ranking; it is never inserted automatically while typing a prefix.
With personalization enabled, words retained at least twice also become completion candidates even when absent from the bundled dictionary. To clear these files, stop ReCast first, then run:
recast --clear-personal-dataThis removes ReCast's personalization and rule-statistics files, not your ignored words or undo exceptions.
- No corrections: check the enabled state, installed keyboards, permissions,
exclusions, and
recast --status. On Linux, verifyinputmembership anduinputaccess, then inspect the service journal. - Wrong Linux backend: set
layout_backend = "hyprland"(orsway,kde,gnome,x11) and restart. Hyprland needs the currentHYPRLAND_INSTANCE_SIGNATUREandXDG_RUNTIME_DIRin the process environment. - macOS permissions broken after reinstall: remove the old Accessibility entry
and add the running copy shown in setup.
make appresets privacy grants; for a manual reinstall,tccutil reset All com.recast.appresets them before you grant access again. Relaunch afterward if needed. - Unwanted spelling fixes: undo immediately, ignore the word, enable Conservative spelling, or disable spelling in Settings.
cargo test independent_correction_evaluation -- --nocapture reports unwanted
changes, missed fixes, wrong fixes, precision, and recall on independently authored
evaluation cases in tests/data/evaluation.tsv. Standalone cases were frozen before
the Hebrew and phrase changes, with exact baselines for existing failures. Expected
results still count toward accuracy; a passing baseline test does not imply perfect
correction. These synthetic cases are not a random sample of real user typing and
must not be used to tune thresholds. The original regression corpus remains separate.
Reviewed baseline changes are recorded separately in
tests/data/evaluation_updates.tsv, leaving the frozen examples unchanged. Each
update must name the exact old and new result and a review reason; stale updates,
new errors, and unreviewed changes fail the test. Replacing a wrong correction
with abstention is allowed only as an explicit update and still counts as a miss.
Regenerate the measured phrase priors by downloading the two public archives named
in src/phrase_counts.tsv, then running:
python3 scripts/build_phrases.py /path/to/eng_news_2020_10K.tar.gz /path/to/heb_news_2020_10K.tar.gz
python3 scripts/build_intent.py /path/to/eng_news_2020_10K.tar.gz /path/to/heb_news_2020_10K.tar.gz
python3 -m unittest discover -s scripts -p 'test_*.py'The builder verifies pinned SHA256 checksums, respects sentence and punctuation
boundaries, and keeps at most 512 pairs per language. Add --check to verify the
committed output without changing it. Only aggregate phrase counts are bundled;
the app never downloads corpora or sends typed text to a server. The intent
builder retains counts observed at least twice, including true context totals
before pruning, and never trains from the correction evaluation cases. It also
supports --check. Compare contextual and context-free latency with:
cargo test --release benchmark_intent_latency_distribution -- --ignored --nocapturecargo build --locked --release
cargo fmt --check
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked --release --test cli
cargo test correction_accuracy_corpus -- --nocapture
make benchSee PERFORMANCE.md for search optimizations, benchmark scope, and further latency opportunities.
The shared correction planner is in src/dictionary/mod.rs, with
spelling in src/spell/mod.rs and completion/lists in
src/complete.rs. src/platform/engine
owns typing, cancellation, completion cycling, and undo across all platforms.
Its modules separate event handling, word state, correction planning, gestures,
injection, and layout switching; platform.rs defines the native adapter contract.
Native adapters handle capture/injection; src/layout handles layout backends.
Add real correction reports to tests/data/corrections.tsv. Optional sequence and application-mode columns exercise language history across words, switches between English and Hebrew, and layout-only behavior. A different sequence or application mode resets history, matching the engine's cancellation. The corpus separates unwanted, missed, and wrong corrections; it is a regression check, not an estimate of accuracy for all typing. Engine tests use a simulated screen; focus benchmarks require a desktop session.
CI checks formatting, tests, Clippy, release builds, and
release CLI behavior on Linux, macOS, and Windows. The manual
Binaries workflow publishes release assets and
checksums, with signing/notarization when repository credentials are configured.
See DISTRIBUTION.md for the release steps and signing secrets.
make help and .\deploy.ps1 -Target help list build, install, and service targets.
en_dict.txt and en_tech.txt include curated programming terms, tools, formats,
and infrastructure names. en_tech.txt is merged at build time and explicitly
protected from spelling changes even when a term is absent from the frequency list.
These additions enable wrong-layout recovery without inventing frequency rankings
or promoting jargon into general-purpose spelling suggestions. Their unchanged English readings are covered by the correction corpus.
Spelling correction also considers missing, extra, or wrong first letters on longer words, including later typos when the edit budget permits. Layout correction recognizes supported Hebrew prefix stacks when the dictionary stem has at least three letters and frequency rank at most 75,000; the full word must have at least five letters. These inferred forms never override an exact current-layout word when the layout is known.
Build-time preprocessing merges, deduplicates, and sorts dictionary entries for
binary search. Source dictionary order therefore does not affect lookup speed.
Do not reorder en_freq.txt or he_freq.txt: their line order defines frequency
rank, which controls correction decisions. Generated frequency blobs are sorted
by word while preserving those ranks.
English additions are imported automatically from the SCOWL-derived
wooorm English dictionary.
Only explicit lowercase entries of at least four letters that also occur in
en_freq.txt are added. This cross-check avoids importing raw subtitle noise,
capitalized names, or short layout collisions. Hunspell affixes are not expanded.
Existing entries and frequency rankings are preserved. Hebrew already contains
all pure Hebrew words of at least four letters in its bundled frequency list.
To repeat the import (Python 3, no packages required):
curl -fsSL https://raw.githubusercontent.com/wooorm/dictionaries/8cfea406b505e4d7df52d5a19bce525df98c54ab/dictionaries/en/index.dic -o /tmp/recast-en.dic
python3 scripts/expand_dictionary.py /tmp/recast-en.dic
python3 scripts/expand_dictionary.py /tmp/recast-en.dic --checkThe importer verifies the pinned source checksum and adds only missing entries. These additions are a filtered extract; SCOWL's notices and redistribution terms are retained in licenses/scowl.txt.
Application code: Apache-2.0 — see LICENSE.
Native editing checks, including rapid Space/Enter, chat sends, focus interruption, selection undo, and mixed-language text, are documented in the native test protocol. The disposable browser fixture records local traces; it does not simulate physical keyboard capture.