Probe Documentation

repository·main·Indexed 20 days ago

An AI-friendly, fully local, semantic code search tool for enterprise-scale codebases. Probe provides AST-aware structural search and a code and markdown context engine to help AI tools and developers reason about code. It features a Node.js SDK, a CLI for AI workflows, a web interface, and MCP integration for AI code editors. The ecosystem includes @probelabs/probe-chat for interactive AI assistance and a Chat Implementation Tool supporting backends like aider and claude-code.

Tokens: 258.6K
Snippets: 774
Records: 1K
Agent score: 67%

What's inside Probe

What is Probe?
main
Probe is a local, AI-friendly semantic code search tool. It is designed to provide high-fidelity context to AI coding assistants by combining the speed of ripgrep with the structural understanding of tree-sitter (AST parsing). Unlike traditional embedding-based search, Probe runs entirely locally and extracts complete code blocks (functions, classes, structs) rather than arbitrary text chunks, ensuring AI models receive complete semantic context.
https://github.com/probelabs/probe/blob/main/docs/features.md
Overview of @probelabs/probe features
main
The @probelabs/probe package is a Node.js wrapper for the probe code search tool. It provides several capabilities for interacting with codebases:
- Search Code: Pattern searching using Elasticsearch-like query syntax.
- Query Code: Finding specific code structures using tree-sitter patterns.
- Extract Code: Retrieving code blocks based on file paths and line numbers.
- List Symbols: Generating a file's table of contents (functions, classes, constants) including line numbers and nesting.
- Edit Code: AI-powered editing including fuzzy text replacement, AST-aware symbol replacement/insertion (supporting 16 languages), and line-targeted editing with optional hash-based integrity verification.
- AI Tools Integration: Ready-to-use tools for Vercel AI SDK, LangChain, and other AI frameworks.
- MCP Server: A built-in Model Context Protocol (MCP) server for seamless AI assistant integration.
- Context Window Compaction: Automatic compression of conversation history to manage token limits.
https://github.com/probelabs/probe/blob/main/npm/README.md
Explore Probe's usage modes
main
Probe can be integrated into your workflow through several different interfaces:
- CLI Mode: Direct command-line interface for manual use.
- MCP Server: Integration with AI editors and assistants via the Model Context Protocol.
- AI Chat: An interactive CLI-based AI assistant for codebase questioning.
- Web Interface: Browser-based exploration of your code.
- Node.js SDK: Programmatic access for building custom tools.
https://github.com/probelabs/probe/blob/main/docs/features.md
Use cases for Probe GitHub Actions integration
main
The Probe GitHub Actions integration allows you to bring code-aware AI assistance directly into your development workflow:
- Ticket Answering Assistant: Users can ask questions via comments (e.g., /probe How does X work?) and Probe will analyze the codebase to provide answers.
- Pull Request Reviewer: Invoke Probe (e.g., /probe Review this change) to receive AI-driven feedback on code changes.
- AI Code Implementation: Request automated changes (e.g., /engineer Refactor this function). Note: This requires setting allow_edit: true and providing contents: write permissions in your workflow.
https://github.com/probelabs/probe/blob/main/docs/guides/github-actions.md
Get started with Probe
main
Probe is a developer-first code intelligence tool providing local-first semantic code search, extraction, and agent workflows. Depending on your goal, you can follow these paths:
- Quick Setup: Use Quick Start or Installation to run Probe immediately.
- CLI Usage: Use the Probe CLI for direct command-line operations like semantic search, block extraction, symbol lookup, and AST-grep structural queries.
- LSP & Indexing: Leverage Language Server Protocol (LSP) features for enhanced intelligence or manage code indexing using probe lsp index* commands.
- Agent & SDK: Integrate Probe into AI workflows via the Probe Agent, use the Node.js SDK for programmatic access, or connect via Model Context Protocol (MCP).
https://github.com/probelabs/probe/blob/main/docs/index.md
Available Implementation Backends
main
Probe Chat supports multiple backends for AI-powered code implementation:
Aider Backend (Default)
- Description: AI pair programming in your terminal.
- Strengths: Battle-tested, supports many models, git integration.
- Requirements: Python 3.8+, pip install aider-chat.
- API Keys: Requires ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY.
Claude Code Backend
- Description: Advanced AI coding assistant powered by Claude.
- Strengths: Latest Claude models, sophisticated code understanding, MCP tools.
- Requirements: Node.js 18+, npm install -g @anthropic-ai/claude-code.
- API Keys: Requires ANTHROPIC_API_KEY.
- Cross-Platform: Supports Windows, macOS, Linux, and WSL.
https://github.com/probelabs/probe/blob/main/examples/chat/implement/README.md
Explore Probe usage patterns and workflows
main
Probe supports several distinct integration patterns depending on your needs:
- Web Interface: Use the web UI to interact with code as a source of truth for product functionality.
- AI Code Editors & MCP: Integrate Probe with AI-powered editors using the Model Context Protocol (MCP).
- CLI for AI Workflows: Use the command line interface for automated or manual AI-assisted workflows.
- Developers & SDK: Build custom tools and integrations using the Node.js SDK.
https://github.com/probelabs/probe/blob/main/docs/use-cases/README.md
What is LLM Script and how does it work?
main
LLM Script is Probe's programmable orchestration engine for running complex, multi-step code analysis tasks. Instead of relying on unpredictable multi-turn AI conversations, it allows you to write (or have an AI write) deterministic JavaScript programs that orchestrate search, extraction, and LLM calls in a sandboxed environment.
Key Characteristics:
- Predictable & Reproducible: Acts like "stored procedures for code intelligence."
- Sandboxed Execution: Runs in a SandboxJS environment with a default 2-minute timeout.
- Safety: Uses AST-level whitelisting to prevent unsafe constructs (e.g., eval, require, import, class, new).
- Automatic Transformation: Automatically injects await before async tool calls and adds loop guards.
- Self-healing: If a script fails, the AI automatically attempts to fix it (up to 2 retries).
Usage Modes:
1. Through Prompting: Describe your goal in natural language, and the AI generates and executes the script.
2. User-Provided Scripts: Write scripts directly for repeatable analysis, CI pipelines, or precise control.
```
// Example: Find all API endpoints and count by HTTP method
const results = search("API endpoint route handler")
const chunks = chunk(results)

const classified = map(chunks, c => LLM(
  "Extract endpoints as JSON: [{method, path}]. ONLY JSON.", c
))

var endpoints = []
for (const batch of classified) {
  const parsed = parseJSON(batch)
  if (parsed) { for (const ep of parsed) { endpoints.push(ep) } }
}

const byMethod = groupBy(endpoints, "method")
var table = "| Method | Count |\n|--------|-------|\n"
for (const method of Object.keys(byMethod)) {
  table = table + "| " + method + " | " + byMethod[method].length + " |\n"
}

return table
```
https://github.com/probelabs/probe/blob/main/docs/llm-script.md
Overview of the ProbeAgent Hooks System
main
The ProbeAgent hooks system provides an event-driven callback mechanism for monitoring and customizing agent behavior. It allows developers to implement logging, analytics, debugging, and custom integrations by subscribing to specific events throughout the agent's lifecycle, message processing, tool execution, and AI streaming phases.
Callbacks can be synchronous or asynchronous and execute in parallel. The system features error isolation, meaning a failure in one hook callback will not prevent other hooks from running or crash the agent.
```
const agent = new ProbeAgent({
  path: './src',
  hooks: {
    'tool:start': (data) => console.log(`Tool: ${data.name}`),
    'tool:end': (data) => console.log(`Done: ${data.name} (${data.duration}ms)`),
    'message:user': (data) => logMessage('user', data.message)
  }
});
```
https://github.com/probelabs/probe/blob/main/docs/probe-agent/sdk/hooks.md
What is the ACP Protocol and when to use it
main
The Agent Communication Protocol (ACP) is an advanced protocol for agent-to-agent and agent-to-tool communication. It is built on JSON-RPC 2.0 and provides features that the Model Context Protocol (MCP) does not, such as session management, conversation history, tool lifecycle tracking, and streaming notifications.
When to use ACP vs MCP
Feature MCP ACP
Tool exposure ✓ ✓
Session management - ✓
Conversation history - ✓
Tool lifecycle tracking - ✓
Streaming notifications - ✓
Multi-session support - ✓
Editor integration ✓ -
Use MCP when:
- Integrating with AI editors (e.g., Cursor, Claude Code).
- Simple tool exposure is sufficient without needing session state.
Use ACP when:
- Building multi-agent systems.
- You need conversation persistence and session isolation.
- You require detailed tool execution tracking and streaming.
- You are building custom AI platforms.
https://github.com/probelabs/probe/blob/main/docs/probe-agent/protocols/acp.md
Understand Tool Syntax: XML vs JSON
main
Probe uses a hybrid syntax for tool calls. It is critical to use the correct format based on whether the tool is native or an MCP tool.
Native Tools (XML Parameters)
Native Probe tools use standard XML tags for parameters. Example:
```
<search>
  <query>authentication</query>
  <path>./src</path>
</search>
```
MCP Tools (JSON Parameters)
MCP tools require parameters to be wrapped in a <params> tag containing a JSON string. Example:
```
<probe_search_code>
<params>
{
  "query": "authentication",
  "path": "/absolute/path/to/project"
}
</params>
</probe_search_code>
```
https://github.com/probelabs/probe/blob/main/examples/chat/MCP_INTEGRATION.md
Understand Probe configuration merging and priority
main
Probe uses a hierarchical configuration system where settings are merged from multiple sources. When a setting is defined in multiple places, the source with the highest priority wins.
Priority Order (Highest to Lowest):
1. Environment Variables: (e.g., PROBE_TIMEOUT=120)
2. Local Configuration: ./.probe/settings.local.json (not committed to git)
3. Project Configuration: ./.probe/settings.json (committed to git)
4. Global Configuration: ~/.probe/settings.json (applies to all projects)
Best Practices:
- Use Global settings for personal preferences across all projects.
- Use Project settings for team-wide configuration to be committed to version control.
- Use Local settings for temporary overrides or personal preferences specific to one project.
- Use Environment variables for CI/CD pipelines or temporary overrides.
https://github.com/probelabs/probe/blob/main/docs/configuration.md

Feature	MCP	ACP
Tool exposure	✓	✓
Session management	-	✓
Conversation history	-	✓
Tool lifecycle tracking	-	✓
Streaming notifications	-	✓
Multi-session support	-	✓
Editor integration	✓	-

Probe Documentation

What's inside Probe

Aider Backend (Default)

Claude Code Backend

When to use ACP vs MCP

Native Tools (XML Parameters)

MCP Tools (JSON Parameters)