PHPackages                             wagnerfnds/ralph-for-laravel - 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. [CLI & Console](/categories/cli)
4. /
5. wagnerfnds/ralph-for-laravel

ActiveLibrary[CLI & Console](/categories/cli)

wagnerfnds/ralph-for-laravel
============================

Runs a Ralph-style loop (100% PHP) from ralph.md or ralph.json in a Laravel project.

v1.0.0(3mo ago)22MITPHPPHP ^8.2

Since Jan 21Pushed 3mo agoCompare

[ Source](https://github.com/wagnerfnds/ralph-for-laravel)[ Packagist](https://packagist.org/packages/wagnerfnds/ralph-for-laravel)[ Docs](https://github.com/wagnerfnds/ralph-for-laravel)[ RSS](/packages/wagnerfnds-ralph-for-laravel/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (5)Versions (2)Used By (0)

Laravel Ralph
=============

[](#laravel-ralph)

A 100% PHP, Laravel-friendly "Ralph Loop" runner that reads `ralph.md` or `ralph.json` from your project root and iteratively drives an external coding agent (CLI) to complete tasks. It keeps state in `.ralph/`, optionally runs checks (tests/lint), and can optionally commit changes to Git as each task passes.

> **No Bash required.** Everything is orchestrated in PHP using Laravel + Symfony Process.

---

Features
--------

[](#features)

- ✅ `php artisan ralph` runs the loop
- ✅ Reads tasks from **project root**:
    - `ralph.md` (Markdown checkboxes)
    - `ralph.json` (PRD-like JSON)
- ✅ Keeps loop state in `.ralph/`:
    - `.ralph/prd.json` (normalized tasks + pass/fail state)
    - `.ralph/progress.log` (optional log file)
    - `.ralph/run.lock` (prevents multiple concurrent runs)
- ✅ Calls any external agent via CLI (configured with `.env` / `config/ralph.php`)
- ✅ Runs configurable checks (tests, lint, etc.)
- ✅ Optional Git workflow (branch + commits per completed story)

---

Requirements
------------

[](#requirements)

- PHP **8.2+**
- Laravel **10 / 11 / 12**
- An external coding agent CLI installed on your machine/CI (e.g. `claude`, `codex`, etc.)
- (Optional) `git` installed if you enable Git features

---

Installation
------------

[](#installation)

```
composer require wagnerfnds/ralph-for-laravel
```

Laravel package discovery should register the service provider automatically.

---

Quick Start
-----------

[](#quick-start)

### 1) Initialize state directory and create an example ralph.md

[](#1-initialize-state-directory-and-create-an-example-ralphmd)

```
php artisan ralph:init --gitignore
```

This will:

- Create `.ralph/` directory
- Create `.ralph/progress.log` (empty)
- Create an example `ralph.md` if it does not exist
- Create `.ralph/.gitignore` so the state directory is not committed

### 2) Add your tasks in ralph.md

[](#2-add-your-tasks-in-ralphmd)

Example:

```
# Ralph TODO

- [ ] Create invoices migration
- [ ] Create Invoice model + casts
- [ ] Build CRUD endpoints for /api/invoices
- [ ] Add Feature tests for the CRUD
```

### 3) Configure your agent in .env

[](#3-configure-your-agent-in-env)

See the [Environment Variables](#environment-variables-env) section below.

### 4) Run the loop

[](#4-run-the-loop)

```
php artisan ralph
```

You can override iterations:

```
php artisan ralph --max=15
```

Dry-run mode (prints what it would do, no agent/checks/git):

```
php artisan ralph --dry-run
```

Disable checks:

```
php artisan ralph --no-checks
```

Disable Git actions:

```
php artisan ralph --no-git
```

---

Input Formats
-------------

[](#input-formats)

### ralph.md (Markdown)

[](#ralphmd-markdown)

- Each checkbox becomes a user story.
- Checked items (`[x]`) are treated as already passed (`passes=true`).
- The first markdown heading (e.g., `# Invoice Feature`) is used to generate a friendly branch name.

**Example:**

```
# Invoice Feature

- [ ] Create invoices migration
- [ ] Create Invoice model + casts
- [ ] Build CRUD endpoints for /api/invoices
- [ ] Add Feature tests for the CRUD
```

This will create a branch named: `ralph/invoice-feature-20250121-143022` (with timestamp to avoid conflicts)

### ralph.json (PRD JSON)

[](#ralphjson-prd-json)

If `ralph.json` exists in the project root, it takes precedence over `ralph.md`.

Example:

```
{
  "project": "my-laravel-app",
  "branchName": "ralph/feature-invoices",
  "description": "Invoices feature",
  "userStories": [
    {
      "id": "US-001",
      "title": "Create invoices migration",
      "description": "As a dev, I want an invoices table so we can store billing data.",
      "priority": 1,
      "passes": false
    }
  ]
}
```

Missing fields are normalized automatically:

- `passes` defaults to `false`
- `priority` defaults to incremental order
- `description` defaults to `title`
- `id` defaults to `US-001`, `US-002`, ...

---

State Directory
---------------

[](#state-directory)

By default, the package stores generated state in:

```
.ralph/
  prd.json
  progress.log
  run.lock

```

- `prd.json` is the normalized PRD used by the loop.
- `run.lock` prevents running multiple loops concurrently.

**Tip:** use `php artisan ralph:init --gitignore` so `.ralph/` is ignored by Git.

---

Environment Variables (.env)
----------------------------

[](#environment-variables-env)

Add these to your `.env`:

```
# Max attempts per story (retries if agent/checks fail)
RALPH_MAX_ITERATIONS=10

# If true, enables Git operations (branch/commit). You can still disable per-run with --no-git.
RALPH_GIT=true

# Optional: create branches prefixed with this value
RALPH_BRANCH_PREFIX=ralph/

# Optional: push branch after commits (useful in CI)
RALPH_PUSH=false

# Your external agent CLI command (must exist on PATH)
RALPH_AGENT_CMD=claude

# Optional: additional arguments for the agent CLI (space-separated)
# Examples: --verbose, --stream, --debug
RALPH_AGENT_ARGS="--verbose"
```

**Notes:**

- `RALPH_AGENT_CMD` can be any executable available in your environment: `claude`, `codex`, a custom wrapper script, etc.
- `RALPH_AGENT_ARGS` allows you to pass additional flags to see the agent's "thinking" process in real-time
- The process output streams in real-time with TTY support when available

---

Configuration (config/ralph.php)
--------------------------------

[](#configuration-configralphphp)

Publish the config:

```
php artisan vendor:publish --tag=ralph-config
```

Then edit `config/ralph.php`:

```
return [
    'inputs' => [
        'json' => base_path('ralph.json'),
        'md'   => base_path('ralph.md'),
    ],

    'state_dir' => base_path('.ralph'),

    'max_iterations' => (int) env('RALPH_MAX_ITERATIONS', 10),

    'agent' => [
        'command' => env('RALPH_AGENT_CMD', 'claude'),
        'args'    => [],
        'timeout' => null,
    ],

    'checks' => [
        // Examples:
        // ['php', 'artisan', 'test'],
        // ['php', 'artisan', 'pint', '--test'],
    ],

    'git' => [
        'enabled' => (bool) env('RALPH_GIT', true),
        'base_branch' => env('RALPH_BASE_BRANCH', null),
        'branch_prefix' => env('RALPH_BRANCH_PREFIX', 'ralph/'),
        'push' => (bool) env('RALPH_PUSH', false),
    ],
];
```

---

Checks
------

[](#checks)

You can define any number of checks that run after the agent completes an iteration:

```
'checks' => [
  ['php', 'artisan', 'test'],
  ['php', 'artisan', 'pint', '--test'],
],
```

If any check fails, the loop stops and reports the failure.

---

Git Workflow
------------

[](#git-workflow)

If Git is enabled, the runner can:

- ensure you are inside a Git repository
- create/switch to a `branchName` (from the PRD or generated)
- commit changes after each story is marked passed

Disable Git for a single run:

```
php artisan ralph --no-git
```

---

Safety / Notes
--------------

[](#safety--notes)

- This package executes external commands (agent CLI, checks, git) in your project directory.
- Review changes before merging.
- Consider running in a dedicated branch.
- In CI, use `RALPH_PUSH=true` only if your credentials are configured safely.

---

Development (Local Testing)
---------------------------

[](#development-local-testing)

During development, you can install this package into a Laravel app using a Composer path repository:

```
{
  "repositories": [
    { "type": "path", "url": "../ralph-for-laravel", "options": { "symlink": true } }
  ],
  "require": {
    "wagnerfnds/ralph-for-laravel": "dev-main"
  }
}
```

Then:

```
composer update wagnerfnds/ralph-for-laravel
php artisan ralph:init --gitignore
php artisan ralph
```

---

Roadmap
-------

[](#roadmap)

- Agent adapters (Claude, Codex, etc.) via Contracts
- Per-iteration logs (`.ralph/iterations/0001.json`)
- Auto-push + PR creation (GitHub CLI)
- Better prompt templates and context strategies

---

License
-------

[](#license)

MIT

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance79

Regular maintenance activity

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

111d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/cb375d241113c8dddb129696eac20899f4b4037d15fe24a01e390b4b10a3e3a1?d=identicon)[wagnerfnds](/maintainers/wagnerfnds)

---

Top Contributors

[![wagnerfnds](https://avatars.githubusercontent.com/u/19960361?v=4)](https://github.com/wagnerfnds "wagnerfnds (1 commits)")

---

Tags

clilaravelautomationaicoding-agentralphprd

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/wagnerfnds-ralph-for-laravel/health.svg)

```
[![Health](https://phpackages.com/badges/wagnerfnds-ralph-for-laravel/health.svg)](https://phpackages.com/packages/wagnerfnds-ralph-for-laravel)
```

###  Alternatives

[nunomaduro/laravel-console-menu

Laravel Console Menu is an output method for your Laravel/Laravel Zero commands.

815412.0k48](/packages/nunomaduro-laravel-console-menu)[laravel-zero/framework

The Laravel Zero Framework.

3371.4M369](/packages/laravel-zero-framework)[nunomaduro/laravel-console-dusk

Laravel Console Dusk allows the usage of Laravel Dusk in Laravel/Laravel Zero artisan commands.

16255.4k7](/packages/nunomaduro-laravel-console-dusk)[rahul900day/laravel-console-spinner

Laravel Console Spinner is a spinner output for Laravel command line.

76125.4k1](/packages/rahul900day-laravel-console-spinner)[socialengine/sniffer-rules

A Lumen 5 and Laravel 5 SquizLabs Code Sniffer 2.0 artisan command. Detect violations of a defined coding standard. It helps your code remains clean and consistent.

1248.2k1](/packages/socialengine-sniffer-rules)[renoki-co/php-helm

PHP Helm Processor is a process wrapper for Kubernetes' Helm v3 CLI. You can run programmatically Helm v3 commands, directly from PHP, with a simple syntax.

1310.5k](/packages/renoki-co-php-helm)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)