Configuration Cookbook

Configuration cookbook

Two ways to configure, always in sync:

1. Tray → "Settings…" — a native GUI with ten panes: Setup, Languages, Hotkeys, Commands, Wordlists, General, Exceptions, Suggestions, Plugins, About.
2. Tray → "Edit config.toml…" — the raw file, for anything the GUI doesn't expose yet:
   • Windows: %APPDATA%\opensource\poltertype\config\config.toml
   • macOS: ~/Library/Application Support/dev.opensource.poltertype/config.toml
   • Linux: ~/.config/poltertype/config.toml

Edits apply without a restart. Since v0.25.2 the file itself is watched, so a hotkey rebound and saved takes effect while the Settings window is still open, and a chord typed straight into the file takes effect the moment you save it. Closing the Settings window additionally picks up wordlists and profile overlays; tray → "Reload Settings" does the same on demand.

Recipes

Limit which layouts the engine considers

[languages]
active  = ["en-US", "uk-UA"]   # empty = every layout the OS has
ignored = ["ru-RU"]            # never switch to these

Silence PolterType in one app

[exceptions]
disabled_apps = ["Code.exe", "kitty"]   # executable basename, case-insensitive

The list is empty by default — two engine-level guards (the identifier guard and the plausibility keep) are what keep PolterType out of kubectl-style tokens everywhere, on every OS. Needs the focus tracker (Windows / Hyprland / X11).

Turn the identifier guard off (or keep it — it's why code survives)

[engine]
suppress_in_identifiers = true   # default; snake_case / camelCase / x2 tokens are left alone

The manual force-switch hotkey (Ctrl+Shift+Backspace; Ctrl+Shift+F9 on Wayland) bypasses every filter by design — use it for that one wrong-layout comment word inside your IDE.

Text expanders / smart commands

[[commands]]
id      = "anrl"
trigger = "anrl"
action  = { type = "type_text", text = "Anatomical Reference List" }

[[commands]]
id      = "to-english"
trigger = "((en))"
action  = { type = "switch_layout", layout = "en-US" }

[[commands]]
id      = "open-config"
trigger = ";cfg"
action  = { type = "open_path", path = "~/.config/poltertype/config.toml" }
apps    = ["Code.exe"]   # optional per-app scoping

Teach it your vocabulary

Easiest: Settings → Wordlists — pick a layout, one word per line, Save. Or drop files into <config-dir>/poltertype/wordlists/ (en-US → en_us.txt). The tooltip's Add to dictionary row does the same thing one word at a time. Per-app overlay profiles are documented in docs/DATA_LAYOUT.md.

Turn the updater off

[updates]
enabled = false   # never check, never download; also deletes anything staged

Tune or disable spelling suggestions

[suggestions]
enabled = false   # or tune timeout / candidate count — see the Suggestions pane

Convert a selection with the same key (0.24.0+)

[selection]
enabled = true   # off by default

The force-switch key then also converts selected text — but only when there is no just-typed word to fix, so nothing changes about the usual gesture. Reading the selection means copying it; your clipboard is restored afterwards. The Hotkeys pane greys the toggle out where the session cannot do it at all (GNOME and Cinnamon on Wayland, macOS) and says why.

Hotkeys (defaults)

Chord	Action
Ctrl+Shift+Space (Ctrl+Shift+P on macOS)	Pause / resume auto-switching
Ctrl+Shift+Backspace (Ctrl+Shift+F9 on Wayland)	Force-switch the last word, ignoring every filter

Both rebindable on the Hotkeys pane; the platform substitutions apply only while you are on the default, and the README explains why each exists.

Modifiers on their own (0.21.0+)

Either hotkey can be bound to modifiers alone — the Punto Switcher / Caramba gesture:

Binding	Gesture
Shift+Shift	Tap Shift twice
Ctrl+Shift, Alt+Shift, …	Hold two modifiers together, then let go

[hotkeys]
manual_switch_last = "Shift+Shift"

They fire when the keys come back up, and only if nothing else was pressed while they were down — so Ctrl+C, Ctrl+Shift+V and typing capitals are left alone. A tap has to be a tap, too: hold longer than half a second and nothing happens.

A single modifier on its own is not offered. PolterType does not see mouse buttons on Windows and macOS, so a bare Shift binding would fire on every Shift+click.

Caps Lock (0.25.0+)

The other Punto Switcher gesture, and the one thing you have to do to your keyboard first:

[hotkeys]
manual_switch_last = "CapsLock"

PolterType watches keys and never swallows them, so the key still latches the lock — and a latched lock makes the corrected word come back in CAPITALS, because the replay is scancodes and the system applies the lock to them. Take the lock off the key and the binding is all that is left on it:

Where	How
X11	setxkbmap -option caps:none (add it to your session start-up)
GNOME / Cinnamon / Budgie	gsettings set org.gnome.desktop.input-sources xkb-options "['caps:none']"
KDE	System Settings → Keyboard → Advanced → Caps Lock behavior → Caps Lock is disabled
sway / labwc / Hyprland	xkb_options = caps:none in the compositor's own input config
keyd, InputActions, …	whatever your remapper calls "make this key do nothing"
Windows / macOS	remap it with your usual tool — the binding takes the same key-stream path there, but has only been measured on Linux so far

Shift+Caps Lock is deliberately not matched, so you keep a way to latch the lock when you actually want it.

The Hotkeys pane's Rebind captures the key too, and the order above is the right one: neutralise the lock first, then rebind. Before 0.25.1 that order was the one that did not work — taking the lock off the key is what leaves it with no name for the pane to match on, so the pane recognised it only until you did what it asked.

Punctuation keys (0.25.0+)

Backtick, brackets, semicolon, quote, comma, period, slash and backslash can carry a hotkey — Ctrl+Backquote, Ctrl+Slash and so on. Before 0.25.0 they were accepted by the settings pane and then answered to nothing on the Wayland and evdev backends, where PolterType matches chords itself. Write them by name:

[hotkeys]
manual_switch_last = "Ctrl+Backquote"