Laravel Ai Harness Laravel Package

Getting Started

mrkoopie/laravel-ai-harness is a dev-only tool that keeps two things in sync for a Laravel project: the local runtime your machine actually uses (Herd, Valet, Yerd 2.x, Sail, native PHP, or cloud) and the instruction/config files your AI coding agents read (Claude, Codex). The payoff day-to-day is that an agent asking "run the tests" or "hit the local site" gets the right PHP binary, the right scheme (HTTP vs HTTPS), and the right service startup commands instead of guessing.

Minimal path for a project install:

composer require --dev 'mrkoopie/laravel-ai-harness:^0.6'
./.ai-harness update
./.ai-harness doctor
./.ai-harness setup

Or install once globally and opt each project in:

composer global require 'mrkoopie/laravel-ai-harness:^0.6'
ai-harness init --global   # run inside each project

Where to look first:

1. .ai-harness.config.dist — the committed reference for every supported key. Read this before editing anything.
2. Your own .ai-harness.config (shared) and .ai-harness.config.global / .ai-harness.config.local (personal, uncommitted).
3. The generated agent files: Claude's settings.local.json and CLAUDE.local.md, Codex's AGENTS.override.md plus its local environment.

First use case worth wiring up: pick your runtime once, set php_version, site_secure, and service_manager, then let the agent run artisan, composer, and test commands unattended without you correcting the PHP version mid-session.

If you are already on 0.5.x, do the config rename before touching Composer — see Gotchas.

Implementation Patterns

Layered configuration. Treat the four config files as a precedence chain rather than four places to put the same thing:

• .ai-harness.config.dist — committed template, the team's baseline.
• .ai-harness.config — committed shared settings (runtime choice, service manager).
• .ai-harness.config.global — per-developer defaults across all their projects (global installs).
• .ai-harness.config.local — per-checkout overrides.

Commit the first two. Never commit the last two. This is the pattern that keeps a team of mixed Herd/Valet/Yerd users on one repo without churn.

One runtime block per file. After the 0.6.0 consolidation there is exactly one php_version and one site_secure per config file, describing the selected runtime. service_manager replaces the old services key. sail_services is unchanged and still lists Sail services specifically — do not fold it into service_manager. Cloud settings and resource-ownership state are also untouched by the rename, so leave them where they are.

local_env.* for machine-specific environment. Rather than each developer editing .env and creating diff noise, put machine-specific values under local_env.* in a personal config file. Setup validates for conflicts and then applies them. Linked worktrees inherit the primary checkout's personal defaults, so a new worktree is immediately usable without re-entering your local paths and ports.

Worktrees as first-class. This is the feature that most changes day-to-day workflow: one agent session per branch in a linked worktree, each inheriting config (including nested applications) from the primary checkout, with per-worktree overrides where needed. After any config change or package upgrade, refresh every live worktree — the hook/validation failure mode is per-worktree, not just the root:

./.ai-harness update && ./.ai-harness doctor && ./.ai-harness setup

Command rhythm. update refreshes managed/generated files after a package bump or config edit. doctor validates configuration and environment — make it the first thing you run when something looks wrong. setup applies runtime side effects (sites, PHP selection, HTTPS, hooks). Running all three in that order is the safe default and is what the upgrade guide prescribes for project installs, global installs, and every existing worktree.

Onboarding a collaborator. composer install, then init (or ai-harness init --global), choose runtime, run doctor and setup. Because generated integrations are registered via .git/info/exclude, the shared .gitignore stays clean — but that also means a fresh clone has no excludes until init runs.

Generated files are merged, not overwritten. If a developer already has a Claude settings.local.json, its existing file permissions survive update/setup. Treat the harness keys as additive within that file; hand-edited permission entries are safe to keep. Codex's AGENTS.override.md and its local environment follow the same ownership model.

Keep it out of CI and production. This is a require-dev tool whose job is local environment parity. Treat generated agent files as developer tooling, not artefacts the build depends on.

Gotchas and Tips

The 0.6.0 rename is hard-breaking with no aliases. Seven keys are rejected outright: herd_php / valet_php / yerd_php → php_version; herd_secure / valet_secure / yerd_secure → site_secure; services → service_manager. Composer's refresh hook and harness commands fail if any remain. Rename in all of .ai-harness.config.dist, .ai-harness.config, .ai-harness.config.global, and .ai-harness.config.local — including personal files inherited by worktrees and each worktree's overrides. Where a file had settings for several runtimes, collapse them to one php_version and one site_secure for the runtime you actually selected, and delete every old key.

^0.5 does not include 0.6.0. Bump the constraint explicitly. And use host Composer for the transition rather than a Sail/container Composer, since the refresh hook runs against your host config files.

Already hit the failed update hook? Recover with --no-scripts, rename, then re-run:

composer require --dev 'mrkoopie/laravel-ai-harness:^0.6' --no-scripts
# rename all seven keys everywhere, including worktree overrides
./.ai-harness update && ./.ai-harness doctor && ./.ai-harness setup

For a global install the same recovery is composer global require 'mrkoopie/laravel-ai-harness:^0.6' --no-scripts, then run ai-harness update / doctor / setup in each configured project and worktree. --no-scripts skips unrelated Composer scripts too — review and re-run those separately.

A stale key in the primary checkout blocks every worktree. Because linked worktrees inherit the primary checkout's personal files, one forgotten herd_php in a root-level .local file will fail doctor in worktrees you never edited. When debugging a post-upgrade failure, search the whole tree for the seven removed key names before anything else.

Herd now writes HTTP URLs when HTTPS is disabled. If your agent instructions, seeders, or browser-test base URLs hardcode https://, this release will surface the mismatch. Audit hardcoded schemes — site_secure is now the single source of truth.

Empty php_version preserves the existing selection; it does not reset to a default. If you clear the value expecting a fallback, you will instead keep whatever was last selected. Set it explicitly when you mean to change it.

Site preferences are inert outside Herd/Valet/Yerd. Native PHP, Sail, and cloud execution ignore site_secure entirely. Don't spend time debugging why a Sail project ignores the HTTPS setting — it's by design. Conversely, Yerd 2.x is now fully supported (commands, site setup, PHP selection, HTTPS, worktree hooks, health checks), including cleanup of harness-owned sites when they are no longer needed.

.git/info/exclude is per-clone and uncommitted. Generated integrations won't show as untracked for you, but a collaborator who hasn't run init will see them as new files and may commit them by accident. Make init an explicit onboarding step, not an implicit one.

Debug order when something is wrong: doctor → confirm which config layer won → check the worktree's inherited personal files → confirm the selected runtime. Most "the agent ran the wrong PHP" reports resolve at step one or two.

Extension points worth knowing: service_manager for how services are described to agents, local_env.* for per-machine values, and the dist file as the team baseline. Per-worktree overrides are the right place for branch-specific runtime needs rather than mutating shared config.