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: closing the Settings window (or tray → "Reload Settings" after hand-edits) picks everything up.

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 is out for a related reason: it is observed rather than consumed, so binding it would flip the lock as well as switch the word.