Control, meter, and permission-gate AI usage from plugins that connect through the WordPress 7 AI connector.
Inspired by WordPress AI Connectors Need More Friction, Not Less. Works with WordPress 7 RC2. Tested with WordPress AI, Virtual Media Folders AI Organizer, and AI Provider for Azure AI Foundry.
- Per-plugin access control — Allow or deny individual plugins from making AI requests.
- Token budgets — Set daily and monthly token limits per plugin and globally.
- Context restrictions — Control which execution contexts (admin, frontend, cron, REST, AJAX, CLI) may trigger AI calls.
- Usage dashboard — Token consumption at a glance: summary cards, progress bars, and per-plugin breakdowns.
- Request logging — Every AI request is logged with provider, model, capability, tokens, and caller attribution.
- Budget alerts — Admin notices and optional email when usage approaches or exceeds limits.
- Developer hooks — Filter and action hooks to extend behaviour without modifying the plugin.
- WordPress 7.0+
- PHP 8.3+
- A configured AI provider in Settings → Connectors
- Download
soderlind-aivalve.zip - Upload via
Plugins → Add New → Upload Plugin - Activate via
WordPress Admin → Plugins - Configure settings via
Settings → AI Valve
git clone https://github.com/soderlind/ai-valve.git cd soderlind-aivalve composer install npm install && npm run build
After activation, AI Valve intercepts all calls made through wp_ai_client_prompt(). Navigate to Settings → AI Valve:
- Dashboard — Token usage for today and this month, per-plugin access/budget controls, provider breakdown, and recent requests.
- Settings — Master switch, default policy, context restrictions, global budgets, and alert configuration.
- Logs — Filterable, paginated request log with purge controls.
AI Valve hooks into three WordPress 7 AI connector events:
| Hook | Purpose |
|---|---|
wp_ai_client_prevent_prompt |
Gate requests — evaluate policy |
wp_ai_client_before_generate_result |
Insert a pending log row with caller attribution |
wp_ai_client_after_generate_result |
Update the pending row with token usage and status |
A pending log row is created before the AI provider is called. If the provider throws (auth error, timeout, bad deployment), a shutdown handler marks the row as error so failed requests are never lost.
Caller attribution uses debug_backtrace() to identify which plugin initiated the request.
When a request is blocked the calling plugin receives a WP_Error with code prompt_prevented. See docs/how-blocking-works.md for the full explanation.
AI Valve exposes hooks so you can extend its behaviour from another plugin or functions.php without editing the source.
| Hook | Type | Purpose |
|---|---|---|
soderlind_aivalve_plugin_policy |
filter | Override the allow/deny decision for any plugin |
soderlind_aivalve_request_denied |
action | React when a request is blocked |
soderlind_aivalve_request_completed |
action | React when a request succeeds (token counts available) |
See docs/hooks.md for signatures, parameter descriptions, and examples.
- Go to Settings → AI Valve → Settings.
- Set the Default policy to Deny.
- Switch to the Dashboard tab.
- In the Per-plugin access table, set each plugin you want to permit to Allow.
Everything not explicitly allowed will be denied.
Yes — use the soderlind_aivalve_plugin_policy filter. See docs/hooks.md.
# PHP (PHPUnit 11 + Brain Monkey) composer install vendor/bin/phpunit # JavaScript (Vitest) npm install npx vitest run
soderlind-aivalve.php Plugin bootstrap and metadata
uninstall.php Cleanup on uninstall
readme.txt WordPress.org readme
README.md GitHub documentation
CHANGELOG.md Release notes
.wordpress-org/ WordPress.org icons, banners, screenshots
docs/ Developer documentation
README.md Documentation index
hooks.md Filters/actions reference
how-blocking-works.md Blocking flow details
src/
Plugin.php Hook registration orchestrator
Admin/AdminPage.php Settings page shell for the React admin app
Alert/AlertManager.php Budget threshold notices and email alerts
Interceptor/
RequestInterceptor.php WP 7 AI hook wiring and pending-row logging
PolicyEngine.php Allow/deny/context/budget evaluation
CallerDetector.php Backtrace to plugin slug attribution
REST/UsageController.php REST API endpoints for admin screens
Settings/Settings.php Options read/write/sanitize
Tracking/
LogRepository.php Custom DB table CRUD and migrations
UsageClock.php Database-aligned date buckets
UsageTracker.php Rolling daily/monthly token counters
js/
index.js React admin entry point
App.jsx Admin app shell and tab routing
api.js REST client wiring
admin-api.js Shared JS API helpers
admin.css Admin UI styles
components/ Dashboard, settings, logs, and tables
build/ Generated admin assets
tests/
Unit/ PHPUnit + Brain Monkey tests
js/ Vitest tests
stubs/ Test stubs for WordPress AI connector
composer.json PHP dependency metadata
package.json npm scripts and JS dependencies
phpunit.xml.dist PHPUnit configuration
vitest.config.mjs Vitest configuration
See docs/README.md for a full index.
GPL-2.0-or-later — see LICENSE.