claudecode-omc 4.3.4

package/templates/hooks/session-start.mjs

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+// OMC Session Start Hook (Node.js)
+// Restores persistent mode states when session starts
+// Cross-platform: Windows, macOS, Linux
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Import timeout-protected stdin reader (prevents hangs on Linux/Windows, see issue #240, #524)
+let readStdin;
+try {
+  const mod = await import(pathToFileURL(join(__dirname, 'lib', 'stdin.mjs')).href);
+  readStdin = mod.readStdin;
+} catch {
+  // Fallback: inline timeout-protected readStdin if lib module is missing
+  readStdin = (timeoutMs = 5000) => new Promise((resolve) => {
+    const chunks = [];
+    let settled = false;
+    const timeout = setTimeout(() => {
+      if (!settled) { settled = true; process.stdin.removeAllListeners(); process.stdin.destroy(); resolve(Buffer.concat(chunks).toString('utf-8')); }
+    }, timeoutMs);
+    process.stdin.on('data', (chunk) => { chunks.push(chunk); });
+    process.stdin.on('end', () => { if (!settled) { settled = true; clearTimeout(timeout); resolve(Buffer.concat(chunks).toString('utf-8')); } });
+    process.stdin.on('error', () => { if (!settled) { settled = true; clearTimeout(timeout); resolve(''); } });
+    if (process.stdin.readableEnded) { if (!settled) { settled = true; clearTimeout(timeout); resolve(Buffer.concat(chunks).toString('utf-8')); } }
+  });
+}
+
+function readJsonFile(path) {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJsonFile(path, data) {
+  try {
+    const dir = join(path, '..');
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(path, JSON.stringify(data, null, 2), 'utf-8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function checkForUpdates(currentVersion) {
+  const cacheFile = join(homedir(), '.omc', 'update-check.json');
+  const now = Date.now();
+  const CACHE_DURATION = 24 * 60 * 60 * 1000; // 24 hours
+
+  // Check cache first
+  const cached = readJsonFile(cacheFile);
+  if (cached && cached.timestamp && (now - cached.timestamp) < CACHE_DURATION) {
+    return cached.updateAvailable ? cached : null;
+  }
+
+  // Fetch latest version from npm
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 2000);
+
+    const response = await fetch('https://registry.npmjs.org/oh-my-claudecode/latest', {
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      throw new Error('Network response was not ok');
+    }
+
+    const data = await response.json();
+    const latestVersion = data.version;
+
+    const updateAvailable = compareVersions(latestVersion, currentVersion) > 0;
+
+    const cacheData = {
+      timestamp: now,
+      latestVersion,
+      currentVersion,
+      updateAvailable
+    };
+
+    writeJsonFile(cacheFile, cacheData);
+
+    return updateAvailable ? cacheData : null;
+  } catch (error) {
+    // Silent fail - network unavailable or timeout
+    return null;
+  }
+}
+
+function compareVersions(v1, v2) {
+  const parts1 = v1.replace(/^v/, '').split('.').map(Number);
+  const parts2 = v2.replace(/^v/, '').split('.').map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    const diff = (parts1[i] || 0) - (parts2[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+// ============================================================================
+// Notepad Support
+// ============================================================================
+
+const NOTEPAD_FILENAME = 'notepad.md';
+const PRIORITY_HEADER = '## Priority Context';
+const WORKING_MEMORY_HEADER = '## Working Memory';
+
+/**
+ * Get notepad path in .omc directory
+ */
+function getNotepadPath(directory) {
+  return join(directory, '.omc', NOTEPAD_FILENAME);
+}
+
+/**
+ * Read notepad content
+ */
+function readNotepad(directory) {
+  const notepadPath = getNotepadPath(directory);
+  if (!existsSync(notepadPath)) {
+    return null;
+  }
+  try {
+    return readFileSync(notepadPath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract a section from notepad content
+ */
+function extractSection(content, header) {
+  // Match from header to next section (## followed by space and non-# char)
+  const regex = new RegExp(`${header}\\n([\\s\\S]*?)(?=\\n## [^#]|$)`);
+  const match = content.match(regex);
+  if (!match) {
+    return null;
+  }
+  // Remove HTML comments and trim
+  let section = match[1];
+  section = section.replace(/<!--[\s\S]*?-->/g, '').trim();
+  return section || null;
+}
+
+/**
+ * Get Priority Context section (for injection)
+ */
+function getPriorityContext(directory) {
+  const content = readNotepad(directory);
+  if (!content) {
+    return null;
+  }
+  return extractSection(content, PRIORITY_HEADER);
+}
+
+/**
+ * Format notepad context for session injection
+ */
+function formatNotepadContext(directory) {
+  const priorityContext = getPriorityContext(directory);
+  if (!priorityContext) {
+    return null;
+  }
+  return `<notepad-priority>
+
+## Priority Context
+
+${priorityContext}
+
+</notepad-priority>`;
+}
+
+async function main() {
+  try {
+    const input = await readStdin();
+    let data = {};
+    try { data = JSON.parse(input); } catch {}
+
+    const directory = data.cwd || data.directory || process.cwd();
+    const sessionId = data.sessionId || data.session_id || data.sessionid || '';
+    const messages = [];
+
+    // Check for updates (non-blocking)
+    // Read version from OMC's own package.json, not the project's (fixes #516)
+    let currentVersion = null;
+    for (let i = 1; i <= 4; i++) {
+      const candidate = join(__dirname, ...Array(i).fill('..'), 'package.json');
+      const pkg = readJsonFile(candidate);
+      if (pkg?.name === 'oh-my-claudecode' && pkg?.version) {
+        currentVersion = pkg.version;
+        break;
+      }
+    }
+
+    const updateInfo = currentVersion ? await checkForUpdates(currentVersion) : null;
+    if (updateInfo) {
+      // Read config to check autoUpgradePrompt preference
+      const configPath = join(homedir(), '.claude', '.omc-config.json');
+      const omcConfig = readJsonFile(configPath) || {};
+      const autoUpgradePrompt = omcConfig.autoUpgradePrompt !== false; // default: true
+
+      if (autoUpgradePrompt) {
+        messages.push(`<session-restore>
+
+[OMC AUTO-UPGRADE AVAILABLE]
+
+oh-my-claudecode v${updateInfo.latestVersion} is available (current: v${updateInfo.currentVersion}).
+
+ACTION: Use AskUserQuestion to ask the user if they want to upgrade now. Offer these options:
+- "Upgrade now" (Recommended): Run \`npm install -g oh-my-claudecode@latest\` via Bash, then run \`omc install --force --skip-claude-check --refresh-hooks\` to reconcile hooks and CLAUDE.md
+- "Skip this time": Continue the session without upgrading
+- "Don't ask again": Tell the user to set "autoUpgradePrompt": false in ~/.claude/.omc-config.json to disable future prompts
+
+Keep the prompt brief. If the user accepts, execute the upgrade commands and report the result.
+
+</session-restore>
+
+---
+`);
+      } else {
+        messages.push(`<session-restore>
+
+[OMC UPDATE AVAILABLE]
+
+A new version of oh-my-claudecode is available: v${updateInfo.latestVersion} (current: ${updateInfo.currentVersion})
+
+To update, run: omc update
+
+</session-restore>
+
+---
+`);
+      }
+    }
+
+    // Check for ultrawork state - only restore if session matches (issue #311)
+    const ultraworkState = readJsonFile(join(directory, '.omc', 'state', 'ultrawork-state.json'))
+      || readJsonFile(join(homedir(), '.omc', 'state', 'ultrawork-state.json'));
+
+    if (ultraworkState?.active && (!ultraworkState.session_id || ultraworkState.session_id === sessionId)) {
+      messages.push(`<session-restore>
+
+[ULTRAWORK MODE RESTORED]
+
+You have an active ultrawork session from ${ultraworkState.started_at}.
+Original task: ${ultraworkState.original_prompt}
+
+Continue working in ultrawork mode until all tasks are complete.
+
+</session-restore>
+
+---
+`);
+    }
+
+    // Check for incomplete todos (project-local only, not global ~/.claude/todos/)
+    // NOTE: We intentionally do NOT scan the global ~/.claude/todos/ directory.
+    // That directory accumulates todo files from ALL past sessions across all
+    // projects, causing phantom task counts in fresh sessions (see issue #354).
+    const localTodoPaths = [
+      join(directory, '.omc', 'todos.json'),
+      join(directory, '.claude', 'todos.json')
+    ];
+    let incompleteCount = 0;
+    for (const todoFile of localTodoPaths) {
+      if (existsSync(todoFile)) {
+        try {
+          const data = readJsonFile(todoFile);
+          const todos = data?.todos || (Array.isArray(data) ? data : []);
+          incompleteCount += todos.filter(t => t.status !== 'completed' && t.status !== 'cancelled').length;
+        } catch {}
+      }
+    }
+
+    if (incompleteCount > 0) {
+      messages.push(`<session-restore>
+
+[PENDING TASKS DETECTED]
+
+You have ${incompleteCount} incomplete tasks from a previous session.
+Please continue working on these tasks.
+
+</session-restore>
+
+---
+`);
+    }
+
+    // Check for notepad Priority Context (ALWAYS loaded on session start)
+    const notepadContext = formatNotepadContext(directory);
+    if (notepadContext) {
+      messages.push(`<session-restore>
+
+[NOTEPAD PRIORITY CONTEXT LOADED]
+
+${notepadContext}
+
+</session-restore>
+
+---
+`);
+    }
+
+    // Load root AGENTS.md if it exists (deepinit output - issue #613)
+    // This ensures AI-readable directory documentation is available from session start
+    const agentsMdPath = join(directory, 'AGENTS.md');
+    if (existsSync(agentsMdPath)) {
+      try {
+        let agentsContent = readFileSync(agentsMdPath, 'utf-8').trim();
+        if (agentsContent) {
+          // Truncate to ~5000 tokens (20000 chars) to avoid context bloat
+          const MAX_AGENTS_CHARS = 20000;
+          let truncationNotice = '';
+          if (agentsContent.length > MAX_AGENTS_CHARS) {
+            agentsContent = agentsContent.slice(0, MAX_AGENTS_CHARS);
+            truncationNotice = `\n\n[Note: Content was truncated. For full context, read: ${agentsMdPath}]`;
+          }
+          messages.push(`<session-restore>
+
+[ROOT AGENTS.md LOADED]
+
+The following project documentation was generated by deepinit to help AI agents understand the codebase:
+
+${agentsContent}${truncationNotice}
+
+</session-restore>
+
+---
+`);
+        }
+      } catch {
+        // Skip if file can't be read
+      }
+    }
+
+    // MCP tool discovery reminder (deferred tools need ToolSearch before use)
+    messages.push(`<session-restore>
+
+[MCP TOOL DISCOVERY REQUIRED]
+
+MCP tools (ask_codex, ask_gemini) are deferred and NOT in your tool list yet.
+Before first use, call ToolSearch("mcp") to discover all available MCP tools.
+If ToolSearch returns no results, MCP servers are not configured -- use Claude agent fallbacks instead.
+
+</session-restore>
+
+---
+`);
+
+    if (messages.length > 0) {
+      console.log(JSON.stringify({
+        continue: true,
+        hookSpecificOutput: {
+          hookEventName: 'SessionStart',
+          additionalContext: messages.join('\n')
+        }
+      }));
+    } else {
+      console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+    }
+  } catch (error) {
+    console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+  }
+}
+
+main();

package/templates/hooks/stop-continuation.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// OMC Stop Continuation Hook (Simplified)
+// Always allows stop - soft enforcement via message injection only.
+
+import { readStdin } from './lib/stdin.mjs';
+
+async function main() {
+  // Consume stdin with timeout protection (required for hook protocol)
+  await readStdin();
+  // Always allow stop
+  console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+}
+
+main();

package/templates/rules/README.md

@@ -0,0 +1,41 @@
+# Rules Templates
+
+This directory contains rule templates that you can copy to your project's `.claude/rules/` directory.
+
+## How to Use
+
+1. Create a `.claude/rules/` directory in your project root
+2. Copy the templates you want to use
+3. Customize them for your project
+4. Rules in `.claude/rules/*.md` will be auto-discovered and injected into context
+
+## Available Templates
+
+| Template | Purpose |
+|----------|---------|
+| `coding-style.md` | Code style and formatting guidelines |
+| `testing.md` | Testing requirements and coverage targets |
+| `security.md` | Security checklist and best practices |
+| `performance.md` | Performance guidelines and model selection |
+| `git-workflow.md` | Git commit and PR workflow |
+| `karpathy-guidelines.md` | Coding discipline — think before coding, simplicity, surgical changes |
+
+## Auto-Discovery
+
+When you place rules in `.claude/rules/`, they are automatically discovered by oh-my-claudecode and injected into the context for all agents working in your project.
+
+## Example
+
+```bash
+# Copy templates to your project
+mkdir -p .claude/rules
+cp templates/rules/security.md .claude/rules/
+cp templates/rules/testing.md .claude/rules/
+
+# Customize for your project
+# Edit .claude/rules/security.md to add project-specific checks
+```
+
+## Customization
+
+Each template has `[CUSTOMIZE]` markers where you should add project-specific guidelines.

package/templates/rules/coding-style.md

@@ -0,0 +1,74 @@
+# Coding Style Rules
+
+## Immutability (CRITICAL)
+
+ALWAYS create new objects, NEVER mutate:
+
+```javascript
+// WRONG: Mutation
+function updateUser(user, name) {
+  user.name = name  // MUTATION!
+  return user
+}
+
+// CORRECT: Immutability
+function updateUser(user, name) {
+  return { ...user, name }
+}
+```
+
+## File Organization
+
+MANY SMALL FILES > FEW LARGE FILES:
+- High cohesion, low coupling
+- 200-400 lines typical, 800 max
+- Extract utilities from large components
+- Organize by feature/domain, not by type
+
+## Error Handling
+
+ALWAYS handle errors comprehensively:
+
+```typescript
+try {
+  const result = await riskyOperation()
+  return result
+} catch (error) {
+  console.error('Operation failed:', error)
+  throw new Error('User-friendly error message')
+}
+```
+
+## Input Validation
+
+ALWAYS validate user input:
+
+```typescript
+import { z } from 'zod'
+
+const schema = z.object({
+  email: z.string().email(),
+  age: z.number().int().min(0).max(150)
+})
+
+const validated = schema.parse(input)
+```
+
+## Code Quality Checklist
+
+Before marking work complete:
+- [ ] Code is readable and well-named
+- [ ] Functions are small (<50 lines)
+- [ ] Files are focused (<800 lines)
+- [ ] No deep nesting (>4 levels)
+- [ ] Proper error handling
+- [ ] No console.log statements
+- [ ] No hardcoded values
+- [ ] Immutable patterns used
+
+## [CUSTOMIZE] Project-Specific Style
+
+Add your project-specific coding style rules here:
+- Naming conventions
+- File structure requirements
+- Framework-specific patterns

package/templates/rules/git-workflow.md

@@ -0,0 +1,41 @@
+# Git Workflow Rules
+
+## Commit Message Format
+
+```
+<type>: <description>
+
+<optional body>
+```
+
+Types: feat, fix, refactor, docs, test, chore, perf, ci
+
+## Pull Request Workflow
+
+When creating PRs:
+1. Analyze full commit history (not just latest commit)
+2. Use `git diff [base-branch]...HEAD` to see all changes
+3. Draft comprehensive PR summary
+4. Include test plan with TODOs
+5. Push with `-u` flag if new branch
+
+## Feature Implementation Workflow
+
+1. **Plan First** - Use `planner` agent
+2. **TDD Approach** - Use `tdd-guide` agent
+3. **Code Review** - Use `code-reviewer` agent after writing code
+4. **Commit** - Follow conventional commits format
+
+## Branch Naming
+
+- `feature/` - New features
+- `fix/` - Bug fixes
+- `refactor/` - Code refactoring
+- `docs/` - Documentation changes
+
+## [CUSTOMIZE] Project-Specific Git Rules
+
+Add your project-specific git workflow here:
+- Branch protection rules
+- Required reviewers
+- CI/CD requirements

package/templates/rules/karpathy-guidelines.md

@@ -0,0 +1,59 @@
+# Karpathy Coding Guidelines
+
+Behavioral guidelines to reduce common LLM coding mistakes, derived from Andrej Karpathy's observations on LLM coding pitfalls. These principles bias toward caution over speed — for trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it — don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

package/templates/rules/performance.md

@@ -0,0 +1,40 @@
+# Performance Rules
+
+## Model Selection Strategy
+
+**Haiku** (90% of Sonnet capability, 3x cost savings):
+- Lightweight agents with frequent invocation
+- Code generation and exploration
+- Worker agents in multi-agent systems
+
+**Sonnet** (Best coding model):
+- Main development work
+- Orchestrating multi-agent workflows
+- Complex coding tasks
+
+**Opus** (Deepest reasoning):
+- Complex architectural decisions
+- Maximum reasoning requirements
+- Research and analysis tasks
+
+## Context Window Management
+
+Avoid last 20% of context window for:
+- Large-scale refactoring
+- Feature implementation spanning multiple files
+- Debugging complex interactions
+
+## Algorithm Efficiency
+
+Before implementing:
+- [ ] Consider time complexity
+- [ ] Avoid O(n^2) when O(n log n) possible
+- [ ] Use appropriate data structures
+- [ ] Cache expensive computations
+
+## [CUSTOMIZE] Project-Specific Performance
+
+Add your project-specific performance requirements here:
+- Response time targets
+- Bundle size limits
+- Database query limits

package/templates/rules/security.md

@@ -0,0 +1,41 @@
+# Security Rules
+
+## Mandatory Security Checks
+
+Before ANY commit:
+- [ ] No hardcoded secrets (API keys, passwords, tokens)
+- [ ] All user inputs validated
+- [ ] SQL injection prevention (parameterized queries)
+- [ ] XSS prevention (sanitized HTML)
+- [ ] CSRF protection enabled
+- [ ] Authentication/authorization verified
+- [ ] Rate limiting on all endpoints
+- [ ] Error messages don't leak sensitive data
+
+## Secret Management
+
+```typescript
+// NEVER: Hardcoded secrets
+const apiKey = "sk-proj-xxxxx"
+
+// ALWAYS: Environment variables
+const apiKey = process.env.API_KEY
+if (!apiKey) throw new Error('API_KEY not configured')
+```
+
+## Security Response Protocol
+
+If security issue found:
+1. STOP immediately
+2. Use `security-reviewer` agent
+3. Fix CRITICAL issues before continuing
+4. Rotate any exposed secrets
+5. Review entire codebase for similar issues
+
+## [CUSTOMIZE] Project-Specific Security
+
+Add your project-specific security requirements here:
+- Authentication method
+- Authorization rules
+- Data encryption requirements
+- Compliance requirements (GDPR, HIPAA, etc.)