Codex Laravel: Practical AI Coding Agent Guide

Codex works well in Laravel projects when you treat it as a senior pair programmer that needs unambiguous project context. Start codex inside the Laravel folder, keep AGENTS.md precise, and drive work through small, testable steps. For CLI specifics, see Codex and How to use Codex CLI: a step-by-step guide. This guide covers setup, prompts, pitfalls, and verification for everyday Laravel development backed by Eloquent, migrations, queues, and PHPUnit or Pest.

Eloquent, migrations, and queues: where Codex fits

Laravel has strong conventions: models map to tables, relationships are explicit, migrations should be append-only in team work, and Artisan commands generate predictable scaffolds. Codex can exploit those conventions if it knows your local rules. It reads Eloquent models and migrations, generates factories and seeders, suggests form requests for validation, and writes queued jobs with the retry semantics you specify. The main benefit is not magic generation but consistent changes that respect Laravel boundaries when you encode them in AGENTS.md.

Preparing a Laravel project with AGENTS.md

Create an AGENTS.md file at the Laravel project root. Codex reads project instructions from that file automatically, so it becomes your source of truth for commands, conventions, and guardrails. Avoid vague advice; list the exact commands the agent should run and the Laravel-specific rules it must follow.

Here is a realistic starting point:

# Laravel project rules

## Commands
- Install: composer install
- Build assets: npm run build
- Run tests: php artisan test --parallel
- Lint: vendor/bin/pint --test
- Static analysis: vendor/bin/phpstan analyse --memory-limit=1G

## Folder conventions
- Models live in app/Models and map to snake_case table names unless $table is set.
- Form requests live in app/Http/Requests; one per action.
- Jobs and mailables live in app/Jobs and app/Mail.
- Migrations are append-only; never edit an already merged migration.
- Keep controllers thin; move business logic to actions or services.

## Rules
- Use declare(strict_types=1); in PHP files.
- Prefer Eloquent relationships over raw joins.
- Queue all slow email or external API work.
- Blade templates get data only from controller variables; no queries in views.
- Use route model binding instead of manual find.
- Factories must reflect the current migration state.

If your project uses Laravel Sail, add ./vendor/bin/sail artisan test as the test command. For multi-environment setups, tell the agent whether migrations should run with --seed and whether queue workers use database, redis, or sync. These details prevent the agent from assuming defaults that differ from your deployment. Update this file as your team adds commands such as php artisan horizon, php artisan test --coverage, or php artisan ide-helper:models.

A practical loop: plan, edit, test, review

A reliable loop avoids large, unreviewable diffs. Ask Codex to plan first, then make one model/migration/controller/test change at a time. When you give Codex a task, include the affected route, model, and test file. Name the desired behavior, not just the code to write. After Codex edits, run the commands and inspect the diff. Use git diff --stat to keep changes reviewable. Then run the test suite and linter, review git diff, and commit only when the change is green.

Example prompts for common Laravel tasks:

• Add a posts table and a Post model with title, slug, body, and published_at. Include the migration, factory, seeder, and a Pest feature test for GET /posts listing published posts.
• Create a SendWelcomeEmail job that is queued after user registration. Use the database queue driver, write a failing test first, then implement the job and listener.
• Refactor PostController@store to use a StorePostRequest and a CreatePost action. Keep the existing feature tests green.
• Write an Artisan command php artisan posts:prune-drafts that deletes drafts older than 30 days. Include an isolated test for the command.
• Convert the post-card Blade partial to use route model binding and add a component test that checks the rendered link.

Strong tasks and Laravel-specific pitfalls

Codex is strong at generating migration schema code, Eloquent models with casts and relationships, factories and seeders, form request validation, queued jobs and listeners, Artisan commands with signatures, and PHPUnit or Pest tests. It also handles refactors that require mechanical changes across many files, such as renaming a column or moving logic from a controller into an action.

Watch it closely in areas where Laravel’s magic hides consequences. It may add DB::raw or joins where an Eloquent relationship is clearer, forget fillable or guarded and introduce mass assignment risk, or introduce N+1 queries by accessing relations in a loop instead of eager loading. It can also write migrations that drop a column but fail to remove indexes or foreign keys first, or it may assume the sync queue driver when production uses redis or database. In Blade, it may use {{ }} where {!! !!} is intended or vice versa; ensure user input is escaped. With queues, a missing ShouldQueue interface turns an intended background job into a synchronous call. In tests, it may use RefreshDatabase but forget DatabaseMigrations or seed state, causing flaky tests. Always check config/queue.php, route model binding, and Blade escaping before accepting changes.

Testing and verification workflows with Codex

Make the agent verify its own work. Ask it to run the exact commands from AGENTS.md after each change and to explain any failures before editing further. If CI fails, a good workflow turns the CI output into a prompt for Codex to reproduce and fix locally; for broader CI automation see Auto fix CI failures and PR comments with AI.

The table below summarizes what to check per layer.

Review the diff not only for syntax but for Laravel-specific consistency: php artisan route:list after route changes, php artisan queue:restart after code deploys that affects queued jobs, and php artisan config:cache only when configuration is correct. For Pest, the same workflow applies; replace PHPUnit test arguments with php artisan test --filter and keep the test naming consistent.

Parallel agents on one repository with AgentVera

For Laravel projects with several work streams, AgentVera runs multiple CLI agents in real terminal panels, each in its own git worktree to avoid overwriting files. That lets one agent build a queued job while another writes migrations. Automatic code review after each turn catches missing fillable and N+1 issues with file:line links, which is especially valuable before merging Eloquent changes. Checkpoints let you undo a bad refactor, and token budgets stop an agent from churning through a long test suite. See AI code review: check what your agents write.

Closing notes

Codex on Laravel becomes predictable when you treat it as a tool driven by explicit project rules and small verification loops. Put the real commands and Laravel conventions in AGENTS.md, insist on tests after each change, and review diffs for Eloquent and migration pitfalls. That approach keeps the agent useful without allowing framework-level surprises into your codebase.