probe

probe

Give your AI agent a brain beyond code.

probe is a CLI tool and MCP server that indexes your project's docs and code, then serves curated, reranked context to AI coding agents in milliseconds.

---

Contents

• Why probe
• Quick Start
• MCP Server Setup
• Indexing
• How It Works
• Example Output
• CLI Reference
• Configuration
• Data Handling

---

Why probe

AI coding agents often answer project questions by grepping, reading files one by one, and assembling context over several tool calls. probe gives them one ranked search across docs and code.

What you get:

• Claude Code plugin with bundled MCP server and usage skill
• Manual Claude Code setup with probe install
• First-use indexing and incremental refresh-before-search
• Hybrid keyword + semantic retrieval across docs, code, text, and PDFs
• Cross-encoder reranking with ZeroEntropy zerank-2
• Local index storage in .probe/
• MCP tools and resources for Claude Code, Cursor, and other MCP-compatible agents

---

Quick Start

Claude Code plugin (recommended)

Get a free ZeroEntropy API key at https://dashboard.zeroentropy.dev. Then run inside Claude Code:

/plugin marketplace add zeroentropy-ai/probe --sparse .claude-plugin plugins
/plugin install probe@zeroentropy
/reload-plugins

Claude Code asks for your ZeroEntropy API key during plugin install. The plugin starts probe with uvx --from probe-search==0.4.0 probe mcp, so Claude Code does not need a separate probe install.

If you use the claude plugin install shell command instead of the /plugin slash command, export ZEROENTROPY_API_KEY before starting Claude Code.

Manual CLI/MCP setup

uv tool install probe-search
# or: pipx install probe-search

export ZEROENTROPY_API_KEY="ze_xxx"
probe install
claude mcp list

Use uv tool install or pipx so the registered probe path stays valid. If you install probe in a temporary virtual environment, rerun probe install after recreating that environment.

For CLI-only use:

pip install probe-search
export ZEROENTROPY_API_KEY="ze_xxx"
probe index .
probe search "how does authentication work"

Verify your setup

probe doctor
probe smoke

probe doctor checks your API key, Claude Code wiring, MCP registration, and local index health without printing secrets or uploading project content. probe smoke indexes a tiny sample project and confirms search works. Use probe smoke --current to validate the current repo.

---

MCP Server Setup (Claude Code, Cursor)

The Claude Code plugin is the best default. For Cursor or advanced use, add a .mcp.json file to your project root:

{
  "mcpServers": {
    "probe": {
      "command": "uvx",
      "args": ["--from", "probe-search", "probe", "mcp"],
      "env": {
        "ZEROENTROPY_API_KEY": "ze_xxx"
      }
    }
  }
}

Your agent gets four tools:

Tool	What it does
probe_search	Search docs and code with automatic refresh and reranking
probe_index	Index or re-index project files
probe_status	Show what's indexed
probe_read	Read a file, optionally with focused line ranges

It also gets MCP resources:

Resource	What it exposes
probe://status	Index status and provider configuration
probe://files	Indexed file list
probe://file/{path}	Read a project file by URL-encoded path

When Claude Code starts probe, probe uses CLAUDE_PROJECT_DIR as the project root. That keeps search, indexing, and file reads pinned to the repo even when the MCP process starts from another directory.

---

Indexing

probe indexes Markdown, MDX, plain text, reStructuredText, AsciiDoc, TeX, YAML, JSON, PDFs, and code in Python, JavaScript, TypeScript, TSX, JSX, Go, Rust, and Java.

File discovery respects root .gitignore and .probeignore files. It also skips .git/, .probe/, __pycache__/, .venv/, and *.pyc.

On first search, probe creates the local .probe/ index automatically. Before later CLI or MCP searches, it checks for added, changed, and deleted files, then refreshes only affected chunks. Set PROBE_REFRESH_TTL=0 to check before every search, or PROBE_REFRESH_TTL=-1 to disable automatic refresh.