Skip to content
/

oh-my-claude (stefandevo)

stefandevo-oh-my-claude · stefandevo/oh-my-claude · ★ 7 · last commit 2026-01-10

Ports oh-my-opencode's Sisyphus multi-agent orchestration to Claude Code natively after Anthropic blocked third-party OAuth access.

Best whenOrchestrators must never implement directly; all specialized work must be delegated to named specialist agents via the Task tool.
Skip ifWorking directly on complex tasks without delegation, Skipping plan validation before execution
vs seeds
superpowers(skills-based framework) and agent-os (markdown scaffold + install scripts), but uniquely adds a TypeScript MCP server a…
Primitive shape 20 total
Skills 4 Subagents 10 Hooks 5 MCP tools 1
00

Summary

oh-my-claude (stefandevo) — Summary

oh-my-claude by stefandevo is a port of the oh-my-opencode multi-agent orchestration system re-implemented natively for Claude Code, created after Anthropic restricted third-party tools from using Claude Code Max subscriptions. The project replaces OpenCode's plugin SDK with Claude Code's native extension points: shell hooks (bash), MCP servers (TypeScript), and markdown agent files. It ships 10 specialized agents (Sisyphus, Prometheus, Momus, Oracle, etc.) coordinated by an orchestrator pattern where planning and execution are separated into distinct agents. Boulder state persistence via .sisyphus/boulder.json allows plan progress to survive session interruptions, and a PreCompact hook preserves critical session state through context window compaction. Optional TDD enforcement, auto-verification hooks, git worktree isolation, and LSP integration round out the feature set.

Differs from seeds: Closest to superpowers (skills-only behavioral framework) + agent-os (markdown scaffold with install scripts), but uniquely extends both by adding a TypeScript MCP server for custom tools, a rich shell-hook layer for auto-verification and TDD enforcement, and named agent personas with an explicit orchestrator-delegator pattern borrowed from oh-my-opencode's Sisyphus/Prometheus architecture — a pattern absent from all 11 seeds.

01

Overview

oh-my-claude (stefandevo) — Overview

Origin

Created in early 2026 by stefandevo in response to Anthropic blocking third-party tools (like OpenCode) from using Claude Code Max subscriptions. The README states: "oh-my-claude solves this by reimplementing the orchestration system using Claude Code's native extension points: Hooks (shell scripts) instead of OpenCode's plugin SDK, MCP servers instead of plugin tools, Native Task tool instead of custom session management."

The project was "entirely generated by Claude Code (using Claude Opus 4.5)" based on the original oh-my-opencode codebase. The author provided direction and tested basic functionality but describes it as "experimental software for personal use."

Philosophy

Separation of concerns: Prometheus plans, Sisyphus executes, Momus validates. The core philosophy mirrors oh-my-opencode: "Sisyphus orchestrator delegates work to specialized agents" and "Separation of Planning & Execution."

The key principle is that "Sisyphus NEVER works alone when specialists are available" — frontend work delegates to Frontend Engineer, deep research to parallel background agents, complex architecture to Oracle.

Manifesto-style Quotes

"oh-my-claude brings enterprise-grade multi-agent orchestration to Claude Code. Instead of Claude doing everything directly, work is coordinated through specialized agents."

"Verification Enforcement: All delegated work must be verified before completion."

"Boulder State Persistence: Plan progress survives session interruptions."

"Trust Mode: Optional auto-approval of common dev tools (npm, git, file edits) to reduce permission prompts."

02

Architecture

oh-my-claude (stefandevo) — Architecture

Distribution

  • Type: Claude Code plugin (bash-script-bundle + npm package for MCP)
  • Install: ./install.sh (downloads from GitHub, installs to ~/.claude/)
# Install
curl -s https://raw.githubusercontent.com/stefandevo/oh-my-claude/main/install.sh | bash

# Uninstall
./uninstall.sh

Directory Tree

oh-my-claude/
├── agents/           # 10 markdown agent files
│   ├── sisyphus.md
│   ├── prometheus.md
│   ├── orchestrator-sisyphus.md
│   ├── momus.md
│   ├── oracle.md
│   ├── explore.md
│   ├── librarian.md
│   ├── frontend-engineer.md
│   ├── document-writer.md
│   └── metis.md
├── skills/           # 4 skill directories
│   ├── plan/
│   ├── start-work/
│   ├── frontend-ui-ux/
│   └── git-master/
├── hooks/            # 5 shell hook scripts
│   ├── pre-tool-use.sh
│   ├── post-tool-use.sh
│   ├── user-prompt-submit.sh
│   ├── stop.sh
│   ├── pre-compact.sh
│   └── lib/          # Shared utilities
├── mcp/              # TypeScript MCP server
│   └── src/
│       ├── index.ts
│       ├── types.ts
│       └── tools/
├── config/
│   ├── categories.json
│   └── worktrees.json
├── install.sh
├── uninstall.sh
├── lsp-setup.sh
└── mcp-extras-setup.sh

State Files

  • .sisyphus/boulder.json — plan progress persistence
  • .sisyphus/drafts/{topic}.md — planning drafts (Prometheus)
  • .sisyphus/plans/{topic}.md — finalized plans

Required Runtime

  • Bash (hooks)
  • Node.js (MCP server)
  • Optional: LSP tooling for 18+ languages

Target Tools

  • Claude Code (primary)
  • Compatible with any environment that supports Claude Code hooks/plugins
03

Components

oh-my-claude (stefandevo) — Components

Agents (10)

Name Purpose
sisyphus Primary executor — delegates to specialists via Task tool, never works alone
orchestrator-sisyphus Delegation coordinator with intent classification
prometheus Planner/interviewer — creates detailed plans, never implements
momus Ruthless plan validator — blocks execution until plan is approved
oracle Architecture consultation agent (read-only)
explore Fast parallel codebase search agent
librarian External docs and OSS code research
frontend-engineer Frontend/UI/UX specialist
document-writer Technical documentation writer
metis Verification and quality assurance agent

Skills (4)

Name Trigger Purpose
plan @plan <topic> or /plan <topic> Activates Prometheus planning mode with interview → draft → plan workflow
start-work /start-work Initiates work session against an approved plan
frontend-ui-ux Skill trigger Frontend/UI design specialist activation
git-master Skill trigger for git operations Git operations with best practices

Hooks (5 shell scripts)

File Event Purpose
pre-tool-use.sh PreToolUse Orchestration constraints, tool blocking, TDD enforcement, permission enforcement
post-tool-use.sh PostToolUse Auto-verification (TypeScript/Python/Go/Rust/JSON/YAML), result processing, error detection
user-prompt-submit.sh UserPromptSubmit Intent classification, ultrawork/TDD keyword detection
stop.sh Stop Continuation enforcement — blocks incomplete work
pre-compact.sh PreCompact Preserves critical session state before context window compaction

MCP Server

  • TypeScript MCP server with custom tools (count unknown from repo inspection)
  • Bundled alongside hooks as a local MCP server

Config Files

  • config/categories.json — task category mappings for intent routing
  • config/worktrees.json — git worktree configuration
05

Prompts

oh-my-claude (stefandevo) — Prompt Excerpts

Excerpt 1: Sisyphus Agent (agents/sisyphus.md)

Technique: Persona + delegation constraint table + intent classification gate

# Sisyphus - Primary Executor Agent

You are "Sisyphus" - a powerful AI agent with orchestration capabilities.

## Identity
**Why Sisyphus?**: Humans roll their boulder every day. So do you. Your code should be
indistinguishable from a senior engineer's.
**Core Identity**: SF Bay Area engineer. Work, delegate, verify, ship. No AI slop.

## Operating Principles
**CRITICAL**: You NEVER work alone when specialists are available.
- Frontend work → delegate via Task tool with appropriate subagent_type
- Deep research → parallel background agents (run_in_background: true)
- Complex architecture → consult Oracle subagent

## Phase 0: Intent Classification

### Step 0: Check Skills FIRST (BLOCKING)
Before ANY classification or action, scan for matching skills.
IF request matches a skill trigger:
  → INVOKE skill immediately
  → Do NOT proceed to Step 1 until skill is invoked

### Step 1: Classify Request Type
| Type | Signal | Action |
|------|--------|--------|
| **Skill Match** | Matches skill trigger | INVOKE skill FIRST |
| **Trivial** | Single file, known location | Direct tools only |
| **Explicit** | Specific file/line, clear command | Execute directly |
| **Exploratory** | "How does X work?" | Fire Explore agents in parallel |
| **Open-ended** | "Improve", "Refactor", "Add feature" | Assess codebase first |
| **Ambiguous** | Unclear scope | Ask ONE clarifying question |

Analysis: Uses "Iron Law" constraint ("NEVER work alone"), decision table for intent routing, and "BLOCKING" CAPS to enforce skill invocation before any other action. Classic delegating-orchestrator persona.


Excerpt 2: Plan Skill (skills/plan/SKILL.md)

Technique: Mode-switching persona injection — transforms agent into Prometheus planner

## Instructions

When this skill is invoked:

### 1. Enter Planning Mode
You are now **Prometheus** - a planner, not an implementer.
**CRITICAL**: You do NOT write code. You create work plans.

### 2. Create Draft
Create a planning draft at `.sisyphus/drafts/{topic}.md`:
# Planning Draft: {topic}
## Requirements [To be filled through interview]
## Decisions [Key decisions made]
## Research Findings [Codebase discoveries]

### 3. Conduct Interview
Ask focused questions to understand:
- What is the core objective?
- What are the success criteria?
- What should NOT be changed?
- Are there existing patterns to follow?
- Should tests be included?

### 5. Generate Plan (Only When Requested)
**Stay in interview mode until user says:**
- "Make it a plan"
- "Generate the plan"
- "Create the work plan"

Analysis: Persona-switching pattern — the skill transforms the running agent into Prometheus mid-session. Hard gate before plan generation requires explicit user phrase, preventing premature execution.

09

Uniqueness

oh-my-claude (stefandevo) — Uniqueness

Differs from Seeds

Closest seed is superpowers (skills-based behavioral framework for Claude Code) combined with elements of agent-os (markdown scaffold + install scripts). However, oh-my-claude (stefandevo) diverges significantly: it adds a TypeScript MCP server for custom tools (no seed has this alongside shell hooks), a 5-hook shell layer that enforces TDD and auto-verifies code edits (superpowers has 1 hook; spec-kit has 18 but they are lifecycle decorators, not enforcement scripts), and a multi-agent persona system with an explicit Sisyphus/Prometheus/Momus orchestration architecture borrowed from oh-my-opencode — absent from all 11 seeds. The boulder state persistence model is also unique: plans survive session interruption via a JSON checkpoint file, which none of the seeds implement.

Positioning

  • The "oh-my-opencode for Claude Code" port: Explicitly designed to give Claude Code users the same multi-agent orchestration that oh-my-opencode gave OpenCode users, without requiring OpenCode or direct API keys
  • Targets Claude Code Max subscribers who lost access to oh-my-opencode after Anthropic's OAuth restriction
  • Experimental/personal use posture: "no warranty, not extensively audited"

Observable Failure Modes

  1. MCP server fragility: TypeScript MCP server must build correctly; if npm run build:mcp fails, custom tools are unavailable
  2. Shell hook parsing brittleness: All 5 hooks parse JSON from stdin using bash + jq; malformed inputs silently fall back to {"decision": "allow"}, potentially bypassing TDD/verification enforcement
  3. Momus as single point of failure: If Momus rejects a plan for unclear reasons, the workflow stalls with no escalation path
  4. Boulder state stale plans: If a plan in .sisyphus/boulder.json refers to files that have changed, Sisyphus may execute against outdated context with no automated detection
  5. Generated-by-AI codebase: Author explicitly states it was "entirely generated by Claude Code" — quality and edge case handling are uncertain
04

Workflow

oh-my-claude (stefandevo) — Workflow

Phases

Phase Agent Artifact Approval Gate
Interview & Draft Prometheus .sisyphus/drafts/{topic}.md User confirms draft
Plan Generation Prometheus .sisyphus/plans/{topic}.md User says "Make it a plan"
Plan Validation Momus Validated plan (blocks if flawed) Momus approval
Execution Sisyphus + specialists Code changes Auto-verification passes
Verification Auto-verification hooks + Metis Syntax/compile check results All checks pass

Key Approval Gates

  1. User must explicitly request plan generation ("Make it a plan" / "Generate the plan")
  2. Momus validates plans before execution proceeds
  3. PostToolUse hook auto-verifies edits before completion
  4. Stop hook enforces continuation if work is incomplete

TDD Mode (Optional)

When activated during @plan:

  • Blocks source file edits until matching test files exist (enforced via pre-tool-use.sh hook)
  • Test-first: tests must be written before implementation

Auto-Verification

PostToolUse hook triggers language-specific checks:

  • TypeScript: tsc --noEmit
  • Python: syntax validation
  • Go: go build
  • Rust: cargo check
  • JSON/YAML: syntax validation

Boulder State

.sisyphus/boulder.json tracks plan progress across sessions. If a session is interrupted, Sisyphus can resume from the last checkpoint.

Git Worktrees (Optional)

  • Isolated workspace per complex task
  • Auto file copying and dependency installation
  • Configured via config/worktrees.json

Trust Mode (Optional)

Auto-approves common dev tools (npm, git, file edits) to reduce permission prompts.

06

Memory Context

oh-my-claude (stefandevo) — Memory & Context

State Storage

  • Type: File-based, project-scoped
  • Location: .sisyphus/ directory in project root

State Files

File Content Lifecycle
.sisyphus/boulder.json Plan progress, current step, completion status Persists across sessions until task complete
.sisyphus/drafts/{topic}.md Prometheus interview drafts Created during planning, updated per response
.sisyphus/plans/{topic}.md Finalized, Momus-approved work plans Created at end of planning, read during execution

Context Preservation

  • PreCompact hook (hooks/pre-compact.sh): Runs before context window compaction to preserve critical session state
  • This prevents loss of plan context, current agent state, and in-progress delegations during long sessions

Handoffs

  • Plans persist in .sisyphus/plans/ between sessions (cross-session handoff: yes)
  • Boulder state allows Sisyphus to resume exactly where execution left off after an interruption
  • Agent identity (which agent is active) is maintained through the session via skill invocation

Memory Limitations

  • No vector database or semantic search
  • No global memory across projects
  • All state is project-local markdown/JSON files
  • Notepad system: .sisyphus/notepad/ mentioned in README for learnings and decisions (wisdom accumulation across sessions)

Context Injection

  • AGENTS.md is loaded as project context
  • Skill triggers inject agent personas mid-session
  • config/categories.json provides intent routing context to hooks
07

Orchestration

oh-my-claude (stefandevo) — Orchestration

Multi-Agent Pattern

Pattern: Hierarchical (orchestrator + specialists)

Sisyphus acts as the orchestrating agent that never implements directly; it delegates via the Claude Code Task tool to named specialists:

User prompt
  → user-prompt-submit.sh (intent classification)
    → Sisyphus (orchestrator)
      → Task(subagent_type="Explore") for codebase search
      → Task(subagent_type="Frontend-Engineer") for UI work
      → Task(subagent_type="Oracle") for architecture
      → Task(subagent_type="Librarian") for docs/research

Planning Separation

A distinct pre-execution phase uses Prometheus (planner) and Momus (validator):

@plan → Prometheus (interview) → Draft → Momus (validation) → Approved Plan → Sisyphus (execution)

Isolation Mechanism

  • Git worktrees: Optional per-task isolated workspaces
  • Config: config/worktrees.json
  • Auto file copying and dependency installation on worktree creation

Execution Mode

  • Interactive loop: User provides request → hooks classify → Sisyphus orchestrates → hooks verify
  • Sessions persist via boulder state; can resume after interruption

Multi-Model

  • No: All agents inherit the same Claude model from the parent session
  • Model selection is not framework-managed

Consensus Mechanism

  • None (no raft/quorum-style coordination)
  • Momus provides single-gatekeeper plan validation before execution

Concurrent Agents

  • Multiple subagents can run in parallel via run_in_background: true in Task calls
  • Primarily used for Explore agents doing parallel codebase search
  • Exact concurrency limit: unknown (Claude Code runtime-determined)

Crash Recovery

  • Boulder state provides implicit crash recovery for plan progress
  • PreCompact hook preserves session state across context window compaction
08

Ui Cli Surface

oh-my-claude (stefandevo) — UI/CLI Surface

CLI Binary

  • Exists: No dedicated binary
  • Install/uninstall handled by install.sh / uninstall.sh bash scripts
  • package.json defines npm run install./install.sh and npm run test./tests/test-hooks.sh

Local UI

  • Exists: No web dashboard or TUI
  • All interaction is through Claude Code's standard interface

IDE Integration

  • Claude Code (primary)
  • VS Code Extension compatibility noted: works with Claude Code VS Code extension
  • LSP integration: lsp-setup.sh sets up Language Server Protocol for 18+ languages

Install Scripts

Script Purpose
install.sh Web installer (downloads from GitHub, configures ~/.claude/)
uninstall.sh Removes installation
lsp-setup.sh Sets up LSP across 18+ languages
mcp-extras-setup.sh Installs optional MCP servers (context7, grep_app)
update.sh Updates to latest version

MCP Extras (Optional)

Additional research MCPs configurable via mcp-extras-setup.sh:

  • context7: Official documentation retrieval
  • grep_app: GitHub code search

Observability

  • Audit log: No dedicated audit log
  • Hook scripts have debug logging capability (via lib/debug.sh) written to project directory
  • Test suite: tests/test-hooks.sh for hook validation

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenCode ★ 165k

Terminal-first AI coding agent with multi-model routing, native desktop app, and a typed .opencode/ configuration system for…

OpenHands ★ 75k

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

DeerFlow ★ 70k

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker…

oh-my-openagent (omo) ★ 60k

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…