Reference for keyboard shortcuts, tray operations, layout switching, the configuration file, and logs
awase switches its behavior based on the combination of the "IME state" and the "engine state."
| IME | Engine | Behavior |
|---|---|---|
| ON | ON | Thumb-shift (NICOLA) input |
| ON | OFF | Ordinary IME input (romaji conversion) |
| OFF | Either | Direct alphanumeric input (the engine stops automatically) |
When the IME is OFF, the engine stops automatically, so awase will not misbehave in password fields and similar contexts.
This lists which character each key outputs in the bundled default layouts (JIS layout/nicola.yab / US layout/nicola_us.yab). The normal plane is produced by a single keystroke; the other three planes are produced by chording (a simultaneous keystroke) with the Muhenkan/Henkan key (thumb shift) or the pinky-shift key.
The layout is fully customizable. You can edit it directly in the "Layout Editor" tab of the Settings window, or create your own .yab file and switch to it (see Switching layouts).
These are the shortcuts in the default configuration. They can be changed in config.toml.
| Category | Keys | Action |
|---|---|---|
| IME | Ctrl + Henkan | Turn the IME ON. If it is already ON, reset it to hiragana / romaji / CapsLock OFF |
| IME | Ctrl + Muhenkan | Turn the IME OFF (idempotent — nothing happens if it is already OFF) |
| IME | Left Shift solo tap | Sustained "IME-ON half-width alphanumeric" toggle. Press and release without pressing any other key to switch on; tap again to release (currently supported by MS-IME only; GJI support is planned) |
| Engine | Ctrl + Shift + Henkan | Turn the NICOLA engine ON (enable thumb-shift input) |
| Engine | Ctrl + Shift + Muhenkan | Turn the NICOLA engine OFF (switch to romaji input) |
| Engine | Ctrl + Shift + F12 | Toggle the engine ON/OFF (global hotkey, configurable in config.toml) |
| System | Ctrl + Shift + F11 | Force-override the focus classification of the current window (switch between text input ↔ bypass) |
| Thumb shift | Henkan | Right thumb-shift key (while the engine is ON, pressed simultaneously with another key for NICOLA detection) |
| Thumb shift | Muhenkan | Left thumb-shift key (while the engine is ON, pressed simultaneously with another key for NICOLA detection) |
| IME | Hankaku/Zenkaku | Toggle the IME ON/OFF (standard Windows behavior) |
| Emergency | Muhenkan × 3 (within 400 ms) | Force the NICOLA engine OFF (for when a stuck Ctrl or similar keeps the shortcuts from working) |
| Emergency | Ctrl+Muhenkan → Ctrl+Henkan → Ctrl+Muhenkan (within 2 seconds) | Panic reset — force a return to the standard state (IME ON, hiragana, engine ON) |
About idempotent IME control: Ctrl+Henkan is the operation "turn the IME ON." Unlike the traditional toggle approach, it always produces the intended result even if the current state has drifted. It operates independently of the engine ON/OFF state. If the IME is already ON, it aligns any in-progress state (katakana, half-width alphanumeric, etc.) to hiragana / romaji / CapsLock OFF and re-commits it.
About the "IME-ON half-width alphanumeric" toggle: A solo tap of left Shift temporarily stops only the NICOLA engine while keeping the IME open, letting you type alphanumeric characters directly (because the IME itself does not close, this works differently from a password field). Tapping left Shift alone again returns to normal kana input. It is also released automatically by a solo tap of the right Shift or by a focus change.
The awase icon lives in the system tray at the far right of the taskbar.
layouts_dir. Selecting one switches the layout immediatelyOpen it by right-clicking the tray icon → "Settings...". After making changes, use the "Apply" button to save them and apply them immediately.
| Item | Description |
|---|---|
| Keyboard model | Choose JIS (Japanese layout) or US (English layout) |
| Simultaneous-keystroke threshold | The time window (ms) within which two keystrokes count as simultaneous. The NICOLA standard default is 100 ms |
| Confirm mode | The timing at which characters are committed. See the table below |
| Speculative-output wait | The wait (ms) before speculative output when using two_phase / adaptive_timing |
| Output mode | Unicode (recommended), PerKey, or Batched. Normally leave it as Unicode |
| Hook mode | Relay (recommended, stable) or Filter (low latency) |
| Auto-start | Whether to start automatically at Windows logon |
| Layout | Selects the .yab layout file to use. "Rescan" refreshes the list |
| Mode | Behavior | Suited for |
|---|---|---|
| wait | Holds until the timeout before committing. Most accurate | People who want to type slowly and accurately |
| speculative | Outputs immediately and replaces on a simultaneous keystroke. Fastest, but flickers briefly | People who prioritize speed above all |
| two_phase | Speculative output after a short wait. Between wait and speculative | People who want a balance |
| adaptive_timing | wait during continuous typing, speculative once typing pauses. Adapts to speed automatically | People whose typing speed varies |
| ngram_predictive | Dynamically decides speculative vs. wait using n-gram statistics. Uses context to improve accuracy | People who want the smartest decision (recommended) |
| Item | Description |
|---|---|
| Left thumb key | The key used for the left thumb-shift key (default: VK_NONCONVERT = Muhenkan) |
| Right thumb key | The key used for the right thumb-shift key (default: VK_CONVERT = Henkan) |
| IME ON/OFF keys | The keys awase actively sends to turn the IME ON/OFF (idempotent). Multiple entries allowed |
| IME ON/OFF toggle | Key that flips ON⇔OFF based on the IME state at the moment it's pressed. Default: the Kanji key. Multiple entries allowed |
| Thumb Shift ON key | The key that turns the NICOLA engine ON. Multiple entries allowed |
| Thumb Shift OFF key | The key that turns the NICOLA engine OFF. Multiple entries allowed |
| Thumb Shift-toggle hotkey | A global hotkey that toggles the engine ON/OFF |
If you use GJI (Google Japanese Input) and have Muhenkan set as a thumb key, awase.exe reads config1.db at startup and whenever GJI is detected, and automatically decides whether to send a dedicated Fn key (default candidate: F21) instead of the raw Muhenkan key on a Muhenkan solo tap ("dedicated Fn-key conversion", ADR-091 §D3.2). This is for advanced users who want to toggle the character type (hiragana/katakana etc.) via a Muhenkan solo tap, and who also want to avoid "mode drift" (awase's assumption about GJI's state diverging from GJI's actual state). If GJI's config1.db doesn't yet have the "kana type switch" binding for that Fn key, awase.exe offers to add it via a popup (with your consent, backed up). There's currently no manual control for this in the settings screen. To pin a specific Fn key, edit config.toml directly, as shown in "Manually configuring GJI dedicated Fn-key conversion" below.
The "IME → awase" direction (keys awase interprets as external IME state changes, e.g. Hankaku/Zenkaku) has been removed from the GUI. It defaults to empty and is rarely needed, and the other candidates (IME-ON/IME-OFF keys) aren't physical keys, so exposing them in the GUI wasn't worth the clutter. You can still configure it by editing config.toml directly, as shown in "Manually setting IME-detection keys" below — but don't assign it the same key as "IME ON/OFF toggle" above, or that key will be double-processed and stop working correctly.
Normally awase.exe auto-detects this when GJI is detected (offering a popup to
add the binding if needed), and no manual action is required. Only edit
config.toml directly as shown below if auto-detection doesn't work,
or if you want to pin a specific Fn key intentionally (there's currently no
setting for this in the settings screen).
The Fn key you specify must have a "kana type switch" binding in GJI's own config1.db. Switch GJI's "Input assistance" to "Custom" (right-click the GJI tray icon → "Properties" → "Key settings" tab), then start awase.exe (or focus GJI) to get the popup that offers to add the binding. The write only reliably takes effect in GJI after you sign out and sign back in. Using the tray icon's "Exit and restart" instead can overwrite the file with GJI's in-memory (pre-write) settings, discarding the change.
Override behavior per app using the combination of process name and window class name.
| Setting type | Description | Example use |
|---|---|---|
| Force as text input | Always enable NICOLA input regardless of the automatic classification | Apps that are mistakenly bypassed |
| Force as bypass | Always disable the engine | Start menu, password managers |
| Force as VK output mode | Send romaji as VK keystrokes | Chrome, Edge, Electron-based apps |
| Force as TSF output mode | Send in TSF native mode | TSF-direct apps such as Windows Terminal |
You can find process names and class names in the log when you start with awase.exe --debug.
| Item | Description |
|---|---|
| n-gram file | Path to the n-gram statistics data (.csv.gz or .toml). Used in ngram_predictive mode |
| n-gram adjustment range | The range (ms) by which n-gram prediction adjusts the simultaneous-keystroke threshold |
| n-gram min/max threshold | The lower and upper bounds (ms) of the threshold adjusted by n-gram prediction |
| Focus debounce | The wait (ms) that prevents false detection during rapid Alt+Tab switching |
| IME polling interval | The period (ms) for detecting changes such as when you operate the language bar with the mouse |
| Layout directory | Path to the folder that holds the .yab files |
awase's behavior can be tuned in detail in config.toml.
The following are the default values. Add a [keys] section to config.toml to override them.
engine_on_ime_key/engine_off_ime_key (an advanced setting that force-sends an IME full-width/half-width mode key when the engine turns ON/OFF) are disabled (unset) by default. This bundles opening/closing the IME with forcing its mode into a single key, so ime_on/ime_off above is usually enough. You can enable it by adding these lines to config.toml manually.
To assign multiple keys, add them to the array: ["Ctrl+Shift+変換", "Ctrl+F8"]
A global hotkey (which works regardless of app focus) is set with engine_toggle_hotkey = "Ctrl+Shift+F12" under [general].
For the new Microsoft IME (Windows 10 20H1 or later), unicode mode is recommended. With per_key / batched, input may not be processed correctly.
Whether you install via the MSI installer or the ZIP distribution's install.ps1, auto-start at Windows logon is enabled by default with no confirmation prompt. You can turn it off from the tray icon menu or with the auto_start setting below.
Auto-start is registered in the HKCU\Software\Microsoft\Windows\CurrentVersion\Run registry key. The Startup folder is not used.
If the start menu or search bar misbehaves, add it to force_bypass.
Detects external IME state changes (e.g. the Hankaku/Zenkaku key). Not in the GUI — edit config.toml directly (most people don't need it). toggle defaults to empty. The Kanji key is already actively handled by the "IME ON/OFF toggle" setting on the Keys tab (keys.ime_toggle, default: the Kanji key) — assigning it here too would double-process the same key and break it.
These are the operations for when input misbehaves or you want to force the engine to stop.
Use this when input as a whole misbehaves — a modifier key is stuck, the IME is confused, pending characters remain, and so on.
Method 1 — tray icon (when the mouse is usable; more reliable)
Right-click the awase icon in the taskbar → "Restart process"
Fully restarts the awase process. This reliably clears any stuck state.
Method 2 — keyboard shortcut (panic reset)
Quickly enter Ctrl+Muhenkan → Ctrl+Henkan → Ctrl+Muhenkan within 2 seconds
(The IME-OFF → IME-ON → IME-OFF sequence. Repeatedly pressing the same key will not trigger it.)
What method 2 does:
On success, the tray balloon notification "State has been reset" is shown.
A last resort for forcing the NICOLA engine to stop when even the normal shortcuts do not work — for example, when the Ctrl key is stuck. It is enabled by default (already assigned to the Muhenkan key).
Operation: tap Muhenkan alone, without pressing it together with another key, three times within 400 ms
* During normal thumb-shift input, this is counted as a "thumb-key solo timeout," so the design makes it unlikely to fire accidentally during the flow of typing.
Thumb-shift layouts are defined in .yab files. You can use several layouts and switch between them.
default_layout = "nicola.yab".yab file in the folder specified by layouts_dir in config.toml (the default is config/)For details on the .yab format, see the README on GitHub.
If something misbehaves, check the logs.
awase.log in the same folder as awase.exe (appended to on each launch)%USERPROFILE%\scoop\apps\awase\current\awase.logWhen you need detailed logs, start in debug mode from a command prompt.
Alternatively, setting the environment variable RUST_LOG=debug before starting has the same effect.
You can report a bug to the developer directly from the tray icon.
report.awase.cc). It is never posted anywhere public like a GitHub IssueUninstall by selecting awase from Windows "Settings → Apps" or "Control Panel → Uninstall a program."
Run uninstall.ps1 from the extracted folder in PowerShell. By default it does not delete config.toml or your layout files (layout/) — this matches the common case of quitting and removing awase temporarily before an upgrade. To remove everything, run uninstall.ps1 -Purge instead.
Note: you do not need to run uninstall.ps1 (or manually delete the folder) before upgrading. Just unzip the new release and run install.ps1 again — your existing settings and layout files are preserved.
Recommended steps for using awase for the first time.
confirm_mode = "ngram_predictive" (recommended)"wait" (accurate but somewhat slower)"adaptive_timing"You may catch a momentary glimpse of "あ" (the throwaway-keystroke feature)
In Chrome and Windows Terminal, when you type for the first time right after the IME turns ON, "あ" may appear momentarily and immediately disappear. This is a sign that the throwaway-keystroke feature is working correctly.
In TSF apps such as Chrome, there is no official way to confirm from the outside whether the IME is ready to accept input. So awase briefly performs the operation "press the A key and delete it with BS" before the screen is drawn, and confirms that input is ready by observing whether the IME was able to convert it to "あ". Based on the information gained from this throwaway keystroke, it sends the character you actually want to type at exactly the right moment. Normally nothing appears on screen, but depending on timing, "あ" may be visible for just an instant.