Oh My Claudecode

oh-my-claudecode

[](https://www.npmjs.com/package/oh-my-claudecode) [](https://www.npmjs.com/package/oh-my-claudecode) [](https://github.com/ragingstar2063/oh-my-claudecode/actions/workflows/publish.yml) [](https://github.com/ragingstar2063/oh-my-claudecode/releases/latest) [](LICENSE)

> Ph'nglui mglw'nafh Cthulhu R'lyeh wgah'nagl fhtagn. > > The agentic operations system for Claude Code.

oh-my-claudecode (OMC) turns a raw Claude Code session into a fully-orchestrated agentic environment. Instead of typing to a single model that loses its mind between sessions, you talk to Cthulhu — a primary orchestrator that plans, delegates to eleven specialized Elder God subagents, remembers what it learned last time via a persistent archive, and trims its own context between delegations so long sessions stay sharp. The specialists are real Claude Code subagents — the installer renders them into ~/.claude/agents/, so Agent(subagent_type: "shoggoth") resolves natively. It is opinionated, integrated, and end-to-end: one install, one command, every piece wired into every other piece.

---

Why this exists

A bare Claude Code session has three structural problems. OMC exists to fix all three at once.

1. No orchestration. One generalist model tries to do everything. It half-plans, half-searches, half-implements, and burns context on tasks that should be routed to specialists.
2. No memory across sessions. Every new session starts cold. You re-explain architecture, re-point to files, re-describe conventions. Built-in mechanisms exist but cap out at ~200 lines of static text.
3. Context rot within a session. Long sessions accumulate raw tool output and subagent results until the main thread is half "past grep dumps" and reasoning quality degrades. Compaction mostly happens at the limit — by then it's too late.

OMC's three pillars address each problem directly.

The three pillars

 ┌───────────────────────────────────────────────────────────────┐
 │                     oh-my-claudecode                          │
 │                                                               │
 │  ┌────────────────┐  ┌─────────────────┐  ┌───────────────┐   │
 │  │  ORCHESTRATION │  │      MEMORY     │  │    CONTEXT    │   │
 │  │                │  │                 │  │  DISCIPLINE   │   │
 │  │   Cthulhu +    │  │  Yith Archive   │  │     Block     │   │
 │  │  11 Elder God  │  │   cross-session │  │   Summarizer  │   │
 │  │   specialists  │  │   persistent    │  │   in-session  │   │
 │  │  intent gate   │  │   retrieval     │  │   trimming    │   │
 │  │  delegation    │  │                 │  │               │   │
 │  └────────────────┘  └─────────────────┘  └───────────────┘   │
 │                                                               │
 │  Lifecycle hooks · Work plans · Slash commands · Config       │
 └───────────────────────────────────────────────────────────────┘

• Orchestration. Cthulhu sits at the top of every session. Every user message passes through an intent gate that classifies the request (trivial / exploratory / implementation / ambiguous) and routes it. Trivial requests run inline. Exploratory work fans out to parallel Shoggoth searches. Implementation tasks get planned as todos first and then delegated to the right specialist. Ten Elder God subagents each own a specific domain — search, architecture advisory, planning, quality review, documentation, autonomous execution, vision analysis, and more.

• Memory. Yith Archive is a persistent, file-backed, retrieval-based memory subsystem that runs entirely in-process. New sessions start with relevant memories auto-injected from past sessions. Notable events get captured during the session and consolidated into durable lessons. No background service, no network I/O, no subprocess management — just an on-disk archive with hybrid keyword + vector retrieval.

• Context discipline. Block Summarizer wraps every delegation. Full subagent output goes to disk at .elder-gods/blocks/.md. The main thread only carries a 3-5 bullet summary forward. Cthulhu can re-read any block with the Read tool if a summary proves insufficient. Long sessions stay small; nothing is ever lost.

These aren't three plugins you pick and choose. They're one integrated system that only works because each piece knows about the others.

What you get

| Capability | What it does | |---|---| | 12 Elder God agents | Cthulhu orchestrator + 11 specialists (search, advisory, planning, review, docs, autonomy, vision, design). Installed as native Claude Code subagents in ~/.claude/agents/ by oh-my-claudecode sync — spawnable via the Agent tool, customizable via config. | | Yith Archive | Persistent cross-session memory with retrieval-based injection. Dozens of memory primitives: remember, search, consolidate, evict, crystallize, reflect, temporal graph, pattern extraction, and more. Exposed to Claude Code as a stdio MCP server with 7 tools. | | Work-packet protocol | LLM-requiring memory ops (consolidate, summarize, reflect, etc.) run in sessions with no API key — each function has a state-machine variant that emits prompts for the parent agent to execute with its own subscription auth. | | Block Summarizer | In-session delegation summarization with on-disk block archive | | 11 lifecycle hooks | Auto-activation, agent sync, memory redirect, continuous Yith capture (session start + every turn), todo enforcement, completion loops, code-quality checks, rule injection, write guards, research/design routing | | 10 slash commands | Direct-invoke any mode or flow from the Claude Code chat bar | | Intent gate | Every user message is classified and routed before Cthulhu acts | | Work plan system | Multi-step planning flow with interview → scope → plan → review before execution | | 3-level config | Defaults → user (~/.claude/oh-my-claudecode.jsonc) → project (.claude/...) with Zod validation and partial parsing | | Background agent manager | Circuit breaker, concurrency limits, task lifecycle tracking | | Project activation | .elder-gods/ marker directory opts a project into Cthulhu mode — unrelated repos stay default Claude Code | | Installer + doctor + dashboard | OpenTUI install wizard, health diagnostics, and a full-screen stats/settings dashboard (oh-my-claudecode dashboard) | | CI/CD | GitHub Actions publishing pipeline with auto-bump, tag, release, and npm push |

Installation

npx oh-my-claudecode install

When Bun is installed, the questions come as a full-screen OpenTUI wizard; otherwise plain prompts collect the same choices. The installer then:

1. Drops hook scripts into ~/.claude/hooks/
2. Registers them in ~/.claude/settings.json
3. Registers the Yith Archive MCP server in ~/.claude.json
4. Copies slash command definitions to ~/.claude/commands/
5. Creates ~/.claude/oh-my-claudecode.jsonc with sensible defaults
6. Renders all 12 agent definitions into ~/.claude/agents/ (same as oh-my-claudecode sync)
7. Downloads the local embedding model (~137 MB, progress bar) into ~/.oh-my-claudecode/models/ and verifies it with a probe embedding (opt-out --no-model)
8. Installs a background ingestion cron (every 6h, opt-out) so the memory archive stays current even when Claude Code is closed
9. Raises Claude Code's transcript retention (cleanupPeriodDays: 365, opt-out) so session history is never deleted before it's ingested
10. Leaves your existing Claude Code config intact (backup is made)

Non-interactive install (for CI or scripts):

npx oh-my-claudecode install --no-tui          # accept all defaults
npx oh-my-claudecode install --no-cron --no-retention  # skip the durability extras

Requirements

• Claude Code CLI installed (npm install -g @anthropic-ai/claude-code or equivalent)
• Node.js 20 or newer
• ~/.claude/ directory writable
• (Optional for Yith Archive summarization/consolidation) ANTHROPIC_API_KEY in ~/.oh-my-claudecode/yith/.env or as an environment variable
• (Optional for the dashboard TUI and the graphical install wizard) Bun — npm install -g bun. Everything else works without it.

Semantic memory retrieval needs nothing extra: @huggingface/transformers ships as a bundled dependency and the local embedding model is downloaded during install. If npm install fails inside sharp on a machine with a system-wide libvips (some Arch/CachyOS setups), retry with SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g oh-my-claudecode.

Quick tour — what a session looks like

Open Claude Code in any project with .elder-gods/ at its root. The cthulhu-auto hook fires on session start and injects Cthulhu's orchestrator prompt. The memory-override hook tells the session to use Yith Archive instead of the built-in memory. Yith Archive's session-start step retrieves and injects the most relevant memories from past work on this project.

You type: "add rate limiting to the auth routes."

1. Intent gate: Cthulhu verbalizes what you want and classifies it as implementation.
2. Plan: Cthulhu writes todos before touching anything.
3. Parallel exploration: Shoggoth fans out in parallel to find existing middleware, the router setup, and any similar rate-limiting patterns already in the codebase. Each result is summarized by the Block Summarizer — the raw output goes to .elder-gods/blocks/, only bullets come back to the main thread.
4. Memory lookup: Cthulhu asks Yith Archive for anything it knows about this project's middleware conventions. The archive returns (for example) "the auth middleware uses jose; the team chose jose over jsonwebtoken due to Edge compat" from last week's session.
5. Execution: Cthulhu or a delegated specialist implements the change following the retrieved conventions.
6. Verification: before declaring done, tests are run, diagnostics checked, evidence shown.
7. Persistence: anything new and worth remembering is committed to Yith Archive for future sessions.

On your next session in the same project, steps 4 and the initial memory injection give you a head start. On a completely unrelated project (no .elder-gods/), Claude Code behaves normally — OMC only activates where you've opted in.

Agent Roster

Every agent below is installed as a real Claude Code subagent file in ~/.claude/agents/.md — spawn any of them with the Agent tool (subagent_type: ""). oh-my-claudecode sync regenerates the files from your config; the agent-sync hook re-runs it automatically at session start so config edits land in the next session.

| Elder God | Model tier | Role | |-----------|-----------|------| | Cthulhu | Opus | Main orchestrator — intent gate, delegation, parallel execution, verification | | Nyarlathotep | Opus | Deep autonomous worker — end-to-end goal execution | | Azathoth | Opus | First-message planner — initial context sweep and routing | | Shub-Niggurath | Opus | Strategic planner — interview → scope → plan → Tsathoggua review | | Yog-Sothoth | Opus | Architecture/debug advisor — read-only, high-reasoning consultation | | Nodens | Opus | Frontend design specialist — intent → spec → impl → polish, vision-capable | | Hastur | Sonnet | Lightweight sub-orchestrator for bounded tasks | | Ithaqua | Sonnet | Pre-planning consultant — intent classification, anti-slop guardrails | | Tsathoggua | Sonnet | Work plan reviewer — blocker-finder, not perfectionist | | Dagon | Sonnet | External documentation and GitHub source research | | The Deep One | Sonnet | Vision agent — images, screenshots, diagrams | | Shoggoth | Haiku | Fast parallel codebase search |

Agent Behavior Enhancements (v0.2.6)

v0.2.6 introduces three orthogonal agent behavior improvements, all enabled by default. These pillars extend how agents reason and operate without changing the core delegation model.

Web Research Enforcement

When a conversation involves date-sensitive knowledge, the web-research-detector PreToolUse hook detects it and injects a directive to spawn a background Dagon research agent (Agent tool, subagent_type: "dagon", run_in_background: true) before answering — so current information lands in the context window instead of a stale training-data guess. Trigger patterns include:

• Version checks: "v1.0", "Node 18", "2024", "latest"
• API updates and breaking changes: "what changed", "deprecated", "breaking"
• Framework release schedules: "Next.js 15 coming soon", "LTS version"

Active only in OMC-activated projects (.elder-gods/ present).

Default: Enabled

Disable: Set web_research.enabled: false in ~/.claude/oh-my-claudecode.jsonc

{
  "web_research": {
    "enabled": false
  }
}

TypeScript Type Safety Linting

oh-my-claudecode lint is an AST-based type-safety linter:

• Bans any types — forces explicit typing or unknown with type guards (error)
• Unsafe casts — flags as any and as unknown (error); structured narrowing casts are allowed
• Missing return types — functions without explicit return type annotations (warn)
• @ts-ignore without reason — requires inline comments explaining suppression (warn)
• Auto-fix support — lint --fix repairs the mechanical violations (: any → : unknown, as any → as unknown, bare @ts-ignore → reasoned)
• Reasoned escape hatch — a @ts-safety: comment on the violating line acknowledges an intentional exception

Run it at pre-commit time to block unsafe code from entering the repository (oh-my-claudecode lint --staged exits 1 on errors — this repo's own .husky/pre-commit does exactly that), and export metrics for CI/CD dashboards with lint --metrics (score percentage, issue counts by rule, trend-comparable JSON snapshots).

Default: Enabled

Disable: Set type_safety.enabled: false in ~/.claude/oh-my-claudecode.jsonc

{
  "type_safety": {
    "enabled": false
  }
}

Nodens — Design Specialization Agent

Nodens is a real Claude Code subagent (installed at ~/.claude/agents/nodens.md, Opus tier) with a design-first system prompt covering:

• Accessibility: WCAG compliance checks, keyboard navigation, screen-reader

support — run via Axe-core/tooling through its Bash access

• Responsive design: component variants across breakpoints
• Playwright test generation: visual regression and interaction tests
• Figma awareness: design-token extraction (colors, typography, spacing)
• Vision capability: analyzes screenshots and design mockups (Opus tier)

When design-related queries are detected, the design-detector hook injects a routing directive telling the session to delegate the task to Nodens (Agent tool, subagent_type: "nodens") instead of handling the design inline. Active only in OMC-activated projects.

Default: Enabled

Disable: Set frontend_design.enabled: false in ~/.claude/oh-my-claudecode.jsonc

{
  "frontend_design": {
    "enabled": false
  }
}

Configuration Examples

Disable all three pillars:

{
  "web_research": { "enabled": false },
  "type_safety": { "enabled": false },
  "frontend_design": { "enabled": false }
}

Enable selective behavior (type safety and design, disable web research):

{
  "web_research": { "enabled": false },
  "type_safety": { "enabled": true },
  "frontend_design": { "enabled": true }
}

Each pillar is independent — disable any combination without affecting the others. All three are checked and active by default on fresh installs.

Yith Archive — persistent cross-session memory

Named for the Great Race of Yith from The Shadow Out of Time — mind-transferring archivists who maintain records across time — Yith Archive is OMC's canonical persistent memory subsystem. It is a novel, in-

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ragingstar2063
• Source: ragingstar2063/oh-my-claudecode
• License: MIT

Install and usage instructions live in the source repository linked above.