This guide is for power users and extension authors who need precise control over Oppla keymaps. It complements the user-facing Key Bindings page and shows advanced patterns, context expressions, conflict resolution rules, and troubleshooting steps. If you’re new to keymaps, start with the user guide: ../configuration/key-bindings.mdx

​
Where keymaps live

  • User keymap: ~/.config/oppla/keymap.json
  • Project keymap (optional): .oppla/keymap.json (project-specific overrides)
  • Default keymaps: packaged with the app (read-only)
User keymaps merge with defaults; project keymaps take precedence for that workspace.

​
Keymap JSON schema (overview)

Keymaps are arrays of entries. Each entry can contain:
  • bindings: map of key sequences to action names or [action, args]
  • context: optional context expression (see below)
  • description: optional human-friendly description
Example: (structured example below) 
{
  "bindings": {
    "ctrl-right": "editor::SelectLargerSyntaxNode",
    "ctrl-left": "editor::SelectSmallerSyntaxNode",
    "cmd-shift-a": "ai::InlineAssist",
    "cmd-enter": "ai::AcceptSuggestion"
  }
}
Note: Use environment-appropriate modifier names (cmd- on macOS, super-/win- on Windows).

​
Key sequence syntax

  • Keys are lowercased, modifiers prefixed (e.g., cmd-, ctrl-, alt-, shift-).
  • Multi-key sequences use space separation: "cmd-k cmd-s" means press Cmd-K, then Cmd-S.
  • Double-tap: "shift shift" maps a double Shift press.
  • Special ai- modifier: maps to your platform’s AI modifier (default: cmd-shift), useful for AI-specific shortcuts.

​
Context expressions

Contexts scope bindings to specific UI states or editor modes. They follow a simple boolean expression language:
  • Basic: Editor, ProjectPanel, ai_panel_focused
  • Predicates: mode=full, extension=py
  • Logical operators: && (and), || (or), ! (not)
  • Example: Editor && mode=full && !ai_suggestion_active
Context specificity rules:
  • More specific contexts win over generic ones.
  • When multiple bindings match, the one with the most specific context expression (highest number of positive clauses) takes precedence.
  • User keymaps override defaults regardless of specificity.

​
AI-aware contexts & modifiers

Oppla introduces several AI-specific contexts and actions; keep these in mind for smooth AI UX: Common AI contexts:
  • ai_suggestion_active
  • ai_panel_focused
  • ai_refactoring
  • ai_generating
Common AI actions:
  • ai::InlineAssist
  • ai::AcceptSuggestion
  • ai::DismissSuggestion
  • ai::NextSuggestion
  • ai::PreviousSuggestion
Use contexts to avoid conflicts between regular editor bindings and AI suggestions (e.g., map tab to ai::AcceptSuggestion only in ai_suggestion_active).

​
Conflict resolution & timing

  • Prefix conflicts: If you have ctrl-w and ctrl-w left, Oppla uses a smart delay based on learned typing speed. You can configure wait time via settings.
  • User bindings override packaged defaults.
  • For ambiguous multi-key sequences, prefer explicit contexts or longer sequences to disambiguate.

​
Debugging keymaps

  • From Command Palette: dev: Open Key Context View — shows current context tree and active bindings.
  • Run “AI: Analyze Keymap Usage” after a week of usage to generate suggested remaps.
  • When bindings don’t fire:
    • Check context expression (negations and scope).
    • Ensure there are no higher-priority bindings in project or default maps.
    • Use the Key Context View to trace the evaluated contexts.

​
Best practices

  • Keep ergonomic frequency in mind: bind common actions to easily reachable keys.
  • Use ai_keymap_learning sparingly for teams; require review before applying org-wide changes.
  • Prefer sequential combos (cmd-k cmd-s) for rarely used or destructive commands.
  • Provide --dry-run or preview actions for AI-powered shortcuts that apply multi-file changes.

​
Examples

Keymap example (project-level) showing context use, AI actions, and action arguments: 
[
  {
    "description": "Editor selection helpers",
    "bindings": {
      "ctrl-right": "editor::SelectLargerSyntaxNode",
      "ctrl-left": "editor::SelectSmallerSyntaxNode"
    }
  },
  {
    "context": "Editor && ai_suggestion_active",
    "bindings": {
      "tab": "ai::AcceptSuggestion",
      "escape": "ai::DismissSuggestion",
      "cmd-right": "ai::NextSuggestion",
      "cmd-left": "ai::PreviousSuggestion"
    }
  },
  {
    "context": "ProjectPanel && not_editing",
    "bindings": {
      "o": "project_panel::Open",
      "a": "ai::AnalyzeFile"
    }
  },
  {
    "description": "AI-refactor with args and approval requirement",
    "context": "ai_refactoring && user_role=maintainer",
    "bindings": {
      "cmd-shift-r": ["ai::Refactor", { "style": "functional", "require_approval": true }]
    }
  }
]

​
Migration tips (from other editors)

  • Map common chords (VSCode ctrl-k ctrl-s) to sequential combos to preserve muscle memory.
  • Provide a compatibility base keymap in base_keymap settings and layer project overrides.
  • Audit conflicts by exporting your current keymap and running the Key Context View to surface conflicts.

​
Troubleshooting

  • After edits, restart or reload Oppla to ensure changes are applied.
  • If keys behave differently across OSes, check use_key_equivalents and platform-specific modifiers.
  • If AI accepts Tab unexpectedly, constrain tab binding to ai_suggestion_active context.

​
Further reading

  • User guide: ../configuration/key-bindings.mdx
  • Configuration reference: ../configuring-oppla.mdx
  • AI Overview & related features: ../ai/overview.mdx
If you want, I can:
  • Produce a linter that validates keymap JSON and context expressions.
  • Generate a sample migration script that converts a VSCode keybindings.json into Oppla’s format.