oh-my-claudecode v4.0.0

Release Date: 2026-02-05

Breaking Changes

Node.js 20 Required - Minimum Node.js version increased from 18 to 20. Users on Node.js 18 must upgrade before using this version. This aligns with Node.js LTS schedule (Node 18 EOL: April 2025).

MCP Response Contract (#424) - ask_codex and ask_gemini now return file paths instead of inline content. output_file parameter is now required. Added working_directory parameter for path resolution.
Prompt Parameter Deprecated (#421) - The prompt parameter for ask_codex and ask_gemini is removed. Use prompt_file instead, which writes prompts to files to avoid OS argument length limits.
Agent Role Required - agent_role parameter is now required for both ask_codex and ask_gemini tools

MCP Core Modules - Extracted shared Codex/Gemini business logic into codex-core.ts and gemini-core.ts, eliminating code duplication between in-process SDK servers and standalone stdio servers
Slim Server Wrappers - Reduced codex-server.ts, codex-standalone-server.ts, gemini-server.ts, and gemini-standalone-server.ts to thin transport wrappers (~40-70 lines each)
Build Scripts - Updated esbuild scripts with global npm module resolution banner for proper native module loading

Codex/Gemini Agent Routing - Codex (ask_codex) now recommended only for reviewer and planning agents (architect, planner, critic, analyst, code-reviewer, security-reviewer, tdd-guide). Gemini (ask_gemini) recommended only for design agents (designer, writer, vision).
CLAUDE.md Compacted - Reduced from 679 to 389 lines (43% smaller). All 33 agents, all skills, and all MCP tools with descriptions now inline.
Agent Tiers Reference - Added External AI Consultation section with strict Codex/Gemini routing per agent domain
Model Routing Enforcement (#384) - Advisory agents enforce read-only behavior; execution agents get full tool access
Gemini Model Fallback Chain - gemini-3-pro-preview → gemini-3-flash-preview → gemini-2.5-pro → gemini-2.5-flash

Levenshtein LRU Cache - Added LRU cache for Levenshtein distance calculations in skill matching
Skill Metadata Cache - Added 30-second TTL cache for skill metadata
Debounced State Writes - Subagent tracker now batches state file writes with 100ms debounce
Pre-compiled Regex Patterns - Pre-compiled 15+ regex patterns in hot paths
Parallel State File Reads - Pre-compact module now reads all state files in parallel
Session Index Caching - Token tracker caches session indices with 5-minute TTL
Space-Optimized Levenshtein - Algorithm now uses O(n) space instead of O(n²)

Job Management Tools (#420) - wait_for_job, check_job_status, kill_job, list_jobs for background Codex/Gemini job control
Version Drift Detection (#422) - Automatic detection and cleanup of stale plugin versions
HUD Fine-Grained Control (#399) - Configurable sessionHealth display elements
MCP Prompt File Parameters (#416) - New prompt_file and output_file parameters
MCP Prompt Persistence Audit Trail - Prompts persisted to disk for debugging and replay
Plugin-Scoped Codex/Gemini MCP Servers - Proper MCP server discovery
MCP System Prompt Injection - Better agent context injection
Built-in MCP Tools - State, notepad, and project memory tools
Configurable Stop Hook Callbacks (#395)
Swarm Aggressive Mode - Wave-based spawning and micro-task decomposition
Codex/Gemini Timeout Increase - Increased to 1 hour for complex analysis

Per-Directory Debounce - Fixed race condition in subagent tracker
TOCTOU Race Condition - Fixed time-of-check-time-of-use race in pre-compact
True LRU Cache - Fixed Levenshtein cache to use true LRU eviction
Session Index Off-by-One - Fixed token tracker session index calculation
Cache Hit Rate Formula (#425) - Corrected calculation (was exceeding 100%)
HUD Token Formatting (#417) - Fixed returning "0.999k" for values under 1000
LSP goto_definition Null Safety (#417) - Fixed crash on LocationLink objects
MCP Output File Suffix (#419) - Fixed writing to .raw suffix
MCP Stdin Prompt Piping - Fixed OS argument length limit issues
HUD Semver Sorting (#373) - Fixed version comparison
Security Hardening - Cross-platform compatibility and security hardening
Codex/Gemini Role Allowlists - Fixed to match documented routing

npm install -g oh-my-claude-sisyphus@4.0.0