{"id":30350294,"url":"https://github.com/probelabs/probe","last_synced_at":"2026-03-11T07:05:40.449Z","repository":{"id":280852619,"uuid":"943383028","full_name":"probelabs/probe","owner":"probelabs","description":"AI-friendly semantic code search engine for large codebases. Combines ripgrep speed with tree-sitter AST parsing. Powers AI coding assistants with precise, context-aware code understanding.","archived":false,"fork":false,"pushed_at":"2026-03-06T12:46:43.000Z","size":20635,"stargazers_count":480,"open_issues_count":11,"forks_count":47,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-03-06T12:48:29.781Z","etag":null,"topics":["ai","ai-coder","ast","cli","code-search","mcp","nodejs-sdk","ripgrep","rust","search-engine","semantic-search","tree-sitter"],"latest_commit_sha":null,"homepage":"https://probelabs.com/probe","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/probelabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-05T16:09:15.000Z","updated_at":"2026-03-06T12:46:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"eb55a581-61bb-403a-a293-ca529690dda7","html_url":"https://github.com/probelabs/probe","commit_stats":null,"previous_names":["buger/probe","probelabs/probe"],"tags_count":358,"template":false,"template_full_name":null,"purl":"pkg:github/probelabs/probe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probelabs%2Fprobe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probelabs%2Fprobe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probelabs%2Fprobe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probelabs%2Fprobe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/probelabs","download_url":"https://codeload.github.com/probelabs/probe/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probelabs%2Fprobe/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30208807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T05:23:27.321Z","status":"ssl_error","status_checked_at":"2026-03-07T05:00:17.256Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-coder","ast","cli","code-search","mcp","nodejs-sdk","ripgrep","rust","search-engine","semantic-search","tree-sitter"],"created_at":"2025-08-18T21:03:30.075Z","updated_at":"2026-03-11T07:05:40.431Z","avatar_url":"https://github.com/probelabs.png","language":"Rust","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.png?2\" alt=\"Probe Logo\" width=\"400\"\u003e\n\u003c/p\u003e\n\n# Probe\n\n**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.\n\nToday'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.\n\n**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.\n\n**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.\n\n**One Probe call captures what takes other tools 10+ agentic loops**—deeper, cleaner, and far less noise.\n\n---\n\n## Table of Contents\n\n- [Why Probe?](#why-probe)\n- [Quick Start](#quick-start)\n- [Features](#features)\n- [Usage Modes](#usage-modes)\n  - [Probe Agent (MCP)](#probe-agent-mcp)\n  - [Raw MCP Tools](#raw-mcp-tools)\n  - [CLI Agent](#cli-agent)\n  - [Direct CLI Commands](#direct-cli-commands)\n  - [Node.js SDK](#nodejs-sdk)\n- [LLM Script](#llm-script)\n- [Installation](#installation)\n- [Supported Languages](#supported-languages)\n- [Documentation](#documentation)\n- [Environment Variables](#environment-variables)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Why Probe?\n\n| Traditional Approach | Probe |\n|---------------------|-------|\n| Grep + read random lines | Semantic search with Elasticsearch syntax |\n| Treats code as text | Understands code structure via tree-sitter AST |\n| Returns fragments | Returns complete functions, classes, structs |\n| Requires indexing | Zero setup, instant results |\n| 10+ loops to gather context | One call, complete picture |\n| Struggles at scale | Built for million-line codebases |\n\n---\n\n## Quick Start\n\n### Option 1: Probe Agent via MCP (Recommended)\n\nOur built-in agent natively integrates with Claude Code, using its authentication—no extra API keys needed.\n\nAdd to `~/.claude/claude_desktop_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"probe\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@probelabs/probe@latest\", \"agent\", \"--mcp\"]\n    }\n  }\n}\n```\n\nThe 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`).\n\n### Option 2: Raw Probe Tools via MCP\n\nIf you prefer direct access to search/query/extract tools without the agent layer:\n\n```json\n{\n  \"mcpServers\": {\n    \"probe\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@probelabs/probe@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n### Option 3: Direct CLI (No MCP)\n\nUse Probe directly from your terminal—no AI editor required:\n\n```bash\n# Semantic search with Elasticsearch syntax\nnpx -y @probelabs/probe search \"authentication AND login\" ./src\n\n# Extract code block at line 42\nnpx -y @probelabs/probe extract src/main.rs:42\n\n# AST pattern matching\nnpx -y @probelabs/probe query \"fn $NAME($$$) -\u003e Result\u003c$RET\u003e\" --language rust\n```\n\n### Option 4: CLI Agent\n\nAsk questions about any codebase directly from your terminal:\n\n```bash\n# One-shot question (works with any LLM provider)\nnpx -y @probelabs/probe@latest agent \"How is authentication implemented?\"\n\n# With code editing capabilities\nnpx -y @probelabs/probe@latest agent \"Refactor the login function\" --allow-edit\n```\n\n---\n\n## Features\n\n- **Code-Aware**: Tree-sitter AST parsing understands your code's actual structure\n- **Semantic Search**: Elasticsearch-style queries (`AND`, `OR`, `NOT`, phrases, filters)\n- **Complete Context**: Returns entire functions, classes, or structs—not fragments\n- **One Call, Full Context**: Captures what takes other tools 10+ loops to gather\n- **Zero Indexing**: Instant results on any codebase, no setup required\n- **Fully Local**: Your code never leaves your machine\n- **Blazing Fast**: Ripgrep-powered scanning handles million-line codebases\n- **Smart Ranking**: BM25, TF-IDF, and hybrid algorithms surface what matters\n- **Multi-Language**: Rust, Python, JavaScript, TypeScript, Go, C/C++, Java, and more\n\n---\n\n## Usage Modes\n\n### Probe Agent (MCP)\n\nThe 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.\n\n```json\n{\n  \"mcpServers\": {\n    \"probe\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@probelabs/probe@latest\", \"agent\", \"--mcp\"]\n    }\n  }\n}\n```\n\n**Why use the agent?**\n- Purpose-built to understand and reason about code\n- Piggybacks on Claude Code / Codex authentication (or use your own API key)\n- Smarter multi-step reasoning for complex questions\n- Built-in code editing, task delegation, and more\n\n**Agent options:**\n\n| Option | Description |\n|--------|-------------|\n| `--path \u003cdir\u003e` | Search directory (default: current) |\n| `--provider \u003cname\u003e` | AI provider: `anthropic`, `openai`, `google` |\n| `--model \u003cname\u003e` | Override model name |\n| `--prompt \u003ctype\u003e` | Persona: `code-explorer`, `engineer`, `code-review`, `architect` |\n| `--allow-edit` | Enable code modification |\n| `--enable-delegate` | Enable task delegation to subagents |\n| `--enable-bash` | Enable bash command execution |\n| `--max-iterations \u003cn\u003e` | Max tool iterations (default: 30) |\n\n---\n\n### Raw MCP Tools\n\nDirect 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.\n\n```json\n{\n  \"mcpServers\": {\n    \"probe\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@probelabs/probe@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\n**Available tools:**\n- `search` - Semantic code search with Elasticsearch-style queries\n- `query` - AST-based structural pattern matching\n- `extract` - Extract code blocks by line number or symbol name\n\n---\n\n### CLI Agent\n\nRun the Probe Agent directly from your terminal:\n\n```bash\n# One-shot question\nnpx -y @probelabs/probe@latest agent \"How does the ranking algorithm work?\"\n\n# Specify search path\nnpx -y @probelabs/probe@latest agent \"Find API endpoints\" --path ./src\n\n# Enable code editing\nnpx -y @probelabs/probe@latest agent \"Add error handling to login()\" --allow-edit\n\n# Use custom persona\nnpx -y @probelabs/probe@latest agent \"Review this code\" --prompt code-review\n```\n\n---\n\n### Direct CLI Commands\n\nFor scripting and direct code analysis.\n\n#### Search Command\n\n```bash\nprobe search \u003cPATTERN\u003e [PATH] [OPTIONS]\n```\n\n**Examples:**\n```bash\n# Basic search\nprobe search \"authentication\" ./src\n\n# Boolean operators (Elasticsearch syntax)\nprobe search \"error AND handling\" ./\nprobe search \"login OR auth\" ./src\nprobe search \"database NOT sqlite\" ./\n\n# Search hints (file filters)\nprobe search \"function AND ext:rs\" ./           # Only .rs files\nprobe search \"class AND file:src/**/*.py\" ./    # Python files in src/\nprobe search \"error AND dir:tests\" ./           # Files in tests/\n\n# Limit results for AI context windows\nprobe search \"API\" ./ --max-tokens 10000\n```\n\n**Key options:**\n\n| Option | Description |\n|--------|-------------|\n| `--max-tokens \u003cn\u003e` | Limit total tokens returned |\n| `--max-results \u003cn\u003e` | Limit number of results |\n| `--reranker \u003calgo\u003e` | Ranking: `bm25`, `tfidf`, `hybrid`, `hybrid2` |\n| `--allow-tests` | Include test files |\n| `--format \u003cfmt\u003e` | Output: `markdown`, `json`, `xml` |\n\n#### Extract Command\n\n```bash\nprobe extract \u003cFILES\u003e [OPTIONS]\n```\n\n**Examples:**\n```bash\n# Extract function at line 42\nprobe extract src/main.rs:42\n\n# Extract by symbol name\nprobe extract src/main.rs#authenticate\n\n# Extract line range\nprobe extract src/main.rs:10-50\n\n# From compiler output\ngo test | probe extract\n```\n\n#### Query Command (AST Patterns)\n\n```bash\nprobe query \u003cPATTERN\u003e [PATH] [OPTIONS]\n```\n\n**Examples:**\n```bash\n# Find all async functions in Rust\nprobe query \"async fn $NAME($$$)\" --language rust\n\n# Find React components\nprobe query \"function $NAME($$$) { return \u003c$$$\u003e }\" --language javascript\n\n# Find Python classes with specific method\nprobe query \"class $CLASS: def __init__($$$)\" --language python\n```\n\n---\n\n### Node.js SDK\n\nUse Probe programmatically in your applications.\n\n```javascript\nimport { ProbeAgent } from '@probelabs/probe/agent';\n\n// Create agent\nconst agent = new ProbeAgent({\n  path: './src',\n  provider: 'anthropic'\n});\n\nawait agent.initialize();\n\n// Ask questions\nconst response = await agent.answer('How does authentication work?');\nconsole.log(response);\n\n// Get token usage\nconsole.log(agent.getTokenUsage());\n```\n\n**Direct functions:**\n\n```javascript\nimport { search, extract, query } from '@probelabs/probe';\n\n// Semantic search\nconst results = await search({\n  query: 'authentication',\n  path: './src',\n  maxTokens: 10000\n});\n\n// Extract code\nconst code = await extract({\n  files: ['src/auth.ts:42'],\n  format: 'markdown'\n});\n\n// AST pattern query\nconst matches = await query({\n  pattern: 'async function $NAME($$$)',\n  path: './src',\n  language: 'typescript'\n});\n```\n\n**Vercel AI SDK integration:**\n\n```javascript\nimport { tools } from '@probelabs/probe';\n\nconst { searchTool, queryTool, extractTool } = tools;\n\n// Use with Vercel AI SDK\nconst result = await generateText({\n  model: anthropic('claude-sonnet-4-6'),\n  tools: {\n    search: searchTool({ defaultPath: './src' }),\n    query: queryTool({ defaultPath: './src' }),\n    extract: extractTool({ defaultPath: './src' })\n  },\n  prompt: 'Find authentication code'\n});\n```\n\n---\n\n## LLM Script\n\nProbe 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.\n\n```javascript\n// AI-generated LLM Script example (await is auto-injected, don't write it)\nconst files = search(\"authentication login\")\nconst chunks = chunk(files)\nconst analysis = map(chunks, c =\u003e LLM(\"Summarize auth patterns\", c))\nreturn analysis.join(\"\\n\")\n```\n\n**Key features:**\n- **Agent integration** - Probe Agent calls `execute_plan` tool to run scripts\n- **Auto-await** - Async calls are automatically awaited (don't write `await`)\n- **All tools available** - `search()`, `query()`, `extract()`, `LLM()`, `map()`, `chunk()`, plus any MCP tools\n- **Sandboxed execution** - Safe, isolated JavaScript environment with timeout protection\n\nSee the full [LLM Script Documentation](./docs/llm-script.md) for syntax and examples.\n\n---\n\n## Installation\n\n### NPM (Recommended)\n\n```bash\nnpm install -g @probelabs/probe\n```\n\n### curl (macOS/Linux)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/probelabs/probe/main/install.sh | bash\n```\n\n### PowerShell (Windows)\n\n```powershell\niwr -useb https://raw.githubusercontent.com/probelabs/probe/main/install.ps1 | iex\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/probelabs/probe.git\ncd probe\ncargo build --release\ncargo install --path .\n```\n\n---\n\n## Supported Languages\n\n| Language | Extensions |\n|----------|------------|\n| Rust | `.rs` |\n| JavaScript/JSX | `.js`, `.jsx` |\n| TypeScript/TSX | `.ts`, `.tsx` |\n| Python | `.py` |\n| Go | `.go` |\n| C/C++ | `.c`, `.h`, `.cpp`, `.cc`, `.hpp` |\n| Java | `.java` |\n| Ruby | `.rb` |\n| PHP | `.php` |\n| Swift | `.swift` |\n| C# | `.cs` |\n| Markdown | `.md` |\n\n---\n\n## Documentation\n\nFull documentation available at [probelabs.com/probe](https://probelabs.com/probe) or browse locally in [`docs/`](./docs/).\n\n### Getting Started\n- [Quick Start](./docs/quick-start.md) - Get up and running in 5 minutes\n- [Installation](./docs/installation.md) - NPM, curl, Docker, and building from source\n- [Features Overview](./docs/features.md) - Core capabilities\n\n### Probe CLI\n- [Search Command](./docs/probe-cli/search.md) - Elasticsearch-style semantic search\n- [Extract Command](./docs/probe-cli/extract.md) - Extract code blocks with full AST context\n- [Query Command](./docs/probe-cli/query.md) - AST-based structural pattern matching\n- [CLI Reference](./docs/probe-cli/cli-reference.md) - Complete command-line reference\n\n### Probe Agent\n- [Agent Overview](./docs/probe-agent/overview.md) - What is Probe Agent and when to use it\n- [API Reference](./docs/probe-agent/sdk/api-reference.md) - ProbeAgent class documentation\n- [Node.js SDK](./docs/probe-agent/sdk/nodejs-sdk.md) - Full Node.js SDK reference\n- [MCP Integration](./docs/probe-agent/protocols/mcp-integration.md) - Editor integration guide\n- [LLM Script](./docs/llm-script.md) - Programmable orchestration DSL\n\n### Guides \u0026 Reference\n- [Query Patterns](./docs/guides/query-patterns.md) - Effective search strategies\n- [Architecture](./docs/reference/architecture.md) - System design and internals\n- [Environment Variables](./docs/reference/environment-variables.md) - All configuration options\n- [FAQ](./docs/reference/faq.md) - Frequently asked questions\n\n---\n\n## Environment Variables\n\n```bash\n# AI Provider Keys\nANTHROPIC_API_KEY=sk-ant-...\nOPENAI_API_KEY=sk-...\nGOOGLE_API_KEY=...\n\n# Provider Selection\nFORCE_PROVIDER=anthropic\nMODEL_NAME=claude-sonnet-4-6\n\n# Custom Endpoints\nANTHROPIC_API_URL=https://your-proxy.com\nOPENAI_API_URL=https://your-proxy.com\n\n# Debug\nDEBUG=1\n```\n\n---\n\n## Contributing\n\nWe welcome contributions! See our [Contributing Guide](https://github.com/probelabs/probe/blob/main/CONTRIBUTING.md).\n\nFor questions or support:\n- [GitHub Issues](https://github.com/probelabs/probe/issues)\n- [Discord Community](https://discord.gg/hBN4UsTZ)\n\n---\n\n## License\n\nApache 2.0 - See [LICENSE](LICENSE) for details.\n","funding_links":[],"categories":["Rust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprobelabs%2Fprobe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprobelabs%2Fprobe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprobelabs%2Fprobe/lists"}