Ralph Hero

A Claude Code plugin that turns Claude into an autonomous software engineer. Ralph triages issues, researches codebases, writes implementation plans, codes in isolated worktrees, creates PRs, and merges -- all driven by a GitHub Projects V2 board.

The naive hero picks tickets, does their best work, and moves on.

How It Works

Ralph manages GitHub issues through a structured workflow state machine:

Backlog → Research Needed → Research in Progress → Ready for Plan
       → Plan in Progress → Plan in Review → In Progress → In Review → Done

Each transition is enforced by hooks and validated by the MCP server. Issues flow through phases -- triage, research, planning, review, implementation, and merge -- with human checkpoints at plan review and code review.

Autonomous mode (/ralph-hero:hero): Ralph drives an issue tree end-to-end, splitting large tickets, researching each sub-issue, creating plans, and implementing them sequentially.

Interactive mode: Use individual skills like /ralph-hero:plan or /ralph-hero:impl with human-in-the-loop verification at each step.

Team mode (/ralph-hero:team): Spawns parallel specialist agents (analyst, builder, integrator) to process issues concurrently.

Installation

Prerequisites

• Claude Code CLI
• Node.js 18+
• A GitHub Personal Access Token with repo and project scopes

Install the Plugin

claude plugins add cdubiel08/ralph-hero

Configure

Add your GitHub token and project settings to .claude/settings.local.json (gitignored):

{
  "env": {
    "RALPH_HERO_GITHUB_TOKEN": "ghp_your_token_here",
    "RALPH_GH_OWNER": "your-github-username",
    "RALPH_GH_PROJECT_NUMBER": "1"
  }
}

Set Up Your Project Board

/ralph-hero:setup

This creates a GitHub Projects V2 board with the required custom fields: Workflow State, Priority, and Estimate.

Token Expired?

gh auth refresh -s repo,project,read:org

Then restart Claude Code. Run just doctor if anything still looks off.

If you're using explicit RALPH_GH_REPO_TOKEN / RALPH_GH_PROJECT_TOKEN / RALPH_HERO_GITHUB_TOKEN: regenerate the PAT at https://github.com/settings/tokens, update ~/.claude/settings.json (or .claude/settings.local.json), restart Claude Code.

Skills

Autonomous Workflow

Run the full pipeline or individual phases:

Interactive Workflow

Human-in-the-loop skills for collaborative development:

Project Management

MCP Server

The plugin bundles an MCP server (ralph-hero-mcp-server) that provides GitHub Projects V2 tools to Claude Code via the Model Context Protocol.

Tools

Architecture

plugin/ralph-hero/
├── .claude-plugin/plugin.json     # Plugin manifest
├── .mcp.json                      # MCP server configuration
├── mcp-server/                    # TypeScript MCP server
│   └── src/
│       ├── index.ts               # Server entrypoint
│       ├── github-client.ts       # GraphQL client (rate limiting, caching, dual-token)
│       ├── types.ts               # GitHub Projects V2 type definitions
│       ├── tools/                 # Tool implementations
│       │   ├── issue-tools.ts
│       │   ├── project-tools.ts
│       │   ├── project-management-tools.ts
│       │   ├── relationship-tools.ts
│       │   ├── batch-tools.ts
│       │   ├── dashboard-tools.ts
│       │   ├── hygiene-tools.ts
│       │   ├── decompose-tools.ts
│       │   └── debug-tools.ts
│       ├── lib/                   # Shared libraries
│       │   ├── workflow-states.ts  # State machine definitions
│       │   ├── cache.ts            # Session and field option caching
│       │   ├── rate-limiter.ts     # Proactive rate limit tracking
│       │   ├── pagination.ts       # GraphQL cursor pagination
│       │   ├── dashboard.ts        # Pipeline aggregation logic
│       │   ├── hygiene.ts          # Board health analysis
│       │   ├── metrics.ts          # Velocity and throughput metrics
│       │   ├── group-detection.ts  # Epic/feature group detection
│       │   ├── pipeline-detection.ts
│       │   ├── filter-profiles.ts  # Query filter presets
│       │   ├── state-resolution.ts # State conflict resolution
│       │   ├── routing-engine.ts   # Issue routing logic
│       │   ├── repo-registry.ts    # Multi-repo registry types
│       │   └── ...
│       └── __tests__/             # 38 test files (vitest)
├── skills/                        # 30 skill definitions
├── agents/                        # 10 specialized agents
├── hooks/                         # 50+ workflow enforcement hooks
└── scripts/                       # CLI and automation scripts

Agents

Ralph uses specialized agents for parallel task execution:

Hooks

Ralph enforces workflow integrity through lifecycle hooks:

• State gates -- Verify issues are in the correct workflow state before skills run
• Branch gates -- Ensure operations requiring main branch are on main
• Worktree gates -- Validate worktree setup for implementation
• Postcondition validators -- Confirm expected outputs (documents committed, comments posted, state changed)
• Artifact validators -- Ensure research/plan documents follow naming conventions
• Lock management -- Prevent concurrent processing of the same issue
• Team protocol validators -- Enforce multi-agent coordination rules

CI/CD

Configuration

Set all variables in .claude/settings.local.json under the "env" key. Do not put tokens in .mcp.json.

Development

cd plugin/ralph-hero/mcp-server
npm install
npm run build
npm test

Tests use Vitest with 38 test files covering tools, lib modules, and integration scenarios.

Release process: Merges to main that touch MCP server source automatically bump the version, tag, and publish to npm. Include #minor or #major in a commit message for larger version bumps.

Security

To report a vulnerability or review our supported versions and disclosure process, see SECURITY.md.

License

MIT