Frequently Asked Questions

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."

Is Probe free?

Yes, Probe is open source under the Apache 2.0 license.

What languages does Probe support?

Probe supports 15+ languages including Rust, JavaScript, TypeScript, Python, Go, C, C++, Java, Ruby, PHP, Swift, C#, HTML, Markdown, and YAML. See Supported Languages.

Installation

How do I install Probe?

# 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

FilesExpand file tree

faq.md

Latest commit

History