# Configuring Horizon

Use this skill whenever the user mentions Horizon by name in a Laravel context.

- Repository: https://github.com/yaojingang/GEOFlow (3990 stars)
- Category: Data and ML
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add yaojingang/GEOFlow --skill configuring-horizon -g -a claude-code -y`
Codex: `npx skills add yaojingang/GEOFlow --skill configuring-horizon -g -a codex -y`
Cursor: `npx skills add yaojingang/GEOFlow --skill configuring-horizon -g -a cursor -y`
Gemini CLI: `npx skills add yaojingang/GEOFlow --skill configuring-horizon -g -a gemini-cli -y`

## Description

Use this skill whenever the user mentions Horizon by name in a Laravel context. Covers the full Horizon lifecycle: installing Horizon (horizon:install, Sail setup), configuring config/horizon.php (supervisor blocks, queue assignments, balancing strategies, minProcesses/maxProcesses), fixing the dashboard (authorization via Gate::define viewHorizon, blank metrics, horizon:snapshot scheduling), and troubleshooting production issues (worker crashes, timeout chain ordering, LongWaitDetected notifications, waits config). Also covers job tagging and silencing. Do not use for generic Laravel queues without Horizon, SQS or database drivers, standalone Redis setup, Linux supervisord, Telescope, or job batching.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Horizon Configuration

## Documentation

Use `search-docs` for detailed Horizon patterns and documentation covering configuration, supervisors, balancing, dashboard authorization, tags, notifications, metrics, and deployment.

For deeper guidance on specific topics, read the relevant reference file before implementing:

- `references/supervisors.md` covers supervisor blocks, balancing strategies, multi-queue setups, and auto-scaling
- `references/notifications.md` covers LongWaitDetected alerts, notification routing, and the `waits` config
- `references/tags.md` covers job tagging, dashboard filtering, and silencing noisy jobs
- `references/metrics.md` covers the blank metrics dashboard, snapshot scheduling, and retention config

## Basic Usage

### Installation

```bash
php artisan horizon:install
```

### Supervisor Configuration

Define supervisors in `config/horizon.php`. The `environments` array merges into `defaults` and does not replace the whole supervisor block:

<!-- Supervisor Config -->
```php
'defaults' => [
    'supervisor-1' => [
        'connection' => 'redis',
        'queue' => ['default'],
        'balance' => 'auto',
        'minProcesses' => 1,
        'maxProcesses' => 10,
        'tries' => 3,
    ],
],

'environments' => [
    'production' => [
        'supervisor-1' => ['maxProcesses' => 20, 'balanceCooldown' => 3],
    ],
    'local' => [
        'supervisor-1' => ['maxProcesses' => 2],
    ],
],
```

### Dashboard Authorization

Restrict access in `App\Providers\HorizonServiceProvider`:

<!-- Dashboard Gate -->
```php
protected function gate(): void
{
    Gate::define('viewHorizon', function (User $user) {
        return $user->is_admin;
    });
}
```

## Verification

1. Run `php artisan horizon` and visit `/horizon`
2. Confirm dashboard access is restricted as expected
3. Check that metrics populate after scheduling `horizon:snapshot`

## Common Pitfalls

The rest: https://github.com/yaojingang/GEOFlow/blob/HEAD/.agents/skills/configuring-horizon/SKILL.md