Smart Ralph is a Claude Code and Codex plugin that transforms vague feature ideas into structured specifications, then executes them task-by-task with fresh context. It prevents context degradation and hallucinated code by breaking complex features into small, focused tasks.

How do I install Smart Ralph for Claude Code?

Run /plugin marketplace add tzachbon/smart-ralph followed by /plugin install ralph-specum@smart-ralph in Claude Code, then restart. For Codex, clone the repo and copy the plugin to ~/.codex/plugins.

What is the Ralph agentic loop pattern?

The Ralph loop pattern, named after ghuntley.com/ralph, is an approach where AI agents execute one small task at a time, refresh context, then move to the next. This prevents the performance degradation that happens during long coding sessions.

Why does my AI coding agent hallucinate imports?

AI agents hallucinate imports when they lose track of context during long sessions. Smart Ralph fixes this by completing one task, refreshing memory, and starting the next task with clean context. No accumulated confusion.

What is spec-driven development?

Spec-driven development creates structured documentation (research, requirements, design, tasks) before writing any code. Smart Ralph automates this: it researches your codebase, generates requirements and design docs, then breaks work into executable tasks.

How does Smart Ralph prevent context degradation?

After each task completes, Smart Ralph reloads context from your spec files. This means the agent never accumulates stale information from previous tasks, preventing the quality degradation you see in long coding sessions.

Does Smart Ralph work with Codex CLI?

Yes. Smart Ralph provides a Codex plugin (ralph-specum-codex) with 14 helper skills. Install it to ~/.codex/plugins and use $ralph-specum commands like $ralph-specum-start, $ralph-specum-triage, and $ralph-specum-implement.

What is triage mode in Smart Ralph?

Triage mode (/ralph-specum:triage) decomposes large features into multiple specs. Instead of one massive spec, you get an epic with linked sub-specs that can be executed independently.

Is Smart Ralph open source?

Yes. Smart Ralph is MIT licensed with 385+ stars on GitHub. Source code at github.com/tzachbon/smart-ralph.

Smart Ralph: Spec-Driven Development for Claude Code and Codex

By Prahlad Menon Published 2026-07-01 3 min read

Ever asked an AI coding agent to “add user authentication” and watched it spiral into a 2000-line monstrosity? Smart Ralph fixes that.

What Is Smart Ralph?

Smart Ralph is a Claude Code and Codex plugin that acts like a tiny product team in your terminal. Give it a loose feature idea, and it:

Researches your codebase and the web
Creates requirements (user stories, acceptance criteria)
Designs architecture (patterns, decisions, tradeoffs)
Breaks down tasks (POC-first, small and executable)
Executes one task at a time with fresh context

The magic is in that last part. Instead of trying to hold your entire codebase in context while writing hundreds of lines, Ralph completes one focused task, refreshes its memory, and moves to the next. No context degradation. No hallucinated imports from files it forgot existed.

The Ralph Loop Pattern

Smart Ralph is named after the Ralph agentic loop pattern and everyone’s favorite Springfield student. The philosophy: don’t overthink, just do the next task.

You: "Add user authentication"
Ralph: *creates research.md, requirements.md, design.md, tasks.md*
Ralph: *executes task 1 with fresh context*
Ralph: *executes task 2 with fresh context*
...
Ralph: "I'm helping!"

Key Features

Spec-Driven Development: Every feature starts with structured documentation before any code is written. Research → Requirements → Design → Tasks → Implementation.

Fresh Context Per Task: After each task completes, Ralph reloads context. This prevents the performance degradation that happens when AI agents work on large files or long sessions.

Triage Mode: For big features that are really multiple specs in disguise, /ralph-specum:triage decomposes them into an epic with linked sub-specs.

Both Claude Code and Codex: Works as a native plugin for Claude Code, and as a skill package for Codex with 14 helper commands.

Getting Started

For Claude Code:

/plugin marketplace add tzachbon/smart-ralph
/plugin install ralph-specum@smart-ralph

For Codex:

git clone https://github.com/tzachbon/smart-ralph.git /tmp/smart-ralph
mkdir -p ~/.codex/plugins
cp -R /tmp/smart-ralph/plugins/ralph-specum-codex ~/.codex/plugins/

Then:

# Smart start (auto-detects resume or new)
/ralph-specum:start user-auth Add JWT authentication

# Quick mode (skip interactive approvals)
/ralph-specum:start "Add user auth" --quick

Why This Matters

The problem with AI coding agents isn’t intelligence — it’s focus. Give Claude or GPT a complex task, and they’ll often:

Write too much code at once
Lose track of what they’ve already implemented
Hallucinate imports or function signatures
Create inconsistent patterns across the codebase

Smart Ralph enforces discipline. By breaking work into small, focused tasks with context refresh between each, it mimics how experienced developers actually work: understand, plan, execute incrementally, verify.

385 stars on GitHub and growing. MIT licensed.

Check it out: github.com/tzachbon/smart-ralph

Frequently Asked Questions

Q: Does Smart Ralph require any external services? A: No. Smart Ralph is self-contained with no external dependencies. It uses your existing Claude Code or Codex setup.

Q: Can I use Smart Ralph for existing codebases? A: Yes. The research phase analyzes your existing codebase structure, so Ralph understands what’s already there before proposing changes.

Q: How is this different from just asking Claude to break tasks down? A: Smart Ralph enforces the breakdown through a structured workflow with separate phases. More importantly, it reloads context between tasks — something you can’t do with a single Claude conversation.

Follow @themedcave for more open source agent tooling.