Vim Leader Key - Keyboard Shortcut Sequences

A Vim-style keyboard shortcut sequences extension for Raycast that enables quick navigation through hierarchical menus using single keystrokes. Organize your apps, commands, and shortcuts into logical groups for lightning-fast access.

Features

🗂️ Hierarchical Organization

• Nested Groups: Create folders to organize related actions
• Single-Key Navigation: Navigate with individual keystrokes (no chord combinations)
• Breadcrumb Navigation: Visual indication of your current location
• Auto-Reset: Configurable timeout to return to root menu

🚀 Action Types

• Applications: Launch apps with file-based or name-based targeting
• URLs: Open websites or Raycast deeplinks
• Folders: Open directories in file manager
• Commands: Execute shell commands

🌐 Browser Selection

• Group-level default: Set a default browser for all URLs in a group
• Per-URL override: Override the group default on individual URL actions
• System default fallback: Uses your OS default browser when no preference is set
• Resolution order: action browser > parent group browser > system default

⚙️ Configuration Management

• Import/Export: Share configurations via JSON files
• Legacy Migration: Automatic upgrade from flat key sequences
• Conflict Detection: Prevents duplicate keys within groups
• Visual Editor: Intuitive forms for adding and editing items
• Quick Capture: Turn your current browser tab, selected Finder item, URL/path text, clipboard URL/path, or frontmost app into a shortcut

🎯 Smart UI/UX

• Type-based Grouping: Items organized by type for easy scanning
• Keyboard Layout Mode: Toggle a compact current-group keyboard map in the detail pane
• Dynamic Icons: App-specific icons and contextual indicators
• Real-time Search: Type to navigate, with context-aware hints
• Comprehensive Actions: Edit, delete, add, and navigate with keyboard shortcuts

Quick Start

1. Install the extension in Raycast
2. Run Leader Key command
3. Press any key to see available actions
4. Use ⌘N to add new actions or ⌘⇧N to add groups
5. Run Quick Capture to add the current app, URL, or folder with a prefilled form

Default Configuration

The extension comes with a platform-aware starter config:

a → Applications/
  ├── b → Browser (Safari / Edge)
  ├── t → Terminal (Terminal.app / Command Prompt)
  ├── f → File Manager (Finder / Explorer)
  ├── c → Calculator
  └── n → Notes (Notes.app / Notepad)
u → URLs/
  ├── g → Google
  └── h → GitHub

Usage Examples

Simple Actions

• Press a then b to open your browser
• Press u then g to open Google

Creating Groups

1. Press ⌘⇧N to create a new group
2. Set a key (e.g., d for "Dev Tools")
3. Add actions to the group using ⌘N

Action Types

Applications:

• Use app bundle paths: /Applications/Visual Studio Code.app
• Or simple names: Visual Studio Code

URLs:

• Websites: https://github.com
• Raycast deeplinks: raycast://extensions/raycast/system/quit-all-applications
• Optionally set a specific browser via the "Open With" dropdown

Commands:

• Shell scripts: open ~/Downloads
• Complex commands: git status && git pull

Quick Capture

Run Quick Capture to detect the current context and create a prefilled shortcut. It tries the active browser tab first when the Raycast Browser Extension is available, then selected Finder items, selected text, clipboard text, and finally the frontmost application. You can edit the label, key, type, value, and destination group before saving.

Configuration

Preferences

• Auto-Reset Timeout: Enable/disable automatic return to root
• Timeout Duration: Set timeout between 2.5-6 seconds
• Open URLs in Active Browser: Open URL shortcuts in the browser behind Raycast when it can open web URLs, with existing configured/default browser behavior as fallback

Import/Export

1. Export: Use Export Config command to save your setup
2. Import: Use Import Config command to load shared configurations
3. Share: JSON files are compatible across installations

JSON Format

{
  "type": "group",
  "actions": [
    {
      "key": "u",
      "type": "group",
      "label": "URLs",
      "browser": "/Applications/Google Chrome.app",
      "actions": [
        {
          "key": "g",
          "type": "url",
          "label": "Google",
          "value": "https://google.com"
        },
        {
          "key": "h",
          "type": "url",
          "label": "GitHub",
          "value": "https://github.com",
          "browser": "/Applications/Firefox.app"
        }
      ]
    },
    {
      "key": "c",
      "type": "application",
      "label": "Calculator",
      "value": "/System/Applications/Calculator.app"
    }
  ]
}

In this example, Google opens in Chrome (group default), while GitHub opens in Firefox (per-action override).

Keyboard Shortcuts

Navigation

• Any Key: Navigate to action or group
• Backspace: Go back one Leader Key group when the search bar has no visible text
• Escape: Follows Raycast's native behavior
• Tab: Enter or exit Leader Key search mode
• ⌘⇧K: Toggle dual-column keyboard layout mode

Management

• ⌘N: Add new action
• ⌘⇧N: Add new group
• ⌘E: Edit current item
• ⌘⌫: Delete current item
• ⌘C: Copy action value

Migration from v1

If you used the previous version with flat key sequences, your configuration will be automatically migrated to the new hierarchical format. Multi-character sequences like ac become nested structures (a → c).

Tips & Best Practices

Organization Strategies

• By Category: Group similar apps (dev/, media/, utils/)
• By Frequency: Put most-used items at root level
• By Workflow: Create project-specific groups

Key Selection

• Use mnemonic keys (c for Calculator, t for Terminal)
• Keep frequently used actions on single keystrokes
• Use logical groupings (a for Applications, u for URLs)

Performance

• The extension has minimal startup time
• Nested navigation is instant
• Large configurations (100+ items) perform well

Troubleshooting

Actions not working?

• Check file paths for applications
• Verify URLs are complete and valid
• Test shell commands in Terminal first

Keys not responding?

• Clear configuration and rebuild if migration failed
• Check for key conflicts within groups
• Ensure timeout isn't too short

Import/Export issues?

• Validate JSON format
• Check that all required fields are present
• Use Export to see proper format

Inspiration & Compatibility

This Raycast extension was inspired by mikker's Leader Key app for macOS. The JSON configuration format is designed to be compatible, allowing easy migration and sharing of configurations between both tools.

While this extension brings the leader key concept to Raycast with additional features like real-time navigation and Raycast-specific integrations, it maintains the same hierarchical philosophy that makes mikker's original app so effective.

Contributing

This extension is part of the Raycast ecosystem. For issues or feature requests, please check the repository or contact the maintainer.

License

MIT