Ralph

Un'implementazione funzionante della tecnica del loop autonomo di Ralph Wiggum per Claude Code.

Contesto

Il plugin ufficiale ralph-wiggum nel marketplace dei plugin di Anthropic è attualmente rotto a causa di un aggiornamento di sicurezza in Claude Code v1.0.20 (Agosto 2025).

La patch di sicurezza (CVE-2025-54795) blocca correttamente la sostituzione di comandi $() e i comandi bash su più righe per prevenire attacchi di command injection. Tuttavia, il file di comando del plugin ufficiale contiene bash su più righe che attiva questa protezione:

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

Sono state segnalate diverse issue:

• #12170 - 23 Nov 2025
• #15640 - 29 Dic 2025
• #15708 - 29 Dic 2025
• #16037 - 1 Gen 2026

Al 3 Gennaio 2026, queste rimangono irrisolte.

Questo Plugin

Questa è una reimplementazione pulita che funziona con le attuali restrizioni di sicurezza di Claude Code.

Differenza architetturale chiave: Il plugin ufficiale tenta di eseguire bash direttamente dal file di comando. Questo plugin invece istruisce Claude a creare il file di stato utilizzando il suo strumento Write, mantenendo il file di comando come puro markdown senza esecuzione bash. L'hook di stop viene eseguito come script shell separato al di fuori del sistema di permessi.

Installazione

Opzione 1: Modalità sviluppo (per test)

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

Opzione 2: Marketplace locale (per uso permanente)

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

# Sposta il plugin nel marketplace
mv /path/to/ralph ~/claude-plugins/

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

Utilizzo

/ralph:ralph-loop "Your task" --max-iterations 30 --completion-promise "DONE"

Argomenti

Esempi

/ralph:ralph-loop "Build a REST API with tests" --completion-promise "API_COMPLETE"

/ralph:ralph-loop "Follow the instructions in CLAUDE.md" --max-iterations 50 --completion-promise "BENCHMARK_COMPLETE"

Annulla

/ralph:cancel-ralph

Come Funziona

1. Comando istruisce Claude a creare .claude/ralph-loop.local.md con task e configurazione
2. Claude lavora sul task
3. Claude termina il suo turno (stop naturale)
4. Hook di stop si attiva, controlla il transcript per <promise>COMPLETION_PROMISE</promise>
5. Non trovato? → L'hook restituisce {"decision": "block", "reason": "..."}, Claude continua
6. Trovato? → L'hook permette lo stop, pulisce il file di stato
7. Iterazioni massime? → L'hook permette lo stop indipendentemente

Requisiti

• Claude Code 1.0.20+
• jq (per il parsing JSON nell'hook di stop)

Crediti

• Geoffrey Huntley — Tecnica Ralph originale
• Boris Cherny — Plugin ufficiale
• Ralph — Questa reimplementazione funzionante

Licenza

MIT