Skip to content

stefandevo/oh-my-claude

BranchesTags

Repository files navigation

oh-my-claude

Multi-Agent Orchestration for Claude Code

A port of oh-my-opencode's sophisticated multi-agent orchestration system to work natively with Claude Code.

Author's Note & Disclaimer

This project was entirely generated by Claude Code (using Claude Opus 4.5) based on the original oh-my-opencode codebase. I provided direction and tested it for basic functionality, but this is experimental software for personal use.

  • No warranty is provided - use at your own risk
  • This is not affiliated with or endorsed by Anthropic or the oh-my-opencode team
  • The code has not been extensively audited or battle-tested
  • Contributions and feedback are welcome, but support is limited

If you find issues, feel free to open a GitHub issue or submit a PR.

Background: Why This Port Exists

In early 2026, Anthropic blocked third-party tools like OpenCode from using Claude Code Max subscriptions ($200/month plan). These tools had been accessing Anthropic's models by emulating the official Claude Code client, but Anthropic implemented authentication restrictions to prevent this.

This created a problem: oh-my-opencode's brilliant multi-agent orchestration system no longer worked for Claude Code Max subscribers - it only functioned via direct API keys, which is significantly more expensive for heavy usage.

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 result: You get the same powerful multi-agent orchestration, but it works natively within Claude Code - no authentication workarounds, no API key costs, full compatibility with your Max subscription.

Table of Contents

Overview

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

  • Prometheus interviews you and creates detailed plans
  • Sisyphus orchestrates execution, delegating to specialists
  • Specialists (Frontend Engineer, Librarian, etc.) handle domain-specific tasks
  • Momus ruthlessly validates plans before execution

Key Features

  • Multi-Agent Orchestration: Sisyphus orchestrator delegates work to specialized agents
  • Separation of Planning & Execution: Prometheus plans, Sisyphus executes
  • 10 Specialized Agents: Each agent optimized for specific tasks
  • Verification Enforcement: All delegated work must be verified before completion
  • Boulder State Persistence: Plan progress survives session interruptions
  • Intent Classification: Automatic routing based on request type
  • Enhanced UX with Structured Questions: Uses Claude Code's AskUserQuestion tool for interactive, clickable options instead of plain text questions
  • Git Worktree Isolation: Optional isolated workspaces for complex tasks with auto file copying and dependency installation
  • LSP Setup Helper: Easy setup script for Language Server Protocol integration across 18+ languages
  • Research Tools: Built-in context7 (documentation) and grep_app (GitHub code search) MCPs
  • Optional TDD Enforcement: Ask during @plan to enforce test-first development - blocks source edits until tests exist
  • Auto-Verification: Automatic syntax/compile checks for TypeScript, Python, Go, Rust, JSON, YAML
  • Context Preservation: PreCompact hook preserves critical session state through compaction
  • Trust Mode: Optional auto-approval of common dev tools (npm, git, file edits) to reduce permission prompts

Comparison with oh-my-opencode

What's the Same?

Feature oh-my-opencode oh-my-claude
Orchestration philosophy Sisyphus delegates, never implements directly Same
Planning workflow Prometheus interviews → draft → plan Same
Verification enforcement Must verify before marking complete Same
Boulder state persistence .sisyphus/boulder.json Same
Notepad wisdom system Learnings, decisions, issues Same
Agent roster 10 specialized agents Same 10 agents

What's Different?

Aspect oh-my-opencode oh-my-claude
Platform OpenCode IDE Claude Code CLI
Plugin system @opencode-ai/plugin SDK Shell hooks + MCP
Hook events 22 custom hooks 5 native hooks (consolidated)
Agent definitions TypeScript AgentConfig Markdown prompts + AGENTS.md
Tool registration Plugin tools API MCP server
Session management ctx.client.session.* API Task tool + filesystem
Installation OpenCode plugin manager Shell script installer
User interaction Plain text questions AskUserQuestion (clickable options)
Git worktrees Not available Built-in (isolated workspaces)
LSP setup Manual configuration lsp-setup.sh (18+ languages)
Research tools Built-in MCPs Built-in (context7, grep_app)
Auto-verification Plugin-based Built-in (TS, Python, Go, Rust, JSON, YAML)
Context preservation Plugin handles PreCompact hook (snapshots + injection)
TDD enforcement Not available Optional (per-plan, blocks source edits until tests exist)
Permission auto-approval Not available Trust Mode (auto-approve dev tools + file ops)

Architecture Comparison

oh-my-opencode                          oh-my-claude
─────────────────                       ─────────────
┌─────────────────┐                     ┌─────────────────┐
│  OpenCode IDE   │                     │  Claude Code    │
├─────────────────┤                     ├─────────────────┤
│  Plugin SDK     │                     │  Shell Hooks    │
│  (TypeScript)   │                     │  (Bash scripts) │
├─────────────────┤                     ├─────────────────┤
│  22 Hook Events │                     │  5 Hook Events  │
├─────────────────┤                     ├─────────────────┤
│  Plugin Tools   │                     │  MCP Server     │
│  (sisyphus_task)│                     │  (boulder, etc) │
└─────────────────┘                     └─────────────────┘
        │                                       │
        ▼                                       ▼
┌─────────────────┐                     ┌─────────────────┐
│  .sisyphus/     │                     │  .sisyphus/     │
│  (state files)  │                     │  (state files)  │
└─────────────────┘                     └─────────────────┘

Migration from oh-my-opencode

If you're coming from oh-my-opencode:

You used to... Now you...
Install via OpenCode plugin manager Run install.sh
Use sisyphus_task tool Claude uses native Task tool
Configure agents in TypeScript Agent prompts in agents/*.md
22 separate hook files 5 consolidated shell scripts
Access session API State managed via filesystem

Command equivalents:

oh-my-opencode          oh-my-claude
──────────────          ────────────
/plan <task>            @plan <task>
/start-work <plan>      /start-work <plan>
ultrawork <task>        ultrawork <task>
ulw <task>              ulw <task>

How It Works

The Hook System

oh-my-claude uses Claude Code's native hook system to intercept and enhance behavior:

User Input
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│  UserPromptSubmit Hook                                      │
│  • Detects keywords (@plan, ultrawork, ulw)                │
│  • Classifies intent                                        │
│  • Injects orchestration context                           │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│  PreToolUse Hook                                            │
│  • Enforces orchestrator constraints                        │
│  • Blocks direct edits in orchestrator mode                │
│  • Validates planning mode restrictions                     │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│  [Claude executes tools]                                    │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│  PostToolUse Hook                                           │
│  • Auto-verifies code changes (TypeScript, Python, etc.)   │
│  • Injects verification reminders after Task completion    │
│  • Tracks files edited and verification failures           │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│  Stop Hook                                                  │
│  • Prevents session end with incomplete todos              │
│  • Enforces boulder (plan) completion                      │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│  PreCompact Hook (context preservation)                     │
│  • Creates snapshots of session state before compaction    │
│  • Preserves git state, blocking issues, recent files      │
│  • Injects critical context into compacted conversation    │
└─────────────────────────────────────────────────────────────┘

The MCP Server

Custom tools are provided via the MCP (Model Context Protocol) server:

  • Boulder tools: Manage plan execution state
  • Notepad tools: Persist learnings across sessions
  • Draft tools: Handle planning drafts
  • Worktree tools: Create and manage isolated git worktrees

State Management

All state is stored in your project's .sisyphus/ directory:

.sisyphus/
├── boulder.json          # Current plan execution state
├── plans/
│   └── auth-system.md    # Generated plans
├── drafts/
│   └── auth-system.md    # In-progress planning drafts
├── notepads/
│   ├── learnings.md      # What worked, what didn't
│   ├── decisions.md      # Architectural decisions made
│   └── issues.md         # Problems encountered
└── worktrees/            # Git worktree isolation (if enabled)
    └── feature-name/     # Isolated workspace with its own branch

VS Code Extension Compatibility

This project was designed and tested with the Claude Code CLI. The VS Code extension should work since it shares the same configuration system, but there are caveats:

What Should Work

  • Hooks and MCP servers are configured in the same settings.json
  • The Task tool and agent delegation use the same underlying engine
  • AskUserQuestion tool is supported in both interfaces

Potential Issues

Concern Notes
Path resolution VS Code may not expand ~ - use absolute paths
Working directory May differ from CLI context
Shell execution Subprocess spawning might behave differently
Windows Bash scripts require WSL or Git Bash

Recommended for VS Code

If using VS Code, prefer absolute paths in your settings:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{ "type": "command", "command": "/absolute/path/to/hooks/pre-tool-use.sh" }]
    }]
  }
}

Note: VS Code compatibility is untested. If you encounter issues, please open a GitHub issue with details.

Installation

Prerequisites

  • Claude Code CLI installed and configured
  • jq for JSON processing: brew install jq (macOS) or apt install jq (Linux)
  • Node.js 18+ (for MCP server)

Quick Install

Run this command in any directory:

bash <(curl -fsSL https://raw.githubusercontent.com/stefandevo/oh-my-claude/main/install.sh)

The interactive installer will guide you through setup.

Alternative: Clone first (if you prefer to inspect before running):

git clone https://github.com/stefandevo/oh-my-claude.git
cd oh-my-claude
./install.sh

The installer will prompt you to choose:

  1. Per-project (recommended for testing)

    • Installs to .claude/oh-my-claude/ in your current project
    • Only affects that specific project
    • Great for trying it out before committing to system-wide

  2. System-wide

    • Installs to ~/.claude/oh-my-claude/
    • Affects all Claude Code sessions
    • Use after you've tested and want it everywhere

Installing in a Different Project

To install in a specific project from anywhere:

cd /path/to/your/project
/path/to/oh-my-claude/install.sh
# Choose option 1 (per-project)

What Gets Created

Per-project installation:

your-project/
├── .claude/
│   ├── settings.json           # Claude Code settings (hooks + MCP servers)
│   └── oh-my-claude/           # The orchestration system
│       ├── hooks/              # Shell hook scripts
│       ├── agents/             # Agent prompt definitions
│       ├── mcp/                # MCP server (built)
│       ├── skills/             # Workflow skills
│       └── config/             # Configuration files

System-wide installation:

~/.claude/
├── settings.json               # Claude Code settings (hooks + MCP servers)
└── oh-my-claude/               # The orchestration system
    └── ...

MCP servers configured in settings.json:

  • oh-my-claude - Boulder state, notepads, drafts, worktrees
  • context7 - Documentation lookup (if enabled during install)
  • grep_app - GitHub code search (if enabled during install)

Updating

To update an existing installation:

# If you have the source repo
cd /path/to/oh-my-claude
git pull
./update.sh

# Or run install.sh - it will detect existing and offer to update
./install.sh

What update.sh does:

  • Detects your installation (per-project or system-wide)
  • Pulls latest from git (if installation is a git repo)
  • Downloads from GitHub (if not a git repo)
  • Rebuilds the MCP server
  • Preserves your settings.json (doesn't overwrite customizations)

If running install.sh on existing installation:

oh-my-claude is already installed at .claude/oh-my-claude

  1) Update existing installation (recommended)
     Pulls latest changes, rebuilds, preserves settings

  2) Fresh reinstall
     Removes existing and installs fresh

  3) Cancel

Tutorial: Your First Orchestrated Task

Step 1: Start a Planning Session

Let's plan a new feature. Start Claude Code in your project:

cd your-project
claude

Then initiate planning:

@plan Add user authentication with JWT tokens

What happens:

  1. The UserPromptSubmit hook detects @plan
  2. Prometheus (the planner) is activated
  3. A draft is created at .sisyphus/drafts/user-authentication.md
  4. Prometheus begins interviewing you

Step 2: Answer Prometheus's Questions

Prometheus will ask clarifying questions using interactive, clickable options:

┌─────────────────────────────────────────────────────────────┐
│  Which authentication method should we implement?           │
│                                                             │
│  ○ JWT tokens (Recommended)                                 │
│    Stateless, scalable, good for APIs                       │
│                                                             │
│  ○ Session cookies                                          │
│    Traditional, requires session store                      │
│                                                             │
│  ○ OAuth 2.0                                                │
│    Third-party providers (Google, GitHub)                   │
│                                                             │
│  ○ Other...                                                 │
└─────────────────────────────────────────────────────────────┘

This enhanced UX uses Claude Code's AskUserQuestion tool to provide:

  • Clickable options instead of typing answers
  • Descriptions explaining each choice
  • Recommended options clearly marked
  • Batch questions for related decisions

Answer thoroughly. Each response updates the draft.

Step 3: Generate the Plan

When Prometheus has enough information:

Make it a plan

What happens:

  1. Prometheus validates the draft is complete
  2. (Optional) Metis reviews for gaps
  3. (Optional) Momus validates ruthlessly
  4. Plan is generated at .sisyphus/plans/user-authentication.md
  5. Draft is deleted

Step 4: Execute the Plan

Start execution with Sisyphus:

/start-work user-authentication

What happens:

  1. Plan is loaded from .sisyphus/plans/
  2. Boulder state is initialized (.sisyphus/boulder.json)
  3. Todos are created from plan checkboxes
  4. Sisyphus begins orchestrating

Step 5: Watch the Orchestration

Sisyphus will:

  1. Delegate tasks to specialists (never implements directly)
  2. Verify each completed task before marking done
  3. Re-delegate if verification fails
  4. Record learnings in notepads

Example flow:

Sisyphus: Task 1: Create User model
         → Delegating to general-purpose agent...

[Agent completes task]

Sisyphus: Verifying User model...
         ✓ File exists: src/models/User.ts
         ✓ TypeScript compiles
         ✓ Required fields present
         → Task 1 complete

Sisyphus: Task 2: Create JWT middleware
         → Delegating to general-purpose agent...

Step 6: Handle Interruptions

If your session ends mid-plan:

claude

The system will detect the active boulder and prompt:

Plan 'user-authentication' is in progress (3/7 tasks complete).
Continue execution?

Workflow Guide

Planning Workflow (@plan)

Use planning for complex features that need thought:

@plan <description>

Best practices:

  • Be descriptive in your initial request
  • Answer Prometheus's questions thoroughly
  • Review the generated plan before executing
  • Use "high accuracy" mode for critical features

Planning commands during interview:

  • Continue answering questions naturally
  • Say "Make it a plan" to generate the final plan
  • Say "Start over" to reset the draft

Orchestration Workflow (ultrawork)

Use orchestration for complex tasks without formal planning:

ultrawork Refactor the payment processing to use Stripe

or shorthand:

ulw Build a REST API for user management

What's different from regular Claude:

  • Sisyphus coordinates instead of implementing directly
  • Work is delegated to specialized agents
  • All results are verified before completion
  • Learnings are recorded for future reference

Execution Workflow (/start-work)

Execute a previously created plan:

/start-work <plan-name>

During execution:

  • Watch Sisyphus delegate and verify
  • Interrupted? Session resumes automatically
  • All progress tracked in boulder state

When NOT to Use Orchestration

Use regular Claude Code (without keywords) for:

  • Simple questions
  • Small bug fixes
  • Quick file edits
  • Exploration/reading code

Agents Reference

Agent Model Configuration

Each agent uses a specific model and temperature optimized for its task:

Agent Model Temp Role
Sisyphus opus 0.1 Primary orchestrator - needs maximum capability
Orchestrator-Sisyphus opus 0.1 Delegation coordinator - complex reasoning
Prometheus opus 0.1 Planner/interviewer - thorough analysis
Metis sonnet 0.1 Pre-planning consultant - cost-efficient validation
Momus opus 0.1 Plan reviewer - ruthless, precise judgment
Oracle opus 0.1 Strategic advisor - deep architectural reasoning
Librarian sonnet 0.1 Documentation researcher - balanced capability
Explore haiku 0.1 Codebase explorer - fast, cheap searches
Frontend Engineer opus 0.7 UI/UX specialist - high creativity
Document Writer sonnet 0.5 Technical writer - moderate creativity

Model Selection Rationale:

  • opus - High-stakes decisions, creativity, complex reasoning
  • sonnet - Balanced capability/cost for research and writing
  • haiku - Speed-critical search tasks (cheap, fast)

Temperature Guide:

  • 0.1 = Deterministic, precise (orchestration, planning, validation)
  • 0.3 = Slight variability (general tasks)
  • 0.5 = Moderate creativity (writing)
  • 0.7 = High creativity (UI/UX design)

Core Orchestration Agents

Agent Trigger Purpose
Sisyphus ultrawork, ulw Primary executor, delegates to specialists
Orchestrator-Sisyphus Plan execution Stricter delegation enforcement
Prometheus @plan Interviews user, creates detailed plans

Validation Agents

Agent Purpose
Metis Pre-planning consultant, identifies gaps before plan generation
Momus Ruthless plan validator, rejects until perfect

Specialist Agents

Agent Specialty
Oracle Strategic architecture decisions, debugging consultation
Librarian Documentation research, OSS exploration
Explore Fast codebase exploration, grep-based search
Frontend Engineer UI/UX design, beautiful interfaces
Document Writer Technical documentation, prose writing

Agent Selection

Sisyphus automatically selects agents based on task type:

Task Type Agent Selected Model Temp
UI/UX work Frontend Engineer opus 0.7
Documentation Document Writer sonnet 0.5
Research Librarian sonnet 0.1
Fast search Explore haiku 0.1
Architecture Oracle opus 0.1
General coding General-purpose sonnet 0.3

Configuration

Categories

Categories map task types to model+temperature combinations. Edit config/categories.json:

{
  "visual-engineering": { "model": "opus", "temperature": 0.7 },
  "ultrabrain": { "model": "opus", "temperature": 0.1 },
  "quick": { "model": "haiku", "temperature": 0.3 },
  "general": { "model": "sonnet", "temperature": 0.3 }
}

Disabling Hooks

To disable specific hooks, add to your Claude Code settings:

{
  "oh-my-claude": {
    "disabledHooks": ["stop", "pre-compact"]
  }
}

MCP Tools Reference

Tool Description
boulder_init Initialize plan execution state
boulder_update Update plan progress
boulder_complete Mark plan as complete
boulder_status Get current plan state
notepad_read Read notepad file
notepad_append Add learning/decision/issue
notepad_list List all notepads
draft_create Create planning draft
draft_update Update draft content
draft_delete Delete draft after plan generation
worktree_create Create isolated git worktree
worktree_list List all project worktrees
worktree_remove Remove a worktree
worktree_status Get current worktree state
worktree_config Get worktree configuration

Git Worktrees

Git worktrees allow you to work on features in isolation without affecting your main working directory. Oh-my-claude integrates worktree support directly into the orchestration workflow.

Why Worktrees?

  • Isolated Changes: Each feature gets its own branch and directory
  • Easy Discard: Don't like the changes? Delete the worktree, branch remains untouched
  • Parallel Work: Work on multiple features simultaneously
  • Safe Experimentation: Try risky refactors without polluting your main checkout

Configuration

Worktree behavior is controlled by config/worktrees.json:

{
  "enabled": true,
  "askBeforeWork": true,
  "location": {
    "base": ".sisyphus/worktrees",
    "gitignore": true
  },
  "copyFiles": {
    "enabled": true,
    "patterns": [".env", ".env.*", ".dev.vars", ".dev.vars.*", ".npmrc", ".nvmrc"],
    "exclude": [".env.production", ".env.prod"]
  },
  "postCreate": {
    "enabled": true,
    "detectPackageManager": true,
    "commands": {
      "npm": "npm install",
      "yarn": "yarn install",
      "pnpm": "pnpm install",
      "bun": "bun install"
    },
    "customCommands": []
  }
}

Configuration Options

Option Description
enabled Enable/disable worktree feature
askBeforeWork Ask user before creating worktree for complex tasks
location.base Where worktrees are created (relative to project root)
location.gitignore Auto-add worktree directory to .gitignore
copyFiles.patterns Glob patterns for files to copy to worktree
copyFiles.exclude Files to exclude from copying
postCreate.detectPackageManager Auto-detect and run package manager install
postCreate.customCommands Additional commands to run after creation

Workflow

When you start a complex task with ultrawork:

  1. Prompt: Claude asks if you want to work in an isolated worktree
  2. Create: If yes, creates worktree with auto-generated or custom name
  3. Copy Files: Copies configured files (.env, etc.) to worktree
  4. Install Dependencies: Runs detected package manager's install command
  5. Inform User: Tells you to cd into the worktree path
  6. Work: All changes happen in the isolated worktree
  7. Complete: Merge branch or discard worktree when done

Example Session

You: ultrawork implement user authentication

Claude: Would you like to work in an isolated git worktree?
        [Yes, create worktree (Recommended)] [No, work in current branch]

You: Yes, create worktree

Claude: Created worktree at .sisyphus/worktrees/user-authentication
        Branch: sisyphus/user-authentication

        Copied files: .env, .env.local
        Running: bun install

        Please cd into the worktree to continue:
        cd .sisyphus/worktrees/user-authentication

MCP Tools

Tool Description
worktree_create(cwd, name?, plan_name?) Create worktree with optional name
worktree_list(cwd) List all worktrees for project
worktree_remove(cwd, name, force?) Remove worktree
worktree_status(cwd) Get current worktree info
worktree_config(cwd) Get worktree configuration

Manual Worktree Commands

If you need to manage worktrees manually:

# List worktrees
git worktree list

# Create worktree manually
git worktree add -b feature/my-feature .sisyphus/worktrees/my-feature

# Remove worktree
git worktree remove .sisyphus/worktrees/my-feature

# Prune stale worktree references
git worktree prune

LSP Integration

Language Server Protocol (LSP) integration gives Claude real-time code intelligence: go-to-definition, find references, diagnostics, and hover documentation.

Quick Setup

./lsp-setup.sh

The script will:

  1. Ask which languages you need LSP for
  2. Install the language server binaries
  3. Provide commands to install Claude Code plugins

Supported Languages

Language Server Install Command
TypeScript/JS vtsls npm install -g @vtsls/language-server typescript
Python pyright pip3 install pyright
Go gopls go install golang.org/x/tools/gopls@latest
Rust rust-analyzer rustup component add rust-analyzer
C/C++ clangd brew install llvm
Java jdtls brew install jdtls
Ruby solargraph gem install solargraph
PHP intelephense npm install -g intelephense

See lsp-setup.sh for the full list of 18+ supported languages.

Manual Setup

If you prefer manual setup:

  1. Install the language server binary:

    npm install -g @vtsls/language-server typescript

  2. Add a plugin marketplace (in Claude Code):

    /plugin marketplace add anthropics/claude-plugins-official

    Or for more languages:

    /plugin marketplace add boostvolt/claude-code-lsps

  3. Install the plugin (in Claude Code):

    /plugin install vtsls@official

  4. Restart Claude Code to activate

What LSP Provides

  • Go to definition: Jump to where symbols are defined
  • Find references: Locate all usages of a function/variable
  • Real-time diagnostics: See errors and warnings immediately
  • Hover documentation: View type info and docs
  • Symbol search: Find symbols across your codebase

Plugin Marketplaces

Marketplace Languages Command
Official 11 /plugin marketplace add anthropics/claude-plugins-official
Boostvolt 23 /plugin marketplace add boostvolt/claude-code-lsps

Research Tools

oh-my-claude includes extended research capabilities configured during installation.

Available Tools

Tool Description Configured By
WebSearch Real-time web search Built-in (Claude Code)
WebFetch Fetch URL content Built-in (Claude Code)
context7 Official documentation lookup install.sh
grep_app Search GitHub code install.sh

context7 - Documentation Lookup

Context7 fetches up-to-date, version-specific documentation directly into your prompts.

Configured during install.sh - optionally provide your free API key from https://context7.com/dashboard for higher rate limits.

Usage:

  • Add "use context7" to prompts, or
  • Ask about library docs: "How do I use React Query mutations? use context7"

Tools provided:

  • resolve-library-id - Find library documentation ID
  • query-docs - Fetch documentation with code examples

grep_app - GitHub Code Search

grep.app MCP searches millions of public GitHub repositories for implementation examples.

Configured during install.sh - no API key required.

Usage:

  • "Search GitHub for React authentication examples"
  • "Find how others implement JWT refresh tokens"

Tools provided:

  • search - Search code across repositories
  • get_file - Fetch specific files from GitHub

Manual Setup (if skipped during install)

If you skipped research tools during installation, run:

./mcp-extras-setup.sh

Which Agents Use These

Agent Tools Used
Librarian context7, grep_app, WebSearch (primary research agent)
Explore grep_app for finding implementation examples
Sisyphus WebSearch for error messages and solutions
Oracle WebSearch for architecture patterns

TDD Mode (Test-Driven Development)

oh-my-claude supports optional TDD enforcement during plan execution. When enabled, source files cannot be edited until corresponding test files exist.

Enabling TDD During Planning

When you use @plan, Prometheus will ask about testing approach:

┌─────────────────────────────────────────────────────────────┐
│  What testing approach should we use for this plan?         │
│                                                             │
│  ○ TDD - Enforced (Recommended for critical code)          │
│    Tests MUST exist before source code can be edited        │
│                                                             │
│  ○ TDD - Guided                                             │
│    Tests encouraged first, but not strictly enforced        │
│                                                             │
│  ○ Tests after                                              │
│    Write tests after implementation                         │
│                                                             │
│  ○ Manual verification only                                 │
│    No automated tests required                              │
└─────────────────────────────────────────────────────────────┘

TDD Modes

Mode Behavior
enforced Source file edits are BLOCKED until corresponding test file exists
guided Claude is reminded to write tests first, but not blocked
tests-after Tests are written after implementation
manual No test requirements

How TDD Enforcement Works

When tdd_mode: enforced is set in the plan:

  1. Plan Configuration stores the TDD setting
  2. Boulder state carries it during execution
  3. PreToolUse hook checks for test files before allowing source edits
  4. Blocks with helpful message if tests don't exist:
TDD ENFORCEMENT: Cannot edit source file without corresponding test.

This plan has TDD mode ENFORCED. You must:
1. Create the test file FIRST
2. Write failing tests for the expected behavior
3. THEN edit the source file to make tests pass

Source file: src/auth/middleware.ts

Expected test file locations:
- Same directory: *.test.* or *.spec.*
- __tests__ subdirectory
- tests/ subdirectory

Supported Test Patterns

Language Test File Patterns
TypeScript/JavaScript *.test.ts, *.spec.ts, __tests__/*.ts
Python test_*.py, *_test.py, tests/test_*.py
Go *_test.go (same directory)
Ruby *_test.rb, *_spec.rb, spec/*_spec.rb
Rust tests/*.rs, inline #[test]

TDD Workflow Example

You: @plan Add user authentication

Prometheus: [asks about requirements...]
            What testing approach should we use?
            > TDD - Enforced

[Plan generated with Configuration section:]
## Configuration
- **TDD Mode**: enforced
- **Test Framework**: vitest

You: /start-work authentication

Sisyphus: Starting with TDD enforced.

         Task 1: Create auth middleware

         Creating test file first:
         → src/middleware/__tests__/auth.test.ts

         [test file created with failing tests]

         Now implementing source:
         → src/middleware/auth.ts

         [implementation complete, tests pass]

Auto-Verification

oh-my-claude automatically verifies code changes after every Edit or Write operation.

Supported Languages

Language Verification Method
TypeScript/JavaScript tsc --noEmit + ESLint
Python python -m py_compile (syntax check)
Go go build (compile check)
Rust cargo check
JSON jq validation
YAML Python yaml.safe_load

How It Works

  1. After Edit/Write: PostToolUse hook runs language-specific verification
  2. On Failure: Error message is injected, preventing commit claims
  3. On Success: Gentle reminder to run full test suite

Example Output

AUTO-VERIFICATION FAILED for src/utils/auth.ts

TypeScript errors detected:
error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

FIX these errors before proceeding. Do NOT commit or claim completion with errors present.

Verification Failure Tracking

The system tracks verification failures across the session:

  • Counter increments on each failed verification
  • Resets after successful git commit
  • PreCompact preserves failure count for context

Disabling Auto-Verification

To disable for a specific project, create .sisyphus/config.json:

{
  "autoVerification": {
    "enabled": false
  }
}

Or disable specific languages:

{
  "autoVerification": {
    "enabled": true,
    "skipLanguages": ["python", "go"]
  }
}

Trust Mode

Claude Code normally asks for permission before running commands or editing files. oh-my-claude offers a Trust Mode during installation that auto-approves common development operations.

Enabling Trust Mode

During installation, you'll see:

Permission Mode
Claude Code asks for permission before running commands and editing files.
You can auto-approve common development operations to reduce prompts.

  1) Trust mode (recommended for development)
     Auto-approve: npm, npx, git, file edits, file creation
     You'll still see what's happening, just fewer prompts

  2) Selective mode
     Only auto-approve MCP tools
     Manual approval for everything else

What Trust Mode Auto-Approves

Category Commands
Package managers npm, npx, yarn, pnpm, bun
Version control git
Build tools tsc, esbuild, vite, cargo, go, rustc
Test runners vitest, jest, pytest
File operations Edit, Write, MultiEdit
Utilities ls, mkdir, cp, mv, rm, chmod, cat, head, tail, grep, find
Runtimes node, python, python3, pip, pip3
MCP tools oh-my-claude, context7, grep_app

Manual Configuration

To modify permissions after installation, edit .claude/settings.json:

{
  "allowedTools": [
    "mcp__oh-my-claude__*",
    "mcp__context7__*",
    "Bash(npm *)",
    "Bash(git *)",
    "Edit",
    "Write"
  ]
}

Security Note

Trust mode is designed for development workflows where you trust the AI to run common commands. You still see all operations in the output - just without confirmation prompts.

For sensitive environments or production systems, use Selective mode and manually approve operations.

Context Preservation

When Claude Code compacts your conversation (due to context limits), the PreCompact hook preserves critical information.

What Gets Preserved

Context Type Description
Session Mode Orchestrator, planning, or normal mode
Active Plan Current boulder/plan being executed
Git State Current branch, uncommitted changes, worktree status
Recent Files Last 10 files you worked on
Blocking Issues Any issues preventing progress
Verification Failures Count of failed verifications this session
Notepad Wisdom Reference to learnings, decisions, issues

Snapshots

Each compaction creates a snapshot at .sisyphus/snapshots/snapshot_YYYYMMDD_HHMMSS.json. The last 5 snapshots are kept for recovery.

Troubleshooting

Debug Logging

To troubleshoot hook behavior and validate orchestration flow, enable debug logging:

Option 1: File marker (per-project)

touch .sisyphus/DEBUG

Option 2: Environment variable

export OH_MY_CLAUDE_DEBUG=true

Logs are written to .sisyphus/debug.log:

[2026-01-10 20:45:12.123] [HOOK] [pre-tool-use] === ENTRY ===
[2026-01-10 20:45:12.124] [HOOK] [pre-tool-use] Tool: Bash | Session: abc123
[2026-01-10 20:45:12.125] [HOOK] [pre-tool-use] Session mode: orchestrator
[2026-01-10 20:45:12.126] [HOOK] [pre-tool-use] Decision: allow
[2026-01-10 20:45:12.127] [HOOK] [pre-tool-use] === EXIT ===

To disable: remove the .sisyphus/DEBUG file or unset the environment variable.

"Command not found: jq"

Install jq:

# macOS
brew install jq

# Ubuntu/Debian
sudo apt install jq

# Fedora
sudo dnf install jq

Hooks Not Firing

  1. Check settings.json has the hook configuration
  2. Verify hook scripts are executable: chmod +x hooks/*.sh
  3. Check for syntax errors: bash -n hooks/user-prompt-submit.sh

MCP Server Not Connecting

  1. Verify it's built: cd mcp && npm run build
  2. Check the path in settings.json matches your installation
  3. Look for errors: node mcp/dist/index.js (should hang waiting for input)

Plan Not Generating

  1. Check .sisyphus/drafts/ for the draft file
  2. Ensure you said "Make it a plan" clearly
  3. Prometheus may need more information - answer more questions

Session Not Resuming Plan

  1. Check .sisyphus/boulder.json exists
  2. Verify the boulder has "complete": false
  3. The Stop hook should prompt you - check it's enabled

Orchestrator Editing Files Directly

If Sisyphus is editing files instead of delegating:

  1. Ensure ultrawork or ulw keyword was used
  2. Check PreToolUse hook is active
  3. The hook should block direct edits with a clear message

Directory Structure

oh-my-claude/
├── README.md                 # This file
├── install.sh                # Interactive installer
├── uninstall.sh              # Clean uninstaller
├── package.json              # Root package
│
├── hooks/                    # Shell hook scripts
│   ├── pre-tool-use.sh       # Orchestration constraints
│   ├── post-tool-use.sh      # Verification injection
│   ├── user-prompt-submit.sh # Intent classification
│   ├── stop.sh               # Continuation enforcement
│   ├── pre-compact.sh        # Context preservation
│   └── lib/                  # Shared utilities
│       ├── state.sh
│       ├── json-utils.sh
│       ├── intent-classifier.sh
│       └── config.sh
│
├── agents/                   # Agent prompt definitions
│   ├── AGENTS.md             # Main agent registry
│   ├── sisyphus.md
│   ├── orchestrator-sisyphus.md
│   ├── prometheus.md
│   ├── metis.md
│   ├── momus.md
│   ├── oracle.md
│   ├── librarian.md
│   ├── explore.md
│   ├── frontend-engineer.md
│   └── document-writer.md
│
├── mcp/                      # MCP server
│   ├── package.json
│   ├── tsconfig.json
│   └── src/
│       ├── index.ts
│       └── tools/
│           ├── boulder-state.ts
│           ├── notepad.ts
│           ├── draft.ts
│           └── worktree.ts
│
├── skills/                   # Workflow skills
│   ├── plan/
│   ├── start-work/
│   ├── frontend-ui-ux/
│   └── git-master/
│
├── config/                   # Configuration
│   ├── default-settings.json
│   ├── categories.json
│   ├── agents-config.json
│   └── worktrees.json
│
└── tests/                    # Test scenarios
    └── scenarios/
        ├── delegation.md
        ├── planning.md
        └── verification.md

Uninstall

Per-Project Uninstall

# Remove the installation
rm -rf .claude/oh-my-claude

# Edit .claude/settings.json to remove hooks and mcpServers entries

System-Wide Uninstall

./uninstall.sh

Or manually:

  1. Remove hooks from ~/.claude/settings.json
  2. Remove MCP server from settings
  3. Delete ~/.claude/oh-my-claude/

Credits

This project is a port of oh-my-opencode by @code-yeongyu. The original project's sophisticated multi-agent orchestration patterns have been adapted to work with Claude Code's native hook system and MCP protocol.

License

MIT

About

Multi-Agent Orchestration for Claude Code - Port of oh-my-opencode

Resources

Readme

License

View license
Activity

Stars

7 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages