Smart Ralph
Turns a feature request into a structured spec, then executes it task by task — spec-driven development for Claude Code and Codex.
- Source repo
- tzachbon/smart-ralph
- Stars
- ★ 561
- Last updated
- 1mo ago
- License
- MIT
- Primary language
- Shell
- FA score
- 73/100 · Some gaps
At a glance
- How it runs
- Works with
- Portable with changesCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers adding features to an existing codebase: run /ralph-specum:index first so research agents can reuse indexed component specs
- Not a fit if
- Teams not using Claude Code or OpenAI Codex as their agent runtime
- Teams unwilling to review and trust the bundled Stop hook
- Adopters who need published benchmarks before choosing a tool
- Source review
- 73/100 · Some gaps
What does this agent do, and when should you use it?
Smart Ralph (tzachbon/smart-ralph) is an MIT-licensed Claude Code plugin that also supports OpenAI Codex, combining the Ralph Wiggum loop with a structured specification workflow. It first converts a feature request into research, requirements, design, and task files, then executes the spec task by task with focused subagents (research-analyst, product-manager, architect-reviewer, task-planner, spec-executor), each implementation task starting with fresh context. Spec files persist in the project's specs/ directory so you can review or edit each phase; progress is recorded in .progress.md and a stopped session resumes via /ralph-specum:start. Large goals can be split by /ralph-specum:triage into dependency-aware epic specs. The repository also ships an alternative ralph-speckit plugin for GitHub's Spec-Kit methodology and an /ralph-specum:index command that writes searchable component specs for existing codebases.
After you invoke /ralph-specum:start [name] "goal" (Claude Code) or $ralph-specum-start (Codex), Smart Ralph runs a pipeline: research-analyst inspects the codebase and searches the web; product-manager writes user stories and acceptance criteria; architect-reviewer defines architecture and trade-offs; task-planner creates a POC-first task sequence; spec-executor implements tasks one at a time, each task passing through make-it-work POC, refactoring, testing, and quality-gate phases (lint, type, CI checks). /ralph-specum:triage splits oversized goals into epic plans; /ralph-specum:prototype tests one design question at a safe phase boundary using a disposable worktree; /ralph-specum:index scans a project and writes searchable component specs under specs/.index/. The --quick flag generates all phases and executes without stopping for approval; --tasks-size fine|coarse controls granularity; [P] marks low-conflict parallel tasks and [VERIFY]/VE tasks denote explicit verification. State lives in .ralph-state.json and .progress.md, with artifacts written to research.md, requirements.md, design.md, and tasks.md under specs/<feature>/.
- Developers adding features to an existing codebase: run /ralph-specum:index first so research agents can reuse indexed component specs
- Users whose goal spans several features or systems: use /ralph-specum:triage to split it into a dependency-aware epic plan
- Teams that want phase-by-phase control: run default mode and approve each artifact between research, requirements, and design
- Solo developers who want fast results: use --quick to generate all spec phases and execute without stopping
- Teams following GitHub's Spec-Kit governance: install the ralph-speckit plugin for a project constitution and requirement-to-task traceability
- Developers unsure about one design decision: run /ralph-specum:prototype at a phase boundary to validate with disposable evidence
How do you install or deploy this agent?
Claude Code: run /plugin marketplace add tzachbon/smart-ralph, then /plugin install ralph-specum@smart-ralph, and restart Claude Code. Codex: run codex plugin marketplace add tzachbon/smart-ralph --sparse .agents/plugins --sparse plugins/ralph-specum-codex, then codex plugin add ralph-specum@smart-ralph; start a new Codex task, run /hooks, review the bundled Stop hook, and trust it for automatic task execution. For local Claude Code development, clone the repository and run claude --plugin-dir ./plugins/ralph-specum.
How do you use this agent?
In Claude Code, run /ralph-specum:start user-auth "Add JWT authentication" for your first spec; add --quick to skip approvals; run /ralph-specum:start with no arguments to resume the active spec. In Codex, use $ralph-specum-start user-auth "Add JWT authentication" or $ralph-specum to let the plugin choose the next action; use $ralph-specum-triage for multi-feature goals. Other key commands: /ralph-specum:research, /ralph-specum:requirements, /ralph-specum:design, /ralph-specum:tasks, /ralph-specum:implement (execute tasks one at a time), /ralph-specum:status (show progress), and /ralph-specum:cancel (cancel execution and remove loop state). On Codex, until the Stop hook is trusted, run $ralph-specum-implement once per task.
What are this agent's strengths and limitations?
- Spec files (research/requirements/design/tasks) persist in the project for review, editing, and resumption, making execution transparent
- Each phase runs in a dedicated subagent, and tasks follow POC validation → refactoring → testing → quality gates with lint, type, and CI checks
- Triage splits large goals into dependency-aware epic plans, and indexing produces searchable component specs that research reuses
- Supports both Claude Code and Codex; since v3.0.0 the execution loop lives in the plugin's Stop hook, removing the need for the separate Ralph Loop plugin
- Tightly bound to the Claude Code and OpenAI Codex host runtimes, with no documented path to other models or environments
- Codex requires reviewing and trusting the bundled Stop hook for automatic execution; otherwise you must run $ralph-specum-implement manually per task
- Upgrading from v2.x requires awareness that v3.0.0 moved execution into the Stop hook; the old Ralph Loop plugin may need uninstalling
- Default mode requires human approval between phases, making the full flow slower; --quick mode skips prototype questions and lets the plugin own design decisions
- The repository publishes no quantitative benchmarks of success rates or performance, so adopters must validate it on their own workloads
How does this agent compare with similar options?
The repository itself offers two workflows: ralph-specum (specs in specs/, best for fast iteration) and ralph-speckit (follows GitHub's Spec-Kit, stores in .specify/specs/ with a project constitution and requirement-to-task traceability, best for team governance and audit trails). Since v3.0.0, Smart Ralph's built-in execution loop also replaces the previously separate Ralph Loop plugin.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Smart Ralph This agent | 73 · Some gaps | Agent plugin / skillFree + model costs | ★ 561 | 1mo ago | Shell | Codex · Claude Code |
| OSpec | 50 · Major gaps | CLIFree + model costs | ★ 391 | 1mo ago | JavaScript | Codex · Claude Code |
| Spec Kit | 78 · Good | CLI | ★ 142k | today | Python | — |
| Autoprompt Skill | 69 · Some gaps | CLIFree + model costs | ★ 1.2k | 19d ago | JavaScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Docs state least-privilege external-effect controls (immutable reviewed terminal records, no push/PR/issue authorization), approval checkpoints between phases (except --quick), and rollback via /cancel, resume state, and .ralph-state. cleanup. Deductions: most claims are README assertions — the actual Stop hook and permission scripts were not in evidence; sensitive-data handling (e.g., index recording MCP servers/URLs, credential risk) is unaddressed; publisher identity is unverified.
Version-sync tests, lock lifecycle tests, and Windows/POSIX process-control tests show strong internal consistency; failure surfaces like StateError, terminationUnverified, and controlError are concretely designed. Deductions: failure-message quality is corroborated only indirectly via tests; recovery guidance points to TROUBLESHOOTING.md whose content was not provided; dependency availability only inferred from CI installs of bats/jq/ripgrep.
Targets both Claude Code and Codex with triage, prototype, and codebase-indexing scenarios; native and simulated Windows coverage shows strong environment fit. Deductions: capability boundaries and trigger precision rely on the command table and flowchart; edge conditions (non-git projects, very large repos) are not spelled out.
README is well structured; installation covers both platforms plus local development and migration; MIT LICENSE file present; CI enforces semver bump and version sync; upgrade notes exist. Deductions: known limitations live in TROUBLESHOOTING.md (not provided); dual specum/speckit plugins and a v2→v3 migration slightly burden naming stability; CONTRIBUTING.md content absent, so maintenance responsibility can only be credited for the reference.
Artifacts are structured spec files kept in the project, human-reviewable and editable, with per-task progress and resume — high output usability. Deductions: marginal value over native planning is not quantified; autonomous loop with fresh context per task may raise token cost, and cost/benefit is not discussed.
README claims about locking, exclusive publication, and receipt-gated publication after source deletion are each backed by unit tests — notable cross-source corroboration. Deductions: some key claims (Stop hook behavior, quick-mode transfer policy) have no implementation files in evidence to check; facts and inference are mostly, but not uniformly, separated.
- Trust conclusions rest largely on README claims; review the Stop hook script and plugin source yourself before installing to confirm behavior matches the docs.
- --quick mode bypasses inter-phase approvals; use it only in controlled environments where continuous autonomous execution is acceptable.
- The indexing feature records external URLs, MCP servers, and installed skills; it may capture sensitive environment details — avoid committing it to public repositories.
- Prototype execution launches and terminates processes (taskkill/killpg); validate in an isolated or sandboxed environment before production use.
- TROUBLESHOOTING.md and CONTRIBUTING.md were not part of the evidence; verify recovery and contribution procedures independently.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v4.0.0 v4.0.0 — Plugin Best Practices v2
Release notes excerpt
Breaking Changes - Commands slimmed to thin orchestrators — procedural logic extracted into 13 references/ files (~60-88% line reduction per command) - Sequential Review Pattern removed — Layer 5 (Artifact Review) is now the single reviewer invocation per task - State updates require explicit jq merge — phase commands no longer use ambiguous JSON literals that could overwrite existing state fields Highlights …View on GitHub ↗ -
v3.1.1 v3.1.1 - Self-contained execution loop
Release notes excerpt
What's New v3.0.0+ - Self-contained Execution Loop Smart Ralph is now fully self-contained with no external plugin dependencies. Key Changes: - 🎉 No more ralph-loop dependency - The execution loop is handled by the built-in stop-hook - 📦 Simpler installation - Just one plugin to install - 🔧 No version compatibility issues between plugins Migration from v2.x 1. Update Smart Ralph to v3.0.0+ 2. Restart Claude Code 3. Existing specs continue working - no changes needed 4. Optionally uninstall ralph-loop if you don't use it elsewhere Installation ```bash …View on GitHub ↗ -
v2.0.0 v2.0.0 - Ralph Wiggum Integration
Release notes excerpt
Breaking Changes Ralph Wiggum plugin now required for task execution. Starting with v2.0.0, Smart Ralph delegates the execution loop to the official Ralph Wiggum plugin instead of using a custom stop-handler. Before upgrading Install the Ralph Wiggum dependency: ```bash /plugin install ralph-wiggum@claude-plugins-official ``` Then restart Claude Code. Migration Guide See [MIGRATION.md](https://github.com/tzachbon/smart-ralph/blob/main/MIGRATION.md) for detailed upgrade instructions. What Changed | Before (v1.x) | After (v2.0.0) | |---------------|----------------| …View on GitHub ↗