probe

Fast project context for AI coding agents.

probe indexes your repo's docs and code, then gives Claude Code, Codex, and other MCP agents a ranked search tool for project knowledge.

Contents

• Quick Start
• Claude Code
• Codex
• CLI and MCP
• Indexing
• Commands
• Configuration
• Data Handling

Quick Start

Get a free ZeroEntropy API key at https://dashboard.zeroentropy.dev.

Claude Code

Run this inside Claude Code:

/plugin marketplace add https://github.com/zeroentropy-ai/probe.git
/plugin install probe@zeroentropy
/reload-plugins

Claude Code asks for your ZeroEntropy API key during install. The plugin starts probe with uvx --from probe-search==0.4.10 probe mcp, so you do not need to install probe separately.

Use the HTTPS URL above. The zeroentropy-ai/probe shorthand makes Claude Code clone over SSH, which requires a configured GitHub SSH key. The Claude Code slash command treats --sparse as part of the URL, so do not pass sparse checkout options there.

Codex

Run this from a shell:

codex plugin marketplace add https://github.com/zeroentropy-ai/probe.git --sparse .agents/plugins --sparse plugins/probe-codex
codex plugin add probe@zeroentropy
export ZEROENTROPY_API_KEY="ze_xxx"

The Codex plugin starts probe with uvx --from probe-search==0.4.10 probe mcp. Keep ZEROENTROPY_API_KEY in your shell before starting Codex, or use the direct installer below to persist the key in Codex's MCP config.

For Codex auto-review, run this once:

uv tool install probe-search
probe install --client codex --approve-tools --allow-zeroentropy-network

This pre-approves probe's MCP tools and allows the narrow ZeroEntropy network egress Codex needs for indexing and reranking.

Plugin Install From A Shell

If you prefer shell commands, probe can install the plugin and direct MCP entry for you:

uv tool install probe-search

probe install --client claude --plugin --api-key "$ZEROENTROPY_API_KEY"
probe install --client codex --plugin --api-key "$ZEROENTROPY_API_KEY" --approve-tools --allow-zeroentropy-network

If you use the claude plugin install shell command directly, pass the plugin config explicitly:

claude plugin marketplace add https://github.com/zeroentropy-ai/probe.git --sparse .claude-plugin plugins
claude plugin install --config zeroentropy_api_key="$ZEROENTROPY_API_KEY" probe@zeroentropy

If Claude says --config not applied, open Claude Code and run /plugin configure probe@zeroentropy, or use probe install --client claude --plugin --api-key "$ZEROENTROPY_API_KEY" so the direct MCP entry also has the key.

CLI and MCP

For CLI-only use:

pip install probe-search
export ZEROENTROPY_API_KEY="ze_xxx"

probe index .
probe search "how does authentication work"

For direct Claude Code or Codex MCP registration:

uv tool install probe-search
export ZEROENTROPY_API_KEY="ze_xxx"

probe install --client claude
probe install --client codex

probe install registers direct MCP by default. It installs the Claude Code or Codex plugin only when you pass --plugin.

For custom Codex installs:

probe install --client codex --codex-home ~/.codex-work --codex-bin /path/to/codex
probe doctor --codex-home ~/.codex-work --codex-bin /path/to/codex

For another MCP-compatible agent, add this to .mcp.json:

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

Start probe from the project root, or set the MCP server working directory to the project root. Claude Code sets CLAUDE_PROJECT_DIR automatically.

Verify Setup

probe doctor
probe smoke

probe doctor checks the API key, Claude Code/Codex wiring, MCP registration, and local index health without printing secrets. probe smoke indexes a tiny sample project and confirms search works. Use probe smoke --current, probe smoke --claude, or probe smoke --codex for deeper checks.

Indexing

probe indexes text-like files and PDFs. It does not rely on a fixed extension allowlist, so files such as Makefile, Dockerfile, and local config files are indexed when they look like text.

Discovery respects nested .gitignore files. .ignore has higher precedence than .gitignore, which lets you keep files out of Git while still letting probe index them. Use .probeignore for probe-specific exclusions.

probe always skips .git/, .probe/, __pycache__/, .venv/, compiled Python files, obvious binary artifacts, and likely secret files such as .env*, *.pem, *.key, .npmrc, .pypirc, and private SSH keys. Set PROBE_INDEX_SECRET_FILES=1 only if you explicitly want those files indexed.

In MCP mode, the first probe_search builds the local .probe/ index. After that, CLI and MCP searches refresh added, changed, and deleted files before search. Set PROBE_REFRESH_TTL=0 to check before every search, or PROBE_REFRESH_TTL=-1 to disable automatic refresh.

If a file cannot be extracted or embedded, probe skips that file, reports it, and continues indexing the rest of the repo. Existing chunks for that file stay in place until the replacement chunks have been embedded successfully.

How Search Works

1. probe chunks files with section, symbol, page, and line metadata.
2. It retrieves candidates with semantic vector search and SQLite FTS5.
3. It fuses and reranks results with ZeroEntropy zerank-2.
4. It returns focused file, section, and line references to the agent.

MCP Tools

MCP resources include probe://status, probe://files, and probe://file/{path}.

Commands

For scripts:

probe search "how does authentication work" --json
probe status --json
probe doctor --json
probe smoke --json

Configuration

probe stores its index and config in .probe/ at the project root. Add .probe/ to .gitignore.

# .probe/config.yaml
providers:
  embedding:
    name: zeroentropy
    model: zembed-1
    dimensions: 1280
  reranker:
    name: zeroentropy
    model: zerank-2

Useful environment variables:

Data Handling

Project chunks and vectors are stored locally in .probe/ with SQLite and numpy. During indexing and search, probe sends query text and chunk text to ZeroEntropy for embedding and reranking. It does not create a remote document index; .probe/ is the durable project index. Likely secret files are skipped by default, but review .probeignore before indexing repositories with unusual credential locations.

Links

• ZeroEntropy
• API Dashboard
• ZeroEntropy API docs
• zembed-1 and zerank-2

License

MIT. See LICENSE.