create-plugin

Create Hamr launcher plugins with proper JSON protocol, testing, and manifest structure

⭐206stars🔀3forks📁View on GitHub🕐Updated Jan 2, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill streamlines the development of Hamr launcher plugins by providing standardized templates, JSON protocol specifications, and testing frameworks. It enables developers to quickly build, test, and deploy custom workflows, search providers, and automated actions within the Hamr ecosystem using a structured manifest and handler approach.

Use Cases

  • 1. Rapid Plugin Prototyping: Quickly generate the necessary manifest.json and handler scripts to extend Hamr launcher functionality with custom triggers.
  • 2. Protocol Implementation: Ensure custom plugins correctly handle JSON-based communication over stdin/stdout for rendering results, executing commands, and displaying rich UI cards.
  • 3. Automated Testing and Validation: Utilize the built-in test-harness and mock data patterns to validate plugin behavior across different lifecycle steps like search, action, and indexing.
  • 4. Custom Search Indexing: Develop plugins that allow local files, databases, or API data to be searchable and actionable directly from the main Hamr launcher interface.
namecreate-plugin
descriptionCreate Hamr launcher plugins with proper JSON protocol, testing, and manifest structure
licenseMIT
compatibilityopencode
projecthamr
typeplugin-development

Creating Hamr Plugins

This skill helps you create plugins for the Hamr launcher. Plugins communicate via JSON over stdin/stdout.

Reference Documentation

For complete protocol details, see:

  • plugins/README.md - Full JSON protocol reference, response types, and examples
  • plugins/AGENTS.md - Condensed reference for AI agents

Plugin Structure

Simple Action (Script)

Single executable file in ~/.config/hamr/plugins/:

#!/bin/bash
notify-send "Hello!"

Multi-Step Workflow (Folder)

my-plugin/
├── manifest.json   # Plugin metadata
├── handler.py      # Main handler (executable)
└── test.sh         # Test script

manifest.json

{
  "name": "My Plugin",
  "description": "What it does",
  "icon": "material_icon_name",
  "trigger": "/myplugin"
}

Optional fields:

  • "handler": "handler.js" - Custom handler filename
  • "poll": 2000 - Auto-refresh interval in ms
  • "index": {"enabled": true} - Enable launcher indexing

Handler Template (Python)

#!/usr/bin/env python3
import json
import os
import sys

TEST_MODE = os.environ.get("HAMR_TEST_MODE") == "1"

def main():
    input_data = json.load(sys.stdin)
    step = input_data.get("step", "initial")
    query = input_data.get("query", "").strip()
    selected = input_data.get("selected", {})
    action = input_data.get("action", "")
    context = input_data.get("context", "")

    if step == "initial":
        print(json.dumps({
            "type": "results",
            "results": [
                {"id": "item1", "name": "First Item", "icon": "star"},
            ],
            "placeholder": "Search..."
        }))
        return

    if step == "search":
        # Filter based on query
        print(json.dumps({
            "type": "results",
            "results": [...],
            "inputMode": "realtime"
        }))
        return

    if step == "action":
        item_id = selected.get("id", "")
        
        if item_id == "__back__":
            # Handle back navigation
            print(json.dumps({
                "type": "results",
                "results": get_initial_results(),
                "clearInput": True
            }))
            return

        # Execute action
        print(json.dumps({
            "type": "execute",
            "execute": {
                "command": ["notify-send", f"Selected: {item_id}"],
                "close": True
            }
        }))

if __name__ == "__main__":
    main()

JSON Protocol

Input (stdin)

{
    "step": "initial|search|action|index|poll",
    "query": "user text",
    "selected": {"id": "item-id"},
    "action": "action-button-id",
    "context": "your-state",
    "session": "session-id",
    "replay": true
}

Response Types

1. results - Show list:

{
    "type": "results",
    "results": [
        {
            "id": "unique-id",
            "name": "Display Name",
            "description": "Subtitle",
            "icon": "material_icon",
            "actions": [{"id": "copy", "name": "Copy", "icon": "content_copy"}]
        }
    ],
    "inputMode": "realtime",
    "placeholder": "Search...",
    "pluginActions": [{"id": "add", "name": "Add", "icon": "add_circle"}]
}

2. execute - Run command:

{
    "type": "execute",
    "execute": {
        "command": ["xdg-open", "/path"],
        "notify": "Done",
        "close": True
    }
}

3. card - Rich content:

{
    "type": "card",
    "card": {"content": "**Markdown**", "markdown": True}
}

4. imageBrowser - Image grid:

{
    "type": "imageBrowser",
    "imageBrowser": {
        "directory": "~/Pictures",
        "title": "Select Image",
        "actions": [{"id": "set", "name": "Set", "icon": "check"}]
    }
}

5. error - Show error:

{"type": "error", "message": "Something went wrong"}

Input Modes

Mode Behavior
realtime Every keystroke triggers search
submit Only Enter triggers search

Testing

Use the test-harness:

export HAMR_TEST_MODE=1
./plugins/test-harness ./plugins/my-plugin/handler.py initial
./plugins/test-harness ./plugins/my-plugin/handler.py search --query "test"
./plugins/test-harness ./plugins/my-plugin/handler.py action --id "item1"

Test Script Template

#!/bin/bash
export HAMR_TEST_MODE=1
source "$(dirname "$0")/../test-helpers.sh"

TEST_NAME="My Plugin Tests"
HANDLER="$(dirname "$0")/handler.py"

test_initial() {
    local result=$(hamr_test initial)
    assert_type "$result" "results"
}

run_tests test_initial

Mock Data Pattern

Always check HAMR_TEST_MODE for testing:

TEST_MODE = os.environ.get("HAMR_TEST_MODE") == "1"

def get_data():
    if TEST_MODE:
        return [{"id": "mock", "name": "Mock Item"}]
    return fetch_real_data()

Plugin Indexing

Enable searchable items in main launcher:

{
  "index": {
    "enabled": true,
    "watchFiles": ["~/.config/my-data.json"]
  }
}

Handle step == "index":

if step == "index":
    print(json.dumps({
        "type": "index",
        "items": [
            {
                "id": "item1",
                "name": "Searchable Item",
                "keywords": ["alias"],
                "execute": {"command": ["xdg-open", "url"]}
            }
        ]
    }))

Common Patterns

Plugin Actions (Toolbar)

"pluginActions": [
    {"id": "add", "name": "Add", "icon": "add_circle"},
    {"id": "wipe", "name": "Wipe", "icon": "delete_sweep", "confirm": "Are you sure?"}
]

Handle with selected.get("id") == "__plugin__".

Context for State

# Set context
{"type": "results", "context": "__edit__:item1", "inputMode": "submit"}

# Read context in search
if context.startswith("__edit__:"):
    item_id = context.split(":")[1]

History Tracking

{
    "type": "execute",
    "execute": {
        "command": ["xdg-open", url],
        "name": "Open Example",  # Required for history
        "icon": "link",
        "close": True
    }
}

Icon Types

  • Material (default): star, folder, content_copy
  • System: Set "iconType": "system" for desktop app icons

Development Workflow

  1. Create manifest.json with name, description, icon
  2. Create handler.py with shebang, make executable
  3. Test with HAMR_TEST_MODE=1 ./plugins/test-harness
  4. Add mock data for test mode
  5. Create test.sh for CI
  6. Plugin auto-loads on file save