rethocker 0.2.1 → 0.2.2

package/README.md

@@ -1,8 +1,27 @@
-# rethocker
-
-Global key interception and remapping for macOS. Intercept any key or combo system-wide, remap keys, fire shell commands, react to key sequences, and scope rules to specific apps — all from TypeScript.
-
-Requires **macOS 13+** and **Accessibility permission** (prompted automatically on first run).
+<p align="center">
+  <img src="src/assets/logo.png" width="280px" align="center" alt="rethocker logo" />
+  <h1 align="center">rethocker</h1>
+  <p align="center">
+    System-wide key interception and remapping for macOS, in TypeScript.
+  </p>
+</p>
+
+<!--- badges -->
+<p align="center">
+  <a href="https://github.com/benjamine/rethocker/actions?query=branch%3Amain"><img src="https://github.com/benjamine/rethocker/actions/workflows/publish.yml/badge.svg?branch=main" alt="rethocker CI status" /></a>
+  <a href="https://twitter.com/beneidel" rel="nofollow"><img src="https://img.shields.io/badge/created%20by-@beneidel-BACABA.svg" alt="Created by Benjamin Eidelman"></a>
+  <a href="https://opensource.org/licenses/MIT" rel="nofollow"><img src="https://img.shields.io/github/license/benjamine/rethocker" alt="License"></a>
+  <a href="https://www.npmjs.com/package/rethocker" rel="nofollow"><img src="https://img.shields.io/npm/dw/rethocker.svg" alt="npm"></a>
+  <a href="https://github.com/benjamine/rethocker" rel="nofollow"><img src="https://img.shields.io/github/stars/benjamine/rethocker" alt="stars"></a>
+</p>
+
+---
+
+- Requires **macOS 13+** and **Accessibility permission** (prompted automatically on first run).
+- Built with a native daemon for low-latency key interception, and a TypeScript API for maximum flexibility and AI agent friendliness.
+- Intercept any key or key chord, with per-app scoping and advanced conditions.
+- Remap to other keys, execute shell commands, or call TypeScript handlers with full access to the API.
+- Bundled with convenient actions for common macOS tasks like window management, media control, etc..
 
 ## Install
 
@@ -14,7 +33,7 @@ brew install rethocker
 rethocker install
 ```
 
-`rethocker install` scaffolds `~/.config/rethocker/default.ts` and registers a LaunchAgent that starts on login and auto-reloads whenever you save the file.
+`rethocker install` scaffolds `~/.config/rethocker/default.ts` (where you write your own rules) and registers a LaunchAgent that starts on login and auto-reloads whenever you save the file.
 
 ```bash
 rethocker log      # live key monitor — see what rethocker captures
@@ -34,6 +53,8 @@ bun add rethocker
 ## Usage
 
 ```ts
+#!/usr/bin/env bun
+
 import { actions, Key, rethocker } from "rethocker"
 
 const rk = rethocker([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rethocker",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Intercept and remap global keys on macOS — with per-app and key-sequence support",
   "type": "module",
   "main": "src/index.ts",

package/src/cli.ts

@@ -183,26 +183,44 @@ async function cmdRunConfig(configFile: string) {
 
 // ─── Help ─────────────────────────────────────────────────────────────────────
 
-const HELP = `
-Usage: rethocker <command>
-
-Commands:
-  install     Scaffold a config file and set up a background agent that
-              starts on login and auto-reloads when the config is saved
-  uninstall   Stop the background agent and remove it (keeps your config)
-  restart     Restart the background agent
-  status      Show whether the background agent is running
-  log         Live key monitor — shows keypresses in rethocker rule syntax
-              so you can copy-paste them directly into your config
-  help        Print this help message
-
-Install via Homebrew:
-  brew tap benjamine/tap
-  brew install rethocker
-  rethocker install
+function buildHelp() {
+  const lines = [
+    "Usage: rethocker <command>",
+    "",
+    "Commands:",
+    "  install     Scaffold a config file and set up a background agent that",
+    "              starts on login and auto-reloads when the config is saved",
+    "  uninstall   Stop the background agent and remove it (keeps your config)",
+    "  restart     Restart the background agent",
+    "  status      Show whether the background agent is running",
+    "  log         Live key monitor — shows keypresses in rethocker rule syntax",
+    "              so you can copy-paste them directly into your config",
+    "  help        Print this help message",
+    "",
+  ];
+
+  if (existsSync(PLIST_FILE)) {
+    const result = run([
+      "launchctl",
+      "print",
+      `${AGENT_DOMAIN}/${AGENT_LABEL}`,
+    ]);
+    const running = result.ok;
+    lines.push(
+      `Config: ${tildeify(CONFIG_FILE)} (your rethocker rules are here)`,
+    );
+    lines.push(`Status: ${running ? "running" : "not running"}`);
+    if (!running)
+      lines.push('Run "rethocker restart" to start the background agent.');
+  } else {
+    lines.push(
+      `Config: ${tildeify(CONFIG_FILE)} (not found — run "rethocker install")`,
+    );
+  }
 
-Docs: ${GITHUB}
-`.trim();
+  lines.push("", `Docs: ${GITHUB}`);
+  return lines.join("\n");
+}
 
 // ─── Command dispatch ─────────────────────────────────────────────────────────
 
@@ -240,12 +258,12 @@ switch (subcommand) {
   case "help":
   case "--help":
   case "-h":
-    console.log(HELP);
+    console.log(buildHelp());
     break;
 
   default:
     if (subcommand) console.error(`Unknown command: "${subcommand}"\n`);
-    console.log(HELP);
+    console.log(buildHelp());
     process.exit(subcommand ? 1 : 0);
 }