How input modes work

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.

NICOLA standard layout diagram

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.

Roman-kana Literal (symbols/digits) Special key Unassigned

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).

Keyboard shortcuts

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 (enabled by default for both MS-IME and Google Japanese Input; you can turn it off on the "Advanced Settings" tab)
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. If you move to another app's window while the toggle is on and then come back, awase returns the original window to kana input too, before the first key you type there (depending on the IME's key settings, it may instead leave the window in half-width alphanumeric mode and reset awase's own toggle state). Moving between windows within the same app is not covered.

Tray-icon operations

The awase icon lives in the system tray at the far right of the taskbar.

Right-click menu

  • Select layout — Lists the .yab files in layouts_dir. Selecting one switches the layout immediately
  • Settings... — Opens the Settings window
  • Clear IME-control learning cache — Deletes the per-app record of whether IMM32 can control the IME ([imm_capability] in cache.toml). Use it to recover from a mislearned entry. The keymap learning table (keymap-learn-table.json) is not deleted
  • Restart process — Fully restarts the process when input misbehaves (see "Emergency operations & reset" for details)
  • Auto-start — Enables/disables auto-start at logon (checked = enabled)
  • Restart as administrator — Restarts awase elevated via UAC. This lets it work even with apps that require administrator privileges (some games, for example)
  • Report a bug... — Sends symptoms and logs to the developer privately (see "Reporting Bugs" for details)
  • Enable/disable toggle — Toggles the engine ON/OFF (the same operation as Ctrl+Shift+F12)
  • Exit — Quits awase

Reading the icon

  • When the icon is shown normally — engine ON (thumb-shift input enabled)
  • When the icon is grayed out — engine OFF (ordinary input)

Settings window (awase-settings)

Open it by right-clicking the tray icon → "Settings...". After making changes, use the "Apply" button to save them and apply them immediately.

General Settings tab

ItemDescription
Keyboard modelChoose JIS (Japanese layout) or US (English layout)
Simultaneous-keystroke thresholdThe time window (ms) within which two keystrokes count as simultaneous. The NICOLA standard default is 100 ms
Auto-startWhether to start automatically at Windows logon
LayoutSelects the .yab layout file to use. "Rescan" refreshes the list

The confirm mode (confirm_mode) and the speculative-output wait (speculative_delay_ms) have been removed from the settings screen. Most users kept the default wait, and offering other modes there added more complexity than benefit. The n-gram tie-break (3-key branching and insufficient-overlap decisions) is always active regardless of confirm_mode. To change it, edit config.toml directly as described under "Confirm-mode options" below. The margins for 3-key branching and insufficient-overlap decisions (timing_margin_percent / min_overlap_margin_percent) can be adjusted with the sliders on the "Advanced Settings" tab.

Confirm-mode options (set manually in config.toml)

This item is currently not in the settings screen. To change it, write confirm_mode directly in the [general] section of config.toml (default: wait).

ModeBehaviorSuited for
wait (default, recommended)Holds until the timeout before committing. Most accuratePeople who want to type slowly and accurately
ngram_predictiveDynamically decides speculative vs. wait using n-gram statistics. Uses context to improve accuracyPeople who want the smartest decision

Key Settings tab

ItemDescription
Left thumb keyThe key used for the left thumb-shift key (default: VK_NONCONVERT = Muhenkan)
Right thumb keyThe key used for the right thumb-shift key (default: VK_CONVERT = Henkan)
IME ON/OFF keysThe keys awase actively sends to turn the IME ON/OFF (idempotent). Multiple entries allowed
IME ON/OFF toggleKey that flips ON⇔OFF based on the IME state at the moment it's pressed. Default: empty (follows the IME's own settings). Multiple entries allowed

The keys that switch between thumb-shift input and romaji input (formerly called the "Thumb Shift ON/OFF keys") have moved to the "Advanced Settings" tab. See "Advanced Settings tab" below for details.

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.

Manually configuring GJI dedicated Fn-key conversion

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).

[general] # Dedicated Fn key to send on a Muhenkan solo tap (default: unset — defer to auto-detection) # muhenkan_solo_tap_dedicated_fn_key = "VK_F21"

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.

Disabled Apps tab

While one of the listed apps has focus, awase is disabled entirely (it does no key conversion and no IME control; raw keys go straight to the app). Apps are specified by process name only; case and the presence or absence of .exe are ignored. Remote Desktop Connection (mstsc.exe) is listed by default. In the settings file this is disable_apps under [app_overrides].

The following settings, which override behavior per app using the combination of process name and window class name, are not in the settings screen. Set them by editing [app_overrides] in config.toml directly (see "Overriding behavior for specific windows" and "Per-app output-mode override" below).

Setting typeDescriptionExample use
Force as text inputAlways enable NICOLA input regardless of the automatic classificationApps that are mistakenly bypassed
Force as bypassAlways disable the engineStart menu, password managers
Force as VK output modeSend romaji as VK keystrokesChrome, Edge, Electron-based apps
Force as TSF output modeSend in TSF native modeTSF-direct apps such as Windows Terminal

You can find process names and class names in the log when you start with awase.exe --debug.

Advanced Settings tab

This tab collects settings you won't touch day to day.

ItemDescription
Switch to thumb-shift inputKeys that switch to thumb-shift input (NICOLA conversion) (formerly the "Thumb Shift ON key"). Multiple entries allowed
Switch to romaji inputKeys that switch to romaji input (passed through without conversion) (formerly the "Thumb Shift OFF key"). Multiple entries allowed
Switch to romaji input on five solo tapsSwitches to romaji input when the specified key is tapped alone five times in a row within 400 ms. An emergency escape for a stuck Ctrl and similar situations
Thumb-shift input / romaji input toggleA global hotkey that toggles between thumb-shift input and romaji input (formerly the "Thumb Shift-toggle hotkey"; default: Ctrl+Shift+F12)
3-key branching marginWhen three keys arrive as character → thumb → character, the boundary (%) between committing on timing alone and deciding with n-gram
Insufficient-overlap marginThe boundary (%) below which the physical overlap time of a character key and a thumb key counts as "insufficient overlap"
Disable IME input-method switching via Alt+KanaBlocks MS-IME's shortcut that switches between romaji input and JIS kana direct input (default: ON. This is a safeguard, because once the IME switches to JIS kana direct input, awase cannot switch it back)
Enable the half-width alphanumeric toggle on a left Shift solo tapA solo tap of left Shift switches to half-width alphanumeric input while keeping the IME ON (default: ON; enabled for both MS-IME and Google Japanese Input). In the settings file this is half_width_alnum_toggle under [general], which accepts "all" (default; enabled for both), "ms_ime_only" (MS-IME only; this cannot be chosen in the settings screen and only takes effect when written in the settings file), or "off" (disabled)
Enable keystroke sequencesInterprets the keystroke-sequence syntax that assigns several key operations to one .yab cell (sending Ctrl+key, multiple actions separated by + within a cell, and @ macro references) (default: ON). When OFF, the text of each cell is treated as plain characters (see "Multiple actions such as committing on punctuation (keystroke sequences)" below)
n-gram filePath to the n-gram statistics data (.csv.gz or .toml). Always used for the simultaneous-keystroke tie-break, regardless of confirm_mode
n-gram adjustment rangeThe range (ms) by which n-gram prediction adjusts the simultaneous-keystroke threshold
n-gram min/max thresholdThe lower and upper bounds (ms) of the threshold adjusted by n-gram prediction
Focus debounceThe wait (ms) that prevents false detection during rapid Alt+Tab switching
IME polling intervalThe period (ms) for detecting changes such as when you operate the language bar with the mouse
Layout directoryPath to the folder that holds the .yab files
Input-language estimation from keystrokesJudges from your first few keystrokes, right after you switch windows or after a period of inactivity, whether you are typing with thumb shift. It is meant to keep the first characters from coming out wrong in windows whose IME state awase cannot read, where awase's assumption and the actual IME state can drift apart. Choose one of the following five "behaviors":
  • Disabled
  • Record only (default) — keystrokes are handled as before; the result of the judgement is only recorded in the journal (the diagnostic record included in bug reports). Key input behavior does not change
  • In windows whose IME state can't be read, switch to hiragana if Japanese
  • In all windows, switch to hiragana if Japanese
  • In all windows, switch to hiragana if Japanese and to half-width alphanumeric if alphanumeric (works only when the half-width alphanumeric toggle is enabled)
For the three "switch to hiragana" options, the settings screen itself warns that the feature "has not yet been verified on real machines." If you run into problems, switch back to "Record only." The numbers and target apps can be adjusted under the collapsible "Details (numbers and target apps)." In the settings file these are mode ("off"/"observe"/"ime_on"/"ime_on_eisu", default "observe") and scope ("unobserved"/"all", default "unobserved") under [auto_detect]

"Input-language estimation from keystrokes" records the result of its judgement in the journal even in the default "Record only" mode. The journal is sent when you attach logs to a bug report, so if that concerns you, set it to "Disabled" or check the pre-send preview.

Key Swap tab

Swaps the positions of the keys you choose. Because it rewrites the Windows registry (Scancode Map), it works regardless of keyboard type or app. On the keyboard diagram, drag the function of the key you want to swap and drop it on the destination key (or click the two keys in turn). Besides swapping two keys, you can also create a swap that rotates three or more keys in turn (for example A→B→C→A).

OperationWhat it does
Swap key positionsOn the keyboard diagram, the upper row is the "key position (physical key)" and the buttons are the "function produced at that position." Swap them by dragging and dropping a function, or by clicking two keys in turn. JIS-only keys can only be used when the keyboard layout is JIS
Common swapsAdds "Eisu / Caps ⇄ Left Ctrl" or "Henkan ⇄ Space" with one click
Also use Eisu / Caps as CtrlLets the Eisu (CapsLock) key also work as Ctrl. The original left Ctrl key keeps working, but the Eisu key itself can no longer be used. This is a separate setting from "Swap key positions"
Apply swaps (restart required)Writes to the registry. This is separate from the window-wide "Apply" and does not save the settings file
Clear allTo undo the swaps, press "Clear all" → "Apply swaps" → restart, in that order. To undo just one swap, press "Revert" under the key ("Clear (N keys)" for a rotation of three or more)

A thumb key that also serves as the IME ON/OFF key cannot be swapped. A confirmation is shown before applying in cases such as when another tool's settings would be lost. Applying shows one administrator-privilege (UAC) prompt, and a restart is needed for the change to take effect (signing out alone is not enough; with Fast Startup enabled, shutting down may not apply it either). This setting affects the whole PC (all users) and does not work inside a Remote Desktop session. Swaps set by other tools are listed read-only, and awase does not change them.

Shortcuts tab — Muhenkan/Henkan as Space only while the IME is OFF

On the "Shortcuts" tab (shortcut remapping), you can register rules that replace a key input with another key. If you set a rule's "IME state" to "when OFF," a solo press of the Muhenkan or Henkan key can be turned into another key only while the IME is OFF (when thumb shift is not active). Pressing the "Make Muhenkan/Henkan Space while the IME is OFF" button adds two rules that turn Muhenkan and Henkan into Space. While the IME is ON, they keep working as thumb-shift keys as before. This is an opt-in feature for those who want it, and nothing is registered by default.

[[keymaps]] from = "VK_NONCONVERT" to = ["VK_SPACE"] ime = "off" [[keymaps]] from = "VK_CONVERT" to = ["VK_SPACE"] ime = "off"

The from of an ime = "off" rule can only be Muhenkan or Henkan without modifiers. Holding the key down does not repeat (one press sends it once). It does not work in the "half-width alphanumeric" state (the IME stays open, in alphanumeric mode). It does not work for a key when awase cannot read the IME's assignment (such as Microsoft IME's own key settings), or when Google Japanese Input's "Key settings" has a Direct Input row for Muhenkan/Henkan (such as inserting a space). When the IME is actually ON but awase thinks it is OFF, Muhenkan may become a Space (or, depending on the IME, a conversion or a full-width space).

IME Key Learning tab

For the IME you use, automatically goes through every supported key × state and measures how pressing each key changes the IME state. Run it if the IME-state display or the opening/closing of NICOLA input sometimes drifts from what you actually type.

OperationWhat it does
Start learningStarts the measurement. While it runs, keep the learning window in front and don't touch the keyboard (switching to another window or pressing a physical key aborts the measurement as a failure). Progress and an estimate of the remaining time are shown
CancelStops the measurement partway
Use the learned results / Run a light re-verificationShown depending on the state of the learned results

The learned results are saved in keymap-learn-table.json. They are not deleted by the tray's "Clear IME-control learning cache."

Key config.toml settings

awase's behavior can be tuned in detail in config.toml.

Customizing shortcuts

The following are the default values. Add a [keys] section to config.toml to override them.

[keys] # NICOLA engine ON (enable thumb-shift input) engine_on = ["Ctrl+Shift+変換"] # NICOLA engine OFF (switch to ordinary input) engine_off = ["Ctrl+Shift+無変換"] # IME ON (switch to hiragana input mode) ime_on = ["Ctrl+変換"] # IME OFF (switch to direct input mode) ime_off = ["Ctrl+無変換"] # IME ON/OFF toggle (flips based on the IME state at the moment it's pressed. Default: empty = follow the IME's own settings) ime_toggle = [] # Emergency: pressing Muhenkan alone three times within 400 ms turns the engine OFF. # A last resort for when Ctrl gets stuck and the shortcuts stop working. # Disable it with an empty string "" or by deleting the line. engine_off_solo_triple = "VK_NONCONVERT"

engine_on_ime_key/engine_off_ime_key (which sent an IME mode key when the engine turned ON/OFF) have been removed. They are ignored if still present in config.toml (a notice is shown at startup — delete those lines). There is no replacement (use ime_on/ime_off above to open/close the IME).

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].

Simultaneous-keystroke detection

[general] # Simultaneous-keystroke detection threshold (milliseconds). The NICOLA standard default is 100 ms. simultaneous_threshold_ms = 100 # Confirm-mode selection (default: wait. Not in the settings screen; edit config.toml by hand) # wait - hold until the timeout (most accurate, default, recommended) # ngram_predictive - dynamically switch speculative/wait with n-gram prediction # (the old speculative / two_phase / adaptive_timing were removed; if left in place awase warns and treats them as wait) confirm_mode = "wait" # Margins (%) for 3-key branching and insufficient-overlap decisions. Adjustable from the # "Advanced Settings" tab of the settings screen (default: 30 / 0). # timing_margin_percent = 30 # min_overlap_margin_percent = 0

Customizing the thumb keys

[general] # Left thumb key (VK code name) left_thumb_key = "VK_NONCONVERT" # Muhenkan key # Right thumb key (VK code name) right_thumb_key = "VK_CONVERT" # Henkan key

Keyboard model and output method

[general] # Keyboard model (the default is fine if you use a JIS keyboard) # keyboard_model = "jis" # JIS keyboard (default) # keyboard_model = "us" # US keyboard

Auto-start settings

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.

[general] # Start automatically at Windows logon # "enabled" - enable auto-start (default) # "disabled" - disable auto-start auto_start = "enabled"

Auto-start is registered in the HKCU\Software\Microsoft\Windows\CurrentVersion\Run registry key. The Startup folder is not used.

Update-check settings

When you right-click the tray icon, awase checks for the latest version and shows it in the menu if a newer one is available (you can also switch this with the "Check for updates" checkbox in the settings screen). No version, OS, or device-specific information is sent. Use the setting below if you want to turn it off, or if you deploy this file directly in an unattended rollout.

[general] # Check for the latest version when the tray icon is right-clicked # true - check (default) # false - no network communication at all update_check = true

This is a per-user setting stored in the same place as config.toml (the install directory); there is no mechanism to apply it to the whole machine at once. If you want to disable it across an organization, place the file in each user's profile, or block access to report.awase.cc on the network side (blocking it does not affect how awase works).

Overriding behavior for specific windows

[app_overrides] # Force text input in specific apps force_text = [ { process = "myapp.exe", class = "MyWindowClass" }, ] # Skip the engine entirely in specific apps force_bypass = [ { process = "SearchHost.exe", class = "SearchHost" }, ]

If the start menu or search bar misbehaves, add it to force_bypass.

Per-app output-mode override

[app_overrides] # Send as VK keystrokes (Chrome / Edge / VS Code and other Electron-based apps) force_vk = [ { process = "chrome.exe", class = "Chrome_RenderWidgetHostHWND" }, { process = "code.exe", class = "Chrome_RenderWidgetHostHWND" }, ] # Send in TSF native mode (Windows Terminal, etc.) force_tsf = [ { process = "WindowsTerminal.exe", class = "CASCADIA_HOSTING_WINDOW_CLASS" }, ]

Manually setting IME-detection keys

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, on and off all default to empty (the IME-On/IME-Off keys are followed automatically). Keys set in the "IME ON/OFF toggle" setting on the Keys tab (keys.ime_toggle, default: empty) are handled actively by awase — assigning the same key here too would double-process it and break it.

[keys.ime_detect] # Key that toggles the IME ON/OFF (default: empty. Don't set this to the # same key as "IME ON/OFF toggle" above — that causes double-processing) # toggle = ["VK_KANJI"] # Key that turns the IME directly ON (default: empty. The IME-On/IME-Off keys (VK_IME_ON/OFF) are followed automatically without listing them) # on = ["VK_DBE_HIRAGANA"] # Key that turns the IME directly OFF (default: empty) # off = ["VK_DBE_SBCSCHAR"]

Multiple actions such as committing on punctuation (keystroke sequences)

This feature lets one key perform several actions together, such as "output a character and then send a commit operation" (equivalent to Yamabuki's CV4D). It is enabled (On) by default. You can switch it with "Enable keystroke sequences" on the "Advanced Settings" tab of the settings screen.

[general] # Enable keystroke sequences # "on" - enabled (default. Interprets + separators, CV4D, and @macro references in .yab cells) # "off" - disabled (interprets the text of each cell as plain characters) keystroke_sequence = "on"

When enabled, you can line up several actions within one .yab cell by separating them with +. CV4D is the notation for Ctrl+M (a key often used to commit a conversion candidate).

[ローマ字シフト無し] '.'+CV4D,ka,ta,...

The example above defines, in a single cell, the action "output 。 and then commit with Ctrl+M." If you want to reuse the same action on several keys, you can give it a name with [[keystroke_macro]] and refer to it as @name.

[[keystroke_macro]] name = "kakko" steps = ["'('", "CV4D", "')'", "CV4D", "左"]

Existing .yab files do not break when this is enabled (cells that do not contain + are interpreted as before). However, cells written in Yamabuki style without a separator (for example .CV4D) need to be rewritten with a + inserted (.+CV4D).

Emergency operations & reset

These are the operations for when input misbehaves or you want to force the engine to stop.

Emergency reset (recommended — try this first)

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:

  • Forcibly releases any held-down Shift / Ctrl / Alt / Win state
  • Cancels the IME's uncommitted composition string
  • Reinitializes the IME state OFF → ON (hiragana input)
  • Flushes the engine's pending state (discards an uncommitted simultaneous keystroke, restores the engine-ON state)
  • Fully resets awase's internal state

On success, the tray balloon notification "State has been reset" is shown.

Force the engine OFF — triple-tap the Muhenkan key

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).

[keys] # Key that turns the engine OFF when tapped alone three times within 400 ms (default: Muhenkan) engine_off_solo_triple = "VK_NONCONVERT" # Specify an empty string to disable it # engine_off_solo_triple = ""

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.

Switching layouts (.yab)

Thumb-shift layouts are defined in .yab files. You can use several layouts and switch between them.

How to switch

  • Right-click the tray icon → Select layout — The easiest method. Switches immediately
  • Settings window "General Settings" tab — Choose from the layout dropdown → "Apply"
  • Edit config.toml — Change the default with default_layout = "nicola.yab"

Adding a custom layout

  1. Place a new .yab file in the folder specified by layouts_dir in config.toml (the default is config/)
  2. Press the "Rescan" button on the "General Settings" tab of the Settings window
  3. The new layout appears in the dropdown; select it and press "Apply"

For details on the .yab format, see the README on GitHub.

Logs & debugging

If something misbehaves, check the logs.

Log file location

  • Normal startup: awase.log in the same folder as awase.exe (appended to on each launch)
  • When installed via Scoop: %USERPROFILE%\scoop\apps\awase\current\awase.log

Start in debug mode

When you need detailed logs, start in debug mode from a command prompt.

awase.exe --debug

Alternatively, setting the environment variable RUST_LOG=debug before starting has the same effect.

Reporting Bugs

You can report a bug to the developer directly from the tray icon.

How to report

  1. Right-click the tray icon and select "Report a bug..."
  2. Choose a symptom category and, if useful, type a description
  3. You can choose what to attach with individual checkboxes. By default, everything except "List of running process names" is attached.
    • Logs (journal + awase.log)
    • Internal state snapshot
    • Config file (config.toml)
    • Layout file (.yab)
    • Conversion-decision statistics (cumulative counters only, such as the number of 3-key simultaneous-keystroke decisions; no keystroke content is included)
    • IME keymap settings (the IME ON/OFF assignments to Muhenkan/Henkan and similar keys. Includes the IME-related rows of Google Japanese Input's custom keymap and the key-effect learning results — only IME states × key numbers; no keystroke content is included)
    • List of running process names (off by default. Executable names only; folder paths are not included)
  4. The pre-send preview shows exactly what will be sent (as JSON), and you can edit it. If you're worried it might contain personal information, edit or remove it here before sending
  5. Clicking "Send" submits it to a private intake endpoint for the developer (report.awase.cc). It is never posted anywhere public like a GitHub Issue

About privacy

  • Submissions are stored in private storage and automatically deleted after roughly 90 days
  • The journal log includes your recent keystroke events (virtual key codes, etc.) verbatim. Nothing is masked, so if you were typing something sensitive, edit or remove that part in the pre-send preview before sending
  • The submission does not include your source IP address (a hashed form is used only briefly for abuse-prevention rate limiting)
  • When "Check for updates" is enabled, awase asks the awase.cc server for the latest version when you right-click the tray icon. No version, OS, or device-specific information is sent (the connecting IP address is recorded in Cloudflare's standard access logs)
  • The update-check setting is stored in each user's config.toml. There is no machine-wide opt-out mechanism

Uninstalling

MSI installer version

Uninstall by selecting awase from Windows "Settings → Apps" or "Control Panel → Uninstall a program."

Scoop version

scoop uninstall awase

ZIP version (portable)

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.

Initial setup steps

Recommended steps for using awase for the first time.

1. Confirm it is running

  • When you start awase, an icon appears in the system tray
  • Open a text editor and run an input test in Notepad or similar
  • Turn the IME ON with Ctrl+Henkan → thumb-shift input begins

2. Adjust the confirm mode (set manually in config.toml)

  • It is not in the settings screen, so edit the [general] section of config.toml directly
  • First try the default confirm_mode = "wait" (recommended; accurate but somewhat slower)
  • If the delay bothers you, try "ngram_predictive"

3. If input does not work well in Chrome / Edge

  • Confirm you are using Google Japanese Input or Microsoft IME (awase supports both IMEs)
  • Turn the IME ON with Ctrl+Henkan before you start typing
  • If only the first character comes out as an alphabetic letter, awase corrects it automatically (TSF cold-start handling)

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.

5. Resetting when the engine misbehaves

  • Explicitly turn the engine ON with Ctrl+Shift+Henkan
  • Explicitly turn the IME ON with Ctrl+Henkan
  • If that still does not resolve it, right-click the tray icon → toggle with "Enable/disable toggle"

Frequently asked questions (FAQ)

Questions we have received from users, with answers.

Which IMEs are supported?

Microsoft IME and Google Japanese Input are supported.

Mozc (the official build and mozc-readable) is treated as the same family as Google Japanese Input (automatic reading of key settings is available for Google Japanese Input only). Because mozc-readable reports the IME's open/closed state and input mode to awase using values the IME itself publishes, it is expected to be able to fix, at the root, the problem of "awase's assumption drifting from the actual IME state." It is still an experimental feature, and we are continuing to verify it on real machines.

Characters come out garbled in a consistent pattern, such as "と" becoming "から"

Most likely the IME's input method is set to "kana input" instead of "romaji input." For example, if "と" (to in romaji) is read as key positions on the JIS kana layout, it becomes "から", and "か" (ka) becomes "のち" — this symptom appears when the romaji you type is output as-is as characters on the JIS kana layout.

awase assumes romaji input. Check the IME's settings and switch the input method back to "romaji input." awase has no way to move the IME into JIS kana input, so it cannot detect and fix this state automatically.

I can only pick conversion candidates with the Space key (the thumb keys don't move to the next candidate)

By default, solo taps of the thumb keys (Henkan / Muhenkan) are always ignored to prevent IME misbehavior (both "Always ignore a solo tap of the Henkan key" and "Always ignore a solo tap of the Muhenkan key" on the "Key Settings" tab of the settings screen are enabled by default).

If you want to use thumb-key solo taps to step through conversion candidates, uncheck the option for the key you actually use as a thumb key ("Always ignore a solo tap of the Muhenkan key" if your left thumb key is Muhenkan, and "Always ignore a solo tap of the Henkan key" if your right thumb key is Henkan).

For a solo tap you have unchecked, if the IME assigns that key to IME on/off/toggle (including when you wrote it in keys.ime_on/ime_off), awase does not pass the raw key to the OS; instead it sends IME on/off just once according to the current state. While the option is checked (the default), awase never moves the IME on a solo tap.

Pressing an IME on/off key leaves the IME and NICOLA states out of sync

When you press an IME key such as Ctrl+Henkan, Ctrl+Muhenkan, Hankaku/Zenkaku, Kana, or Kanji, awase makes sure — whatever its internal state — that the actual IME state matches the meaning of the key within one press for absolute keys (IME on, IME off) and within two presses for toggle keys (a guarantee meant to eliminate the "nothing changes no matter how many times I press it" situation). The state can still drift temporarily, for example when another program operates the IME, but pressing the key again fixes it.

Known exception: with MS-IME itself + real Chrome, the IME off that awase sends may not take effect (even right after restarting awase). To turn the IME off in this combination, use a key that reaches MS-IME directly, such as the Eisu key. This guarantee is not yet supported for Windows Terminal + Google Japanese Input, or for apps that relay input to another machine, such as Remote Desktop.

The Muhenkan key misfires in the middle of a word (the kana type switches unintentionally, etc.)

Another key you meant to press simultaneously may, depending on timing, be detected as a solo tap of the Muhenkan key. If you have unchecked the option in the item above, that solo tap is sent straight to the OS / IME and causes an unintended mode switch.

Checking "Always ignore a solo tap of the Muhenkan key" (enabled by default) stops solo taps from being sent at all and prevents the misfire. Note, however, that with this setting enabled, the "step through candidates with the thumb keys" behavior in the item above is not available — the two cannot be used together.

Simultaneous keystrokes are too strict, and some characters (such as "れ") are hard to type

Try raising the "Simultaneous-keystroke threshold" (default 100 ms) on the General Settings tab a little. Adjusting it to somewhere around 150–250 ms to match your typing speed may help. If you edit config.toml directly, change simultaneous_threshold_ms.

In Chrome / Edge / Brave and similar, a different character such as "あ" flashes and disappears when typing the first character

This is normal. As a cold-start countermeasure, the "throwaway-keystroke feature" briefly sends a dummy character to check whether the IME is ready to accept input. For details, see "If input does not work well in Chrome / Edge" under "Initial setup steps." In some apps, such as text editors, the warm state is kept, so this may not happen at all.

I want to know which key symbols such as : and @ are assigned to

The "NICOLA standard layout diagram" near the top of this page shows the assignment of every key. If you want your own arrangement, you can change it in the "Layout Editor" tab of the settings screen or by editing the .yab file directly.

Things go wrong when used together with other thumb-shift software or resident IME tools

Avoid using awase together with resident software that, like awase, hooks keyboard input — such as Japanist or Yamabuki R. The conflict can make input unstable. If you are switching to awase, uninstall your existing thumb-shift software first.