npm package: @sparktory/context-search
Description: Zero-config local code search for large repos: CLI, library API, daemon, and MCP server
Author: Vyas Sathya
Latest version: 0.3.0

# @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

```bash
npm install -D @sparktory/context-search
```

Then run:

```bash
npx context-search --help
```

## Quick Start

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

## Commands

```bash
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:

```bash
--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:

```bash
npx context-search-mcp
```

Available MCP tools:

- `index_codebase`
- `search_code`
- `find_symbol`
- `doctor_index`
- `index_stats`

Example `.mcp.json`:

```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:

```bash
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

```ts
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:

```txt
# 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`](https://github.com/VyasSathya/Sparktory/blob/main/packages/context-search/docs/TIERS.md) - pricing and feature split
- [`docs/COMPETITIVE_RESEARCH_2026-03-06.md`](https://github.com/VyasSathya/Sparktory/blob/main/packages/context-search/docs/COMPETITIVE_RESEARCH_2026-03-06.md) - official pricing anchors and market takeaways
- [`docs/LAUNCH_PLAN_2026-03-06.md`](https://github.com/VyasSathya/Sparktory/blob/main/packages/context-search/docs/LAUNCH_PLAN_2026-03-06.md) - one-week execution plan
- [`docs/PRICING_PAGE_COPY.md`](https://github.com/VyasSathya/Sparktory/blob/main/packages/context-search/docs/PRICING_PAGE_COPY.md) - landing page copy
- [`docs/OUTREACH_COPY.md`](https://github.com/VyasSathya/Sparktory/blob/main/packages/context-search/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

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

## License

MIT