ContextKeys

ContextKeys

ContextKeys lets one keyboard key or mouse button perform different actions depending on what you are doing in Minecraft. It works with standard actions from Minecraft and installed Fabric mods.

First setup

Before opening ContextKeys for the first time:

1. Open Options → Controls → Key Binds.
2. Find Open ContextKeys.
3. Assign a key to it.
4. Enter a world and press that key to open the editor.

The binding starts unassigned so ContextKeys does not take over an existing control.

Smart Keys

A Smart Key is a keyboard key, mouse button, or modifier combination managed by ContextKeys.

To create one:

1. Open ContextKeys.
2. Select Create Smart Key.
3. Press the key or mouse button you want to use.
4. Add one or more rules.
5. Choose a fallback for situations where no rule matches.

Smart Keys can be enabled, disabled, or deleted at any time.

Rules

Each rule follows a simple structure:

WHEN all selected conditions match, run this action.

Rules are checked from top to bottom. The first matching enabled rule wins, and only its action runs. Use Up and Down to change rule priority.

A rule without conditions always matches, so it is useful as a general action at the bottom of the list. Rules can also be disabled without deleting them.

Conditions

Rules can check:

1. The exact item, namespace, or item tag in your main hand.
2. The exact item, namespace, or item tag in your off hand.
3. Whether you are sneaking.
4. The exact block or block tag you are looking at.
5. The entity type you are looking at.
6. Whether you are riding anything.
7. The exact entity type you are riding.
8. Whether normal gameplay is active with no screen open.
9. Whether one specific screen is open.

All conditions in one rule must match.

Select Use Current Context to create conditions from what ContextKeys currently observes, such as your held item, targeted block, targeted entity, riding state, sneaking state, or open screen. You choose which suggested facts to add.

You can also select Condition to enter a condition manually.

Actions

ContextKeys discovers normal key actions registered by Minecraft and installed Fabric mods.

You can search for an action by its name, category, origin, translation key, or current binding.

Select Learn Action when you know the assigned key but not the action name. Press that assigned key, then choose from the matching actions.

ContextKeys targets only the selected action. Other actions sharing the same original binding are not intentionally triggered with it.

Action modes

Every selected key action can use one of three modes.

AUTO uses the safe default behavior and performs one activation.

PRESS performs exactly one activation. Use it for actions such as dropping an item, opening a screen, changing perspective, or swapping hands.

HOLD activates the action and keeps it held until you release the Smart Key. Use it for actions that depend on a held control, such as certain zoom or movement related mod actions.

When HOLD begins, ContextKeys keeps the selected action locked until release. Changing items or context while holding the Smart Key does not switch to another rule.

Fallback

The fallback runs when no rule matches.

You can choose:

1. Original Input to preserve the normal behavior of the Smart Key.
2. Do Nothing to suppress the input.
3. Another discovered key action.

Original Input is usually the best choice when you want the key to behave normally outside your configured situations.

Conflicts

The Conflicts screen finds physical bindings currently shared by multiple Minecraft actions.

Select a conflict to create a Smart Key with disabled rule candidates for those actions. You can then enable the actions you want, add conditions, and arrange their priority.

HUD

Enable the HUD to see which action currently wins for each Smart Key.

The At button cycles through four positions:

1. TL means top left.
2. TR means top right.
3. BL means bottom left.
4. BR means bottom right.

The HUD uses the same rule evaluation as actual input handling.

Debug mode

Enable Debug when a rule does not behave as expected.

The debug display shows the latest Smart Key input, relevant context information, rule results, the winning action, and the selected dispatch mode.

Saving, export, and import

Changes are saved automatically to config/contextkeys.json. Smart Keys, rule order, conditions, actions, modes, fallback choices, enabled states, HUD settings, and the selected HUD position persist after restarting Minecraft.

Export writes a readable copy to config/contextkeys-export.json.

Import loads config/contextkeys-import.json. The file is validated before it replaces the active configuration. If importing fails, the current configuration is preserved.

Missing actions or references remain visible with warnings instead of crashing or silently deleting your setup.

Safe input handling

ContextKeys preserves normal typing in focused text fields such as chat, commands, signs, books, anvil names, and search boxes.

Held actions are released when appropriate, including after releasing the Smart Key, changing screens, losing window focus, disconnecting, changing the configuration, disabling or deleting the relevant setup, or closing the client.