oh-my-claudecode

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/<timestamp>.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/<name>.md — spawn any of them with the Agent tool (subagent_type: "<name>"). 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: <reason> 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 <path> (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-process combined implementation inspired by the broader ecosystem of agent-memory research, rewritten from scratch to fit a single-process Claude Code plugin instead of a multi-client service.

What it gives you

• Hybrid retrieval — BM25 keyword search combined with semantic embedding search (local nomic model by default, 768 dims, lazy-downloaded on first use) and a graph retrieval weight. Memories AND observations both land in the same index at write-time, so yith_search returns freshly-written memories immediately.
• Exposed as an MCP server — during install, Yith Archive is registered with Claude Code as a stdio MCP server named yith-archive. Sessions get 7 tools: yith_remember, yith_search, yith_recall, yith_context, yith_observe, yith_commit_work, and yith_trigger (escape hatch for ~90 advanced memory functions, with a curated top-20 catalog embedded in the tool description).
• Rich memory primitives — remember, search, recall, context, observe, plus dozens more under the hood: consolidation pipelines, temporal graph retrieval, lesson crystallization, pattern extraction, eviction and retention policies, file-scoped memory index, sliding window compression, query expansion, working memory, session timeline, export/import.
• Automatic capture — notable events during a session can be observed into the archive; a background consolidation pass merges similar memories into distilled lessons.
• Zero external runtime — file-backed JSON storage at ~/.oh-my-claudecode/yith/necronomicon.json (legacy installs are auto-migrated from store.json on boot). Atomic writes via tmpfile + rename so a crash mid-write can't corrupt the tome. No database, no background server, no subprocess, no network, no ports to manage. The MCP server itself is registered user-level in ~/.claude.json.
• Crash-safe work-packet flows — pending continuations for LLM-requiring operations persist to the same store and survive server restarts; resuming with the same continuation token picks up where the flow left off.
• Replaces Claude Code's built-in auto-memory via the memory-override SessionStart hook, which tells the session not to write to the built-in memory files. Disable the override with disabled_hooks: ["memory-override"] if you prefer to keep the built-in system active.

The binding ritual (oh-my-claudecode bind)

Fresh installs start with an empty necronomicon.json. To populate it with history, run one command in your terminal:

oh-my-claudecode bind

This kicks off a six-phase ritual with a real ANSI TUI (progress bars, section headers, per-phase status):

1. Embedding sigil — downloads the local nomic embedding model (~137 MB) with a live byte-counter progress bar.
2. Claude Code transcripts — scans every subdirectory under ~/.claude/projects/ (every project you've ever opened a session in), parses the .jsonl transcripts, and writes one raw observation per user prompt / assistant text / tool call.
3. Opencode grimoire — if you're migrating from oh-my-opencode, the ritual auto-detects ~/.local/share/opencode/opencode.db and imports every project / session / message / part it finds.
4. Sisyphus migration — walks your home looking for legacy .sisyphus/ directories (the oh-my-opencode equivalent of .elder-gods/) and copies plans, handoffs, and evidence into the new layout without touching the source.
5. Project code scan — for each project the CLI has seen, walks the code tree (gitignore-aware) and seeds preliminary memories: language stats, package metadata, README sections, directory tree.
6. Sealing — reports how many raw observations are queued for compression and points you at the next step.

The ritual is resumable: if any phase errors or you interrupt it, re-running oh-my-claudecode bind picks up from the failed phase via the KV.bindState cursor — no manual intervention required.

Phase 2 (LLM-dependent compression of raw observations into searchable memories) runs inside a Claude Code session via the work-packet loop. Either:

• Open Claude Code and run /necronomicon-bind — uses your subscription auth via the MCP work-packet protocol.
• Or rely on the ingestion cron (installed by default during oh-my-claudecode install; reinstall or retune with oh-my-claudecode bind --install-cron --interval 6h). The cron tick ingests new transcripts and drives compression unattended via claude -p. No API key needed.

Capture durability

Three mechanisms guarantee session history reaches the archive before Claude Code's transcript cleanup can delete it:

1. Session hooks — yith-capture ingests at session start, after every assistant turn, immediately before context compaction, and when a session ends (/clear, exit) — so neither forced compaction nor a manual clear can lose anything: the full pre-compaction transcript is already in the archive, and the post-compact/post-clear session can recall it with yith_search. Compression drains when the queue passes 20 observations or any observation sits raw for 24 hours.
2. Background cron — the default 6-hour bind --resume tick captures even when Claude Code never opens.
3. Retention raise — the installer sets cleanupPeriodDays: 365 in Claude Code's settings (with your consent) so the deletion window can never outrun ingestion.

Every successful transcript ingestion stamps a health beacon (~/.oh-my-claudecode/yith/.last-bind-success). oh-my-claudecode doctor and the Cthulhu session preflight warn when the beacon is stale, the CLI is missing, or the cron is gone — capture can't silently break.

Work-packet protocol — LLM ops without an API key

13 of Yith's memory operations need an LLM to do their work (crystallize, consolidate, consolidate-pipeline, compress, summarize, flow-compress, graph-extract, temporal-graph-extract, expand-query, skill-extract, reflect, enrich-window, enrich-session). If Yith has its own ANTHROPIC_API_KEY in ~/.oh-my-claudecode/yith/.env, these run directly in-process.

If no API key is configured, the session doesn't lose access to these functions — they just route through the work-packet protocol instead. Each LLM-requiring function has a -step state-machine variant that emits WorkPacket descriptors (systemPrompt + userPrompt + metadata) instead of calling the LLM itself. The flow looks like this:

yith_trigger("mem::consolidate-pipeline", {...})
   ↓
{status: "needs_llm_work", workPackets: [...], continuation: "wp_..."}
   ↓
Claude Code session executes each packet's prompts with its own subscription auth
   ↓
yith_commit_work(continuation, [{id, completion}, ...])
   ↓
{status: "needs_llm_work", ...} (another round) OR {status: "success", result}

Multi-call functions like consolidate-pipeline chain multiple rounds (semantic → reflect → procedural). Loop functions like consolidate / reflect / enrich-session emit packets in adaptive batches via planLoopBatches — small loops go "all-at-once" in one round, large loops batch in chunks sized by packet count or total prompt bytes. doctor --yith-functions marks LLM-requiring functions with a ⚡ so callers know to expect the needs_llm_work envelope.

Programmatic API

import { createYithArchive } from "oh-my-claudecode"

const archive = createYithArchive()  // defaults to ~/.oh-my-claudecode/yith

await archive.remember({
  content: "The auth middleware uses jose — jsonwebtoken was removed due to Edge incompatibility.",
  type: "architecture",
  concepts: ["auth", "middleware", "jose"],
  files: ["src/middleware/auth.ts"],
})

const results = await archive.search({ query: "how does auth work", limit: 5 })

// When you're done
await archive.shutdown()

Environment configuration

Yith Archive reads its own variables from ~/.oh-my-claudecode/yith/.env (or the ambient environment):

| Variable | Purpose | |---|---| | ANTHROPIC_API_KEY | LLM calls for summarization, consolidation, reflection | | EMBEDDING_PROVIDER | local (default — install pins it) or an explicit hosted opt-in: gemini/openai/voyage/cohere/openrouter with the matching API key. Ambient API keys in your shell are deliberately ignored — your session history never routes through a hosted API unless you ask. | | YITH_MODEL_CACHE | Where the local model lives (default ~/.oh-my-claudecode/models) | | AUTO_FORGET_ENABLED | false to disable background eviction sweeps | | CONSOLIDATION_ENABLED | false to disable automatic memory consolidation | | YITH_GRAPH_WEIGHT | Weight of graph retrieval in hybrid search (default 0.3) | | YITH_DEBUG | Any value enables verbose logging |

Block Summarizer — in-session context discipline

Long Claude Code sessions die a slow death: every delegation to a subagent pipes the full raw output back into the main context. After an hour of real work, half of what's in front of the model is yesterday's grep dumps, and reasoning quality suffers accordingly.

Block Summarizer is OMC's solution: at every delegation boundary, the full output is written to disk and the main thread continues from a 3-5 bullet summary. The raw block is never lost — it's sitting at .elder-gods/blocks/<timestamp>-<slug>.md and can be re-read with the Read tool if Cthulhu needs it.

The technique is a novel combined implementation inspired by the broader ecosystem of context-compression research, adapted specifically to the delegation boundary (which is the only "block boundary" a harness can cleanly observe from outside the model).

How Cthulhu uses it

Cthulhu's orchestrator prompt has two relevant principles baked in:

6. Summarize after delegation — after every Agent(subagent_type=...) call, write the full output to .elder-gods/blocks/<timestamp>-<slug>.md and continue reasoning from a 3-5 bullet summary.
7. Persist insights to Yith Archive — salient facts from delegation blocks become durable memories.

You don't have to do anything to enable this — it's automatic when Cthulhu is active. Blocks accumulate as a replayable audit trail of every delegation the session performed. Commit them, grep them, diff them, or nuke the .elder-gods/blocks/ directory between runs.

Programmatic API

import { summarizeBlock } from "oh-my-claudecode"

const { summary, blockPath, blockId } = await summarizeBlock({
  agentName: "shoggoth",
  fullOutput: rawSubagentOutput,
  taskDescription: "Find all usages of the legacy auth helper",
})

Slash Commands

After installation these are available in Claude Code sessions:

| Command | Description | |---------|-------------| | /cthulhu | Activate Cthulhu orchestrator mode (also creates .elder-gods/ on first use) | | /necronomicon-bind | Necronomicon binding ritual — shells out to oh-my-claudecode bind (real TUI, all-projects ingestion, opencode import, sisyphus migration, preliminary code scan) then drains pending compression via the work-packet loop using this session's LLM | | /shoggoth | Fast parallel codebase search | | /yog-sothoth | Consult the architecture/debug advisor | | /elder-loop | Start the self-referential completion loop | | /cancel-elder-loop | Stop the active completion loop | | /old-ones-init | Generate the hierarchical AGENTS.md knowledge base | | /invoke-shub | Strategic planning interview flow | | /session-handoff | Create a detailed session continuation document | | /exorcise-ai-slop | Purge AI-generated code smells from the current codebase |

Lifecycle Hooks

11 hooks are installed into Claude Code's settings.json. They provide the connective tissue between OMC's subsystems and the live session. Hooks marked scoped only act in OMC-activated projects (.elder-gods/ present) — unrelated repos keep stock Claude Code behavior. yith-capture and agent-sync are deliberately global: memory capture and agent freshness apply machine-wide.

| Hook | Event | Scope | Description | |------|-------|-------|-------------| | cthulhu-auto | SessionStart | scoped | Auto-activate Cthulhu orchestrator mode; reports Necronomicon binding state and capture health | | memory-override | SessionStart | scoped | Redirect persistent memory writes from Claude Code's built-in auto-memory to Yith Archive | | agent-sync | SessionStart | global | Re-render ~/.claude/agents/ (and project-level overrides) in the background so config edits land in the next session | | yith-capture | SessionStart + Stop + PreCompact + SessionEnd | global | Continuous Yith ingestion — at session start, after every assistant turn, immediately before context compaction, and when the session ends (/clear, exit), spawns a background bind --resume --claude-only to pull new transcript lines into the archive, and spawns claude -p to drain pending compression when the queue passes 20 observations or sits raw for 24h. PreCompact/SessionEnd bypass the debounce. Non-blocking; fail-safe. | | todo-continuation | Stop | global | Inject a reminder to continue if incomplete todos exist when stopping | | elder-loop | Stop | self-gating | Self-referential completion loop — acts only while a loop you started via /elder-loop is active | | comment-checker | PostToolUse | scoped | Warn when AI-slop comments are introduced (comments that explain obvious code) | | rules-injector | PreToolUse | scoped | Auto-inject .elder-gods/rules/*.md into every agent's context | | write-guard | PreToolUse | scoped | Warn when Write is used on an existing file (suggest Edit instead) | | web-research-detector | PreToolUse | scoped | Detect date-sensitive queries and direct a background Dagon research spawn | | design-detector | PreToolUse | scoped | Detect design/frontend tasks and direct routing to Nodens |

Disable specific hooks via config:

{ "disabled_hooks": ["comment-checker", "write-guard"] }

Activation via .elder-gods/

By default, Cthulhu only takes over when you explicitly type /cthulhu. To auto-activate on every new session in a project, create the marker directory at the project root:

mkdir .elder-gods

The cthulhu-auto hook walks upward from the current directory looking for .elder-gods/. If it finds one, Cthulhu's orchestrator prompt is injected at SessionStart; if not, nothing happens — unrelated projects keep their normal Claude Code behavior. You can also drop architectural rules into .elder-gods/rules/*.md and work plans into .elder-gods/plans/*.md — the other hooks will pick them up automatically.

Turn auto-activation off globally with:

{ "disabled_hooks": ["cthulhu-auto"] }

Configuration

Config file: ~/.claude/oh-my-claudecode.jsonc (user-level) and/or .claude/oh-my-claudecode.jsonc (project-level). Project config overrides user config for scalar and object fields. Array fields like disabled_* are unioned across levels.

Agent settings are applied by oh-my-claudecode sync (run automatically at install and by the agent-sync hook at session start): user-level config renders into ~/.claude/agents/, and project-level agent overrides render into the project's .claude/agents/, where they shadow the user-level agent of the same name. One limitation: an agent can be disabled machine-wide (disabled_agents at user level) but not per-project — Claude Code's project agents shadow, they don't remove.

{
  // Override models for specific agents
  "agents": {
    "cthulhu": {
      "model": "opus",
      "prompt_append": "Always write tests for every function you create."
    },
    "shoggoth": {
      "model": "haiku"
    }
  },

  // Disable agents you don't need
  "disabled_agents": ["nyarlathotep", "the-deep-one"],

  // Disable specific lifecycle hooks
  "disabled_hooks": ["comment-checker", "write-guard"],

  // Elder Loop settings (completion loop)
  "elder_loop": {
    "max_iterations": 15,
    "strategy": "continue"  // or "reset"
  },

  // Background agent limits
  "background_task": {
    "max_concurrent": 8,
    "circuit_breaker_threshold": 3
  }
}

Available models

Only Claude models are supported. Agent definitions use the tier aliases opus / sonnet / haiku — Claude Code resolves each alias to the current model of that tier at runtime, so installed agents never go stale when a new model ships. To pin an exact snapshot, set a full claude-* model ID in the agent's model field instead; it passes through verbatim.

After editing config, run oh-my-claudecode sync (or just start a new session — the agent-sync hook re-renders automatically).

Project-Level Setup

Architectural rules

Place rules in .elder-gods/rules/*.md. They are auto-injected into every agent's context by the rules-injector hook, so every specialist sees them without you repeating yourself:

.elder-gods/
└── rules/
    ├── no-any.md          # No TypeScript `any`
    ├── test-coverage.md   # Minimum test requirements
    └── naming-conv.md     # Naming conventions

Example .elder-gods/rules/no-any.md:

# No TypeScript `any`

NEVER use `any` type. Use `unknown` and narrow appropriately, or define a proper type.
This rule is non-negotiable. Tsathoggua will reject any plan that introduces `any`.

Work plans

Plans are stored in .elder-gods/plans/*.md and reviewed by Tsathoggua before execution.

Use /invoke-shub to start the planning flow:

1. Shub-Niggurath surveys the codebase
2. Interviews you with scoping questions
3. Creates a plan at .elder-gods/plans/<task>.md
4. Tsathoggua reviews it for executability — OKAY or REJECT with at most 3 blocking issues
5. Cthulhu orchestrates the implementation

Knowledge base

Use /old-ones-init to generate AGENTS.md files at the root and in key subdirectories. These give every agent project context at a glance, without repeated exploration and without consuming tool-budget on re-discovery.

Dashboard

oh-my-claudecode dashboard

A full-screen control panel rendered with OpenTUI (the terminal UI engine behind opencode) — gruvbox dark soft, a colorized ASCII wordmark splash, and a calm editorial layout: health is a one-line verdict, detail is opt-in. Four tabs:

• Overview — archive counts (memories, observations, sessions, pending compression), embedding provider and model-cache size, capture health with last-ingest age, disk usage, and binding-ritual phase states
• Doctor — the verdict plus only the checks that need attention (a reveals the full suite)
• Agents — the Elder God roster with model tier, category, cost, and install state
• Settings — toggle the three pillars, individual hooks, and individual agents with the keyboard; changes write ~/.claude/oh-my-claudecode.jsonc and re-sync agents automatically

Keys: ←→/1-4 tabs · ↑↓ select · enter toggle · a all checks · r refresh · q quit. Requires Bun (npm install -g bun) for OpenTUI's native renderer — the command tells you exactly that if Bun is missing. oh-my-claudecode stats [--json] prints the same data headlessly.

Diagnostics

npx oh-my-claudecode doctor

Checks:

• ~/.claude/ directory exists
• settings.json present
• All hook scripts installed
• Hooks registered in settings
• Agent definitions installed and in sync with config
• Slash commands installed
• Plugin config valid
• Yith archive boots; MCP server registered in ~/.claude.json
• Background ingestion cron installed
• Capture health — when transcript ingestion last succeeded
• Transcript retention window (cleanupPeriodDays) high enough that history can't be deleted before ingestion

Project Structure

oh-my-claudecode/
├── src/
│   ├── agents/               # 12 Elder God agent definitions + builder + markdown renderer
│   ├── config/               # Zod schema — full type system
│   ├── hooks/                # Lifecycle hook scripts and configs
│   ├── linters/              # AST type-safety linter (lint CLI engine)
│   ├── features/
│   │   ├── yith-archive/     # Persistent cross-session memory (~14k LOC)
│   │   │   ├── functions/    #   40+ memory primitives
│   │   │   ├── state/        #   KV store, vector index, hybrid search, reranker
│   │   │   ├── providers/    #   Anthropic / OpenRouter / Gemini / Minimax providers
│   │   │   ├── prompts/      #   Summarization, consolidation, reflection templates
│   │   │   ├── triggers/     #   Event triggers for session lifecycle
│   │   │   ├── eval/         #   Quality/validation helpers
│   │   │   └── index.ts      #   createYithArchive() factory — public API
│   │   ├── block-summarizer/ # In-session context trimming
│   │   ├── background-agent/ # BackgroundManager (circuit breaker, concurrency)
│   │   ├── skill-loader/     # Discovers user skills from .claude/skills/
│   │   └── mcp-manager/      # Skill-scoped MCP lifecycle
│   ├── shared/               # Logging, deep-merge, model resolution
│   └── cli/                  # Installer, sync, doctor, lint, bind, list-agents
├── commands/                 # Markdown slash commands (installed to ~/.claude/commands/)
├── CHANGELOG.md              # Release history
├── LICENSE                   # MIT
└── NECRONOMICON.md           # Plugin architecture reference

Agent detail

Cthulhu (main orchestrator)

The heart of the system. Every user message passes through Cthulhu's intent gate:

1. Verbalize intent — explicitly classify what the user wants before acting
2. Route accordingly — trivial → direct tools; exploratory → parallel Shoggoth agents; implementation → plan + delegate; ambiguous → one question
3. Plan before acting — if 2+ steps, create detailed todos immediately
4. Delegate aggressively — never work alone when a specialist is available
5. Verify before completing — diagnostics, tests, evidence required
6. Summarize after delegation — full block to disk, main thread continues from bullets
7. Persist insights to Yith Archive — salient facts become cross-session memory

Shoggoth (codebase search)

Fire 3+ in parallel. They're formless and free. Use for finding where X is implemented, discovering patterns to follow, cross-module structure discovery.

Yog-Sothoth (architecture advisor)

Consult when an architecture decision requires multi-system tradeoffs, after 2+ failed fix attempts, or when completing a significant implementation and you want a self-review pass. Responses always include: bottom line (2-3 sentences), action plan (≤7 steps), effort estimate.

Shub-Niggurath + Tsathoggua (planning flow)

Shub-Niggurath interviews → creates .elder-gods/plans/<task>.md → Tsathoggua reviews it → OKAY or REJECT with max 3 blocking issues → Cthulhu executes.

The Elder Loop

Activate with /elder-loop [completion promise]. The loop writes state to .claude/elder-loop-state.json. On each Stop event, the hook checks whether the promise is met — if not, it injects a reminder to continue. Deactivate with /cancel-elder-loop.

Development

git clone https://github.com/ragingstar2063/oh-my-claudecode
cd oh-my-claudecode
npm install
npm run build
npm run typecheck

Releases are published automatically via GitHub Actions on every push to main — the workflow bumps the patch version, publishes to npm, tags the commit, and creates a GitHub release.

Philosophy

• Delegate first — specialists exist for a reason; use them
• Parallel by default — independent work always runs simultaneously
• Evidence required — no task is complete without diagnostics or test proof
• Plan before touching files — todos before edits, every time
• Trim on delegation boundaries — every delegation is a block; the block lives on disk, the main thread lives in summaries
• Persist what matters — across sessions, knowledge compounds; don't re-explain
• No AI slop — no unnecessary abstractions, no useless comments, no scope creep
• Blocker-finding, not perfectionism — reviews find actual blockers, not nitpicks

Attribution

Yith Archive and Block Summarizer are novel combined implementations inspired by the broader ecosystem of agent-memory and context-compression research. They were rewritten from scratch to fit a single-process Claude Code plugin and are released here under MIT as part of oh-my-claudecode.

License

MIT — see LICENSE.