Kalimera

Kalimera ☀️

Interactive installer that scaffolds a fresh Laravel application — one guided CLI flow from laravel new to a fully configured, quality-checked, Sail-running app with all the tools you need.

Instead of a boilerplate — a frozen copy of someone else's choices that goes stale — kalimera automates the initialization step itself: a fresh, current Laravel application prepared exactly the way you want it, the same way every time. Your package set is defined once in kalimera.config.json (the built-in catalog is the Spatie collection — replace it with your own), Pint + PHPStan + Rector and Sail are wired from the first commit, every choice is made at once upfront, and the whole run is unattended — driven by you or by your coding agent through the agent skill. A ready-to-build project in minutes, no manual setup each time.

Requirements

The host's PHP and Composer create the application and download its packages; everything that runs PHP afterwards runs inside Sail, on the PHP version you chose. Node.js is not needed on the host — npm install runs in the container. Before anything is installed, kalimera checks for every tool above and stops with a clear message if one is missing.

The host PHP needs the extensions Laravel itself needs to boot a fresh skeleton: curl, mbstring, openssl, pdo_sqlite, tokenizer, xml/dom and zip (or the unzip binary). The setups below include them.

macOS

Docker Desktop (or OrbStack) provides the daemon; PHP, Composer and the Laravel installer come from php.new, the one-liner the Laravel docs recommend, or from Homebrew.

# PHP + Composer + Laravel installer (php.new)
/bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.4)"

# …or with Homebrew
brew install php composer
composer global require laravel/installer

# Docker and git
brew install --cask docker   # then start Docker Desktop once
xcode-select --install       # git, if `git --version` asks for it

Make sure ~/.composer/vendor/bin is on your PATH (php.new does this for you).

Ubuntu (22.04 / 24.04)

Ubuntu's own archive ships PHP 8.1 (22.04) or 8.3 (24.04), both too old to run kalimera, so PHP 8.4 comes from the ondrej/php PPA — or use curl -fsSL https://php.new/install/linux/8.4 | bash instead of the first two blocks.

# PHP 8.4 and the extensions the host needs
sudo apt update
sudo apt install -y software-properties-common curl git unzip
sudo add-apt-repository -y ppa:ondrej/php
sudo apt install -y php8.4-cli php8.4-curl php8.4-mbstring php8.4-xml php8.4-zip php8.4-sqlite3

# Composer and the Laravel installer
curl -sS https://getcomposer.org/installer | php -- --install-dir=/tmp
sudo mv /tmp/composer.phar /usr/local/bin/composer
composer global require laravel/installer
echo 'export PATH="$HOME/.config/composer/vendor/bin:$PATH"' >> ~/.bashrc

# Docker Engine with the compose plugin (Sail needs `docker compose`, v2)
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"

Log out and back in (or run newgrp docker) after usermod — until then docker info fails with "permission denied" and kalimera reports that the Docker daemon did not answer. Never run kalimera with sudo to get around it: the app's files would end up owned by root.

Check the whole setup in one go:

php -v && composer --version && laravel --version && docker info --format '{{.ServerVersion}}' && git --version

Installation

Global (recommended)

Install once, use kalimera from anywhere — same mechanism as the laravel installer.

composer global require welldigit/kalimera

Make sure composer's global bin directory (~/.composer/vendor/bin or ~/.config/composer/vendor/bin) is in your PATH — if the laravel command works, it already is.

Working from a local checkout

Developing kalimera itself? Point global composer at your working copy with a path repository instead of Packagist (the symlink means every local change is instantly live):

composer global config repositories.kalimera '{"type": "path", "url": "/absolute/path/to/kalimera", "options": {"symlink": true}}'
composer global require welldigit/kalimera:@dev

(:@dev is needed because a path repository has no tagged releases — the package only exists as dev-main, and composer's default stability is stable.) A path repository is canonical, so it silently shadows the Packagist version even after you're done — switch back with:

composer global config --unset repositories.kalimera
composer global require welldigit/kalimera

Local (no global install)

cd kalimera && composer install

Then call the binary by its full path from wherever the new app should live:

cd ~/www
/path/to/kalimera/bin/kalimera new

The app is created in the current working directory — don't run kalimera from inside this repo unless you want the app scaffolded into it.

Usage

kalimera new                   # prompts for everything, creates ./<app-name>
kalimera new my-app            # skip the name prompt
kalimera new ~/www/my-app      # a path works too — the app is created exactly there

Options:

What it does

1. Prompts for everything upfront: app name, starter kit (React / Vue / Livewire / Svelte / none, with optional manual Inertia), ecosystem packages (Horizon, Fortify, Laravel AI, Scout, Nightwatch), Sail services, PHP version constraint (default ^8.5), quality tools, additional packages, Postmark, GitHub repos for Boost skills, and any extra packages — then shows a summary and one final confirm. Before anything runs it checks that php, composer, laravel, docker and git are there, that PHP is 8.3+ and Composer 2.2+, and that Docker answers.

Then, on the host — no container exists yet:

2. laravel new with Pest and git, no interaction.
3. Installs Sail with the chosen services and pins its runtime to the chosen PHP version (sail:install --php=<minor>; it only writes compose.yaml and .env — the image is built later, once).
4. Restricts require.php to the chosen constraint and pins composer's config.platform.php to the container's PHP — the exact version from your local Sail image when there is one — so the host's composer picks packages for the container whatever PHP the host runs. The pin stays in the app, so a later host-side composer update keeps resolving for the container.
5. Publishes the Pint / PHPStan (Larastan + IDE Helper) / Rector configs (pint.json, phpstan.neon.dist, rector.php) and composer scripts: pint:dry, pint:fix, phpstan, phpstan-clear, ide-helper, rector:dry, rector:fix and the aggregate quality. Generated ide-helper files are gitignored.
6. Prepares Laravel Vet (chosen at the quality-tools prompt, on by default): allows its composer plugin and adds a vet script plus @vet in quality.
7. Optionally adds Postmark (symfony/postmark-mailer, the transport behind config/mail.php's postmark entry) with postmark:push / postmark:pull composer scripts and a POSTMARK_API_KEY env placeholder, and the Core structure: src/{Domain,Shared,Support,Feature,Infrastructure} with .gitkeep files, mapped to a PSR-4 namespace of your choice (Core by default).
8. Downloads every package with the host's composer in one go — a runtime batch, a --dev batch, then each optional package (Nightwatch, extras) on its own, which warns instead of failing. Nothing executes yet (--no-scripts --no-plugins), and only network failures are retried.
9. Installs the AI-agent guard: publishes app/Providers/AgentGuardServiceProvider.php and registers it last in bootstrap/providers.php, so destructive database commands (db:wipe, migrate:fresh/refresh/reset/rollback) are prohibited whenever an AI agent is driving the app — exactly as they already are in production. Detection comes from laravel/pao's AgentDetector, which ships with new Laravel apps by default and recognizes Claude Code, Cursor, Codex, Copilot, Gemini and others. Registration order matters and the provider must boot after AppServiceProvider; see TROUBLESHOOTING.md.

Then in the container, where the chosen PHP runs:

10. Picks free host ports right before binding them (APP_PORT, FORWARD_DB_PORT, …) so parallel projects never clash, and boots the containers (sail up -d --wait).
11. Records Vet's trust file (vet --init writes vet.json from every package just downloaded), then composer install — which checks the PHP extensions the host skipped, runs the composer plugins and package:discover — and publishes laravel-assets. From here on each composer install, update and require shows the code it is about to write into vendor/ and fails on a version nobody has read — review it with sail composer vet in a terminal. Commit vet.json. No minimum-release-age is set: the floor rejects releases younger than it even when trusted, so a fresh application would arrive failing its own audit — TROUBLESHOOTING.md has the recipe for turning it on.
12. Sets up the ecosystem packages: horizon:install, fortify:install (skipped when the starter kit already ships it), Laravel AI's config and conversations migration, and Scout's config with SCOUT_DRIVER=database — full-text search on PostgreSQL or MySQL with no extra service (collection without either).
13. Publishes the configs/migrations of the chosen additional packages. The built-in catalog is the Spatie collection (laravel-data, laravel-view-models, laravel-query-builder, laravel-backup, laravel-permission, laravel-activitylog, laravel-translatable) — replace it with your own via Configuration.
14. Optionally installs Laravel Boost (on by default): you pick the AI agents (Claude Code, Cursor, Codex, Copilot, …) upfront — kalimera preconfigures boost.json and runs boost:install --guidelines --skills --mcp --no-interaction, fully unattended. (Select no agents to answer Boost's own prompts instead.) Then pulls your skills from GitHub via boost:add-skill <owner/repo> --all — one run per repository, so you can list several space- or comma-separated at the prompt. Finishes with boost:update --no-discover --no-interaction so the guidelines and skills are the latest guidance rather than whatever the installed release bundled (a warning, never a failure).
15. Finalizes: migrates, npm install, generates the IDE helper files, formats the fresh skeleton with Rector + Pint, repairs the published stubs PHPStan would reject (no baseline, so composer quality starts green on its own merits), and commits.

Configuration

Kalimera works with zero configuration — the built-in setup is the curated Well Digit stack. To adapt it to your own, drop a kalimera.config.json next to where you run kalimera (or point at one with --config=path). Everything in it is optional; whatever you omit keeps the built-in behavior.

{
    "$schema": "https://raw.githubusercontent.com/welldigit/kalimera/main/schema/kalimera.config.schema.json",
    "preselected": {
        "starterKit": "vue",
        "sailServices": ["mysql", "redis", "mailpit"],
        "phpConstraint": "^8.4",
        "boostSkillRepos": ["acme/boost-skills"],
        "coreNamespace": "Acme\\Core"
    },
    "additionalPackages": [
        {
            "package": "spatie/laravel-medialibrary",
            "label": "medialibrary — file attachments for Eloquent models",
            "preselected": true,
            "publishProviders": ["Spatie\\MediaLibrary\\MediaLibraryServiceProvider"]
        },
        {
            "package": "barryvdh/laravel-debugbar",
            "label": "debugbar — in-browser debug toolbar",
            "dev": true
        }
    ]
}

• preselected — the pre-chosen answers of every prompt, and exactly what --defaults installs unattended. Keys mirror the prompts: starterKit, installInertia, aroundPackages, sailServices, phpConstraint, qualityTools, installPostmark, installBoost (false skips the Boost step and the two questions behind it), coreNamespace (null skips the Core scaffold), boostAgents, boostSkillRepos, extraPackages, extraDevPackages.
• additionalPackages replaces the built-in Spatie catalog shown by the "additional packages" prompt. Each entry takes a composer package (a version constraint like vendor/package:^2.0 works), an optional prompt label, dev to require with --dev, preselected to have it chosen by default, and publishProviders to run vendor:publish for after installation.

The built-in setup itself lives in schema/kalimera.config.schema.json: each property's enum lists the available options — what is there — and the default values of preselected and additionalPackages are the built-in choices — what is chosen. Kalimera reads it on start, so editing that file changes what the installer offers out of the box (your fork, your stack), while a kalimera.config.json overrides it per project. Referencing it via $schema gives your editor completion for every option. Validation happens in kalimera itself: every loaded file is checked on start and unknown keys or invalid values are refused with a precise error, so a typo fails before anything is installed, not halfway through.

Agent skill

The repo ships a ready-made agent skill at skills/kalimera/ that teaches AI coding agents to drive kalimera end-to-end. The agent becomes the prompt layer: it re-asks kalimera's full prompt set in its own interface (starter kit, Sail services, ecosystem and Spatie packages, PHP constraint, quality tools, Core structure, Boost agents, …), encodes the answers into a config JSON, and runs the installer unattended with --defaults — kalimera's own prompts would die in the agent's non-TTY shell. It then verifies the result and resumes failed runs. The skill is plain Markdown in the open Agent Skills format, so any skills-aware tool can consume it.

• Claude Code — one symlink and the skill applies to every session on the machine. After the global install above, link through composer's vendor directory — it keeps working once the package is on Packagist, and composer global update refreshes the skill content:

  ln -s ~/.composer/vendor/welldigit/kalimera/skills/kalimera ~/.claude/skills/kalimera
  

  (~/.config/composer/vendor/... on Linux; linking straight to a cloned repo works too.)

• Cursor, Codex, and friends — they support the same format: copy or symlink skills/kalimera/ into the tool's skills directory (see its Agent Skills docs), or paste SKILL.md into its global rules/instructions.

Layout

bin/kalimera        entry point
src/                installer code (WellDigit\Kalimera\)
  KalimeraInstaller.php   the orchestrator behind `kalimera new`
  Contracts/        interfaces: Pipeline, PortChecker, ProcessRunner
  Exceptions/       one exception class per failure mode
  Payloads/         immutable data carriers: Argument, InstallerOption
  Pipelines/        the installation steps, executed in order
  Services/         invokable and multi-op helpers (files, shell, sail, prompts)
schema/             kalimera.config.schema.json — the built-in setup and config file reference
skills/             agent skill that teaches AI agents to drive kalimera (see Agent skill)
templates/          pint.json, phpstan.neon.dist, rector.php shipped into generated apps
tests/              Pest suite (WellDigit\Kalimera\Tests\)

Quality & tests

The package dogfoods the same tooling it installs into new applications:

composer test       # the full Pest suite
composer quality    # rector:dry + pint:dry + phpstan (level 8) + tests

Individual scripts: pint:dry / pint:fix, rector:dry / rector:fix, phpstan, phpstan-clear, test and test:coverage.

The suite is split into three Pest test suites:

tests/Unit          one test file per src/ class (Services, Pipelines, Payloads)
tests/Feature       in-process dry-run snapshot: the exact command sequence `kalimera new
                    --dry-run --defaults` produces, plus usage/exit-code behavior
tests/Arch          architecture rules: strict types, readonly classes, no debug output,
                    pipeline contract, Services/Payloads layer boundaries

Steps talk to the outside world only through the ProcessRunner, PortChecker and ExecutableFinder seams, so the whole installer runs in-process against fakes (tests/Fakes/) — no Docker, network or laravel binary needed to test it.

Continuous integration

.github/workflows/ci.yml runs on every push and pull request:

Because every test fakes the process runner, the suite proves kalimera emits the right commands but never that they succeed. Before a release, scaffold a real application with kalimera new <app> --defaults --log against real Docker and check the containers are up — every bug found in real use so far (every sail command running twice, an inherited volume, a frozen progress line) survived the faked-runner suite and only showed up in a real run.