Documentation

Everything you need to search WordPress source code with Veloria

Search Guide

Veloria is a code search engine for the WordPress ecosystem. It indexes the source code of every plugin, theme, and core version published on wordpress.org, letting you search across the entire directory in seconds.

▸ Search uses regex (Go's RE2 syntax) for powerful pattern matching across source files.
▸ Results are cached and shareable via URL so you can bookmark or send them to others.
▸ Public searches are visible to everyone on the recent searches page. Private searches are only visible to you.

Regex Reference

Veloria uses Go's RE2 regular expression engine. Below is a quick reference of common syntax.

Pattern	Description
`.`	Any character (except newline)
`*`	Zero or more of the preceding element
`+`	One or more of the preceding element
`?`	Zero or one of the preceding element
`\d`	Digit (equivalent to [0-9])
`\w`	Word character (letter, digit, or underscore)
`\s`	Whitespace character (space, tab, newline)
`[abc]`	Character class — matches a, b, or c
`[^abc]`	Negated class — matches anything except a, b, or c
`(a\|b)`	Alternation — matches a or b
`(?:...)`	Non-capturing group
`^` / `$`	Start / end of line
`\b`	Word boundary

Example Patterns

WordPress-specific regex patterns to help you get started.

WordPress Hooks

do_action\(\s*['"]

Find action hook invocations throughout plugin and theme code.

Filter Applications

apply_filters\(\s*['"]

Find where filters are applied, useful for discovering extension points.

Database Queries

\$wpdb->(query|prepare|get_results)\(

Locate direct database calls for security auditing and performance review.

Sanitization Functions

sanitize_[a-z_]+\(

Find usage of WordPress sanitization functions across the codebase.

REST API Routes

register_rest_route\(

Discover REST API endpoint registrations in plugins and themes.

Enqueue Scripts

wp_enqueue_(script|style)\(

Find where scripts and stylesheets are enqueued for the front-end or admin.

Options API

(get|update|delete)_option\(

Track WordPress options usage for configuration and settings management.

Gutenberg Blocks

registerBlockType\(

Find block registration calls in JavaScript for the Gutenberg editor.

Search Options

Fine-tune your search with these options, all available from the home page search form.

Source

Choose which data source to search. Plugins covers 60,000+ WordPress.org plugins. Themes covers 12,000+ WordPress.org themes. Core includes all tagged WordPress core releases.

File Type Filter

Restrict results to specific file extensions such as .php, .js, .css, .html, .json, .xml, .txt, .md, or .sql. Leave set to "All files" to search everything.

Case Sensitivity

Enabled by default. When case sensitive, getData will not match getdata or GETDATA. Disable for broader matching.

Exclude Minified

When enabled, files ending in .min.js and .min.css are skipped. This reduces noise from compiled or compressed assets.

Visibility

Public searches appear on the shared recent searches page and can be found by anyone with the link. Private searches are only visible to you when signed in.

MCP Integration

Veloria exposes an MCP (Model Context Protocol) server so AI assistants can search WordPress source code directly. Connect your favourite AI tool and query the entire WordPress directory without leaving your editor.

Available Tools

search_code

Search source code with regex patterns. Supports file type filtering, case sensitivity, context lines around matches, and pagination via search_id.

list_extensions

Browse available extensions by data source type (plugins, themes, cores). Supports search filtering and pagination.

get_extension_details

Get detailed metadata for a specific plugin, theme, or core release. Returns version, description, WP/PHP requirements, ratings, install counts, and index status.

get_repo_stats

Get index statistics for one or all data source types. Shows total extensions, indexed count, and coverage percentage.

list_files

List all files in an indexed extension's source tree. Supports an optional glob pattern to filter by filename (e.g. *.php).

read_file

Read the contents of a file from an indexed extension's source tree. Returns numbered lines with support for start_line and max_lines parameters for reading sections of large files.

Remote Server (Recommended)

Veloria hosts a remote MCP endpoint at https://veloria.dev/mcp using Streamable HTTP transport. No local dependencies required — just point your client at the URL.

Claude Desktop

Add the following to your Claude Desktop configuration file:

{"mcpServers": {"veloria": {"type": "streamable-http", "url": "https://veloria.dev/mcp"}}}

Config file location: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.

Claude Code

claude mcp add --transport http veloria https://veloria.dev/mcp

VS Code Copilot

Add the following to your .vscode/settings.json:

{"mcp": {"servers": {"veloria": {"type": "http", "url": "https://veloria.dev/mcp"}}}}

Authentication (Optional)

The MCP endpoint works without authentication, but you can optionally log in to link searches to your account. Authenticated searches appear in your My Searches list.

Log in to Veloria via GitHub, GitLab, or Atlassian
Go to Settings → API Tokens and create a token
Add the token to your MCP client configuration as a Bearer token

Claude Desktop — add headers to your config:

{"mcpServers": {"veloria": {"type": "streamable-http", "url": "https://veloria.dev/mcp", "headers": {"Authorization": "Bearer vel_YOUR_TOKEN"}}}}

Claude Code:

claude mcp add --transport http --header "Authorization: Bearer vel_YOUR_TOKEN" veloria https://veloria.dev/mcp

VS Code Copilot — add headers to your settings:

{"mcp": {"servers": {"veloria": {"type": "http", "url": "https://veloria.dev/mcp", "headers": {"Authorization": "Bearer vel_YOUR_TOKEN"}}}}}

Note: Authentication is optional. The remote server at https://veloria.dev/mcp works without any API keys — tokens are only needed to link searches to your account.

Self-Hosting

Veloria is open source and can be self-hosted on your own infrastructure. This guide walks through setting up a production instance using Docker Compose for dependencies and the Veloria binary.

Prerequisites

Build tools

Go 1.26 or later and Node.js 22 or later are required to compile the binary and frontend assets.

Docker and Docker Compose

Used to run PostgreSQL and MinIO alongside the Veloria binary.

Git

For cloning the repository.

1. Start Dependencies

Create a docker-compose.yml for the required services:

services:
  postgres:
    image: postgres:17-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: veloria
      POSTGRES_PASSWORD: veloria
      POSTGRES_DB: veloria
    volumes:
      - veloria-postgres:/var/lib/postgresql/data

  minio:
    image: minio/minio:latest
    ports:
      - "9000:9000"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    command: server /data --console-address ":9001"
    volumes:
      - veloria-minio:/data

volumes:
  veloria-postgres:
  veloria-minio:

docker compose up -d

2. Build Veloria

Clone the repository and build the binary:

git clone https://github.com/PeterBooker/veloria.git
cd veloria

# Build frontend assets
go generate ./assets/...

# Build the binary
CGO_ENABLED=0 go build -trimpath -o veloria ./cmd/veloria

3. Configure

Create a .env file alongside the binary. All configuration is via environment variables:

ENV=production
PORT=9071
DATA_DIR=/etc/veloria/data

# Database
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=veloria
DB_USERNAME=veloria
DB_PASSWORD=veloria
DB_SSLMODE=disable

# S3 / MinIO
S3_ENDPOINT=localhost:9000
S3_BUCKET=veloria-searches
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin

# Session encryption (generate a random string)
SESSION_SECRET=change-me-to-a-random-secret

# Indexing
INDEXER_CONCURRENCY=2
SEARCH_CONCURRENCY=24

See the full configuration reference for all available environment variables.

4. Run

Run database migrations and start the server:

# Run database migrations
./veloria migrate up

# Start the server
./veloria

Veloria will start on port 9071 by default. The background indexer automatically discovers and indexes plugins, themes, and core releases.

Optional Features

TLS with Let's Encrypt

Set APP_URL to your domain, ACME_EMAIL to your email, and CLOUDFLARE_API_TOKEN for DNS-01 challenges. Veloria handles certificate issuance and renewal automatically.

OAuth Login

Enable user login via GitHub, GitLab, or Atlassian by setting their respective CLIENT_ID and CLIENT_SECRET environment variables, along with OAUTH_BASE_URL.

Observability

Veloria supports OpenTelemetry for traces, logs, and Prometheus metrics. Set OTEL_EXPORTER_TYPE=otlp and configure OTEL_EXPORTER_OTLP_ENDPOINT to send telemetry to your collector.

MCP Server

The MCP endpoint is enabled by default at /mcp. Set MCP_ENABLED=false to disable it.

Tip: For production deployments, run Veloria as a systemd service so it starts automatically on boot and restarts on failure. Place the binary at /opt/veloria/veloria and create a unit file pointing to it.