HookAnchor User Guide

HookAnchor is a powerful command launcher for macOS that provides instant access to applications, files, URLs, and custom commands through a keyboard-driven popup interface.

Table of Contents

1. Installation
2. Getting Started
3. Basic Usage
4. Key Features
5. Command Types
6. Keyboard Shortcuts
7. Creating Commands
8. Tips and Tricks
9. Troubleshooting

Installation

Requirements

• macOS 11.0 or later
• A keyboard trigger method (see Setup Keyboard Trigger below)

Installation Steps

1. Download HookAnchor

   • Download the latest HookAnchor-{version}.dmg from releases

2. Install the Application

   • Open the DMG file
   • Drag HookAnchor.app to your Applications folder

3. First Launch - Bypass macOS Security

   Because HookAnchor is not signed with an Apple Developer certificate, macOS will block it on first launch. Follow these steps:

   1. Try to open HookAnchor.app from Applications (double-click)
      • You’ll see: “HookAnchor cannot be opened” with “Move to Trash” option
      • Click “Done” or “Cancel”
   2. Open System Settings:
      • Go to System Settings (or System Preferences)
      • Select Privacy & Security
      • Scroll down to the Security section
      • You should see: “HookAnchor.app was blocked from use because it is not from an identified developer”
   3. Approve the app:
      • Click “Open Anyway”
      • Try opening HookAnchor.app again
      • In the new dialog, click “Open”

   Important Notes:

   • The “Open Anyway” button only appears briefly after you try to open the app
   • If you don’t see it, try opening HookAnchor.app again, then immediately check System Settings
   • This security bypass is only needed once - after that, the app opens normally

4. Grant Permissions: Allow accessibility permissions when prompted

5. You’re Done!: Press Option+Space (⌥Space) from anywhere to open HookAnchor

6. Setup Keyboard Trigger (choose one method below - Option 1 is recommended)

Setting Up Keyboard Triggers

You can trigger HookAnchor using any of these methods:

Option 1: Built-in Global Hotkey (Simplest - No Setup Required!)

HookAnchor includes a native global hotkey system that works out of the box!

By default, HookAnchor uses Option+Space (⌥Space) to show the popup from any application.

To change the hotkey:

1. Open the configuration file:

   open ~/.config/hookanchor/config.yaml

2. Find the global_hotkey line (around line 21):

   global_hotkey: "Option+Space"

3. Change it to your preferred key combination:

   global_hotkey: "Option+`"          # Option+Backtick
   global_hotkey: "Command+Shift+Space"  # Cmd+Shift+Space
   global_hotkey: "Control+Space"     # Control+Space

4. Save the file and restart HookAnchor

Supported keys: - Modifiers: Option, Command, Control, Shift - Keys: Space, Return, Enter, , Backtick - **Format**: Use+` to combine (e.g., “Option+Space”, “Command+Shift+Return”)

Advantages: - ✅ Works from any application system-wide - ✅ No third-party software needed - ✅ No system settings to configure - ✅ Just works!

Option 2: Keyboard Maestro (Power Users)

If you use Keyboard Maestro:

1. Create a new macro
2. Set trigger to your desired key (e.g., Caps Lock, F13, or any combo)
3. Add action: Open a File, Folder or Application
4. Select: /Applications/HookAnchor.app
5. Enable “Reopen” option for instant triggering

Option 3: Karabiner-Elements (Caps Lock)

For using Caps Lock as trigger:

1. Download Karabiner-Elements

2. Install and grant permissions

3. Add this rule to use Caps Lock:

   {
     "description": "Caps Lock opens HookAnchor",
     "manipulators": [{
       "type": "basic",
       "from": { "key_code": "caps_lock" },
       "to": [{ "shell_command": "open /Applications/HookAnchor.app" }]
     }]
   }

Option 4: Other Automation Tools

HookAnchor works with any tool that can launch applications: - BetterTouchTool: Assign to gestures or keys - Alfred: Create a workflow to launch HookAnchor - Raycast: Add as a script command - Hammerspoon: Configure in Lua script

Getting Started

Triggering HookAnchor

Once you’ve set up your keyboard trigger, press your chosen key combination to open the HookAnchor popup. The popup displays a searchable list of all your commands.

Basic Navigation

• Type to search - Start typing to filter commands
• Arrow keys - Navigate through commands
• Enter - Execute selected command
• Escape - Close the popup

Basic Usage

Searching Commands

1. Press your configured trigger key to open HookAnchor
2. Start typing part of a command name
3. Matching commands appear instantly
4. Use arrow keys to select
5. Press Enter to execute

Command Organization

Commands are organized into patches (groups). When you see a command like:

Work > Project Setup

This means “Project Setup” is in the “Work” patch.

Submenus

Similar commands are automatically grouped into submenus. For example:

Git >

Pressing Enter on this opens a submenu with all Git-related commands.

Key Features

1. Universal Command Launcher

Launch anything from one place: - Applications - Websites - Folders - Shell commands - Custom scripts

2. Smart Search

• Fuzzy matching - Type “prj” to find “Project”
• Case insensitive - “TERMINAL” matches “Terminal”
• Partial matching - “doc” matches “Documents”

3. Markdown Integration

HookAnchor scans configured folders for markdown files and creates commands from: - Anchor files (markdown files matching folder names) - Code blocks in markdown - Links in markdown files

4. URL Scheme Support

Use hook:// URLs from anywhere:

open "hook://terminal"    # Opens Terminal
open "hook://slack"       # Opens Slack

5. Context Grabber

Capture context from any application: 1. Press + in the popup 2. Enter a name for the command 3. Wait for countdown 4. Click on any window/application 5. HookAnchor creates a command for it

Command Types

Keyboard Shortcuts

Creating Commands

Method 1: Using Templates

1. Open HookAnchor (your configured trigger key)
2. Press a template key (e.g., % for anchor)
3. Enter the command name
4. Edit details if needed
5. Save the command

Method 2: Using the Grabber

1. Open HookAnchor
2. Press +
3. Enter a name
4. Wait for countdown
5. Click the target window
6. Command is created automatically

Method 3: Markdown Files

Create commands in markdown files within your configured markdown_roots:

# My Commands

Terminal : app Terminal
Chrome : app Google Chrome
GitHub : url https://github.com

Method 4: Direct Configuration

Edit ~/.config/hookanchor/config.yaml to add custom functions and templates.

Tips and Tricks

Quick Access Patterns

1. Two-letter shortcuts: Name frequently used commands with 2-3 letters
   • gh → GitHub
   • tm → Terminal
   • sl → Slack
2. Patch prefixes: Use consistent prefixes for groups
   • dev-server → Development server
   • dev-build → Development build
   • dev-test → Development tests
3. Smart naming: Use descriptive but searchable names
   • Instead of: “Open”
   • Use: “Open Project Folder”

Advanced Search

• Patch search: Type patch name to see all commands in that group
• Action filter: Type action name (app, url, cmd) to filter by type
• Recent filter: Recently used commands appear first

Workflow Integration

1. Project Anchors: Create anchor commands for each project
   • Automatically opens folder
   • Can launch associated tools
   • Integrates with tmux if configured
2. URL Shortcuts: Create shortcuts for frequently visited sites
   • Work sites with work browser
   • Personal sites with personal browser
3. Script Launchers: Turn complex scripts into simple commands
   • Build processes
   • Deployment scripts
   • Testing suites

Troubleshooting

Popup Doesn’t Appear

1. Verify your keyboard trigger is properly configured:

   • macOS Shortcuts: Check System Settings → Keyboard → Keyboard Shortcuts → App Shortcuts
   • Keyboard Maestro: Ensure macro is enabled and trigger is set
   • Karabiner: Check Karabiner-Elements is running and rule is active

2. Test launching manually:

   open /Applications/HookAnchor.app

3. Check HookAnchor process is running:

   ps aux | grep HookAnchor

4. Check logs for errors:

   tail -f ~/.config/hookanchor/anchor.log

Commands Not Found

1. Check markdown_roots configuration

2. Force rescan with ` key

3. Verify file permissions

4. Check scanner is finding files:

   ha --rescan

URL Handling Issues

• HookAnchor uses a separate URLHandler app for stability

• Check URL handler registration:

  /System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -dump | grep hook:

• Should show com.hookanchor.urlhandler

Performance Issues

1. Reduce max_rows in configuration
2. Disable merge_similar if not needed
3. Increase scan_interval_seconds
4. Check log file size (auto-rotates at 10MB)

Reset Configuration

To start fresh with default configuration:

# Backup current config, then remove it to regenerate defaults
cp ~/.config/hookanchor/config.yaml ~/.config/hookanchor/config.backup.yaml && rm ~/.config/hookanchor/config.yaml
# Restart HookAnchor to load defaults

Restore from Backup

To restore commands from a previous backup:

# Copy an earlier version of commands.txt from backups folder
# This will load previous commands over the existing commands
cp ~/.config/hookanchor/backups/commands_YYYYMMDD_HHMMSS.txt ~/.config/hookanchor/commands.txt

# Or restore the cache file to replace current commands with earlier version
cp ~/.config/hookanchor/backups/cache_YYYYMMDD_HHMMSS.json ~/.config/hookanchor/commands_cache.json

Both files in the backups folder use matching timestamps, so you can restore both from the same point in time.

Getting Help

Use the CLI help system for detailed information:

ha --help              # General help and command overview
ha --help-config       # Configuration reference
ha --help-templates    # Templates and scripting guide

Additional resources: - Logs: Check ~/.config/hookanchor/anchor.log for debugging - Issues: Report bugs at https://github.com/oblinger/hookanchor/issues

Action Reference

Action types specify what kind of command to execute. These are used in command definitions to tell HookAnchor how to handle the command.