Absortio

Email → Summary → Bookmark → Email

Add New Statistics About
← Back to list
Previous Next

GitHub - harris21/laravel-herd-worktree

https://github.com/harris21/laravel-herd-worktree • Jan 26, 2026 17:53

Extracto

Contribute to harris21/laravel-herd-worktree development by creating an account on GitHub.

Resumen

Resumen Principal

La habilidad Laravel Herd Worktree para Claude Code representa una solución avanzada y automatizada para desarrolladores que trabajan con proyectos Laravel y Laravel Herd en macOS. Su función principal es simplificar drásticamente la gestión de entornos de desarrollo aislados, permitiendo la creación rápida y eficiente de git worktrees para ramas de características específicas. Esta herramienta se encarga de todo el proceso, desde la creación física del worktree en una subcarpeta .worktrees/, su vinculación automática con Laravel Herd para servirlo bajo un dominio http://<nombre-rama>.test, hasta la configuración minuciosa del archivo .env para ajustar URLs, dominios de sesión y ajustes de Sanctum. Además, instala las dependencias necesarias (composer install, npm install) y gestiona los procesos de desarrollo como Vite, asegurando un entorno listo para trabajar. Este nivel de automatización elimina las tareas manuales propensas a errores, agilizando el flujo de trabajo y permitiendo a los desarrolladores concentrarse en la codificación con una confianza renovada en la consistencia de sus entornos.

Elementos Clave

  • Automatización Integral de Worktrees: La habilidad crea de forma autónoma un directorio de trabajo aislado (.worktrees/<nombre-rama>/) para cada rama de característica, garantizando que los cambios y configuraciones de cada proyecto se mantengan estrictamente separados. Esto es crucial para evitar conflictos y asegurar la estabilidad entre distintos desarrollos simultáneos.
  • Configuración Dinámica con Laravel Herd: Se integra perfectamente con Laravel Herd, configurando automáticamente el worktree para ser servido en un dominio local dedicado (http://<nombre-rama>.test). La habilidad también actualiza el archivo .env del worktree con las URL correctas, dominios de sesión y los ajustes necesarios para Laravel Sanctum, adaptándose al nuevo entorno aislado.
  • Gestión Automatizada de Dependencias y Procesos de Desarrollo: La herramienta no solo clona el código, sino que también ejecuta composer install y npm install para asegurar que todas las dependencias estén actualizadas y listas. Adicionalmente, gestiona procesos clave como Vite, eliminando instancias obsoletas y arrancando nuevas para garantizar que los assets y la recarga en vivo funcionen correctamente.
  • Activación Intuitiva y Flexible: La habilidad se invoca automáticamente mediante prompts en lenguaje natural dentro de Claude Code, como "Configura un worktree para feature-login". Ofrece flexibilidad para configurar la rama base para Pull Requests, elegir el gestor de paquetes (npm, yarn, pnpm) y especificar flags de Composer, adaptándose a las particularidades de cada proyecto.

Análisis e Implicaciones

Esta habilidad tiene el potencial de transformar la eficiencia del desarrollo de Laravel, eliminando el "fricción" inicial y recurrente de configurar

Contenido

Laravel Herd Worktree

Laravel Herd Worktree

A Claude Code skill that automates setting up git worktrees for Laravel projects served by Laravel Herd.

What It Does

When you need to work on a feature branch in isolation, this skill:

  1. Creates a git worktree in .worktrees/<branch-name>
  2. Links with Laravel Herd to serve the worktree at http://<branch-name>.test
  3. Configures environment - copies and updates .env with correct URLs, session domains, and Sanctum settings
  4. Installs dependencies - runs composer install and npm install
  5. Starts development - kills stale Vite processes and starts fresh

It also handles cleanup and PR creation when you're done.

Prerequisites

  • Laravel Herd installed and running on macOS
  • Git for version control
  • Vite as the frontend build tool (skill assumes Vite, not Webpack/Mix)
  • npm as package manager (adjust commands if using yarn/pnpm)
  • Laravel Sanctum if using API authentication (optional - skill handles this if present)

Installation

Via Claude Marketplace (Recommended)

/plugin install laravel-herd-worktree@harrisrafto-laravel-tools

Manual Installation

  1. Clone this repository:

    git clone https://github.com/harris21/laravel-herd-worktree.git ~/.claude/plugins/laravel-herd-worktree

  2. Add to your Claude Code configuration:

    claude plugins add ~/.claude/plugins/laravel-herd-worktree

Usage

The skill is automatically invoked when you mention worktrees with Laravel Herd projects. Example prompts:

  • "Set up a worktree for feature-login"
  • "Create an isolated workspace for this branch"
  • "I need to work on a feature branch in isolation"

Manual Invocation

Configuration

Default Branch

The skill defaults to develop as the base branch for PRs. If your project uses a different default branch (e.g., main or master), you can:

  1. Let Claude detect it automatically (it will check git symbolic-ref refs/remotes/origin/HEAD)
  2. Specify it when creating the PR

Package Manager

The skill assumes npm. If you use yarn or pnpm, the skill will ask before running install commands.

Composer Flags

If your project requires specific composer flags (like --ignore-platform-reqs), the skill will ask during setup.

What Gets Created

your-project/
├── .worktrees/
│   └── feature-branch/      # Your isolated worktree
│       ├── .env             # Configured for http://feature-branch.test
│       ├── vendor/          # Fresh composer install
│       └── node_modules/    # Fresh npm install

Plus a Herd site at http://feature-branch.test

Common Issues

401 Unauthorized on API routes

  • Add worktree domain to SANCTUM_STATEFUL_DOMAINS in .env
  • Run php artisan config:clear

Cookie rejected for invalid domain

  • Update SESSION_DOMAIN in .env to match worktree domain
  • Add SESSION_SECURE_COOKIE=false for HTTP sites

CORS Errors / White page

  • Ensure vite.config.js has host: 'localhost' and cors: true
  • Restart Vite from the worktree directory

Mixed Content Error

  • Don't secure the Herd site (use HTTP, not HTTPS)
  • Keep APP_URL as http:// not https://

Assets not loading

  • Kill all Vite processes: pkill -f "node.*vite"
  • Remove hot file: rm -f public/hot
  • Restart Vite from worktree

See the skill's "Common Issues" section for complete troubleshooting.

Publishing (For Maintainers)

To add this skill to the Claude marketplace:

/plugin marketplace add harris21/laravel-herd-worktree

To update an already installed plugin:

/plugin update laravel-herd-worktree@harrisrafto-laravel-tools

License

MIT - see LICENSE

Fuente: GitHub