PHPackages woda/laravel-ralph - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. woda/laravel-ralph ActiveLibrary[Utility & Helpers](/categories/utility) woda/laravel-ralph ================== Claude Code agent loop runner for Laravel 0223—0%PHPCI failing Since Feb 24Pushed 2mo agoCompare [ Source](https://github.com/wwwoda/laravel-ralph)[ Packagist](https://packagist.org/packages/woda/laravel-ralph)[ RSS](/packages/woda-laravel-ralph/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependenciesVersions (3)Used By (0) Ralph ===== [](#ralph) Claude Code agent loop runner for Laravel. Runs Claude CLI iteratively in a GNU screen session, tracking progress, detecting completion, and logging everything. Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 11 or 12 - Node.js - [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude` in PATH) - GNU `screen` (not needed with `--once`) Installation ------------ [](#installation) ``` composer require woda/laravel-ralph ``` Setup ----- [](#setup) ``` php artisan ralph:init ``` Configures `.claude/settings.json` with sandbox permissions so Claude doesn't hang waiting for bash approval. Usage ----- [](#usage) ``` # Interactive — choose from open GitHub issues, PRDs, or enter a prompt manually php artisan ralph:start # Work on a GitHub issue php artisan ralph:start --issue=42 # Inline prompt php artisan ralph:start --prompt="Refactor the payment service" # Prompt from file php artisan ralph:start --prompt=prompts/task.md # Single iteration, foreground (no screen) php artisan ralph:start --once --prompt="Fix the failing tests" ``` ### Options [](#options) FlagDescription`name`Session name (argument, optional)`--issue=N`Work on a GitHub issue`--prompt=TEXT|FILE`Inline prompt or path to prompt file`--iterations=N`Max iterations (default: 30)`--model=MODEL`Override Claude model`--budget=USD`Max spend per Claude invocation`--fresh`Don't resume — each iteration is independent`--resume`Resume a previous session`--attach`Auto-attach to screen after start`--once`Single iteration in foreground### Managing Sessions [](#managing-sessions) ``` # List running sessions php artisan ralph:status php artisan ralph:status --json php artisan ralph:status --clean # Remove dead entries # Attach to a session php artisan ralph:attach php artisan ralph:attach my-feature # Kill a session php artisan ralph:kill my-feature php artisan ralph:kill --all --force # View logs php artisan ralph:logs php artisan ralph:logs --tail php artisan ralph:logs --lines=100 php artisan ralph:logs --all # List all log files ``` Configuration ------------- [](#configuration) ``` php artisan vendor:publish --tag=ralph-config ``` ### `config/ralph.php` [](#configralphphp) ``` 'loop' => [ 'default_iterations' => env('RALPH_LOOP_ITERATIONS', 30), 'permission_mode' => env('RALPH_PERMISSION_MODE', 'acceptEdits'), 'model' => env('RALPH_MODEL'), 'completion_marker' => 'COMPLETE', 'max_consecutive_failures' => env('RALPH_MAX_CONSECUTIVE_FAILURES', 3), ], 'prompt' => [ 'default_file' => env('RALPH_PROMPT_FILE'), 'prd_path' => 'prd/backlog', 'suffix' => 'Focus on one task at a time. Run tests after changes. ...', 'continuation' => 'Continue working. Check the PRD and progress files ...', ], 'screen' => [ 'prefix' => 'ralph', 'shell' => env('RALPH_SCREEN_SHELL', 'zsh'), ], 'tracking' => [ 'file' => env('RALPH_TRACKING_FILE', '.live-agents'), ], 'logging' => [ 'directory' => storage_path('ralph-logs'), 'non_json_warn_threshold' => 50, ], 'script_path' => null, ``` ### Prompt Customization [](#prompt-customization) Ralph appends `prompt.suffix` to every initial prompt and uses `prompt.continuation` as the prompt for iterations 2+. There is no base system prompt — Ralph passes your content directly to `claude -p` and relies on Claude's defaults and your project's `CLAUDE.md`. ### PRD Mode [](#prd-mode) Place PRDs at `prd/backlog/{name}/project.md`. Optionally add a `progress.md` alongside it. Ralph discovers these in the interactive menu and passes them as `@file` references to Claude. How It Works ------------ [](#how-it-works) 1. You provide a prompt (issue, PRD, file, or text). 2. Ralph writes the prompt to a temp file, appends the configured suffix. 3. A Node.js loop runner (`ralph-loop.cjs`) spawns `claude -p` with `--output-format stream-json`. 4. On iteration 1, a new session is created. On iterations 2+, the session is resumed with the continuation prompt. 5. Each iteration's output is scanned for the completion marker (`COMPLETE`). 6. The loop stops when: the marker is detected (exit 0), max iterations reached (exit 2), or consecutive failures exceed the threshold (exit 1). All of this runs inside a GNU screen session so you can detach and reattach freely. License ------- [](#license) MIT ### Health Score 25 — LowBetter than 37% of packages Maintenance56 Moderate activity, may be stable Popularity16 Limited adoption so far Community8 Small or concentrated contributor base Maturity15 Early-stage or recently created project Bus Factor1 Top contributor holds 90% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/1c3a6b11aea9668c9e9ca0c0f8515ef114d344acb552c695d715d35d5b388ea4?d=identicon)[woda](/maintainers/woda) --- Top Contributors [![developeratexample](https://avatars.githubusercontent.com/u/14004359?v=4)](https://github.com/developeratexample "developeratexample (9 commits)")[![davidmondok](https://avatars.githubusercontent.com/u/3883758?v=4)](https://github.com/davidmondok "davidmondok (1 commits)") ### Embed Badge ![Health badge](/badges/woda-laravel-ralph/health.svg) ``` [![Health](https://phpackages.com/badges/woda-laravel-ralph/health.svg)](https://phpackages.com/packages/woda-laravel-ralph) ``` ### Alternatives [desandro/masonry Cascading grid layout library 16.7k424.4k1](/packages/desandro-masonry) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)