Scry

Scry is a local-first code intelligence server for your Git repositories. It indexes a project once, keeps the index fresh in a daemon, and exposes semantic search plus grounded question answering through both a human CLI and MCP tools for coding agents.

The core workflow is setup-once/use-anywhere:

1. Install one scry binary.
2. Run scry setup once with provider credentials available.
3. Open any Git repository.
4. Use scry search, scry ask, or the scry.search and scry.ask MCP tools.

Why Scry?

• Local-first project state. Repository registration, file metadata, chunks, vectors, index jobs, and watcher state live in local SQLite storage.
• One binary. The same Rust executable provides the CLI, daemon, provider clients, and MCP stdio server.
• Agent-friendly by default. Global MCP entries for Claude Code, Cursor, and Codex let agents bind to whichever Git repo they were launched in.
• Grounded answers. scry ask answers from cited indexed chunks instead of treating your repository as generic model context.
• Explicit degradation. Provider failures are surfaced as structured, redacted diagnostics so users can tell fatal indexing failures from fallback search quality or ask-only degradation.
• Secret-aware indexing. Scry respects Git ignore rules and has additional defaults for generated files, dependency trees, caches, binaries, and common secret-bearing files.

Status

Scry is early software. It has deterministic integration coverage for the local setup, daemon, indexing, search, ask, MCP, diagnostics, and fallback paths, but provider availability still depends on your credentials, account access, quota, region, and network.

The package is declared as dual-licensed under MIT OR Apache-2.0.

Requirements

• Rust 1.76 or newer.
• A Git repository for project-bound indexing, watching, search, ask, or MCP tool calls.
• Provider credentials:

Capability	Provider	Credential
Embeddings	Gemini	GEMINI_API_KEY
Reranking	ZeroEntropy	ZERO_ENTROPY_API_KEY
Grounded answers	DeepSeek	DEEPSEEK_API_KEY

Scry reads credentials from the process environment, a project-local ignored dotenv file, or the OS keyring. .env.example lists the supported names without example secret values.

Install

From a checkout:

cargo install --path .

For local development without touching your normal Cargo install root:

cargo install --path . --root target/scry-install-smoke --force
target/scry-install-smoke/bin/scry --version

Quick Start

Configure credentials through your shell, ignored dotenv, or keyring, then run:

scry setup --all-agents

For automation:

scry setup --all-agents --non-interactive

Search from any Git repo:

scry search "where are credentials loaded?" --limit 5
scry search "where are credentials loaded?" --json --limit 5

Ask a grounded question:

scry ask "How does setup validate providers?" --limit 5
scry ask "How does setup validate providers?" --json --limit 5

Inspect health:

scry status
scry doctor --json

Install MCP entries after setup, or refresh them after reinstalling Scry:

scry mcp install --all-agents

How It Works

The daemon is the owner of project registration, watcher restoration, indexing jobs, search, rerank, and ask. CLI commands and MCP tools both route through the daemon so humans and agents see the same behavior.

When a command runs inside a Git repository, Scry resolves that repository, registers it on first use, starts or reuses a watcher, and indexes supported files into chunks and embeddings. Search embeds the query, retrieves matching chunks, optionally reranks the candidates, and returns citations. Ask uses the same retrieval path, then sends bounded grounded context to the ask provider.

Provider failure policy:

Capability	Failure behavior
Gemini embeddings	Fatal for fresh indexing and search readiness.
ZeroEntropy reranking	Search can fall back to vector results and reports rerank metadata.
DeepSeek ask	Search can still work, but scry ask reports ask degradation.

Commands

Command	Purpose
scry setup	Configure credentials, provider defaults, daemon state, and optional MCP entries.
scry search <query>	Search the current Git project through the daemon.
scry ask <question>	Answer from grounded context in the current Git project.
scry status	Inspect current worktree and daemon health without mutating state.
scry doctor	Run fuller diagnostics and exit non-zero for unhealthy findings.
scry projects	Register the current Git project and list known projects.
`scry daemon <start	stop
scry mcp install	Install global MCP config for supported agent hosts.
scry config show	Print non-secret effective configuration.

Run scry --help or scry <command> --help for the full CLI surface.

Documentation

• Architecture: daemon, storage, indexing, providers, and MCP runtime.
• Configuration: credentials, provider defaults, local state, ignore behavior, and diagnostics.
• MCP agent setup: Claude Code, Cursor, Codex, trusted cwd behavior, and legacy project-scoped fallback.
• Local development: deterministic tests, package checks, install smoke, and contributor troubleshooting.
• Live provider smokes: opt-in commands and redacted evidence rules for real provider validation.

Development

cargo fmt --check
cargo test --quiet
cargo package --allow-dirty

The deterministic acceptance helper runs the project-level smoke expected before release work:

scripts/final-acceptance.sh

Live provider tests are ignored by default and require explicit opt-in flags. They should not run in the default test suite or default CI path.

Contributing

Issues and pull requests are welcome while the project stabilizes. Please read CONTRIBUTING.md before opening a change, especially the sections on deterministic tests, live-provider evidence, and redaction.

Security

Do not include real provider keys, dotenv contents, prompts, provider response bodies, source text, or secret-bearing local paths in issues or logs. See SECURITY.md for reporting guidance.