Content
<p align="center">
<img src="logo.png?2" alt="Probe Logo" width="400">
</p>
# Probe
**We read code 10x more than we write it.** Probe is a code and markdown context engine, with a built-in agent, made to work on enterprise-scale codebases.
Today's AI coding tools use a caveman approach: grep some files, read random lines, hope for the best. It works on toy projects. It falls apart on real codebases.
**Probe is a context engine built for reading and reasoning.** It treats your code as code—not text. AST parsing understands structure. Semantic search finds what matters. You get complete, meaningful context in a single call.
**The Probe Agent** is purpose-built for code understanding. It knows how to wield the Probe engine expertly—searching, extracting, and reasoning across your entire codebase. Perfect for spec-driven development, code reviews, onboarding, and any task where understanding comes before writing.
**One Probe call captures what takes other tools 10+ agentic loops**—deeper, cleaner, and far less noise.
---
## Table of Contents
- [Why Probe?](#why-probe)
- [Quick Start](#quick-start)
- [Features](#features)
- [Usage Modes](#usage-modes)
- [Probe Agent (MCP)](#probe-agent-mcp)
- [Raw MCP Tools](#raw-mcp-tools)
- [CLI Agent](#cli-agent)
- [Direct CLI Commands](#direct-cli-commands)
- [Node.js SDK](#nodejs-sdk)
- [LLM Script](#llm-script)
- [Installation](#installation)
- [Supported Languages](#supported-languages)
- [Documentation](#documentation)
- [Environment Variables](#environment-variables)
- [Contributing](#contributing)
- [License](#license)
---
## Why Probe?
Most code search tools fall into two camps: **text-based** (grep, ripgrep) or **embedding-based** (vector search requiring indexing and an embedding model). Probe takes a third path: **AST-aware structural search with zero setup**.
| | grep/ripgrep | Embedding tools (grepai, Octocode) | Probe |
|---|---|---|---|
| **Setup time** | None | Minutes (indexing + embedding service) | None |
| **Code understanding** | Text only | Text chunks (can split mid-function) | AST-aware (returns complete functions/classes) |
| **Search method** | Regex | Vector similarity | Elasticsearch-style boolean queries + BM25 |
| **Result quality** | Line fragments | ~512-char chunks | Complete semantic code blocks |
| **Ranking** | None (line order) | Cosine similarity | BM25/TF-IDF/Hybrid with SIMD acceleration |
| **External dependencies** | None | Embedding API (Ollama/OpenAI) | None |
| **Token awareness** | No | Partial | Yes (`--max-tokens`, session dedup) |
| **Works offline** | Yes | Only with local model | Always |
| **AI agent integration** | None | MCP server | Full agent loop + MCP + Vercel AI SDK |
### The key insight: AI agents don't need embedding search
Embedding-based tools solve vocabulary mismatch -- finding "authentication" when the code says `verify_credentials`. But when an AI agent is the consumer, **the LLM already handles this**:
```
User: "find the authentication logic"
-> LLM generates: probe search "verify_credentials OR authenticate OR login OR auth_handler"
-> Probe returns complete AST blocks in milliseconds
```
The LLM translates intent into precise boolean queries. Probe gives it a powerful query language (`AND`, `OR`, `+required`, `-excluded`, `"exact phrases"`, `ext:rs`, `lang:python`) purpose-built for this. Combined with session dedup, the agent can run 3-4 rapid searches and cover more ground than a single embedding query -- faster, deterministic, and with zero setup cost.
---
## Quick Start
### Option 1: Probe Agent via MCP (Recommended)
Our built-in agent natively integrates with Claude Code, using its authentication—no extra API keys needed.
Add to `~/.claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"probe": {
"command": "npx",
"args": ["-y", "@probelabs/probe@latest", "agent", "--mcp"]
}
}
}
```
The Probe Agent is purpose-built to read and reason about code. It piggybacks on Claude Code's auth (or Codex auth), or works with any model via your own API key (e.g., `GOOGLE_API_KEY`).
### Option 2: Raw Probe Tools via MCP
If you prefer direct access to search/query/extract tools without the agent layer:
```json
{
"mcpServers": {
"probe": {
"command": "npx",
"args": ["-y", "@probelabs/probe@latest", "mcp"]
}
}
}
```
### Option 3: Direct CLI (No MCP)
Use Probe directly from your terminal—no AI editor required:
```bash
# Semantic search with Elasticsearch syntax
npx -y @probelabs/probe search "authentication AND login" ./src
# Extract code block at line 42
npx -y @probelabs/probe extract src/main.rs:42
# AST pattern matching
npx -y @probelabs/probe query "fn $NAME($$$) -> Result<$RET>" --language rust
```
### Option 4: CLI Agent
Ask questions about any codebase directly from your terminal:
```bash
# One-shot question (works with any LLM provider)
npx -y @probelabs/probe@latest agent "How is authentication implemented?"
# With code editing capabilities
npx -y @probelabs/probe@latest agent "Refactor the login function" --allow-edit
```
---
## Features
- **Code-Aware**: Tree-sitter AST parsing understands your code's actual structure
- **Semantic Search**: Elasticsearch-style queries (`AND`, `OR`, `NOT`, phrases, filters)
- **Complete Context**: Returns entire functions, classes, or structs -- not text chunks that break mid-function
- **Zero Indexing**: Instant results on any codebase. No embedding models, no vector databases, no setup
- **Deterministic**: Same query always returns the same results. No model variance, no stale indexes
- **Fully Local**: Your code never leaves your machine. No API calls for search
- **Blazing Fast**: SIMD-accelerated pattern matching + ripgrep scanning + rayon parallelism
- **Smart Ranking**: BM25, TF-IDF, and hybrid algorithms with optional BERT reranking
- **Token-Aware**: `--max-tokens` budget, session-based dedup to avoid repeating context
- **Built-in Agent**: Multi-provider (Anthropic, OpenAI, Google, Bedrock) with retry, fallback, and context compaction
- **Multi-Language**: Rust, Python, JavaScript, TypeScript, Go, C/C++, Java, Ruby, PHP, Swift, Solidity, Crystal, C#, Bash, QML, and more
---
## Usage Modes
### Probe Agent (MCP)
The recommended way to use Probe with AI editors. The Probe Agent is a specialized coding assistant that reasons about your code—not just pattern matches.
```json
{
"mcpServers": {
"probe": {
"command": "npx",
"args": ["-y", "@probelabs/probe@latest", "agent", "--mcp"]
}
}
}
```
**Why use the agent?**
- Purpose-built to understand and reason about code
- Piggybacks on Claude Code / Codex authentication (or use your own API key)
- Smarter multi-step reasoning for complex questions
- Built-in code editing, task delegation, and more
**Agent options:**
| Option | Description |
|--------|-------------|
| `--path <dir>` | Search directory (default: current) |
| `--provider <name>` | AI provider: `anthropic`, `openai`, `google` |
| `--model <name>` | Override model name |
| `--prompt <type>` | Persona: `code-explorer`, `engineer`, `code-review`, `architect` |
| `--allow-edit` | Enable code modification |
| `--enable-delegate` | Enable task delegation to subagents |
| `--enable-bash` | Enable bash command execution |
| `--max-iterations <n>` | Max tool iterations (default: 30) |
---
### Raw MCP Tools
Direct access to Probe's search, query, and extract tools—without the agent layer. Use this when you want your AI editor to call Probe tools directly.
```json
{
"mcpServers": {
"probe": {
"command": "npx",
"args": ["-y", "@probelabs/probe@latest", "mcp"]
}
}
}
```
**Available tools:**
- `search` - Semantic code search with Elasticsearch-style queries
- `query` - AST-based structural pattern matching
- `extract` - Extract code blocks by line number or symbol name
- `symbols` - List all symbols in a file (functions, classes, constants) with line numbers
---
### CLI Agent
Run the Probe Agent directly from your terminal:
```bash
# One-shot question
npx -y @probelabs/probe@latest agent "How does the ranking algorithm work?"
# Specify search path
npx -y @probelabs/probe@latest agent "Find API endpoints" --path ./src
# Enable code editing
npx -y @probelabs/probe@latest agent "Add error handling to login()" --allow-edit
# Use custom persona
npx -y @probelabs/probe@latest agent "Review this code" --prompt code-review
```
---
### Direct CLI Commands
For scripting and direct code analysis.
#### Search Command
```bash
probe search <PATTERN> [PATH] [OPTIONS]
```
**Examples:**
```bash
# Basic search
probe search "authentication" ./src
# Boolean operators (Elasticsearch syntax)
probe search "error AND handling" ./
probe search "login OR auth" ./src
probe search "database NOT sqlite" ./
# Search hints (file filters)
probe search "function AND ext:rs" ./ # Only .rs files
probe search "class AND file:src/**/*.py" ./ # Python files in src/
probe search "error AND dir:tests" ./ # Files in tests/
# Limit results for AI context windows
probe search "API" ./ --max-tokens 10000
```
**Key options:**
| Option | Description |
|--------|-------------|
| `--max-tokens <n>` | Limit total tokens returned |
| `--max-results <n>` | Limit number of results |
| `--reranker <algo>` | Ranking: `bm25`, `tfidf`, `hybrid`, `hybrid2` |
| `--allow-tests` | Include test files |
| `--format <fmt>` | Output: `markdown`, `json`, `xml` |
#### Extract Command
```bash
probe extract <FILES> [OPTIONS]
```
**Examples:**
```bash
# Extract function at line 42
probe extract src/main.rs:42
# Extract by symbol name
probe extract src/main.rs#authenticate
# Extract line range
probe extract src/main.rs:10-50
# From compiler output
go test | probe extract
```
#### Symbols Command
```bash
probe symbols <FILES> [OPTIONS]
```
**Examples:**
```bash
# List symbols in a file
probe symbols src/main.rs
# JSON output for programmatic use
probe symbols src/main.rs --format json
# Multiple files
probe symbols src/main.rs src/lib.rs
```
#### Query Command (AST Patterns)
```bash
probe query <PATTERN> [PATH] [OPTIONS]
```
**Examples:**
```bash
# Find all async functions in Rust
probe query "async fn $NAME($$$)" --language rust
# Find React components
probe query "function $NAME($$$) { return <$$$> }" --language javascript
# Find Python classes with specific method
probe query "class $CLASS: def __init__($$$)" --language python
```
---
### Node.js SDK
Use Probe programmatically in your applications.
```javascript
import { ProbeAgent } from '@probelabs/probe/agent';
// Create agent
const agent = new ProbeAgent({
path: './src',
provider: 'anthropic'
});
await agent.initialize();
// Ask questions
const response = await agent.answer('How does authentication work?');
console.log(response);
// Get token usage
console.log(agent.getTokenUsage());
```
**Direct functions:**
```javascript
import { search, extract, query, symbols } from '@probelabs/probe';
// Semantic search
const results = await search({
query: 'authentication',
path: './src',
maxTokens: 10000
});
// Extract code
const code = await extract({
files: ['src/auth.ts:42'],
format: 'markdown'
});
// List symbols in a file
const fileSymbols = await symbols({
files: ['src/auth.ts']
});
// AST pattern query
const matches = await query({
pattern: 'async function $NAME($$$)',
path: './src',
language: 'typescript'
});
```
**Vercel AI SDK integration:**
```javascript
import { tools } from '@probelabs/probe';
const { searchTool, queryTool, extractTool } = tools;
// Use with Vercel AI SDK
const result = await generateText({
model: anthropic('claude-sonnet-4-6'),
tools: {
search: searchTool({ defaultPath: './src' }),
query: queryTool({ defaultPath: './src' }),
extract: extractTool({ defaultPath: './src' })
},
prompt: 'Find authentication code'
});
```
---
## LLM Script
Probe Agent can use the `execute_plan` tool to run deterministic, multi-step code analysis tasks. LLM Script is a sandboxed JavaScript DSL where the AI generates executable plans combining search, extraction, and LLM reasoning in a single pipeline.
```javascript
// AI-generated LLM Script example (await is auto-injected, don't write it)
const files = search("authentication login")
const chunks = chunk(files)
const analysis = map(chunks, c => LLM("Summarize auth patterns", c))
return analysis.join("\n")
```
**Key features:**
- **Agent integration** - Probe Agent calls `execute_plan` tool to run scripts
- **Auto-await** - Async calls are automatically awaited (don't write `await`)
- **All tools available** - `search()`, `query()`, `extract()`, `LLM()`, `map()`, `chunk()`, plus any MCP tools
- **Sandboxed execution** - Safe, isolated JavaScript environment with timeout protection
See the full [LLM Script Documentation](./docs/llm-script.md) for syntax and examples.
---
## Installation
### NPM (Recommended)
```bash
npm install -g @probelabs/probe
```
### curl (macOS/Linux)
```bash
curl -fsSL https://raw.githubusercontent.com/probelabs/probe/main/install.sh | bash
```
### PowerShell (Windows)
```powershell
iwr -useb https://raw.githubusercontent.com/probelabs/probe/main/install.ps1 | iex
```
### From Source
```bash
git clone https://github.com/probelabs/probe.git
cd probe
cargo build --release
cargo install --path .
```
---
## Supported Languages
| Language | Extensions |
|----------|------------|
| Rust | `.rs` |
| JavaScript/JSX | `.js`, `.jsx` |
| TypeScript/TSX | `.ts`, `.tsx` |
| Python | `.py` |
| Go | `.go` |
| C/C++ | `.c`, `.h`, `.cpp`, `.cc`, `.hpp` |
| Java | `.java` |
| Ruby | `.rb` |
| PHP | `.php` |
| Swift | `.swift` |
| Solidity | `.sol` |
| Crystal | `.cr` |
| C# | `.cs` |
| Markdown | `.md` |
| HTML | `.html`, `.htm` |
| YAML | `.yaml`, `.yml` |
| Bash | `.sh`, `.bash` |
| QML | `.qml` |
---
## Documentation
Full documentation available at [probelabs.com/probe](https://probelabs.com/probe) or browse locally in [`docs/`](./docs/).
### Getting Started
- [Quick Start](./docs/quick-start.md) - Get up and running in 5 minutes
- [Installation](./docs/installation.md) - NPM, curl, Docker, and building from source
- [Features Overview](./docs/features.md) - Core capabilities
### Probe CLI
- [Search Command](./docs/probe-cli/search.md) - Elasticsearch-style semantic search
- [Extract Command](./docs/probe-cli/extract.md) - Extract code blocks with full AST context
- [Symbols Command](./docs/probe-cli/symbols.md) - List all symbols in files with line numbers
- [Query Command](./docs/probe-cli/query.md) - AST-based structural pattern matching
- [CLI Reference](./docs/probe-cli/cli-reference.md) - Complete command-line reference
### LSP & Indexing
- [LSP Features](./docs/lsp-features.md) - What `--lsp` adds for semantic code intelligence
- [LSP Quick Reference](./docs/lsp-quick-reference.md) - Day-to-day LSP command cheatsheet
- [Indexing Overview](./docs/indexing-overview.md) - Project indexing concepts and workflow
- [Indexing CLI Reference](./docs/indexing-cli-reference.md) - `probe lsp index*` command reference
LSP capabilities include call hierarchy enrichment (`extract --lsp`), direct symbol operations (`probe lsp call definition|references|hover|...`), daemon diagnostics (`probe lsp logs --analyze`), and workspace indexing (`probe lsp index`, `probe lsp index-status`).
### Probe Agent
- [Agent Overview](./docs/probe-agent/overview.md) - What is Probe Agent and when to use it
- [API Reference](./docs/probe-agent/sdk/api-reference.md) - ProbeAgent class documentation
- [Node.js SDK](./docs/probe-agent/sdk/nodejs-sdk.md) - Full Node.js SDK reference
- [MCP Integration](./docs/probe-agent/protocols/mcp-integration.md) - Editor integration guide
- [LLM Script](./docs/llm-script.md) - Programmable orchestration DSL
### Guides & Reference
- [Query Patterns](./docs/guides/query-patterns.md) - Effective search strategies
- [How Probe Compares](./docs/reference/comparison.md) - vs embedding search, knowledge graphs, LSP tools
- [Architecture](./docs/reference/architecture.md) - System design and internals
- [Environment Variables](./docs/reference/environment-variables.md) - All configuration options
- [FAQ](./docs/reference/faq.md) - Frequently asked questions
---
## Environment Variables
```bash
# AI Provider Keys
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=...
# Provider Selection
FORCE_PROVIDER=anthropic
MODEL_NAME=claude-sonnet-4-6
# Custom Endpoints
ANTHROPIC_API_URL=https://your-proxy.com
OPENAI_API_URL=https://your-proxy.com
# Debug
DEBUG=1
```
---
## Contributing
We welcome contributions! See our [Contributing Guide](https://github.com/probelabs/probe/blob/main/CONTRIBUTING.md).
For questions or support:
- [GitHub Issues](https://github.com/probelabs/probe/issues)
- [Discord Community](https://discord.gg/hBN4UsTZ)
---
## License
---
For questions or contributions, please open an issue on [GitHub](https://github.com/probelabs/probe/issues) or join our [Discord community](https://discord.gg/hBN4UsTZ) for discussions and support. Happy coding—and searching!
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available