PHPackages arielmejiadev/healing-factor - 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. arielmejiadev/healing-factor ActiveLibrary arielmejiadev/healing-factor ============================ Adds Self Healing Super Powers To Your App 1.0.0(1mo ago)00[1 PRs](https://github.com/ArielMejiaDev/healing-factor/pulls)MITPHPPHP ^8.4CI passing Since Mar 23Pushed 1mo agoCompare [ Source](https://github.com/ArielMejiaDev/healing-factor)[ Packagist](https://packagist.org/packages/arielmejiadev/healing-factor)[ Docs](https://github.com/ariel-mejia-dev/healing-factor)[ GitHub Sponsors](https://github.com/ariel-mejia-dev)[ RSS](/packages/arielmejiadev-healing-factor/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)Dependencies (14)Versions (3)Used By (0) [![Healing Factor Dashboard](images/preview.png)](images/preview.png) Healing-Factor ============== [](#healing-factor) [![Latest Version on Packagist](https://camo.githubusercontent.com/9e60b88906a79509bd37afdff70acd45b8adef26b68982ad7028f98ed0852ff3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f617269656c2d6d656a69612d6465762f6865616c696e672d666163746f722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ariel-mejia-dev/healing-factor)[![GitHub Tests Action Status](https://camo.githubusercontent.com/06d475f8abccfebb6a9a28f8394e153028e123f4100938c5d816c989899fd16f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f617269656c2d6d656a69612d6465762f6865616c696e672d666163746f722f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/ariel-mejia-dev/healing-factor/actions?query=workflow%3Arun-tests+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/ced2e3b2877a5c9e86db67eef48c7722d70306af55aa0c1f622c04cd44d650cf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f617269656c2d6d656a69612d6465762f6865616c696e672d666163746f722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ariel-mejia-dev/healing-factor) A self-healing Laravel package that catches exceptions and automatically creates pull requests with fixes using AI. When an error occurs in your app, Healing-Factor captures it, spins up an AI agent in an isolated git worktree, and opens a draft PR with the fix — all without touching your production code. To learn all about it, head over to the extensive documentation. How It Works ------------ [](#how-it-works) 1. An exception occurs in your Laravel app 2. Healing-Factor captures it via a **webhook** (Nightwatch/Bugsnag) or the built-in **exception listener** 3. The exception is fingerprinted, debounced, and deduplicated 4. A queued job creates an **isolated git worktree** on a new branch 5. An AI agent (Claude Code, OpenCode, or the Anthropic API) analyzes the code and writes a fix 6. The fix is committed, pushed, and a **draft pull request** is opened 7. The worktree is automatically cleaned up 8. You review the PR and merge Requirements ------------ [](#requirements) - PHP 8.4+ - Laravel 11 or 12 - [GitHub CLI (`gh`)](https://cli.github.com/) installed and authenticated - A queue worker running **Plus one of:** DriverRequires`cli`[Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [OpenCode](https://github.com/opencode-ai/opencode) installed on the server`api`Only an `ANTHROPIC_API_KEY` (no CLI installation needed)Installation ------------ [](#installation) ``` composer require ariel-mejia-dev/healing-factor ``` ``` php artisan healing-factor:install ``` This publishes the config, runs the migration, and verifies your setup. Quick Start ----------- [](#quick-start) Pick the setup that matches your environment: ### Option A: CLI Driver + Exception Listener (simplest) [](#option-a-cli-driver--exception-listener-simplest) No external monitor needed. Healing-Factor listens to Laravel errors directly. ``` APP_ENV=staging HEALING_FACTOR_DRIVER=cli HEALING_FACTOR_CLI_TOOL=claude HEALING_FACTOR_MONITOR=exception_listener ``` ### Option B: CLI Driver + Nightwatch Webhook [](#option-b-cli-driver--nightwatch-webhook) ``` APP_ENV=staging HEALING_FACTOR_DRIVER=cli HEALING_FACTOR_CLI_TOOL=claude HEALING_FACTOR_MONITOR=nightwatch HEALING_FACTOR_WEBHOOK_SECRET=your-strong-random-secret ``` ### Option C: API Driver (no CLI installation needed) [](#option-c-api-driver-no-cli-installation-needed) Ideal for staging/production servers (DigitalOcean, Laravel Cloud, AWS) where you can't install CLI tools. ``` APP_ENV=staging HEALING_FACTOR_DRIVER=api HEALING_FACTOR_MONITOR=exception_listener ANTHROPIC_API_KEY=sk-ant-... HEALING_FACTOR_GITHUB_PAT=github_pat_... ``` Then start a queue worker: ``` php artisan queue:work --timeout=3700 ``` > **Why `APP_ENV=staging`?** Healing-Factor only runs in `production` and `staging` by default. In `local`, errors are expected during development. You can change this in `config/healing-factor.php` under `environments`. > **Why no `ANTHROPIC_API_KEY` for CLI?** Claude Code handles its own authentication. The API driver calls the Anthropic API directly, so it needs the key. Verify Your Setup ----------------- [](#verify-your-setup) ``` php artisan healing-factor:test ``` This creates a test issue and dispatches it for resolution. Add `--sync` to skip the queue. Dashboard --------- [](#dashboard) Healing-Factor includes a web dashboard at `/healing-factor` to browse issues, view stacktraces, see PR links, and retry failed resolutions. By default it's only accessible in `local`. To allow access in other environments, register an auth gate in your `AppServiceProvider`: ``` use ArielMejiaDev\HealingFactor\Facades\HealingFactor; public function boot(): void { HealingFactor::auth(function ($user) { return in_array($user->email, [ 'admin@example.com', ]); }); } ``` Artisan Commands ---------------- [](#artisan-commands) CommandDescription`healing-factor:install`Publish config, run migration, verify setup`healing-factor:test`Create a test issue to verify the pipeline`healing-factor:status`Show all issues with summary statistics`healing-factor:retry {id}`Retry a failed issue`healing-factor:prune`Delete old resolved/failed issues`healing-factor:recover-stale`Mark stuck `resolving` issues as `failed`### Recommended Schedule [](#recommended-schedule) ``` // routes/console.php use Illuminate\Support\Facades\Schedule; Schedule::command('healing-factor:recover-stale')->hourly(); Schedule::command('healing-factor:prune')->daily(); ``` Configuration Highlights ------------------------ [](#configuration-highlights) All config lives in `config/healing-factor.php`. Key options: OptionEnv VariableDefaultDescriptionMaster switch`HEALING_FACTOR_ENABLED``true`Disable all processingDry run`HEALING_FACTOR_DRY_RUN``false`Log actions without executingDriver`HEALING_FACTOR_DRIVER``cli``cli` or `api`CLI tool`HEALING_FACTOR_CLI_TOOL``claude``claude` or `opencode`Monitor`HEALING_FACTOR_MONITOR``nightwatch``nightwatch`, `bugsnag`, or `exception_listener`Timeout`HEALING_FACTOR_PROCESS_TIMEOUT``3600`Max seconds for CLI processDebounce`HEALING_FACTOR_DEBOUNCE_MINUTES``5`Min minutes between same exception### Exception Categories [](#exception-categories) Customize AI behavior per exception type — each category can override `cli_tool`, `model`, `timeout`, `max_turns`, and `prompt`: ``` 'categories' => [ 'quick_fixes' => [ 'timeout' => 1800, 'max_turns' => 15, 'exceptions' => [ErrorException::class, TypeError::class, ...], ], 'complex_fixes' => [ 'timeout' => 3600, 'max_turns' => 30, 'exceptions' => [LogicException::class, RuntimeException::class, ...], ], ], ``` ### Ignored Exceptions [](#ignored-exceptions) Exceptions that should never be processed (infrastructure issues, unfixable errors): ``` 'ignored_exceptions' => [ \OutOfMemoryError::class, \Illuminate\Http\Exceptions\ThrottleRequestsException::class, \Symfony\Component\HttpKernel\Exception\HttpException::class, \Illuminate\Session\TokenMismatchException::class, ], ``` Events ------ [](#events) EventFired When`IssueCreated`Issue created from webhook or exception`IssueResolving`Resolution starts`IssueResolved`Resolution succeeds`IssueResolutionFailed`Resolution fails``` use ArielMejiaDev\HealingFactor\Events\IssueResolved; Event::listen(IssueResolved::class, function (IssueResolved $event) { // Send Slack notification, update status page, etc. }); ``` What Healing-Factor Can Fix --------------------------- [](#what-healing-factor-can-fix) Any runtime exception that occurs while the app is still running: - Undefined variables/properties, type errors, bad method calls - Missing models, query errors, validation logic errors - Authorization/authentication bugs, route and controller errors - Logic errors (RuntimeException, DomainException, off-by-one mistakes) What It Cannot Fix ------------------ [](#what-it-cannot-fix) - PHP syntax errors (app can't boot) - Fatal errors that kill the process (OOM, segfaults) - Infrastructure failures (DB down, Redis unreachable) - Environment/configuration issues - Issues requiring human judgment (business logic, UX, architecture) Documentation ------------- [](#documentation) See [docs/documentation.md](docs/documentation.md) for the full reference including webhook setup, signature verification, API driver details, custom prompts, security model, theming, and troubleshooting. Testing ------- [](#testing) ``` composer test ``` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Credits ------- [](#credits) - [ArielMejiaDev](https://github.com/ArielMejiaDev) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 39 — LowBetter than 86% of packages Maintenance90 Actively maintained with recent releases Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity52 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 45d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/31971074?v=4)[ArielMejiaDev](/maintainers/ArielMejiaDev)[@ArielMejiaDev](https://github.com/ArielMejiaDev) --- Top Contributors [![ArielMejiaDev](https://avatars.githubusercontent.com/u/31971074?v=4)](https://github.com/ArielMejiaDev "ArielMejiaDev (26 commits)") --- Tags laravelariel-mejia-devhealing-factor ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/arielmejiadev-healing-factor/health.svg) ``` [![Health](https://phpackages.com/badges/arielmejiadev-healing-factor/health.svg)](https://phpackages.com/packages/arielmejiadev-healing-factor) ``` ### Alternatives [vormkracht10/laravel-mails Laravel Mails can collect everything you might want to track about the mails that has been sent by your Laravel app. 24149.7k](/packages/vormkracht10-laravel-mails)[spatie/laravel-prometheus Export Laravel metrics to Prometheus 2651.3M6](/packages/spatie-laravel-prometheus)[hydrat/filament-table-layout-toggle Filament plugin adding a toggle button to tables, allowing user to switch between Grid and Table layouts. 6292.3k1](/packages/hydrat-filament-table-layout-toggle)[scalar/laravel Render your OpenAPI-based API reference 6183.9k2](/packages/scalar-laravel)[ralphjsmit/laravel-helpers A package containing handy helpers for your Laravel-application. 13704.6k2](/packages/ralphjsmit-laravel-helpers)[musahmusah/laravel-multipayment-gateways A Laravel Package that makes implementation of multiple payment Gateways endpoints and webhooks seamless 852.2k1](/packages/musahmusah-laravel-multipayment-gateways) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)