nunomaduro/pao is an excellent tool that help with trimming down your PHP tools output for agent consumption. It supports multiple tools, including PHPStan, pest, PHPUnit and even Laravel Artisan specific commands.

If you are running this directly, there shouldn’t be any issue. However, I prefer to run everything inside the container, this includes all static analysis, unit testing, and formatting.

pao depends on shipfastlabs/agent-detector for the agent detection algorithm. I am using Claude Code, and for this, pao is specifically relying for ClAUDECODE and CLAUDE_CODE environment variables.

Claude Code sets CLAUDECODE=1 in every shell session it spawns, so on the host machine detection works automatically, but not when running it inside a container via docker compose exec.

The most straightforward solution is to forward the variable explicitly on each docker compose exec invocation using the -e flag:

docker compose exec ${CLAUDECODE:+-e CLAUDECODE="$CLAUDECODE"} app composer test

The ${CLAUDECODE:+-e CLAUDECODE="$CLAUDECODE"} expansion emits -e CLAUDECODE=1 when CLAUDECODE is set and non-empty, and expands to nothing otherwise, so pao activates correctly on the environment it is triggered.