@sparktory/context-search

Zero-config local code search for large repos.

context-search is a developer-first search engine for source code. It ships as:

• a CLI for indexing and searching local repos
• a library API for tools and apps
• a low-latency local daemon
• an MCP server for Claude Code, Cursor, and similar tools

It uses hybrid BM25 + vector ranking, AST-aware chunking for supported languages, and a zero-key local path by default.

Why this exists

rg is excellent for exact text.

context-search is for the next question:

• "Where is playback state updated?"
• "What code decides who wins a battle?"
• "Find the symbol that owns retry logic"
• "Show me the main implementations of task orchestration"

It is designed for repos that are large enough that exact-string search stops being enough, but you still want a local tool you can trust.

Install

npm install -D @sparktory/context-search

Then run:

npx context-search --help

Quick Start

npx context-search index
npx context-search search "playback isPlaying currentTime"
npx context-search symbol SceneEditor
npx context-search doctor

Commands

context-search index [path]              Index workspace files
context-search search "query"            Search the index
context-search symbol SymbolName         Find definitions by symbol name
context-search stats                     Show index statistics
context-search doctor                    Check freshness and missing-file drift
context-search workspace init            Create workspace metadata for team features
context-search workspace                 Show workspace metadata
context-search save-search Name "query"  Save a named search
context-search saved-searches            List saved searches
context-search run-saved-search Name     Run a saved search
context-search delete-saved-search Name  Delete a saved search
context-search history                   Show recent search history
context-search analytics                 Show search analytics
context-search daemon                    Start a local HTTP daemon
context-search connect --start           Start or discover a daemon
context-search benchmark                 Run the built-in benchmark set

Useful flags:

--local            Force local Jina embeddings
--tfidf            Force TF-IDF embeddings
--voyage           Force Voyage embeddings (requires VOYAGE_API_KEY)
--bm25-only        Disable vector search
--fusion=dbsf      Use DBSF fusion (default)
--fusion=rrf       Use reciprocal rank fusion
--no-mmr           Disable MMR reranking
--regex            Force regex chunking instead of AST chunking
--top=10           Number of search results
--limit=10         Limit history and analytics output
--days=30          Filter history and analytics by time window
--tags=a,b         Attach tags to a saved search
--actor=name       Attach an actor name to history and analytics records
--json             Emit machine-readable JSON
--daemon           Route search through a running daemon
--daemon-url=URL   Route through a specific daemon instance
--daemon-token=X   Bearer token for daemon auth

Embeddings

Provider resolution for auto mode:

1. VOYAGE_API_KEY in env -> Voyage
2. local @huggingface/transformers runtime available -> Jina local embeddings
3. otherwise -> TF-IDF

That means the package works in a no-key setup out of the box. If local Jina is unavailable, it degrades to TF-IDF instead of failing the entire workflow.

MCP Server

Start the MCP server:

npx context-search-mcp

Available MCP tools:

• index_codebase
• search_code
• find_symbol
• doctor_index
• index_stats

Example .mcp.json:

{
  "mcpServers": {
    "context-search": {
      "command": "npx",
      "args": ["context-search-mcp"],
      "env": {
        "CONTEXT_SEARCH_AUDIT_LOG": "1"
      }
    }
  }
}

Team Foundations

The package now includes local-first team primitives that can be promoted into a hosted offering later:

• workspace metadata via context-search workspace init
• daemon bearer auth via CONTEXT_SEARCH_DAEMON_TOKEN
• saved searches
• search history
• search analytics

Those features live in .context-search/ in the repo root when enabled.

Daemon Mode

Use daemon mode when you want lower-latency repeated searches:

npx context-search connect --start
npx context-search search "battle winner scoring" --daemon

The daemon exposes local endpoints for /health, /search, /symbol, /stats, and /doctor.

Additional team-oriented endpoints:

• /workspace
• /workspace/init
• /saved-searches
• /saved-searches/run
• /history
• /analytics

Programmatic API

import { buildIndex, search, startDaemon } from '@sparktory/context-search';

await buildIndex({ rootPath: process.cwd() });

const result = await search('.context-index.json', '.context-embeddings.ndjson', {
  query: 'where is playback state updated',
  topK: 5,
  mode: 'auto',
});

console.log(result.results[0]);

const server = await startDaemon({
  indexPath: '.context-index.json',
  embeddingsPath: '.context-embeddings.ndjson',
});

server.close();

Ignore Rules

Create a .context-searchignore file in the repo root to exclude custom paths:

# ignore generated content
coverage
android
ios
dist

Rules are substring-based and are evaluated relative to the indexed repo root.

If you want workspace metadata, saved searches, and history to stay local-only, add .context-search/ to your repo .gitignore.

Environment Variables

• VOYAGE_API_KEY: enables Voyage embeddings
• CONTEXT_SEARCH_DAEMON_URL: routes CLI search commands to a daemon
• CONTEXT_SEARCH_DAEMON_TOKEN: bearer token for daemon auth
• CONTEXT_SEARCH_AUDIT_LOG: if set, writes NDJSON search audit events. Use 1 to write .context-search-audit.ndjson in the current repo.
• CONTEXT_SEARCH_HISTORY=1: forces history capture into .context-search/history.ndjson even without a workspace config
• CONTEXT_SEARCH_ACTOR: default actor name for search history and analytics
• CONTEXT_SEARCH_DEBUG_CLI=1: prints daemon/bootstrap debug output

Commercial Packaging

The package is open and usable today as the free tier.

Launch packaging:

| Tier | Audience | What is included | | --- | --- | --- | | Free OSS | Solo developers | Local CLI, library API, daemon, MCP server, BM25 + vector search, repo-local indexing | | Team | Small engineering teams | Planned: shared indexes, repo sync, hosted MCP/search API, saved searches, workspace auth, analytics, support | | Enterprise | Larger orgs | Planned: on-prem/VPC deployment, SSO, SCIM, audit export, retention controls, SLA |

Commercial docs:

• docs/TIERS.md - pricing and feature split
• docs/COMPETITIVE_RESEARCH_2026-03-06.md - official pricing anchors and market takeaways
• docs/LAUNCH_PLAN_2026-03-06.md - one-week execution plan
• docs/PRICING_PAGE_COPY.md - landing page copy
• docs/OUTREACH_COPY.md - outreach and discovery call copy

If your team wants the paid tier, open a GitHub issue using the Context Search Team Interest template in this repo.

Current Constraints

• indexing is local-first, not a hosted search service
• BM25 exactness is still better than semantic search for some narrow symbol queries
• large repos benefit from daemon mode
• local Jina embeddings may require extra runtime setup depending on platform and install settings
• shared indexes and repo sync are not implemented yet; the current team features are local foundations

Development

pnpm type-check
pnpm test
pnpm build
npm pack --dry-run

License

MIT