The ai_audit_dir function
For a whole theme or plugin, the single-file loop isn't enough. This companion gathers every relevant file in a directory, concatenates them with ### FILE: markers, and lets you ask a specific question across the set — or run a constrained critical-issues sweep if you don't have one:
# ------ Directory audit: gather files, answer a specific question ------
ai_audit_dir() {
local model="deepseek-v4-pro"
if [ "$1" = "-f" ]; then
model="deepseek-v4-flash"
shift
fi
local dir="$1"; shift || true
if [ ! -d "$dir" ]; then
echo "Usage: ai_audit_dir [-f] <directory> [specific question]"
echo ""
echo "Examples:"
echo " ai_audit_dir ./bl-themes/mytheme \"Are there any files that reference a function or class that doesn't exist in this theme or Bludit core?\""
echo " ai_audit_dir ./src \"Find any path where unvalidated user input reaches a SQL query or filesystem operation.\""
echo " ai_audit_dir -f ./my-plugin \"Summarize what this plugin does and how its files connect.\""
return 1
fi
local tmpfile
tmpfile=$(mktemp /tmp/ai_audit_dir.XXXXXX)
echo "Gathering files from $dir ..."
while IFS= read -r -d '' file; do
echo "" >> "$tmpfile"
echo "### FILE: ${file#$dir/}" >> "$tmpfile"
echo '```' >> "$tmpfile"
cat "$file" >> "$tmpfile"
echo "" >> "$tmpfile"
echo '```' >> "$tmpfile"
done < <(find "$dir" -type f \
\( -name '*.php' -o -name '*.css' -o -name '*.html' -o -name '*.js' \
-o -name '*.conf' -o -name '*.ini' -o -name '*.yml' -o -name '*.yaml' \
-o -name '*.json' -o -name '*.txt' -o -name '*.md' \) \
-print0 2>/dev/null)
local file_count
file_count=$(grep -c "^### FILE:" "$tmpfile")
echo "Found $file_count files ($(wc -l < "$tmpfile") lines total)."
if [ "$file_count" -eq 0 ]; then
echo "No matching files found."
rm -f "$tmpfile"
return 1
fi
if [ "$file_count" -gt 20 ]; then
echo "Warning: $file_count files — that's a lot. Ctrl+C within 3s to abort."
sleep 3
fi
echo ""
# --- Context detection — same Bludit heuristic as ai_audit ---
local context=""
local dirname_lower
dirname_lower=$(basename "$(realpath "$dir" 2>/dev/null || echo "$dir")" | tr '[:upper:]' '[:lower:]')
local fullpath_lower
fullpath_lower=$(realpath "$dir" 2>/dev/null | tr '[:upper:]' '[:lower:]')
local content_sample
content_sample=$(head -200 "$tmpfile" 2>/dev/null)
if echo "$content_sample" | grep -qiE 'bludit|bl-kernel|bl-themes|bl-plugins' \
|| echo "$dirname_lower" | grep -qE '^bl-|bludit' \
|| echo "$fullpath_lower" | grep -qE '/bl-themes/|/bl-plugins/|/bl-kernel/|/bludit/'; then
if [ -f "${AI_AUDIT_REFS}/bludit.md" ]; then
context=$(cat "${AI_AUDIT_REFS}/bludit.md")
echo "Attached Bludit reference (~$(wc -c < "${AI_AUDIT_REFS}/bludit.md" | numfmt --to=iec))"
fi
fi
# --- End context detection ---
if [ -n "$*" ]; then
local user_task="$*"
echo "Task: $user_task"
echo ""
local system_prompt="You are a code reviewer examining multiple files from a project.
Each file is marked with '### FILE: <path>' and wrapped in code fences.
The user has asked you to: ${user_task}
Answer specifically and concisely. Do not volunteer unrelated findings.
If you reference a file in your answer, use its path as shown in the FILE markers."
else
echo "Task: find critical issues only (no question provided — use -f for fast check)"
echo ""
local system_prompt="You are a code reviewer examining multiple files from a project.
Each file is marked with '### FILE: <path>' and wrapped in code fences.
FLAG ONLY:
- References to functions, classes, constants, or files that do not exist
anywhere in the provided file set or in the framework reference below.
- Security holes exploitable by an unauthenticated visitor.
- Logic that would silently produce wrong output for end users.
DO NOT FLAG:
- Code style, organization, or architecture preferences.
- Admin-only concerns (admins have full code execution access).
- Performance speculation.
- Missing optional files.
- Any finding you are less than 90% certain about.
If you find nothing that meets these criteria, say so and stop."
fi
if [ -n "$context" ]; then
system_prompt="${system_prompt}
---
# VERIFIED FRAMEWORK REFERENCE (source-code-verified)
- THEME_DIR_* constants are defined by the core boot sequence
before any theme file loads — do not flag them as undefined.
- init.php is OPTIONAL for themes.
- Admin users have full code execution. Admin-supplied HTML in site
settings is not a vulnerability.
- Trust this reference over your training data for API details.
${context}
---
"
fi
local -a cmd=(llm -m "$model" -s "$system_prompt")
if command -v glow >/dev/null 2>&1; then
"${cmd[@]}" < "$tmpfile" | glow -
else
"${cmd[@]}" < "$tmpfile"
fi
rm -f "$tmpfile"
}
Two cautions specific to the directory sweep. First, the find patterns include .conf, .ini, .yml, and .json — all of which can hold credentials in the wrong directory. Point this at theme and plugin folders, not project roots that might contain environment files. Second, the 20-file warning exists because a directory sweep sends the whole file set to the model at once; watch the total line count before you trust it to hold context on all of it.
What the functions do not do
This is the section that matters, so read it before you use the thing.
As written, both functions are pipes. The model receives text on stdin and writes text to stdout. There is no tool flag, no shell access, no file handle, no write path. A hallucination can waste your time or produce bad advice — but it cannot delete a directory, modify a file, or run a command, because nothing here ever executes the model's output. The worst case is that you read a bad suggestion, believe it, and apply it yourself. That is a human decision, and it stays one.
llm does have a tool mode — llm --tool and tool plugins, available since llm 0.26 — and with it the model can execute code in your terminal. That is not a bad feature, but it is a different tool than the one above. These functions deliberately do not use it.
Unprivileged by default, root by exception
These functions live in the unprivileged user's ~/.bashrc, and that placement is doing real work. llm doesn't need root — only reading the file does. When you want to audit something root-owned, like a file in /etc/nginx/snippets, copy it down to your user and audit the copy:
sudo cp /etc/nginx/snippets/php.conf /tmp/php.conf
ai_audit /tmp/php.conf
rm /tmp/php.conf
This keeps llm — and its API call, and its SQLite log of every prompt and response — out of root's context entirely. Root gets the syntax check and the final write. The model only ever sees a throwaway copy.
Keep the agentic version out of production. If you later decide you want llm's tool mode — the version that can actually make changes — confine it to a development environment. A sandbox, a container, a staging box, anything without a public IP and without production data. Tools change the failure mode from "bad advice" to "bad action," and the history of agentic coding tools since 2025 has been a steady reminder that models can be steered into running things you didn't intend. This is the line worth being stubborn about: the read-only functions can run anywhere; the tool-enabled version runs where a mistake is an afternoon, not an outage.
Findings first, rewrites second
Both prompts ask for findings, not full rewrites. That's a deliberate default.
A rewrite is convenient — you get a corrected file back — but it's also the riskiest thing a model can produce. It may "fix" things that weren't broken, modernize syntax you didn't ask it to touch, or drop a comment that carried context you'll need six months from now. You then diff the whole file to find out what changed, which is more work than reviewing a findings list. If you prefer rewrites for small files, change the prompt — the -f examples in the usage text already point in that direction. Just know it's a trade, not a free upgrade: you're trading review time before the model runs for review time after.
Where this fits
These functions are the CLI cousin of the workflow in the Bludit 3.22.0 developer reference — that article builds a verified reference set and feeds it to a model with a canary test; this one wraps a model in a read-only pipe and attaches the same references by context detection. Both rest on the same rule: the model is a fast collaborator, not an authority.
The standard these functions are reaching for is set by the Bludit production stability audit — a real source review that turned up eight findings a model would have needed serious steering to catch. That's the bar: the function flags, you verify, and the audit is the proof that verification still matters.
And the broader context is worth naming once. The same force that makes a model useful for code review is the one that let researchers find PHP2Shell — AI is a force multiplier in both directions. A read-only audit loop is the defensive version of that multiplier. The difference is that yours stays under human control.
The one non-negotiable
Everything above is tooling. The part that cannot be skipped is the human in the loop — the same discipline documented in the Bludit 3.22.0 developer reference: the model suggests, you decide. These functions are built to force that arrangement — read-only, findings-first, no write path — but a script can only hold a boundary you actually believe in. The moment you let a model's output reach a server without reading it is the moment you've stopped auditing and started delegating, and delegated judgment is how a clever-sounding mistake becomes a production outage.
The loop is short and it never changes: run the audit, read every finding, decide what applies, verify against the running system, apply the change yourself. The model shortens the first step. The rest is still yours, and it's the rest that keeps you a sysadmin rather than a spectator.
This guide documents a read-only AI code-audit loop built on the llm command-line tool: two bash functions that pipe files into a model, run syntax checks as advisory input rather than gates, refuse credential-bearing paths, attach verified framework references by context detection, and return findings rather than rewrites. The article is primarily about the safety boundary — what the functions do not do — rather than the model itself.
Compatibility: The functions require bash and llm; the read-only pattern works on any llm release, while the tools discussion applies to llm 0.26+. Model names are placeholders — substitute whatever llm models reports for your provider. The advisory preflight covers PHP, shell, and Python; other file types pass through unchecked. The Bludit context detection depends on a reference file at ${HOME}/.config/ai-audit/refs/bludit.md and should be extended only for ecosystems where the model's training data is demonstrably unreliable. Tested on Debian Trixie with Python 3.12.
2026-11-10: Initial publication — CLI AI audit loop with llm installation, the ai_audit and ai_audit_dir functions (secret guard, advisory syntax preflight, Bludit context detection, FLAG/DO NOT FLAG prompt contract, glow fallback), unprivileged-by-default and agentic-separation safety guidance, and a findings-vs-rewrite tradeoff. Cross-linked to the Bludit developer reference, the Bludit production stability audit, and the PHP defense-in-depth guide.