oh-my-codex 0.6.3 → 0.7.0

package/skills/configure-openclaw/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: configure-openclaw
+description: Configure OpenClaw notification gateway via natural language
+triggers:
+  - "configure openclaw"
+  - "setup openclaw"
+  - "openclaw notifications"
+  - "openclaw gateway"
+---
+
+# Configure OpenClaw Notifications
+
+Set up OpenClaw as a notification gateway so OMX can route session events through your own HTTP endpoint or CLI command.
+
+## What is OpenClaw?
+
+OpenClaw is a self-hosted notification gateway that lets you receive OMX events however you want — HTTP webhooks to your own server, shell commands, or any integration you build. Unlike platform-specific notifiers (Discord, Slack), OpenClaw gives you full control over message routing and format.
+
+**Two gateway modes:**
+- **HTTP Gateway** — OMX POSTs JSON events to your HTTP endpoint
+- **CLI Command Gateway** — OMX runs a shell command with event data as arguments or stdin
+
+## 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 `~/.codex/.omx-config.json`.
+
+## Step 1: Detect Existing Configuration
+
+```bash
+CONFIG_FILE="$HOME/.codex/.omx-config.json"
+
+if [ -f "$CONFIG_FILE" ]; then
+  HAS_OPENCLAW=$(jq -r '.notifications.openclaw.enabled // false' "$CONFIG_FILE" 2>/dev/null)
+  GATEWAY_TYPE=$(jq -r '.notifications.openclaw.gatewayType // empty' "$CONFIG_FILE" 2>/dev/null)
+  ENDPOINT=$(jq -r '.notifications.openclaw.endpoint // empty' "$CONFIG_FILE" 2>/dev/null)
+  COMMAND=$(jq -r '.notifications.openclaw.command // empty' "$CONFIG_FILE" 2>/dev/null)
+
+  if [ "$HAS_OPENCLAW" = "true" ]; then
+    echo "EXISTING_CONFIG=true"
+    echo "GATEWAY_TYPE=$GATEWAY_TYPE"
+    [ -n "$ENDPOINT" ] && echo "ENDPOINT=$ENDPOINT"
+    [ -n "$COMMAND" ] && echo "COMMAND=$COMMAND"
+  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: Choose Gateway Type
+
+Use AskUserQuestion:
+
+**Question:** "Which OpenClaw gateway mode do you want to use?"
+
+**Options:**
+1. **HTTP Gateway** - OMX sends a POST request with JSON to your endpoint. Good for web servers, n8n, Zapier webhooks, or any HTTP-capable service.
+2. **CLI Command Gateway** - OMX runs a shell command you specify. Good for local scripts, custom notification tools, or anything shell-scriptable.
+
+## Step 3A: HTTP Gateway Setup
+
+If user chose HTTP:
+
+Use AskUserQuestion:
+
+**Question:** "Enter your OpenClaw HTTP endpoint URL. OMX will POST JSON event data to this URL."
+
+The user types their URL in the "Other" field.
+
+**Validate** the URL:
+- Must start with `http://` or `https://`
+- If invalid, explain the format and ask again
+
+### Optional: Secret Header
+
+Use AskUserQuestion:
+
+**Question:** "Add an authorization header to secure requests? (Optional)"
+
+**Options:**
+1. **Yes, add Bearer token** - Sends `Authorization: Bearer <token>`
+2. **Yes, add custom header** - Specify header name and value
+3. **No auth header** - Open endpoint (use firewall rules or IP allowlist instead)
+
+If they want a Bearer token or custom header, collect the values.
+
+## Step 3B: CLI Command Gateway Setup
+
+If user chose CLI Command:
+
+Use AskUserQuestion:
+
+**Question:** "Enter the shell command OMX should run for each notification event. Use these placeholders:
+- `{event}` — event name (e.g. session-end)
+- `{session_id}` — session identifier
+- `{project}` — project name/path
+- `{message}` — formatted notification message
+
+Example: `notify-send 'OMX: {event}' '{message}'`
+Example: `~/.local/bin/my-notifier --event {event} --msg '{message}'`"
+
+The user types their command in the "Other" field.
+
+**IMPORTANT: Dual activation gate for CLI Command gateways**
+
+CLI command gateways require TWO environment variables to be set:
+- `OMX_OPENCLAW=1` — enables the OpenClaw gateway
+- `OMX_OPENCLAW_COMMAND=1` — specifically enables CLI command execution
+
+This two-gate design prevents accidental command execution when only the config file is present. Remind the user to set both in their shell profile.
+
+## Step 4: Map Events
+
+Use AskUserQuestion with multiSelect:
+
+**Question:** "Which events should be routed through OpenClaw?"
+
+**Options (multiSelect: true):**
+1. **Session end (Recommended)** - When a Codex session finishes
+2. **Input needed** - When Codex is waiting for your response
+3. **Session start** - When a new session begins
+4. **Session continuing** - When a persistent mode keeps the session alive
+
+Default selection: session-end + ask-user-question.
+
+## Step 5: Write Configuration
+
+Read the existing config, merge the OpenClaw settings, and write back:
+
+```bash
+CONFIG_FILE="$HOME/.codex/.omx-config.json"
+mkdir -p "$(dirname "$CONFIG_FILE")"
+
+if [ -f "$CONFIG_FILE" ]; then
+  EXISTING=$(cat "$CONFIG_FILE")
+else
+  EXISTING='{}'
+fi
+```
+
+### For HTTP Gateway:
+
+```bash
+# ENDPOINT, AUTH_HEADER_NAME, AUTH_HEADER_VALUE are collected from user
+echo "$EXISTING" | jq \
+  --arg endpoint "$ENDPOINT" \
+  --arg headerName "$AUTH_HEADER_NAME" \
+  --arg headerValue "$AUTH_HEADER_VALUE" \
+  '.notifications = (.notifications // {enabled: true}) |
+   .notifications.enabled = true |
+   .notifications.openclaw = {
+     enabled: true,
+     gatewayType: "http",
+     endpoint: $endpoint,
+     headers: (if $headerName == "" then null else {($headerName): $headerValue} end)
+   }' > "$CONFIG_FILE"
+```
+
+### For CLI Command Gateway:
+
+```bash
+# COMMAND is collected from user
+echo "$EXISTING" | jq \
+  --arg command "$COMMAND" \
+  '.notifications = (.notifications // {enabled: true}) |
+   .notifications.enabled = true |
+   .notifications.openclaw = {
+     enabled: true,
+     gatewayType: "command",
+     command: $command
+   }' > "$CONFIG_FILE"
+```
+
+### Add event-specific config if user didn't select all events:
+
+```bash
+# Example: disable session-start if not selected
+echo "$(cat "$CONFIG_FILE")" | jq \
+  '.notifications.events = (.notifications.events // {}) |
+   .notifications.events["session-start"] = {enabled: false}' > "$CONFIG_FILE"
+```
+
+## Step 6: Explain Activation Gates
+
+Regardless of gateway type, explain the activation model:
+
+```
+OpenClaw Activation Gates
+─────────────────────────
+OpenClaw requires environment variables to be set before it activates.
+This prevents accidental notifications in shared or CI environments.
+
+For HTTP Gateway:
+  export OMX_OPENCLAW=1
+
+For CLI Command Gateway (requires both):
+  export OMX_OPENCLAW=1
+  export OMX_OPENCLAW_COMMAND=1
+
+Add these to your ~/.zshrc or ~/.bashrc.
+```
+
+## Step 7: Test the Configuration
+
+After writing config, offer to test:
+
+Use AskUserQuestion:
+
+**Question:** "Send a test notification through OpenClaw to verify the setup?"
+
+**Options:**
+1. **Yes, test now (Recommended)** - Run a test dispatch
+2. **No, I'll test later** - Skip testing
+
+### If testing HTTP Gateway:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" \
+  -H "Content-Type: application/json" \
+  ${AUTH_HEADER_NAME:+-H "$AUTH_HEADER_NAME: $AUTH_HEADER_VALUE"} \
+  -d '{"event":"test","message":"OMX OpenClaw test notification","session_id":"test"}' \
+  "$ENDPOINT"
+```
+
+### If testing CLI Command Gateway:
+
+Replace placeholders in the command with test values and run it.
+
+Report success or failure. If it fails, help debug (check URL accessibility, command path, permissions).
+
+## Step 8: Confirm
+
+Display the final configuration summary:
+
+```
+OpenClaw Gateway Configured!
+
+  Type:     HTTP / CLI Command
+  Endpoint: https://your-server/omx-hook  (HTTP only)
+  Command:  notify-send 'OMX' '{message}'  (CLI only)
+  Events:   session-end, ask-user-question
+
+Config saved to: ~/.codex/.omx-config.json
+
+Activation (add to ~/.zshrc or ~/.bashrc):
+  export OMX_OPENCLAW=1
+  export OMX_OPENCLAW_COMMAND=1   # CLI Command gateways only
+
+To reconfigure: /configure-openclaw
+To configure other platforms: /configure-notifications
+```
+
+## Environment Variable Reference
+
+```bash
+# Required for all OpenClaw gateways
+export OMX_OPENCLAW=1
+
+# Required additionally for CLI Command gateways
+export OMX_OPENCLAW_COMMAND=1
+
+# HTTP gateway: override endpoint URL
+export OMX_OPENCLAW_URL="https://your-server/omx-hook"
+```

package/skills/configure-slack/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: configure-slack
+description: Configure Slack webhook notifications via natural language
+triggers:
+  - "configure slack"
+  - "setup slack"
+  - "slack notifications"
+  - "slack webhook"
+---
+
+# Configure Slack Notifications
+
+Set up Slack notifications so OMX can ping you when sessions end, need input, or complete background tasks.
+
+## 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 `~/.codex/.omx-config.json`.
+
+## Step 1: Detect Existing Configuration
+
+```bash
+CONFIG_FILE="$HOME/.codex/.omx-config.json"
+
+if [ -f "$CONFIG_FILE" ]; then
+  HAS_SLACK=$(jq -r '.notifications.slack.enabled // false' "$CONFIG_FILE" 2>/dev/null)
+  WEBHOOK_URL=$(jq -r '.notifications.slack.webhookUrl // empty' "$CONFIG_FILE" 2>/dev/null)
+  CHANNEL=$(jq -r '.notifications.slack.channel // empty' "$CONFIG_FILE" 2>/dev/null)
+  USERNAME=$(jq -r '.notifications.slack.username // empty' "$CONFIG_FILE" 2>/dev/null)
+  MENTION=$(jq -r '.notifications.slack.mention // empty' "$CONFIG_FILE" 2>/dev/null)
+
+  if [ "$HAS_SLACK" = "true" ]; then
+    echo "EXISTING_CONFIG=true"
+    [ -n "$WEBHOOK_URL" ] && echo "WEBHOOK_URL=$WEBHOOK_URL"
+    [ -n "$CHANNEL" ] && echo "CHANNEL=$CHANNEL"
+    [ -n "$USERNAME" ] && echo "USERNAME=$USERNAME"
+    [ -n "$MENTION" ] && echo "MENTION=$MENTION"
+  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 Webhook URL
+
+Use AskUserQuestion:
+
+**Question:** "Paste your Slack Incoming Webhook URL. To create one: Go to api.slack.com/apps > Your App > Incoming Webhooks > Add New Webhook to Workspace > Copy URL"
+
+The user will type their webhook URL in the "Other" field.
+
+**Validate** the URL:
+- Must start with `https://hooks.slack.com/services/` or `https://hooks.slack.com/workflows/`
+- If invalid, explain the format and ask again
+
+## Step 3: Configure Channel (Optional)
+
+Use AskUserQuestion:
+
+**Question:** "Which Slack channel should receive notifications? (Optional — leave blank to use the webhook's default channel)"
+
+**Options:**
+1. **Use webhook default** - The channel configured in the Slack app integration
+2. **Specify a channel** - Enter a channel name (e.g. `#dev-alerts`) or channel ID
+
+Note: Overriding the channel requires the webhook to have permission for that channel.
+
+## Step 4: Configure Mention (Optional)
+
+Use AskUserQuestion:
+
+**Question:** "Would you like notifications to mention (ping) someone?"
+
+**Options:**
+1. **Yes, mention a user** - Tag a user with `<@UXXXXXXXX>`
+2. **Yes, mention a channel** - Tag everyone with `<!channel>` or `<!here>`
+3. **No mentions** - Just post the message without pinging anyone
+
+### If user wants to mention a user:
+
+Ask: "What is the Slack member ID to mention? (Click the user's profile > More > Copy member ID)"
+
+Format: `<@UXXXXXXXX>` (e.g. `<@U012AB3CD>`)
+
+### If user wants a channel mention:
+
+Choose between:
+- `<!channel>` — notifies all channel members regardless of online status
+- `<!here>` — notifies only currently active channel members
+
+## Step 5: Configure Display Name (Optional)
+
+Use AskUserQuestion:
+
+**Question:** "Custom bot display name in Slack? (Shows as the message sender)"
+
+**Options:**
+1. **OMX (default)** - Display as "OMX"
+2. **Codex CLI** - Display as "Codex CLI"
+3. **Custom** - Enter a custom name
+
+## Step 6: Configure Events
+
+Use AskUserQuestion with multiSelect:
+
+**Question:** "Which events should trigger Slack notifications?"
+
+**Options (multiSelect: true):**
+1. **Session end (Recommended)** - When a Codex session finishes
+2. **Input needed** - When Codex is waiting for your response (great for long-running tasks)
+3. **Session start** - When a new session begins
+4. **Session continuing** - When a persistent mode keeps the session alive
+
+Default selection: session-end + ask-user-question.
+
+## Step 7: Write Configuration
+
+Read the existing config, merge the new Slack settings, and write back:
+
+```bash
+CONFIG_FILE="$HOME/.codex/.omx-config.json"
+mkdir -p "$(dirname "$CONFIG_FILE")"
+
+if [ -f "$CONFIG_FILE" ]; then
+  EXISTING=$(cat "$CONFIG_FILE")
+else
+  EXISTING='{}'
+fi
+
+# WEBHOOK_URL, CHANNEL, MENTION, USERNAME are collected from user
+echo "$EXISTING" | jq \
+  --arg url "$WEBHOOK_URL" \
+  --arg channel "$CHANNEL" \
+  --arg mention "$MENTION" \
+  --arg username "$USERNAME" \
+  '.notifications = (.notifications // {enabled: true}) |
+   .notifications.enabled = true |
+   .notifications.slack = {
+     enabled: true,
+     webhookUrl: $url,
+     channel: (if $channel == "" then null else $channel end),
+     mention: (if $mention == "" then null else $mention end),
+     username: (if $username == "" then null else $username end)
+   }' > "$CONFIG_FILE"
+```
+
+### Add event-specific config if user didn't select all events:
+
+For each event NOT selected, disable it:
+
+```bash
+# Example: disable session-start if not selected
+echo "$(cat "$CONFIG_FILE")" | jq \
+  '.notifications.events = (.notifications.events // {}) |
+   .notifications.events["session-start"] = {enabled: false}' > "$CONFIG_FILE"
+```
+
+## Step 8: Test the Configuration
+
+After writing config, offer to send a test notification:
+
+Use AskUserQuestion:
+
+**Question:** "Send a test notification to verify the setup?"
+
+**Options:**
+1. **Yes, test now (Recommended)** - Send a test message to your Slack channel
+2. **No, I'll test later** - Skip testing
+
+### If testing:
+
+```bash
+RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" \
+  -H "Content-Type: application/json" \
+  -d "{\"text\": \"${MENTION:+$MENTION\\n}OMX test notification - Slack is configured!\", \"username\": \"${USERNAME:-OMX}\"}" \
+  "$WEBHOOK_URL")
+
+if [ "$RESPONSE" = "200" ]; then
+  echo "Test notification sent successfully!"
+else
+  echo "Failed (HTTP $RESPONSE). Check the webhook URL and channel permissions."
+fi
+```
+
+Report success or failure. Common issues:
+- **400 Bad Request**: Malformed JSON or invalid channel override
+- **403 Forbidden**: Channel override not permitted by the webhook
+- **404 Not Found**: Webhook URL is invalid or revoked — regenerate it in Slack
+
+## Step 9: Confirm
+
+Display the final configuration summary:
+
+```
+Slack Notifications Configured!
+
+  Webhook:  https://hooks.slack.com/services/...
+  Channel:  #dev-alerts (or "webhook default")
+  Mention:  <!channel> (or "none")
+  Username: OMX
+  Events:   session-end, ask-user-question
+
+Config saved to: ~/.codex/.omx-config.json
+
+You can also set these via environment variables:
+  OMX_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
+  OMX_SLACK_MENTION=<!channel>
+
+To reconfigure: /configure-slack
+To configure Discord: /configure-discord
+To configure Telegram: /configure-telegram
+```
+
+## Environment Variable Alternative
+
+Users can skip this wizard entirely by setting env vars in their shell profile:
+
+```bash
+export OMX_SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."
+export OMX_SLACK_MENTION="<!channel>"  # optional
+```
+
+Env vars are auto-detected by the notification system without needing `.omx-config.json`.

package/skills/omx-setup/SKILL.md

@@ -10,14 +10,14 @@ Use this skill when users want to install or refresh oh-my-codex for the **curre
 ## Command
 
 ```bash
-omx setup [--force] [--dry-run] [--verbose] [--scope <user|project-local|project>]
+omx setup [--force] [--dry-run] [--verbose] [--scope <user|project>]
 ```
 
 Supported setup flags (current implementation):
 - `--force`: overwrite/reinstall managed artifacts where applicable
 - `--dry-run`: print actions without mutating files
 - `--verbose`: print per-file/per-step details
-- `--scope`: choose install scope (`user`, `project-local`, `project`)
+- `--scope`: choose install scope (`user`, `project`)
 
 ## What this setup actually does
 
@@ -25,31 +25,26 @@ Supported setup flags (current implementation):
 
 1. Resolve setup scope:
    - `--scope` explicit value
-   - else persisted `./.omx/setup-scope.json`
+   - else persisted `./.omx/setup-scope.json` (with automatic migration of legacy values)
    - else interactive prompt on TTY (default `user`)
    - else default `user` (safe for CI/tests)
-2. Create project OMX directories (`./.omx/state`, `./.omx/plans`, `./.omx/logs`) and persist effective scope
-3. For `user`/`project-local` scope:
-   - install prompts
-   - remove legacy prompt shims
-   - install native agent configs
-   - install skills
-   - merge OMX config.toml
-4. For `project` scope: skip prompt/skill/config/native-agent installs with console messages
-6. Verify required team MCP comm tool exports exist in built `dist/mcp/state-server.js`
-7. Generate project-root `./AGENTS.md` from `templates/AGENTS.md` (or skip when existing and no force)
-8. Configure notify hook references and write `./.omx/hud-config.json`
+2. Create directories and persist effective scope
+3. Install prompts, native agent configs, skills, and merge config.toml (scope determines target directories)
+4. Verify required team MCP comm tool exports exist in built `dist/mcp/state-server.js`
+5. Generate project-root `./AGENTS.md` from `templates/AGENTS.md` (or skip when existing and no force)
+6. Configure notify hook references and write `./.omx/hud-config.json`
 
 ## Important behavior notes
 
 - `omx setup` only prompts for scope when no scope is provided/persisted and stdin/stdout are TTY.
 - Local project orchestration file is `./AGENTS.md` (project root).
+- If `AGENTS.md` exists and `--force` is not used, interactive TTY runs ask whether to overwrite. Non-interactive runs preserve the file.
 - Scope targets:
   - `user`: user directories (`~/.codex`, `~/.agents/skills`, `~/.omx/agents`)
-  - `project-local`: local directories (`./.codex`, `./.agents/skills`, `./.omx/agents`)
-  - `project`: project-only OMX setup (`./.omx/*`, `AGENTS.md`, HUD)
-- If persisted scope is `project-local`, `omx` launch automatically uses `CODEX_HOME=./.codex` unless user explicitly overrides `CODEX_HOME`.
+  - `project`: local directories (`./.codex`, `./.agents/skills`, `./.omx/agents`)
+- If persisted scope is `project`, `omx` launch automatically uses `CODEX_HOME=./.codex` unless user explicitly overrides `CODEX_HOME`.
 - With `--force`, AGENTS overwrite may still be skipped if an active OMX session is detected (safety guard).
+- Legacy persisted scope values (`project-local`) are automatically migrated to `project` with a one-time warning.
 
 ## Recommended workflow
 
@@ -70,8 +65,8 @@ omx doctor
 ## Expected verification indicators
 
 From `omx doctor`, expect:
-- Prompts installed (scope-dependent: user or project-local)
-- Skills installed (scope-dependent: user or project-local)
+- Prompts installed (scope-dependent: user or project)
+- Skills installed (scope-dependent: user or project)
 - AGENTS.md found in project root
 - `.omx/state` exists
 - OMX MCP servers configured in scope target `config.toml` (`~/.codex/config.toml` or `./.codex/config.toml`)