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.
---
## Why Probe?
| Traditional Approach | Probe |
|---------------------|-------|
| Grep + read random lines | Semantic search with Elasticsearch syntax |
| Treats code as text | Understands code structure via tree-sitter AST |
| Returns fragments | Returns complete functions, classes, structs |
| Requires indexing | Zero setup, instant results |
| 10+ loops to gather context | One call, complete picture |
| Struggles at scale | Built for million-line codebases |
---
## 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
```
---
## Table of Contents
- [Features](#features)
- [Usage Modes](#usage-modes)
- [Probe Agent (MCP)](#probe-agent-mcp)
- [Raw MCP Tools](#raw-mcp-tools)
- [CLI Agent](#cli-agent)
- [Direct CLI](#direct-cli-commands)
- [Node.js SDK](#nodejs-sdk)
- [Installation](#installation)
- [Supported Languages](#supported-languages)
- [Documentation](#documentation)
---
## 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 fragments
- **One Call, Full Context**: Captures what takes other tools 10+ loops to gather
- **Zero Indexing**: Instant results on any codebase, no setup required
- **Fully Local**: Your code never leaves your machine
- **Blazing Fast**: Ripgrep-powered scanning handles million-line codebases
- **Smart Ranking**: BM25, TF-IDF, and hybrid algorithms surface what matters
- **Multi-Language**: Rust, Python, JavaScript, TypeScript, Go, C/C++, Java, 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
---
### 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
```
#### 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 } 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'
});
// 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-5-20250929'),
tools: {
search: searchTool({ defaultPath: './src' }),
query: queryTool({ defaultPath: './src' }),
extract: extractTool({ defaultPath: './src' })
},
prompt: 'Find authentication code'
});
```
---
## 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` |
| C# | `.cs` |
| Markdown | `.md` |
---
## Documentation
### Getting Started
- [Quick Start](https://probelabs.com/probe/quick-start) - Get up and running in 5 minutes
- [Installation](https://probelabs.com/probe/installation) - NPM, curl, Docker, and building from source
- [Features Overview](https://probelabs.com/probe/features) - Core capabilities
### Probe CLI
- [Search Command](https://probelabs.com/probe/probe-cli/search) - Elasticsearch-style semantic search
- [Extract Command](https://probelabs.com/probe/probe-cli/extract) - Extract code blocks with full AST context
- [Query Command](https://probelabs.com/probe/probe-cli/query) - AST-based structural pattern matching
- [CLI Reference](https://probelabs.com/probe/probe-cli/cli-reference) - Complete command-line reference
### Probe Agent
- [Agent Overview](https://probelabs.com/probe/probe-agent/overview) - What is Probe Agent and when to use it
- [API Reference](https://probelabs.com/probe/probe-agent/sdk/api-reference) - ProbeAgent class documentation
- [Node.js SDK](https://probelabs.com/probe/probe-agent/sdk/nodejs-sdk) - Full Node.js SDK reference
- [MCP Integration](https://probelabs.com/probe/probe-agent/protocols/mcp-integration) - Editor integration guide
### Guides & Reference
- [Query Patterns](https://probelabs.com/probe/guides/query-patterns) - Effective search strategies
- [Architecture](https://probelabs.com/probe/reference/architecture) - System design and internals
- [Environment Variables](https://probelabs.com/probe/reference/environment-variables) - All configuration options
- [FAQ](https://probelabs.com/probe/reference/faq) - 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-5-20250929
# 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
Apache 2.0 - See [LICENSE](LICENSE) for details.
