Frequently Asked Questions

May 20, 2026 · View on GitHub

Common questions about Probe CLI and Probe Agent.

General

What is Probe?

Probe is a semantic code search and AI agent platform consisting of two products:

Probe CLI - A Rust-based tool for fast, intelligent code search
Probe Agent - A Node.js SDK for building AI coding assistants

How is Probe different from grep/ripgrep?

Feature	grep/ripgrep	Probe
Speed	Fast	Fast (uses ripgrep internally + SIMD acceleration)
AST awareness	No	Yes (tree-sitter)
Semantic search	No	Yes (BM25, TF-IDF, BERT)
Code block extraction	No	Yes (full functions/classes)
AI integration	No	Yes (MCP, SDK, built-in agent)
Token limits	No	Yes (--max-tokens)

How is Probe different from embedding-based tools (grepai, Octocode)?

Embedding-based tools convert code into vectors and use cosine similarity for search. Probe uses keyword matching with AST-aware code extraction and BM25 ranking instead.

Feature	Embedding tools	Probe
Setup	Requires indexing + embedding service	Zero setup, works instantly
Natural language search	Built-in (vector similarity)	Delegated to AI agent (LLM generates boolean queries)
Exact search	Weak (approximate matching)	Strong (SIMD-accelerated exact patterns)
Result unit	Text chunks (can split mid-function)	Complete AST blocks (functions, classes, structs)
External dependencies	Ollama, OpenAI, or other embedding API	None
Determinism	Results vary with model/index state	Same query always returns same results
Latency	100ms+ (embedding generation + vector lookup)	Milliseconds (in-process pattern matching)
Index maintenance	Must re-index on code changes	No index to maintain

Why no embeddings? When an AI agent uses Probe, the LLM itself handles vocabulary mismatch. It knows "authentication" might be verify_token, check_credentials, or auth_middleware, and generates precise boolean queries covering all variants. This is faster, cheaper, and more deterministic than embedding-based similarity search.

How does Probe compare to code knowledge graph tools (Stakgraph, ABCoder)?

Knowledge graph tools build a structural representation of your codebase (call graphs, dependency edges, type hierarchies). Probe focuses on search and extraction -- it finds and returns code, while graph tools map relationships.

Feature	Graph tools (Stakgraph, ABCoder)	Probe
Call graph	Yes (function-level edges)	Coming soon (via LSP integration)
Dependency analysis	Yes (typed relationships)	Not yet
Setup	Heavy (Neo4j, batch parsing, LSP servers)	Zero
Search	Limited (graph traversal, node name lookup)	Full-featured (boolean queries, BM25, AST-aware)
Token awareness	Limited	Built-in (--max-tokens, session dedup)
Real-time	Requires rebuild on changes	Always current (stateless)

These tools are complementary: graph tools excel at "what calls this function?" while Probe excels at "find me the code that handles X."

# Via npm (recommended)
npm install -g @probelabs/probe

# Via cargo
cargo install probe-search

# Via Homebrew (macOS)
brew install probelabs/tap/probe

# Direct download
# See https://github.com/probelabs/probe/releases

Do I need Rust to use Probe?

No. The npm package includes pre-built binaries for all major platforms. You only need Rust if building from source.

Probe isn't finding my files. Why?

Check these common issues:

.gitignore: Probe respects .gitignore by default. Use --no-gitignore to include ignored files.
Language support: Ensure your language is supported.
Path: Verify you're searching the correct directory.
Permissions: Ensure read access to files.

# Debug: show what files Probe sees
probe search "test" ./ --files-only -v

Search

How do I search for exact phrases?

Use quotes:

probe search "\"exact phrase\""
probe search "'exact phrase'"

Or use the --exact flag:

probe search "myFunction" ./ --exact

How do I exclude certain files?

Use the --ignore flag or search hints:

# Ignore patterns
probe search "config" ./ --ignore "*.test.ts" --ignore "node_modules/*"

# Using search hints
probe search "config NOT dir:tests NOT ext:spec.ts" ./

Why are my results in a different order than expected?

Probe uses ranking algorithms (BM25 by default) to order results by relevance. Factors include:

Term frequency
Document length
Field matches

To change ranking:

probe search "api" ./ --reranker tfidf
probe search "api" ./ --reranker hybrid

How do I search only in specific file types?

# By extension
probe search "function AND ext:ts,tsx" ./

# By language
probe search "function" ./ --language typescript

# By file type (ripgrep types)
probe search "function AND type:rust" ./

Can I use regex in searches?

Probe uses Elasticsearch-style syntax, not regex. For regex, use the grep subcommand:

probe grep "user[A-Z]\w+" ./src

AI Integration

Which AI providers does Probe support?

Provider	API Key Variable
Anthropic Claude	`ANTHROPIC_API_KEY`
OpenAI	`OPENAI_API_KEY`
Google Gemini	`GOOGLE_GENERATIVE_AI_API_KEY`
AWS Bedrock	AWS credentials
Claude Code	`claude` CLI installed
Codex	`codex` CLI installed

How do I use Probe with Claude Code?

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "probe": {
      "command": "probe",
      "args": ["mcp"]
    }
  }
}

How do I limit token usage?

# CLI
probe search "auth" ./ --max-tokens 8000

# SDK
const agent = new ProbeAgent({
  path: './src',
  maxResponseTokens: 4096
});

Can Probe edit my code?

Yes, with explicit permission:

const agent = new ProbeAgent({
  path: './src',
  allowEdit: true,  // Enable edit/create tools
  enableBash: true  // Enable command execution
});

Performance

How can I make Probe faster?

Use language filters: --language rust
Set result limits: --max-results 20
Use session pagination: --session my-search
Increase parser pool: PROBE_PARSER_POOL_SIZE=8

Why is the first search slow?

Probe warms up tree-sitter parsers on first use. Subsequent searches are faster. To skip warmup:

PROBE_NO_PARSER_WARMUP=1 probe search "query" ./

How do I profile Probe performance?

DEBUG=1 probe search "query" ./

This shows timing for each phase (scanning, parsing, ranking).

Probe Agent SDK

How do I persist conversation history?

Implement a custom StorageAdapter:

class MyDatabaseAdapter extends StorageAdapter {
  async loadHistory(sessionId) {
    return await db.messages.findAll({ sessionId });
  }
  async saveMessage(sessionId, message) {
    await db.messages.create({ sessionId, ...message });
  }
  async clearHistory(sessionId) {
    await db.messages.destroy({ sessionId });
  }
}

const agent = new ProbeAgent({
  storageAdapter: new MyDatabaseAdapter()
});

How do I handle API rate limits?

Enable retry with backoff:

const agent = new ProbeAgent({
  retry: {
    maxRetries: 3,
    initialDelay: 1000,
    backoffFactor: 2
  },
  fallback: {
    strategy: 'any'  // Try other providers
  }
});

Can I stream responses?

Yes:

await agent.answer("Explain this code", [], {
  onStream: (chunk) => {
    process.stdout.write(chunk);
  }
});

How do I add custom tools?

Use MCP to expose custom tools:

const agent = new ProbeAgent({
  enableMcp: true,
  mcpConfig: {
    mcpServers: {
      'my-tools': {
        command: 'node',
        args: ['my-mcp-server.js'],
        transport: 'stdio'
      }
    }
  }
});

Troubleshooting

"No API key found" error

Set at least one API key:

export ANTHROPIC_API_KEY=sk-...
# or
export OPENAI_API_KEY=sk-...

Or install Claude Code CLI:

# If claude command is available, it will be used automatically
which claude

"ENOENT" or "File not found" errors

Check that:

The file path is correct
You have read permissions
The file isn't in .gitignore (or use --no-gitignore)

MCP server not connecting

Check the MCP config path
Verify the command exists
Enable debug logging: DEBUG_MCP=1

Memory issues with large codebases

Use --max-results to limit results
Use --session for pagination
Increase Node.js memory: NODE_OPTIONS=--max-old-space-size=8192

Troubleshooting - Detailed solutions
Glossary - Technical terms
Environment Variables - Configuration