Ralph

Una implementación funcional de la técnica de bucle autónomo Ralph Wiggum para Claude Code.

Antecedentes

El plugin oficial ralph-wiggum en el mercado de plugins de Anthropic actualmente no funciona debido a una actualización de seguridad en Claude Code v1.0.20 (agosto de 2025).

El parche de seguridad (CVE-2025-54795) bloquea correctamente la sustitución de comandos $() y los comandos bash multilínea para prevenir ataques de inyección de comandos. Sin embargo, el archivo de comandos del plugin oficial contiene bash multilínea que activa esta protección:

Error: Bash command permission check failed for pattern "...": 
Command contains newlines that could separate multiple commands

Se han presentado múltiples incidencias:

• #12170 - 23 de noviembre de 2025
• #15640 - 29 de diciembre de 2025
• #15708 - 29 de diciembre de 2025
• #16037 - 1 de enero de 2026

A fecha de 3 de enero de 2026, siguen sin resolverse.

Este Plugin

Esta es una reimplementación limpia que funciona con las restricciones de seguridad actuales de Claude Code.

Diferencia arquitectónica clave: El plugin oficial intenta ejecutar bash directamente desde el archivo de comandos. Este plugin, en cambio, indica a Claude que cree el archivo de estado usando su herramienta Write, manteniendo el archivo de comandos como markdown puro sin ejecución de bash. El hook de parada se ejecuta como un script de shell independiente fuera del sistema de permisos.

Instalación

Opción 1: Modo de desarrollo (para pruebas)

claude --plugin-dir /path/to/ralph

Opción 2: Mercado local (para uso permanente)

# Crear mercado
mkdir -p ~/claude-plugins/.claude-plugin
echo '{"name": "local", "owner": {"name": "You"}}' > ~/claude-plugins/.claude-plugin/marketplace.json

# Mover plugin al mercado
mv /path/to/ralph ~/claude-plugins/

# En Claude Code:
/plugin marketplace add ~/claude-plugins
/plugin install ralph@local

Uso

/ralph:ralph-loop "Tu tarea" --max-iterations 30 --completion-promise "HECHO"

Argumentos

Argumento	Descripción	Valor por defecto
prompt	La tarea a completar	(obligatorio)
--max-iterations N	Límite de seguridad	30
--completion-promise TEXTO	Señal de finalización	TASK_COMPLETE

Ejemplos

/ralph:ralph-loop "Construye una API REST con pruebas" --completion-promise "API_COMPLETE"

/ralph:ralph-loop "Sigue las instrucciones en CLAUDE.md" --max-iterations 50 --completion-promise "BENCHMARK_COMPLETE"

Cancelar

/ralph:cancel-ralph

Cómo Funciona

1. Comando indica a Claude que cree .claude/ralph-loop.local.md con la tarea y configuración
2. Claude trabaja en la tarea
3. Claude finaliza su turno (parada natural)
4. Hook de parada se activa, revisa el transcript en busca de <promise>COMPLETION_PROMISE</promise>
5. ¿No encontrado? → El hook devuelve {"decision": "block", "reason": "..."}, Claude continúa
6. ¿Encontrado? → El hook permite la parada, limpia el archivo de estado
7. ¿Máximas iteraciones? → El hook permite la parada sin importar nada más

Requisitos

• Claude Code 1.0.20+
• jq (para análisis JSON en el hook de parada)

Créditos

• Geoffrey Huntley — Técnica Ralph original
• Boris Cherny — Plugin oficial
• Ralph — Esta reimplementación funcional

Licencia

MIT