All articles
Lukas Mateffy·Apr 5, 2026·6 min read
AUTOMATED PERFORMANCE

Agents + laraperf = hands-free optimization

AI coding agents can run captures, analyze results, and apply fixes. Performance optimization becomes part of your CI/CD pipeline instead of a quarterly chore.

The promise of AI coding agents isn't just that they can write code—it's that they can run tools, interpret output, and iterate. When you pair this capability with laraperf's structured JSON output, you get something powerful: an agent that can autonomously find and fix performance issues.

This isn't theoretical. Claude Code and Cursor can already run terminal commands, read files, and apply edits. Give them laraperf commands that output JSON they can parse, and they can navigate to slow queries, read the surrounding code context, and apply eager loading or index optimizations.

Manual vs Agent workflow

Manual workflow
  • —Remember to run performance tests (you won't)
  • —Open browser, navigate to Debugbar UI
  • —Sift through hundreds of queries manually
  • —Copy-paste SQL into psql to run EXPLAIN
  • —Manually write fix, hope it works
  • —No record of what was checked or changed
Agent workflow
  • Agent runs perf:watch on every test run
  • Parses JSON output programmatically
  • Navigates to exact file:line from source field
  • Reads context and applies appropriate fix
  • Re-verifies and reports before/after metrics
  • Documents changes in PR description

The key difference is consistency. Humans are bad at repetitive tasks—we forget to run checks, we miss edge cases, we get interrupted. Agents don't forget. They run the same checks every time, with the same thoroughness, whether it's 2 AM or the middle of a busy workday.

The other difference is precision. When a human sees "slow query on line 47," they open the file and read around that area to understand context. An LLM agent does the exact same thing—it reads the surrounding code, understands the model relationships, and applies the appropriate fix (eager loading for N+1, index suggestions for slow scans, etc).

A complete agent session

0:00
$ perf:watch --seconds=60
✓ session=session-20260416-143201 pid=48291
0:01
$ php artisan test
Running test suite... (2 min)
1:00
$ perf:query --n1=3 --slow=50
Found 2 N+1 candidates, 1 slow query >50ms
1:02
$ perf:explain --hash=a1b2c3d4
{ "Plan": { "Node Type": "Seq Scan"... } }
1:05

Agent analyzes: N+1 in DealResource can be fixed with ::with('contact'). Slow query needs trigram index on email.

1:30
$ perf:watch --seconds=60 && perf:query
✓ 0 N+1 candidates, 0 slow queries. 47 queries → 2 queries.

Notice how the agent doesn't just apply a fix and hope—it verifies. The final step re-runs the capture and checks that the metrics actually improved. If the N+1 is still there or the slow query persists, the agent knows the fix didn't work and tries a different approach.

This verification step is crucial because not all performance issues are what they seem. Sometimes what looks like an N+1 is actually necessary (distinct queries for distinct purposes). Sometimes the slow query is slow for reasons an index can't fix (large result sets, complex calculations). The agent reads the context and makes informed decisions, just like a human would.

CI/CD Integration

Add performance gates to your deployment pipeline

Pull request checks

Block PRs that introduce N+1 queries or slow queries exceeding configured thresholds

Regression testing

Compare query counts before/after. Fail build if queries increased more than 10%

Production safety

Run captures on staging before deploy. Catch issues that only show with real data volume

Auto-fix workflow

Agent comments on PR with suggested fixes including ready-to-apply code patches

Setting CI thresholds

The key to CI integration is setting appropriate thresholds. A blanket "zero N+1 queries" rule will give you false positives—sometimes you legitimately need multiple queries. Better thresholds look like:

N+1 threshold: Allow up to 3 instances of repeated queries, but flag anything beyond that. Or set it per-route: critical paths (checkout, login) have stricter limits than admin dashboards.

Slow query threshold: Base this on user impact. Queries under 50ms don't materially affect page load times. Queries over 200ms start to be noticeable. Queries over 1000ms are serious problems.

Query count threshold: Track total queries per request. A 20% increase might indicate a regression even if individual queries are fast.

GitHub Actions example

.github/workflows/perf.yml
name: Performance Check
on: [pull_request]
jobs:
  perf:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Start capture
        run: php artisan perf:watch --seconds=120 &

      - name: Run tests
        run: php artisan test

      - name: Check for regressions
        run: |
          N1_COUNT=$(php artisan perf:query --n1=3 | jq '.n1.candidates | length')
          SLOW_COUNT=$(php artisan perf:query --slow=100 | jq '.slow_queries | length')

          if [ "$N1_COUNT" -gt 0 ] || [ "$SLOW_COUNT" -gt 0 ]; then
            echo "Found $N1_COUNT N+1 queries and $SLOW_COUNT slow queries"
            php artisan perf:query --n1=3 --slow=100
            exit 1
          fi

The workflow above starts a capture, runs your test suite (which exercises the application), then checks for performance regressions. If any are found, it prints the details and fails the build.

You can enhance this with automatic agent intervention. On failure, the action could trigger an agent to analyze the output, apply fixes, and push a commit to the PR. This turns performance regression detection into automatic performance regression correction.

Ready for agents

Every command outputs structured JSON to stdout. Status lines go to stderr. Safe to pipe into jq, grep, or agent analysis tools.

  • Exit codes: 0 for success, non-zero for errors
  • File:line in every result for precise navigation
  • Session-based isolation prevents cross-run contamination
  • Machine-readable timestamps for trend analysis

Get started

Two ways to install — manual or let your agent handle it.

Manual install

1Install via Composer
composer require mateffy/laraperf --dev
2Using Laravel Boost?

If you have Laravel Boost installed, run the following after installing laraperf — the skill is automatically added.

php artisan boost:update

Let your agent do it

Install the skill permanently with the CLI, or paste a prompt for a one-shot setup.

npx skills add mateffy/laraperf

Or paste this prompt for a quick one-shot:

Using Laravel Boost? Run php artisan boost:update after installing — the skill is added automatically.

All articlesHome