pi-search-agent extension

Overview

pi-search-agent adds local semantic search to pi. It builds a semantic index of your codebase, runs embedding-based retrieval, and uses a configurable LLM to filter and summarize results via a search subagent.

First-time setup

On first run you will be prompted (via UI) to:

1. Enter your OPENAI_API_KEY (used for embeddings).
2. Choose a search model (recommended: cerebras / zai-glm-4.7).
   • Alternatively, anthropic / claude-haiku-4-5 is a good default if you want reasoning.

Configuration is stored in:

~/.pi/extensions/pi-search-agent/.env

You can edit the file manually later. Supported keys:

• OPENAI_API_KEY
• SEARCH_PROVIDER (e.g. cerebras, openai)
• SEARCH_MODEL (e.g. zai-glm-4.7, gpt-4o-mini)
• SEARCH_THINKING (optional: off, minimal, low, medium, high, xhigh)

Tools

search_agent(query, cwd?, queryExtrapolation?, path?, mode?, logSubagent?)

Search locally and run a subagent to refine results.

• query: natural language search query
• cwd: directory to search (defaults to current workspace)
• queryExtrapolation: additional queries to run and merge
• path: optional filter (file/dir/glob/substring)
• mode: currently ignored (defaults to code)
• logSubagent: writes JSON log to disk when true

Example:

search_agent(query: "How do we authenticate API requests?", path: "src", logSubagent: true)

local_embedding_search(query, cwd?, path?, mode?)

Run embedding search only (one result per file).

Example:

local_embedding_search(query: "retry logic", path: "packages/api")

Commands

/search-agent-settings

Open an interactive UI to configure or change:

• OPENAI_API_KEY
• SEARCH_PROVIDER + SEARCH_MODEL
• SEARCH_THINKING

Settings are saved to:

~/.pi/extensions/pi-search-agent/.env

/search-agent <query> [--path <filter>] [--cwd <dir>] [--mode <mode>] [--log]

Run the semantic search pipeline directly from a user command (no need to ask the model to call the tool).

Examples:

/search-agent How do we authenticate API requests?
/search-agent "retry logic" --path packages/api
/search-agent "where is initializeOpenAI" --cwd ~/src/ai-extensions/semantic-search --log

How it works

1. File discovery: streams find results and yields to the event loop to avoid blocking the UI.
2. Chunking: files are split into overlapping chunks for stable embeddings.
3. Embeddings: generated with OpenAI (text-embedding-3-small) and cached on disk.
4. Index storage: index metadata + chunks are persisted per-cwd.
5. Search pipeline:
   • embedding matches → merged per file
   • subagent refines results and provides a concise answer
6. Summaries / filtering: uses the configured SEARCH_PROVIDER + SEARCH_MODEL (and optional SEARCH_THINKING).

Data locations

• Index: ~/.pi/agent/cache/semantic-search/<hash>/
• Embedding cache: ~/.pi/agent/cache/semantic-search/embeddings/
• Subagent logs (when enabled): ~/.pi/agent/cache/semantic-search/subagent-logs/

Legacy tools / UI

Legacy tools are disabled by default. Enable them with:

PI_SEMANTIC_LEGACY=1

This re-enables:

• semantic_index, semantic_search
• /semantic interactive UI

Notes

• mode is accepted but currently ignored; code includes markdown.
• Indexing is per-cwd. If no index exists, it is created automatically.
• The recommended search model is cerebras / zai-glm-4.7.
• SEARCH_THINKING is clamped to off for non-reasoning models (so it has no effect for cerebras/zai-glm-4.7).