Smart Ralph: a Claude Code plugin that turns a feature request into a spec, then executes it task by task
Spec-driven development with smart compaction. Claude Code plugin combining Ralph Wiggum loop with structured specification workflow.
At a glance
- What is it?
- Smart Ralph wraps the Ralph Wiggum loop in a spec-driven workflow: research, requirements, design and tasks are written to disk before any code runs. The plugin is MIT licensed and Shell based, and it targets Claude Code and Codex users who want approval checkpoints rather than one long autonomous run.
- Who is it for?
- Adopt Smart Ralph if you already work inside Claude Code or Codex and your features are large enough that a single prompt would lose context. Skip it for one-file edits, for repositories where you cannot commit spec artifacts, and for any workflow that needs a non-Anthropic runtime.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 6 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Smart Ralph targets: context loss in long agent runs
A single long agent session degrades. The model that wrote the first file is not the model reasoning about the tenth, because the window has filled with tool output and half-finished edits. Smart Ralph's answer is to move the durable state out of the conversation and into the repository. The README states that it creates research, requirements, design and task files before implementation, and that the spec files stay in the project so each phase can be reviewed or edited before execution. Progress is recorded between tasks, and the plugin can resume after a stopped session. That is the whole premise: the conversation becomes disposable, the files do not.
The audience is narrow and specific. You need Claude Code or Codex installed, you need a repository where adding a specs directory is acceptable, and you need features big enough to justify four planning artifacts. A one-line bug fix does not benefit from a requirements document. The README's own quick start uses "Add JWT authentication" as the example goal, which is a reasonable signal of the intended size.
How the pipeline actually flows, from /start to execution
The entry point is /start, which the README describes as detecting scope. If the goal fits one spec, the flow is linear: research, then requirements, then design, then tasks, then execution. If the goal is too big, /start routes to /triage instead, which runs its own sub-pipeline of exploration research, a triage analyst, validation research, and a finalized epic plan. That epic plan then emits Spec 1, Spec 2 and so on, each of which re-enters the normal research-to-execution chain.
Each phase is handed to a named agent rather than the same general-purpose assistant. The README lists them: triage-analyst splits features and maps dependencies, research-analyst inspects the codebase and checks feasibility, product-manager writes user stories and acceptance criteria, architect-reviewer defines architecture and trade-offs, task-planner produces a POC-first sequence, and spec-executor implements tasks and runs quality gates. The separation matters because it means the requirements phase is not being asked to also think about implementation details.
Execution itself follows four ordered phases per the README: make it work with a proof of concept, refactor the working implementation, add unit, integration and end-to-end coverage, then run lint, type and CI checks as quality gates. Each implementation task starts with fresh context. That last detail is the mechanism that distinguishes this from a plain agent loop, and it is also the reason the spec files have to be good. Fresh context means the executor only knows what the task file and the surrounding artifacts tell it.
Installation and the commands you will actually type
For Claude Code, the README gives two commands: /plugin marketplace add tzachbon/smart-ralph, then /plugin install ralph-specum@smart-ralph. Restart Claude Code afterwards. For local development against a clone, the documented invocation is claude --plugin-dir ./plugins/ralph-specum.
Codex takes a different path. The marketplace command is codex plugin marketplace add tzachbon/smart-ralph with two --sparse flags pointing at .agents/plugins and plugins/ralph-specum-codex, followed by codex plugin add ralph-specum@smart-ralph. The README instructs you to start a new Codex task after installation, then run /hooks, review the bundled Stop hook, and trust it if you want automatic task execution. Until that hook is trusted, you run $ralph-specum-implement once per task by hand. That is a meaningful difference from the Claude Code path, where the loop is expected to drive itself.
Command namespaces differ by platform. Claude Code uses /ralph-specum:<name>, for example /ralph-specum:start user-auth "Add JWT authentication". Codex uses $ralph-specum-<name> and folds new into $ralph-specum-start. The README notes that Codex asks for approval after each spec artifact unless the command includes the exact --quick flag. Planning controls include --tasks-size fine or coarse for granularity, a [P] marker for low-conflict parallel tasks, and [VERIFY] plus VE tasks for explicit verification.
The prototype phase and its worktree isolation rules
Prototypes are the part of the design with the most explicit constraints, and they are worth reading closely. In normal mode, Smart Ralph may suggest a prototype after research or requirements, and you can also invoke /ralph-specum:prototype at what the README calls a safe phase boundary. In quick mode, no prototype questions are asked at all: the plugin owns the decisions and always continues to design after the prototype outcome.
Source handling is where the rules get concrete. Prototype source stays in a sibling worktree or an eligible scratch directory. Quick mode transfers no source into the current checkout. Normal mode transfers only paths you approve. The README also states that reviewed terminal records are immutable, and that local evidence does not authorize a push, a remote branch, a PR update, an issue write, or record deletion. Those are unusual restrictions for a coding agent plugin, and they read as a deliberate response to the failure mode where a throwaway experiment quietly becomes committed production code.
The trade-off is friction. If you are prototyping something you already intend to keep, quick mode's refusal to transfer source into the checkout means you will retype or re-apply the work. That is the correct default for a disposable experiment and the wrong one for a spike you planned to keep.
Where the workflow breaks down or is the wrong tool
The clearest limitation is the artifact overhead. Four planning documents plus a tasks file, plus a .progress.md file, for every spec. On a small change that is more writing than coding, and the review burden lands on you because the README explicitly positions the artifacts as reviewable and editable between phases. If nobody reads them, the pipeline is generating paperwork that the executor then treats as ground truth.
Fresh context per task is a genuine constraint as well as a feature. A task file that under-specifies a dependency will produce an executor that does not know the dependency exists. The README's answer is the [VERIFY] and VE task markers and the POC-first ordering, but those only help if the task planner got the decomposition right in the first place.
The Codex path has an extra failure mode documented in the README itself: until you review and trust the bundled Stop hook, automatic task execution does not happen and you must run $ralph-specum-implement per task. Someone who installs the Codex plugin and expects the Claude Code behaviour will find the loop stalled and may not connect that to the hook. There is also no homepage listed for the project, so the README and the in-repo Codex installation guide are the documentation surface you get.
Finally, this is a plugin for Claude Code and Codex specifically. If your team standardises on a different agent runtime, none of the command surface transfers.
How it differs from running the bare Ralph loop
The plain Ralph Wiggum pattern, as commonly described, is a loop that repeatedly feeds a prompt to an agent until the work is done, with the prompt and whatever is in the working tree as the only state. Smart Ralph keeps the loop but inserts a planning pipeline in front of it and a file-based memory behind it. The README's v2.0.0 release is titled Ralph Wiggum Integration, which is when that loop was folded in, and v3.1.1 is titled Self-contained execution loop, which the README reflects in the claim that the execution loop has no external plugin dependencies.
The practical difference is where correction happens. With a bare loop you correct by interrupting and re-prompting. With Smart Ralph you can edit the requirements or design file before execution, or run /ralph-specum:refactor to update requirements, design or tasks. That is a different kind of intervention: you are fixing the specification rather than the transcript. The cost is latency, since nothing executes until the artifacts exist, and the benefit is that a wrong assumption is caught in a document instead of in ten edited files.
A lighter alternative for the same problem is to keep the agent loop and rely on a codebase index plus a single written plan. Smart Ralph's /ralph-specum:index command scans an existing project and writes searchable component specs under specs/.index/, which research agents then use to find code the project already has. That index is useful on its own even if you never run the full triage pipeline.
Maintenance cost, licensing and what to check before committing
The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the standard permissive arrangement, and it means the plugin can be vendored into a private repository without a legal review in most organisations. This is a description of the licence text, not legal advice; if your organisation has rules about bundling third-party code, follow those rules.
Upgrade cost is shaped by the plugin architecture. Installation goes through a marketplace command, and the README notes that the in-repo Codex installation guide covers updates, local development with codex plugin marketplace add ., and migration from the old platforms/codex/ skills path. That migration note is the signal that the plugin layout has moved at least once, and the release history supports the same reading: v2.0.0, v3.1.1 and v4.0.0 are major or near-major jumps within roughly a year, with v4.0.0 subtitled Plugin Best Practices v2. Expect the command surface and the on-disk spec layout to keep shifting between minor versions.
Before adopting, verify three things in your own checkout. Confirm that the specs directory and .progress.md are acceptable in your repository and your .gitignore policy. Run /ralph-specum:index on a small existing project and read the output under specs/.index/ to see whether the generated component specs describe your code accurately. And on Codex, run /hooks and read the bundled Stop hook before trusting it, because that decision is what turns the loop from manual to automatic.
Editorial conclusion
Adopt Smart Ralph if you already work inside Claude Code or Codex and your features are large enough that a single prompt would lose context. Skip it for one-file edits, for repositories where you cannot commit spec artifacts, and for any workflow that needs a non-Anthropic runtime. Before trusting it on real work, run /ralph-specum:index on a small existing project and read the generated files under specs/.index/ to confirm the index describes code you recognise.
Community notes