claudecode-omc 4.4.5 → 4.4.6

package/skills/configure-openclaw/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: configure-openclaw
+description: Configure OpenClaw gateway integration for waking external automations and AI agents on hook events
+triggers:
+  - "configure openclaw"
+  - "setup openclaw"
+  - "openclaw gateway"
+  - "openclaw setup"
+---
+
+# Configure OpenClaw
+
+Set up OpenClaw so OMC can wake external gateways — triggering automations, workflows, or AI agents — when hook events fire during Claude sessions.
+
+OpenClaw is NOT a notification system. It sends structured instruction payloads to programmable HTTPS endpoints. This makes it ideal for triggering n8n workflows, custom AI agents, webhook automations, or any HTTPS-capable system.
+
+---
+
+## How This Skill Works
+
+This is an interactive, natural-language configuration skill. Walk the user through setup by asking questions with AskUserQuestion. Write the result to `~/.claude/omc_config.openclaw.json`.
+
+---
+
+## Step 1: Detect Existing Configuration
+
+```bash
+CONFIG_FILE="${OMC_OPENCLAW_CONFIG:-$HOME/.claude/omc_config.openclaw.json}"
+
+if [ -f "$CONFIG_FILE" ]; then
+  IS_ENABLED=$(jq -r '.enabled // false' "$CONFIG_FILE" 2>/dev/null)
+  GATEWAY_COUNT=$(jq -r '.gateways | keys | length' "$CONFIG_FILE" 2>/dev/null)
+  HOOK_COUNT=$(jq -r '[.hooks | to_entries[] | select(.value.enabled == true)] | length' "$CONFIG_FILE" 2>/dev/null)
+
+  if [ "$IS_ENABLED" = "true" ]; then
+    echo "EXISTING_CONFIG=true"
+    echo "GATEWAY_COUNT=$GATEWAY_COUNT"
+    echo "HOOK_COUNT=$HOOK_COUNT"
+  else
+    echo "EXISTING_CONFIG=false"
+  fi
+else
+  echo "NO_CONFIG_FILE"
+fi
+```
+
+If existing config is found, show the user what's currently configured and ask if they want to update or reconfigure.
+
+---
+
+## Step 2: Collect Gateway URL
+
+Use AskUserQuestion:
+
+**Question:** "What is your OpenClaw gateway URL? (Must be HTTPS, e.g. https://my-gateway.example.com/wake)"
+
+The user will type their URL in the "Other" field.
+
+**Validate** the URL:
+- Must start with `https://`
+- Must be a valid URL
+- If invalid, explain the requirement and ask again
+
+---
+
+## Step 3: Collect Auth Header (Optional)
+
+Use AskUserQuestion:
+
+**Question:** "Does your gateway require an Authorization header?"
+
+**Options:**
+1. **Yes, Bearer token** - I'll provide a Bearer token (e.g., `Bearer sk-...`)
+2. **Yes, custom header value** - I'll type the full header value
+3. **No auth required** - The gateway is open or uses a different auth method
+
+If user selects option 1 or 2, ask:
+
+**Question:** "Paste your Authorization header value (e.g., `Bearer sk-mytoken123`)"
+
+The user will type the value in the "Other" field.
+
+---
+
+## Step 4: Configure Hook Events
+
+Use AskUserQuestion with multiSelect:
+
+**Question:** "Which hook events should trigger your OpenClaw gateway?"
+
+**Options (multiSelect: true):**
+1. **session-start** - When a new Claude session begins. Variables: `{{sessionId}}`, `{{projectName}}`, `{{projectPath}}`
+2. **session-end** - When a session ends. Variables: `{{contextSummary}}`, `{{reason}}`, `{{sessionId}}`
+3. **stop** - When Claude stops (idle/completion). Variables: `{{sessionId}}`, `{{projectName}}`
+4. **pre-tool-use** - Before each tool call (high frequency). Variables: `{{toolName}}`, `{{sessionId}}`
+5. **post-tool-use** - After each tool call (high frequency). Variables: `{{toolName}}`, `{{sessionId}}`
+6. **keyword-detector** - On every prompt submission. Variables: `{{prompt}}`, `{{sessionId}}`
+7. **ask-user-question** - When Claude needs user input. Variables: `{{question}}`, `{{sessionId}}`
+
+Default selection: session-start, session-end, stop.
+
+**Note:** pre-tool-use, post-tool-use, and keyword-detector fire very frequently. Only enable them if your gateway can handle the volume.
+
+---
+
+## Step 5: Collect Instruction Templates
+
+For each selected event, ask the user for an instruction template. Show the available template variables for that event type.
+
+Use AskUserQuestion for each event:
+
+**Example for session-start:**
+
+**Question:** "Instruction template for `session-start` events. Available variables: `{{sessionId}}`, `{{projectName}}`, `{{projectPath}}`, `{{timestamp}}`"
+
+**Options:**
+1. **Use default** - "Session started for project {{projectName}}"
+2. **Custom** - Enter my own instruction text
+
+**Example for session-end:**
+
+**Question:** "Instruction template for `session-end` events. Available variables: `{{sessionId}}`, `{{projectName}}`, `{{contextSummary}}`, `{{reason}}`, `{{timestamp}}`"
+
+**Options:**
+1. **Use default** - "Session ended. Summary: {{contextSummary}}"
+2. **Custom** - Enter my own instruction text
+
+**Example for stop:**
+
+**Question:** "Instruction template for `stop` events. Available variables: `{{sessionId}}`, `{{projectName}}`, `{{projectPath}}`, `{{timestamp}}`"
+
+**Options:**
+1. **Use default** - "Session stopping for project {{projectName}}"
+2. **Custom** - Enter my own instruction text
+
+**Example for pre-tool-use:**
+
+**Question:** "Instruction template for `pre-tool-use` events. Available variables: `{{toolName}}`, `{{sessionId}}`, `{{projectName}}`, `{{timestamp}}`"
+
+**Options:**
+1. **Use default** - "Tool {{toolName}} about to be used"
+2. **Custom** - Enter my own instruction text
+
+**Example for post-tool-use:**
+
+**Question:** "Instruction template for `post-tool-use` events. Available variables: `{{toolName}}`, `{{sessionId}}`, `{{projectName}}`, `{{timestamp}}`"
+
+**Options:**
+1. **Use default** - "Tool {{toolName}} completed"
+2. **Custom** - Enter my own instruction text
+
+**Example for keyword-detector:**
+
+**Question:** "Instruction template for `keyword-detector` events. Available variables: `{{prompt}}`, `{{sessionId}}`, `{{projectName}}`, `{{timestamp}}`"
+
+**Options:**
+1. **Use default** - "Keyword detected: {{prompt}}"
+2. **Custom** - Enter my own instruction text
+
+**Example for ask-user-question:**
+
+**Question:** "Instruction template for `ask-user-question` events. Available variables: `{{question}}`, `{{sessionId}}`, `{{projectName}}`, `{{timestamp}}`"
+
+**Options:**
+1. **Use default** - "User input requested: {{question}}"
+2. **Custom** - Enter my own instruction text
+
+---
+
+## Step 6: Write Configuration
+
+Build and write the config to `~/.claude/omc_config.openclaw.json`:
+
+```bash
+CONFIG_FILE="${OMC_OPENCLAW_CONFIG:-$HOME/.claude/omc_config.openclaw.json}"
+mkdir -p "$(dirname "$CONFIG_FILE")"
+
+# GATEWAY_URL, AUTH_HEADER, and per-event instructions are collected from user
+# SELECTED_EVENTS is the list of enabled hook events
+# Build the JSON using jq
+
+# Example: session-start and session-end selected, bearer auth
+jq -n \
+  --arg gateway_url "$GATEWAY_URL" \
+  --arg auth_header "$AUTH_HEADER" \
+  --arg session_start_instruction "$SESSION_START_INSTRUCTION" \
+  --arg session_end_instruction "$SESSION_END_INSTRUCTION" \
+  --arg stop_instruction "$STOP_INSTRUCTION" \
+  '{
+    enabled: true,
+    gateways: {
+      "my-gateway": {
+        url: $gateway_url,
+        headers: (if $auth_header != "" then {"Authorization": $auth_header} else {} end),
+        method: "POST",
+        timeout: 10000
+      }
+    },
+    hooks: {
+      "session-start": {gateway: "my-gateway", instruction: $session_start_instruction, enabled: true},
+      "session-end": {gateway: "my-gateway", instruction: $session_end_instruction, enabled: true},
+      "stop": {gateway: "my-gateway", instruction: $stop_instruction, enabled: true}
+    }
+  }' > "$CONFIG_FILE"
+```
+
+Adjust the hooks object to include only the events the user selected, with their chosen instructions.
+
+---
+
+## Step 7: Test the Gateway
+
+After writing config, offer to send a test wake call:
+
+Use AskUserQuestion:
+
+**Question:** "Send a test wake call to your gateway to verify the connection?"
+
+**Options:**
+1. **Yes, test now (Recommended)** - Send a test HTTP POST to the gateway
+2. **No, I'll test later** - Skip testing
+
+If testing:
+
+```bash
+GATEWAY_URL="USER_PROVIDED_URL"
+AUTH_HEADER="USER_PROVIDED_AUTH_HEADER"  # may be empty
+
+# Build auth header arg
+AUTH_ARG=""
+if [ -n "$AUTH_HEADER" ]; then
+  AUTH_ARG="-H \"Authorization: $AUTH_HEADER\""
+fi
+
+RESPONSE=$(eval curl -s -w "\n%{http_code}" \
+  -H "Content-Type: application/json" \
+  $AUTH_ARG \
+  -d '{"event":"session-start","instruction":"OpenClaw test wake from OMC configure wizard","timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","context":{}}' \
+  "$GATEWAY_URL")
+
+HTTP_CODE=$(echo "$RESPONSE" | tail -1)
+BODY=$(echo "$RESPONSE" | head -1)
+
+if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "201" ] || [ "$HTTP_CODE" = "202" ] || [ "$HTTP_CODE" = "204" ]; then
+  echo "Test wake succeeded (HTTP $HTTP_CODE)!"
+else
+  echo "Test wake failed (HTTP $HTTP_CODE):"
+  echo "$BODY"
+fi
+```
+
+Report success or failure. Common issues:
+- **401 Unauthorized**: Auth header is missing or incorrect
+- **403 Forbidden**: Token does not have permission
+- **404 Not Found**: Gateway URL path is incorrect
+- **SSL error**: URL must be HTTPS with a valid certificate
+- **Connection refused**: Gateway is not running or URL is wrong
+
+---
+
+## Step 8: Confirm
+
+Display the final configuration summary:
+
+```
+OpenClaw Gateway Configured!
+
+  Gateway:  https://my-gateway.example.com/wake
+  Auth:     Bearer *** (configured)
+  Events:   session-start, session-end, stop
+
+Config saved to: ~/.claude/omc_config.openclaw.json
+
+To activate OpenClaw, use one of:
+  omc --openclaw                  (per-session flag)
+  export OMC_OPENCLAW=1           (environment variable)
+
+Debug logging:
+  export OMC_OPENCLAW_DEBUG=1     (logs wake results to stderr)
+
+Custom config path:
+  export OMC_OPENCLAW_CONFIG=/path/to/config.json
+
+To reconfigure: /oh-my-claudecode:configure-openclaw
+```
+
+---
+
+## Template Variables Reference
+
+| Event | Available Variables |
+|-------|-------------------|
+| `session-start` | `{{sessionId}}`, `{{projectPath}}`, `{{projectName}}`, `{{timestamp}}`, `{{event}}` |
+| `session-end` | `{{sessionId}}`, `{{projectPath}}`, `{{projectName}}`, `{{contextSummary}}`, `{{reason}}`, `{{timestamp}}`, `{{event}}` |
+| `pre-tool-use` | `{{sessionId}}`, `{{projectPath}}`, `{{projectName}}`, `{{toolName}}`, `{{timestamp}}`, `{{event}}` |
+| `post-tool-use` | `{{sessionId}}`, `{{projectPath}}`, `{{projectName}}`, `{{toolName}}`, `{{timestamp}}`, `{{event}}` |
+| `stop` | `{{sessionId}}`, `{{projectPath}}`, `{{projectName}}`, `{{timestamp}}`, `{{event}}` |
+| `keyword-detector` | `{{sessionId}}`, `{{projectPath}}`, `{{projectName}}`, `{{prompt}}`, `{{timestamp}}`, `{{event}}` |
+| `ask-user-question` | `{{sessionId}}`, `{{projectPath}}`, `{{projectName}}`, `{{question}}`, `{{timestamp}}`, `{{event}}` |
+
+Unresolved variables (e.g., `{{unknown}}`) are left as-is in the instruction text.
+
+---
+
+## Environment Variable Alternative
+
+Users can skip this wizard entirely by setting env vars and writing the config manually:
+
+```bash
+# Enable OpenClaw
+export OMC_OPENCLAW=1
+
+# Optional: override config file path
+export OMC_OPENCLAW_CONFIG="$HOME/.claude/omc_config.openclaw.json"
+
+# Optional: enable debug logging
+export OMC_OPENCLAW_DEBUG=1
+```
+
+The config file path defaults to `~/.claude/omc_config.openclaw.json`. Use `OMC_OPENCLAW_CONFIG` to override.

package/skills/external-context/SKILL.md

@@ -1,17 +1,12 @@
 ---
 name: external-context
-description: Invoke Gemini MCP (preferred) or parallel document-specialist agents for external web searches and documentation lookup
+description: Invoke parallel document-specialist agents for external web searches and documentation lookup
 argument-hint: <search query or topic>
 ---
 
 # External Context Skill
 
-Fetch external documentation, references, and context for a query. Uses Gemini MCP as the preferred path (single call, 1M context window); falls back to parallel document-specialist Claude agents when MCP is unavailable.
-
-## Overview
-
-1. **Preferred: Gemini MCP** - Single `ask_gemini` call with `agent_role="document-specialist"` handles multi-facet synthesis in one shot
-2. **Fallback: Parallel agents** - Decompose into 2-5 facets, spawn parallel document-specialist Claude agents
+Fetch external documentation, references, and context for a query. Decomposes into 2-5 facets and spawns parallel document-specialist Claude agents.
 
 ## Usage
 
@@ -29,75 +24,7 @@ Fetch external documentation, references, and context for a query. Uses Gemini M
 
 ## Protocol
 
-### Step 0: Discover MCP Tools
-
-Before first MCP use, call `ToolSearch("mcp")` to discover deferred MCP tools. If results include `ask_gemini`, use the Preferred path. If no MCP tools are found, use the Fallback path.
-
----
-
-### Preferred Path: Gemini MCP
-
-**When:** `ToolSearch("mcp")` returns `ask_gemini`.
-
-1. Write the query to a prompt file:
-
-```
-.omc/prompts/ext-context-{timestamp}.md
-```
-
-Prompt file contents:
-
-```markdown
-Search the web for external documentation, examples, and references on the following query:
-
-**Query:** <original query>
-
-Cover all relevant facets (up to 5). For each facet:
-- Cite all sources with URLs
-- Summarize key findings
-- Note any version/date caveats
-
-Output format:
-## External Context: <query>
-
-### Key Findings
-1. **<finding>** - Source: [title](url)
-
-### Detailed Results
-
-#### Facet 1: <name>
-<aggregated findings with citations>
-
-### Sources
-- [Source 1](url)
-```
-
-2. Call `ask_gemini` with background execution:
-
-```python
-ask_gemini(
-    agent_role="document-specialist",
-    prompt_file=".omc/prompts/ext-context-{timestamp}.md",
-    output_file=".omc/prompts/ext-context-{timestamp}-output.md",
-    background=True
-)
-```
-
-3. Wait for completion:
-
-```python
-wait_for_job(job_id=<returned job id>)
-```
-
-4. Read the output file and present synthesized results to the user.
-
----
-
-### Fallback Path: Parallel Document-Specialist Agents
-
-**When:** `ToolSearch("mcp")` returns no MCP tools (Gemini unavailable).
-
-#### Facet Decomposition
+### Step 1: Facet Decomposition
 
 Given a query, decompose into 2-5 independent search facets:
 
@@ -114,7 +41,7 @@ Given a query, decompose into 2-5 independent search facets:
 ...
 ```
 
-#### Parallel Agent Invocation
+### Step 2: Parallel Agent Invocation
 
 Fire independent facets in parallel via Task tool:
 
@@ -126,11 +53,9 @@ Task(subagent_type="oh-my-claudecode:document-specialist", model="sonnet", promp
 
 Maximum 5 parallel document-specialist agents.
 
----
-
-### Synthesis Output Format
+### Step 3: Synthesis Output Format
 
-Regardless of path used, present results in this format:
+Present synthesized results in this format:
 
 ```markdown
 ## External Context: <query>
@@ -154,6 +79,5 @@ Regardless of path used, present results in this format:
 
 ## Configuration
 
-- Maximum 5 parallel document-specialist agents (fallback path)
-- Gemini handles multi-facet synthesis in one shot (preferred path)
+- Maximum 5 parallel document-specialist agents
 - No magic keyword trigger - explicit invocation only

package/skills/hud/SKILL.md

@@ -57,7 +57,7 @@ Then, use the Write tool to create `~/.claude/hud/omc-hud.mjs` with this exact c
 #!/usr/bin/env node
 /**
  * OMC HUD - Statusline Script
- * Wrapper that imports from plugin cache or development paths
+ * Wrapper that imports from dev paths, plugin cache, or npm package
  */
 
 import { existsSync, readdirSync } from "node:fs";
@@ -65,38 +65,49 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 
-// Semantic version comparison: returns negative if a < b, positive if a > b, 0 if equal
-function semverCompare(a, b) {
-  // Use parseInt to handle pre-release suffixes (e.g. "0-beta" -> 0)
-  const pa = a.replace(/^v/, "").split(".").map(s => parseInt(s, 10) || 0);
-  const pb = b.replace(/^v/, "").split(".").map(s => parseInt(s, 10) || 0);
-  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-    const na = pa[i] || 0;
-    const nb = pb[i] || 0;
-    if (na !== nb) return na - nb;
-  }
-  // If numeric parts equal, non-pre-release > pre-release
-  const aHasPre = /-/.test(a);
-  const bHasPre = /-/.test(b);
-  if (aHasPre && !bHasPre) return -1;
-  if (!aHasPre && bHasPre) return 1;
-  return 0;
-}
-
 async function main() {
   const home = homedir();
+  let pluginCacheVersion = null;
   let pluginCacheDir = null;
 
-  // 1. Try plugin cache first (marketplace: omc, plugin: oh-my-claudecode)
-  const pluginCacheBase = join(home, ".claude/plugins/cache/omc/oh-my-claudecode");
+  // 1. Development paths (only when OMC_DEV=1)
+  if (process.env.OMC_DEV === "1") {
+    const devPaths = [
+      join(home, "Workspace/oh-my-claudecode/dist/hud/index.js"),
+      join(home, "workspace/oh-my-claudecode/dist/hud/index.js"),
+      join(home, "projects/oh-my-claudecode/dist/hud/index.js"),
+    ];
+
+    for (const devPath of devPaths) {
+      if (existsSync(devPath)) {
+        try {
+          await import(pathToFileURL(devPath).href);
+          return;
+        } catch { /* continue */ }
+      }
+    }
+  }
+
+  // 2. Plugin cache (for production installs)
+  // Respect CLAUDE_CONFIG_DIR so installs under a custom config dir are found
+  const configDir = process.env.CLAUDE_CONFIG_DIR || join(home, ".claude");
+  const pluginCacheBase = join(configDir, "plugins", "cache", "omc", "oh-my-claudecode");
   if (existsSync(pluginCacheBase)) {
     try {
       const versions = readdirSync(pluginCacheBase);
       if (versions.length > 0) {
-        const latestVersion = versions.sort(semverCompare).reverse()[0];
-        pluginCacheDir = join(pluginCacheBase, latestVersion);
-        const pluginPath = join(pluginCacheDir, "dist/hud/index.js");
-        if (existsSync(pluginPath)) {
+        // Filter to only versions with built dist/hud/index.js
+        // This prevents picking an unbuilt new version after plugin update
+        const builtVersions = versions.filter(version => {
+          const pluginPath = join(pluginCacheBase, version, "dist/hud/index.js");
+          return existsSync(pluginPath);
+        });
+
+        if (builtVersions.length > 0) {
+          const latestVersion = builtVersions.sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).reverse()[0];
+          pluginCacheVersion = latestVersion;
+          pluginCacheDir = join(pluginCacheBase, latestVersion);
+          const pluginPath = join(pluginCacheDir, "dist/hud/index.js");
           await import(pathToFileURL(pluginPath).href);
           return;
         }
@@ -104,28 +115,27 @@ async function main() {
     } catch { /* continue */ }
   }
 
-  // 2. Development paths
-  const devPaths = [
-    join(home, "Workspace/oh-my-claudecode/dist/hud/index.js"),
-    join(home, "workspace/oh-my-claudecode/dist/hud/index.js"),
-    join(home, "Workspace/oh-my-claudecode/dist/hud/index.js"),
-    join(home, "workspace/oh-my-claudecode/dist/hud/index.js"),
-  ];
-
-  for (const devPath of devPaths) {
-    if (existsSync(devPath)) {
-      try {
-        await import(pathToFileURL(devPath).href);
-        return;
-      } catch { /* continue */ }
+  // 3. npm package (global or local install)
+  try {
+    await import("oh-my-claudecode/dist/hud/index.js");
+    return;
+  } catch { /* continue */ }
+
+  // 4. Fallback: provide detailed error message with fix instructions
+  if (pluginCacheDir && existsSync(pluginCacheDir)) {
+    // Plugin exists but dist/ folder is missing - needs build
+    const distDir = join(pluginCacheDir, "dist");
+    if (!existsSync(distDir)) {
+      console.log(`[OMC HUD] Plugin installed but not built. Run: cd "${pluginCacheDir}" && npm install && npm run build`);
+    } else {
+      console.log(`[OMC HUD] Plugin dist/ exists but HUD not found. Run: cd "${pluginCacheDir}" && npm run build`);
     }
-  }
-
-  // 3. Fallback - HUD not found (provide actionable error message)
-  if (pluginCacheDir) {
-    console.log(`[OMC] HUD not built. Run: cd "${pluginCacheDir}" && npm install`);
+  } else if (existsSync(pluginCacheBase)) {
+    // Plugin cache directory exists but no built versions found
+    console.log("[OMC HUD] Plugin cache found but no built versions. Run: /oh-my-claudecode:omc-setup");
   } else {
-    console.log("[OMC] Plugin not found. Run: /oh-my-claudecode:omc-setup");
+    // No plugin installation found at all
+    console.log("[OMC HUD] Plugin not installed. Run: /oh-my-claudecode:omc-setup");
   }
 }
 
@@ -272,9 +282,21 @@ If the HUD is not showing:
 2. Restart Claude Code after setup completes
 3. If still not working, run `/oh-my-claudecode:omc-doctor` for full diagnostics
 
+**Legacy string format migration:** Older OMC versions wrote `statusLine` as a plain string (e.g., `"~/.claude/hud/omc-hud.mjs"`). Modern Claude Code (v2.1+) requires an object format. Running the installer or `/oh-my-claudecode:hud setup` will auto-migrate legacy strings to the correct object format:
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node /home/username/.claude/hud/omc-hud.mjs"
+  }
+}
+```
+
+**Node 24+ compatibility:** The HUD wrapper script imports `homedir` from `node:os` (not `node:path`). If you encounter `SyntaxError: The requested module 'path' does not provide an export named 'homedir'`, re-run the installer to regenerate `omc-hud.mjs`.
+
 Manual verification:
 - HUD script: `~/.claude/hud/omc-hud.mjs`
-- Settings: `~/.claude/settings.json` should have `statusLine` configured
+- Settings: `~/.claude/settings.json` should have `statusLine` configured as an object with `type` and `command` fields
 
 ---