oh-my-claude-sisyphus 3.5.1 → 3.5.5

package/scripts/install.sh

@@ -720,161 +720,6 @@ Delegate tasks to specialized agents using the Task tool:
 - NEVER leave work incomplete
 CMD_EOF
 
-# omc-default mode command (project-scoped)
-cat > "$CLAUDE_CONFIG_DIR/commands/omc-default.md" << 'CMD_EOF'
----
-description: Configure oh-my-claudecode in local project (.claude/CLAUDE.md)
----
-
-$ARGUMENTS
-
-## Task: Configure oh-my-claudecode Default Mode (Project-Scoped)
-
-**CRITICAL**: This skill ALWAYS downloads fresh CLAUDE.md from GitHub to your local project. DO NOT use the Write tool - use bash curl exclusively.
-
-### Step 1: Create Local .claude Directory
-
-Ensure the local project has a .claude directory:
-
-```bash
-# Create .claude directory in current project
-mkdir -p .claude && echo "✅ .claude directory created" || echo "❌ Failed to create .claude directory"
-```
-
-### Step 2: Download Fresh CLAUDE.md (MANDATORY)
-
-Execute this bash command to download fresh CLAUDE.md to local project config:
-
-```bash
-# Download fresh CLAUDE.md to project-local .claude/
-curl -fsSL "https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claude-sisyphus/main/docs/CLAUDE.md" -o .claude/CLAUDE.md && \
-echo "✅ CLAUDE.md downloaded successfully to .claude/CLAUDE.md" || \
-echo "❌ Failed to download CLAUDE.md"
-```
-
-**MANDATORY**: Always run this command. Do NOT skip. Do NOT use Write tool.
-
-**FALLBACK** if curl fails:
-Tell user to manually download from:
-https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claude-sisyphus/main/docs/CLAUDE.md
-
-### Step 3: Verify Plugin Installation
-
-The oh-my-claudecode plugin provides all hooks automatically via the plugin system. Verify the plugin is enabled:
-
-```bash
-grep -q "oh-my-claudecode" ~/.claude/settings.json && echo "Plugin enabled" || echo "Plugin NOT enabled"
-```
-
-If plugin is not enabled, instruct user:
-> Run: `claude /install-plugin oh-my-claudecode` to enable the plugin.
-
-### Step 4: Confirm Success
-
-After completing all steps, report:
-
-✅ **oh-my-claudecode Project Configuration Complete**
-- CLAUDE.md: Updated with latest configuration from GitHub at ./.claude/CLAUDE.md
-- Scope: **PROJECT** - applies only to this project
-- Hooks: Provided by plugin (no manual installation needed)
-- Agents: 19+ available (base + tiered variants)
-- Model routing: Haiku/Sonnet/Opus based on task complexity
-
-**Note**: This configuration is project-specific and won't affect other projects or global settings.
-
----
-
-## 🔄 Keeping Up to Date
-
-After installing oh-my-claudecode updates (via npm or plugin update), run `/omc-default` again in your project to get the latest CLAUDE.md configuration. This ensures you have the newest features and agent configurations.
-
----
-
-## 🌍 Global vs Project Configuration
-
-- **`/omc-default`** (this command): Creates `./.claude/CLAUDE.md` in your current project
-- **`/omc-default-global`**: Creates `~/.claude/CLAUDE.md` for all projects
-
-Project-scoped configuration takes precedence over global configuration.
-CMD_EOF
-
-# omc-default-global mode command (global)
-cat > "$CLAUDE_CONFIG_DIR/commands/omc-default-global.md" << 'CMD_EOF'
----
-description: Configure oh-my-claudecode globally in ~/.claude/CLAUDE.md
----
-
-$ARGUMENTS
-
-## Task: Configure oh-my-claudecode Default Mode (Global)
-
-**CRITICAL**: This skill ALWAYS downloads fresh CLAUDE.md from GitHub to your global config. DO NOT use the Write tool - use bash curl exclusively.
-
-### Step 1: Download Fresh CLAUDE.md (MANDATORY)
-
-Execute this bash command to erase and download fresh CLAUDE.md to global config:
-
-```bash
-# Remove existing CLAUDE.md and download fresh from GitHub
-rm -f ~/.claude/CLAUDE.md && \
-curl -fsSL "https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claude-sisyphus/main/docs/CLAUDE.md" -o ~/.claude/CLAUDE.md && \
-echo "✅ CLAUDE.md downloaded successfully to ~/.claude/CLAUDE.md" || \
-echo "❌ Failed to download CLAUDE.md"
-```
-
-**MANDATORY**: Always run this command. Do NOT skip. Do NOT use Write tool.
-
-**FALLBACK** if curl fails:
-Tell user to manually download from:
-https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claude-sisyphus/main/docs/CLAUDE.md
-
-### Step 2: Clean Up Legacy Hooks (if present)
-
-Check if old manual hooks exist and remove them to prevent duplicates:
-
-```bash
-# Remove legacy bash hook scripts (now handled by plugin system)
-rm -f ~/.claude/hooks/keyword-detector.sh
-rm -f ~/.claude/hooks/stop-continuation.sh
-rm -f ~/.claude/hooks/persistent-mode.sh
-rm -f ~/.claude/hooks/session-start.sh
-```
-
-Check `~/.claude/settings.json` for manual hook entries. If the "hooks" key exists with UserPromptSubmit, Stop, or SessionStart entries pointing to bash scripts, inform the user:
-
-> **Note**: Found legacy hooks in settings.json. These should be removed since the plugin now provides hooks automatically. Remove the "hooks" section from ~/.claude/settings.json to prevent duplicate hook execution.
-
-### Step 3: Verify Plugin Installation
-
-The oh-my-claudecode plugin provides all hooks automatically via the plugin system. Verify the plugin is enabled:
-
-```bash
-grep -q "oh-my-claudecode" ~/.claude/settings.json && echo "Plugin enabled" || echo "Plugin NOT enabled"
-```
-
-If plugin is not enabled, instruct user:
-> Run: `claude /install-plugin oh-my-claudecode` to enable the plugin.
-
-### Step 4: Confirm Success
-
-After completing all steps, report:
-
-✅ **oh-my-claudecode Global Configuration Complete**
-- CLAUDE.md: Updated with latest configuration from GitHub at ~/.claude/CLAUDE.md
-- Scope: **GLOBAL** - applies to all Claude Code sessions
-- Hooks: Provided by plugin (no manual installation needed)
-- Agents: 19+ available (base + tiered variants)
-- Model routing: Haiku/Sonnet/Opus based on task complexity
-
-**Note**: Hooks are now managed by the plugin system automatically. No manual hook installation required.
-
----
-
-## 🔄 Keeping Up to Date
-
-After installing oh-my-claudecode updates (via npm or plugin update), run `/omc-default-global` again to get the latest CLAUDE.md configuration. This ensures you have the newest features and agent configurations.
-CMD_EOF
-
 # Plan command (Prometheus planning system)
 cat > "$CLAUDE_CONFIG_DIR/commands/plan.md" << 'CMD_EOF'
 ---
@@ -1003,57 +848,7 @@ Plans are saved to `.omc/plans/` for later execution with `/sisyphus`.
 Tell me about what you want to build or accomplish. I'll ask questions to understand the full scope before creating a plan.
 CMD_EOF
 
-# Ralph Loop Command
-cat > "$CLAUDE_CONFIG_DIR/commands/ralph-loop.md" << 'CMD_EOF'
----
-description: Start self-referential development loop until task completion
----
-
-[RALPH LOOP ACTIVATED]
-
-$ARGUMENTS
-
-## How Ralph Loop Works
-
-You are starting a Ralph Loop - a self-referential development loop that runs until task completion.
-
-1. Work on the task continuously and thoroughly
-2. When the task is FULLY complete, output: `<promise>DONE</promise>`
-3. If you stop without the promise tag, the loop will remind you to continue
-4. Maximum iterations: 100 (configurable)
-
-## Exit Conditions
-
-- **Completion**: Output `<promise>DONE</promise>` when fully done
-- **Cancel**: User runs `/cancel-ralph`
-- **Max Iterations**: Loop stops at limit
-
-## Guidelines
-
-- Break the task into steps and work through them systematically
-- Test your work as you go
-- Don't output the promise until you've verified everything works
-- Be thorough - the loop exists so you can take your time
-
----
-
-Begin working on the task. Remember to output `<promise>DONE</promise>` when complete.
-CMD_EOF
-
-# Cancel Ralph Command
-cat > "$CLAUDE_CONFIG_DIR/commands/cancel-ralph.md" << 'CMD_EOF'
----
-description: Cancel active Ralph Loop
----
-
-[RALPH LOOP CANCELLED]
-
-The Ralph Loop has been cancelled. You can stop working on the current task.
-
-If you want to start a new loop, use `/ralph-loop "task description"`.
-CMD_EOF
-
-echo -e "${GREEN}✓ Installed 10 slash commands${NC}"
+echo -e "${GREEN}✓ Installed 8 slash commands${NC}"
 
 echo -e "${BLUE}[5/6]${NC} Installing hook scripts..."
 mkdir -p "$CLAUDE_CONFIG_DIR/hooks"
@@ -1724,16 +1519,14 @@ Use the Task tool to delegate to specialized agents:
 | Command | Description |
 |---------|-------------|
 | `/orchestrate <task>` | Activate OMC multi-agent orchestration |
-| `/omc-default` | Configure OMC for current project (./.claude/CLAUDE.md) |
-| `/omc-default-global` | Configure OMC globally (~/.claude/CLAUDE.md) |
+| `/omc-setup` | Configure OMC (--local for project, --global for all) |
 | `/ultrawork <task>` | Maximum performance mode with parallel agents |
 | `/deepsearch <query>` | Thorough codebase search |
 | `/analyze <target>` | Deep analysis and investigation |
-| `/plan <description>` | Start planning session with Planner |
+| `/plan <description>` | Start planning session |
 | `/review [plan-path]` | Review a plan with Critic |
-| `/planner <task>` | Strategic planning with interview workflow |
 | `/ralph <task>` | Self-referential loop until task completion |
-| `/cancel-ralph` | Cancel active Ralph Loop |
+| `/cancel` | Cancel active loops/modes |
 
 ## Planning Workflow
 
@@ -1833,8 +1626,7 @@ echo "  claude                        # Start Claude Code normally"
 echo ""
 echo -e "${YELLOW}Slash Commands:${NC}"
 echo "  /sisyphus <task>              # Activate Sisyphus orchestration mode"
-echo "  /omc-default                  # Configure for current project"
-echo "  /omc-default-global           # Configure globally"
+echo "  /omc-setup                    # Configure OMC (--local or --global)"
 echo "  /ultrawork <task>             # Maximum performance mode"
 echo "  /deepsearch <query>           # Thorough codebase search"
 echo "  /analyze <target>             # Deep analysis mode"
@@ -1871,12 +1663,11 @@ echo "  # Or run this install script again:"
 echo "  curl -fsSL https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claude-sisyphus/main/scripts/install.sh | bash"
 echo ""
 echo -e "${YELLOW}After Updates:${NC}"
-echo "  Run '/omc-default' (project) or '/omc-default-global' (global)"
-echo "  to download the latest CLAUDE.md configuration."
-echo "  This ensures you get the newest features and agent behaviors."
+echo "  Run '/omc-setup' to download the latest CLAUDE.md configuration."
+echo "  Use '--local' for project or '--global' for all projects."
 echo ""
 echo -e "${BLUE}Quick Start:${NC}"
 echo "  1. Run 'claude' to start Claude Code"
-echo "  2. Type '/omc-default' for project config or '/omc-default-global' for global"
+echo "  2. Type '/omc-setup' for configuration wizard"
 echo "  3. Or use '/sisyphus <task>' for one-time activation"
 echo ""

package/scripts/keyword-detector.mjs

@@ -137,7 +137,7 @@ function activateUltraworkState(directory, prompt) {
     last_checked_at: new Date().toISOString()
   };
 
-  // Write to local .omc directory
+  // Write to local .sisyphus directory
   const localDir = join(directory, '.omc');
   if (!existsSync(localDir)) {
     try { mkdirSync(localDir, { recursive: true }); } catch {}

package/scripts/persistent-mode.mjs

@@ -55,7 +55,7 @@ function writeJsonFile(path, data) {
 
 // Read PRD and get status
 function getPrdStatus(projectDir) {
-  // Check both root and .omc for prd.json
+  // Check both root and .sisyphus for prd.json
   const paths = [
     join(projectDir, 'prd.json'),
     join(projectDir, '.omc', 'prd.json')

package/scripts/test-mutual-exclusion.ts

@@ -18,10 +18,10 @@ function printTest(testName: string, passed: boolean) {
 async function runTests() {
   console.log('\n=== Testing Mutual Exclusion Between UltraQA and Ralph Loop ===\n');
 
-  // Create temp directory with .omc subfolder
-  const tempDir = mkdtempSync(join(tmpdir(), 'omc-test-'));
-  const omcDir = join(tempDir, '.omc');
-  mkdirSync(omcDir, { recursive: true });
+  // Create temp directory with .sisyphus subfolder
+  const tempDir = mkdtempSync(join(tmpdir(), 'sisyphus-test-'));
+  const sisyphusDir = join(tempDir, '.sisyphus');
+  mkdirSync(sisyphusDir, { recursive: true });
 
   console.log(`Using temp directory: ${tempDir}\n`);
 

package/scripts/test-remember-tags.ts

@@ -5,8 +5,8 @@ import { spawn } from 'child_process';
 
 // Create test directory
 const testDir = join(tmpdir(), `remember-tag-test-${Date.now()}`);
-const omcDir = join(testDir, '.omc');
-mkdirSync(omcDir, { recursive: true });
+const sisyphusDir = join(testDir, '.sisyphus');
+mkdirSync(sisyphusDir, { recursive: true });
 
 console.log('Testing remember tag processing in post-tool-verifier.mjs\n');
 
@@ -50,7 +50,7 @@ try {
 
   await runHook(input1);
 
-  const notepadPath = join(omcDir, 'notepad.md');
+  const notepadPath = join(sisyphusDir, 'notepad.md');
   if (existsSync(notepadPath)) {
     const content = readFileSync(notepadPath, 'utf-8');
     if (content.includes('pnpm') && content.includes('Working Memory')) {
@@ -78,7 +78,7 @@ try {
 
   await runHook(input2);
 
-  const notepadPath = join(omcDir, 'notepad.md');
+  const notepadPath = join(sisyphusDir, 'notepad.md');
   const content = readFileSync(notepadPath, 'utf-8');
   if (content.includes('API endpoint') && content.includes('Priority Context')) {
     console.log('✓ PASS: Priority remember tag saved to Priority Context\n');
@@ -95,7 +95,7 @@ console.log('Test 3: Non-Task tool should not process tags');
 try {
   // Clean up first
   rmSync(testDir, { recursive: true });
-  mkdirSync(omcDir, { recursive: true });
+  mkdirSync(sisyphusDir, { recursive: true });
 
   const input3 = {
     toolName: 'Bash',
@@ -106,7 +106,7 @@ try {
 
   await runHook(input3);
 
-  const notepadPath = join(omcDir, 'notepad.md');
+  const notepadPath = join(sisyphusDir, 'notepad.md');
   if (!existsSync(notepadPath)) {
     console.log('✓ PASS: Bash tool did not trigger remember tag processing\n');
   } else {

package/scripts/test-session-injection.ts

@@ -4,8 +4,8 @@ import { join } from 'path';
 
 // Create test notepad
 const testDir = join(tmpdir(), `session-test-${Date.now()}`);
-const omcDir = join(testDir, '.omc');
-mkdirSync(omcDir, { recursive: true });
+const sisyphusDir = join(testDir, '.sisyphus');
+mkdirSync(sisyphusDir, { recursive: true });
 
 const notepadContent = `# Notepad
 
@@ -22,10 +22,10 @@ Some working memory entry
 User notes here
 `;
 
-writeFileSync(join(omcDir, 'notepad.md'), notepadContent);
+writeFileSync(join(sisyphusDir, 'notepad.md'), notepadContent);
 
 // Test priority context extraction (mimics session-start.mjs logic)
-const content = readFileSync(join(omcDir, 'notepad.md'), 'utf-8');
+const content = readFileSync(join(sisyphusDir, 'notepad.md'), 'utf-8');
 const priorityMatch = content.match(/## Priority Context\n([\s\S]*?)(?=\n## [^#]|$)/);
 const cleanContent = priorityMatch ? priorityMatch[1].replace(/<!--[\s\S]*?-->/g, '').trim() : '';
 

package/scripts/uninstall.sh

@@ -63,8 +63,6 @@ rm -f "$CLAUDE_CONFIG_DIR/agents/prometheus.md"
 # Remove commands
 echo -e "${BLUE}Removing commands...${NC}"
 rm -f "$CLAUDE_CONFIG_DIR/commands/sisyphus.md"
-rm -f "$CLAUDE_CONFIG_DIR/commands/sisyphus-default.md"
-rm -f "$CLAUDE_CONFIG_DIR/commands/sisyphus-default-global.md"
 rm -f "$CLAUDE_CONFIG_DIR/commands/ultrawork.md"
 rm -f "$CLAUDE_CONFIG_DIR/commands/deepsearch.md"
 rm -f "$CLAUDE_CONFIG_DIR/commands/analyze.md"
@@ -72,8 +70,6 @@ rm -f "$CLAUDE_CONFIG_DIR/commands/plan.md"
 rm -f "$CLAUDE_CONFIG_DIR/commands/review.md"
 rm -f "$CLAUDE_CONFIG_DIR/commands/prometheus.md"
 rm -f "$CLAUDE_CONFIG_DIR/commands/orchestrator.md"
-rm -f "$CLAUDE_CONFIG_DIR/commands/ralph-loop.md"
-rm -f "$CLAUDE_CONFIG_DIR/commands/cancel-ralph.md"
 rm -f "$CLAUDE_CONFIG_DIR/commands/update.md"
 
 # Remove skills

package/skills/autopilot/SKILL.md

@@ -114,7 +114,7 @@ Optional settings in `.claude/settings.json`:
 ## Cancellation
 
 ```
-/oh-my-claudecode:cancel-autopilot
+/oh-my-claudecode:cancel
 ```
 
 Or say: "stop", "cancel", "abort"

package/skills/cancel/SKILL.md

@@ -38,6 +38,8 @@ The skill checks state files to determine what's active:
 - `.omc/swarm-state.json` → Swarm detected
 - `.omc/ultrapilot-state.json` → Ultrapilot detected
 - `.omc/pipeline-state.json` → Pipeline detected
+- `.omc/state/plan-consensus.json` → Plan Consensus detected
+- `.omc/ralplan-state.json` → Plan Consensus detected (legacy)
 
 If multiple modes are active, they're cancelled in order of dependency:
 1. Autopilot (includes ralph/ultraqa/ecomode cleanup)
@@ -48,6 +50,7 @@ If multiple modes are active, they're cancelled in order of dependency:
 6. Swarm (standalone)
 7. Ultrapilot (standalone)
 8. Pipeline (standalone)
+9. Plan Consensus (standalone)
 
 ## Force Clear All
 
@@ -73,6 +76,8 @@ This removes all state files:
 - `.omc/state/swarm-tasks.json`
 - `.omc/ultrapilot-state.json`
 - `.omc/pipeline-state.json`
+- `.omc/state/plan-consensus.json`
+- `.omc/ralplan-state.json`
 - `~/.claude/ralph-state.json`
 - `~/.claude/ultrawork-state.json`
 - `~/.claude/ecomode-state.json`
@@ -120,6 +125,15 @@ fi
 if [[ -f .omc/ultraqa-state.json ]]; then
   ULTRAQA_ACTIVE=$(cat .omc/ultraqa-state.json | jq -r '.active // false')
 fi
+
+PLAN_CONSENSUS_ACTIVE=false
+
+# Check both new and legacy locations
+if [[ -f .omc/state/plan-consensus.json ]]; then
+  PLAN_CONSENSUS_ACTIVE=$(cat .omc/state/plan-consensus.json | jq -r '.active // false')
+elif [[ -f .omc/ralplan-state.json ]]; then
+  PLAN_CONSENSUS_ACTIVE=$(cat .omc/ralplan-state.json | jq -r '.active // false')
+fi
 ```
 
 ### 3A. Force Mode (if --force or --all)
@@ -140,6 +154,8 @@ if [[ "$FORCE_MODE" == "true" ]]; then
   rm -f .omc/state/swarm-tasks.json
   rm -f .omc/ultrapilot-state.json
   rm -f .omc/pipeline-state.json
+  rm -f .omc/state/plan-consensus.json
+  rm -f .omc/ralplan-state.json
 
   # Remove global state files
   rm -f ~/.claude/ralph-state.json
@@ -308,6 +324,8 @@ if [[ "$FORCE_MODE" == "true" ]]; then
   rm -f .omc/state/swarm-tasks.json
   rm -f .omc/ultrapilot-state.json
   rm -f .omc/pipeline-state.json
+  rm -f .omc/state/plan-consensus.json
+  rm -f .omc/ralplan-state.json
 
   # Remove global state files
   rm -f ~/.claude/ralph-state.json
@@ -526,6 +544,20 @@ if [[ -f .omc/pipeline-state.json ]]; then
   fi
 fi
 
+# 9. Check Plan Consensus (standalone)
+if [[ "$PLAN_CONSENSUS_ACTIVE" == "true" ]]; then
+  echo "Cancelling Plan Consensus mode..."
+
+  # Clear state files
+  rm -f .omc/state/plan-consensus.json
+  rm -f .omc/ralplan-state.json
+
+  echo "Plan Consensus cancelled. Planning session ended."
+  echo "Note: Plan file preserved at path specified in state."
+  CANCELLED_ANYTHING=true
+  exit 0
+fi
+
 # No active modes found
 if [[ "$CANCELLED_ANYTHING" == "false" ]]; then
   echo "No active OMC modes detected."
@@ -539,6 +571,7 @@ if [[ "$CANCELLED_ANYTHING" == "false" ]]; then
   echo "  - Swarm (.omc/swarm-state.json)"
   echo "  - Ultrapilot (.omc/ultrapilot-state.json)"
   echo "  - Pipeline (.omc/pipeline-state.json)"
+  echo "  - Plan Consensus (.omc/state/plan-consensus.json)"
   echo ""
   echo "Use --force to clear all state files anyway."
 fi
@@ -556,6 +589,7 @@ fi
 | Swarm | "Swarm cancelled. Coordinated agents stopped." |
 | Ultrapilot | "Ultrapilot cancelled. Parallel autopilot workers stopped." |
 | Pipeline | "Pipeline cancelled. Sequential agent chain stopped." |
+| Plan Consensus | "Plan Consensus cancelled. Planning session ended." |
 | Force | "All OMC modes cleared. You are free to start fresh." |
 | None | "No active OMC modes detected." |
 
@@ -570,6 +604,7 @@ fi
 | Swarm | No | N/A |
 | Ultrapilot | No | N/A |
 | Pipeline | No | N/A |
+| Plan Consensus | Yes (plan file path preserved) | N/A |
 
 ## Notes
 

package/skills/doctor/SKILL.md

@@ -91,7 +91,7 @@ ls -la ~/.claude/skills/ 2>/dev/null
 
 Look for files like:
 - `architect.md`, `researcher.md`, `explore.md`, `executor.md`, etc. in agents/
-- `ultrawork.md`, `omc-default.md`, `omc-default-global.md`, `deepsearch.md`, etc. in commands/
+- `ultrawork.md`, `deepsearch.md`, etc. in commands/
 - Any oh-my-claudecode-related `.md` files in skills/
 
 ---

package/skills/help/SKILL.md

@@ -51,7 +51,7 @@ This is the **only command** you need to know. It downloads the configuration an
 
 ## For 2.x Users
 
-Your old commands still work! `/ralph`, `/ultrawork`, `/planner`, etc. all function exactly as before.
+Your old commands still work! `/ralph`, `/ultrawork`, `/plan`, etc. all function exactly as before.
 
 But now you don't NEED them - everything is automatic.
 
@@ -62,4 +62,4 @@ But now you don't NEED them - everything is automatic.
 
 ---
 
-*Version: 3.4.0*
+*Version: 3.5.5*

package/skills/hud/SKILL.md

@@ -46,11 +46,21 @@ if [ -n "$PLUGIN_VERSION" ]; then
 fi
 ```
 
-**If NOT_BUILT**, the plugin needs to be compiled. Run:
+**⚠️ CRITICAL: If NOT_BUILT, the plugin MUST be compiled before the HUD can work!**
+
+**WHY THIS HAPPENS:** The `dist/` directory contains compiled TypeScript code and is NOT stored on GitHub (it's in .gitignore). When you install the plugin from the marketplace, the build step happens automatically via the `prepare` script during `npm install`. However, if the plugin wasn't properly installed or the build failed, you'll get this error.
+
+**THE FIX:** Run npm install in the plugin directory to build it:
 ```bash
 cd ~/.claude/plugins/cache/omc/oh-my-claudecode/$PLUGIN_VERSION && npm install
 ```
-This will install dependencies and build the TypeScript code automatically (via the `prepare` script).
+
+This will:
+1. Install all dependencies
+2. Run the `prepare` script which executes `npm run build`
+3. Generate the `dist/hud/index.js` file that the HUD wrapper needs
+
+**DO NOT** try to download `dist/hud/index.js` from GitHub raw URLs - it doesn't exist there!
 
 **Step 3:** If omc-hud.mjs is MISSING or argument is `setup`, create the HUD directory and script:
 
@@ -74,6 +84,7 @@ import { join } from "node:path";
 
 async function main() {
   const home = homedir();
+  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");
@@ -82,7 +93,8 @@ async function main() {
       const versions = readdirSync(pluginCacheBase);
       if (versions.length > 0) {
         const latestVersion = versions.sort().reverse()[0];
-        const pluginPath = join(pluginCacheBase, latestVersion, "dist/hud/index.js");
+        pluginCacheDir = join(pluginCacheBase, latestVersion);
+        const pluginPath = join(pluginCacheDir, "dist/hud/index.js");
         if (existsSync(pluginPath)) {
           await import(pluginPath);
           return;
@@ -108,8 +120,12 @@ async function main() {
     }
   }
 
-  // 3. Fallback
-  console.log("[OMC] run /omc-setup to install properly");
+  // 3. Fallback - HUD not found (provide actionable error message)
+  if (pluginCacheDir) {
+    console.log(`[OMC] HUD not built. Run: cd "${pluginCacheDir}" && npm install`);
+  } else {
+    console.log("[OMC] Plugin not found. Run: /oh-my-claudecode:omc-setup");
+  }
 }
 
 main();