Weave Code
Pao Laravel Package
laravel/pao
Agent-optimized output for PHP tools. Auto-detects AI agents (Claude Code, Cursor, Devin, Gemini CLI) and replaces verbose PHPUnit/Pest/Paratest/PHPStan output with minimal structured JSON; cleans Laravel Artisan output too. Zero config; human output unchanged.
PAO is agent-optimized output for PHP testing tools.
Frequently asked questions about Pao
- How does Laravel PAO detect AI agents like Claude Code or Cursor?
- PAO uses the `laravel/agent-detector` library to analyze environment signals like terminal emulators, process names, and metadata. It checks for known AI agent patterns (e.g., `claude-code`, `cursor`, `gemini-cli`) and only activates when those are detected. You can manually override detection with the `PAO_IGNORE` environment variable if needed.
- Will PAO break my existing Laravel Artisan commands or CLI tools?
- PAO only modifies output when an AI agent is detected. For humans, Artisan commands retain full ANSI colors, formatting, and box-drawing characters. However, if your scripts rely on specific ANSI formatting, test them post-installation. PAO strips only noise (excess whitespace, redundant decorations) while preserving core functionality.
- Does Laravel PAO work with Laravel 11 or PHP 8.2?
- No, PAO requires **Laravel 12+** and **PHP 8.3+** due to dependencies like PHPUnit 12+ and Pest 4+. If you’re on older versions, you’ll need to upgrade or use a different solution. The package explicitly targets modern Laravel stacks for optimal compatibility and performance.
- How does PAO handle custom Pest plugins or PHPUnit extensions?
- PAO integrates with core test runners (Pest, PHPUnit, Paratest) via autoloader hooks, but custom plugins or extensions might not be fully supported. Test your specific toolchain pre-release. If a plugin alters output structure, PAO may not recognize it as a test result, leading to partial JSON conversion. Check the [GitHub issues](https://github.com/laravel/pao/issues) for known edge cases.
- Can I disable PAO for specific commands or environments?
- Yes. Set the `PAO_IGNORE` environment variable to disable agent detection entirely. For granular control, wrap commands in a script that exports this variable. PAO also respects the `NO_COLOR` environment variable, which will suppress ANSI cleaning in Artisan output if set.
- What’s the performance impact of using PAO in large test suites?
- PAO adds minimal overhead—primarily JSON serialization for AI agents. Benchmarks show negligible slowdowns (sub-5% for 10,000+ tests) in agent environments. For humans, there’s no impact. If performance is critical, test your largest suite post-installation. The tradeoff is AI agents receiving optimized, token-efficient output.
- Does PAO support other AI agents besides Claude Code, Cursor, and Gemini?
- PAO currently supports **Claude Code, Cursor, Devin, and Gemini CLI** via `laravel/agent-detector`. New agents can be added via pull requests to the detector library. If you’re using an unsupported agent, PAO will default to human-readable output. Check the [detector’s GitHub](https://github.com/laravel/agent-detector) for updates.
- How can I verify PAO is working correctly in my Laravel app?
- Run a test or Artisan command in your terminal (human output should remain unchanged). Then, simulate an AI agent environment by setting `PAO_AGENT=1` (or use a tool like `curl` to mimic agent headers). Check if output switches to JSON. For Artisan, compare `php artisan --version` with and without PAO active.
- Are there alternatives to PAO for AI-optimized PHP tooling?
- Alternatives include custom scripts using `symfony/console` or `phpunit/console` to filter output, or tools like `jq` to post-process JSON. However, PAO is the only Laravel-native solution with zero-config integration for PHPUnit, Pest, Paratest, and Artisan. For Symfony/Laminas, you’d need manual setup. PAO’s strength lies in its seamless Laravel ecosystem fit.
- Will PAO work in CI/CD pipelines or headless environments?
- Yes, PAO is designed for CI/CD. It only activates in AI agent environments, so pipelines running tests normally will see no changes. If your CI uses an AI agent (e.g., GitHub Copilot in a workflow), PAO will optimize output for it. Ensure your CI environment doesn’t set `PAO_IGNORE` unless you want to disable agent detection entirely.
Weaver
How can I help you explore Laravel packages today?