Prism

Semantic change intelligence for coding agents. Prism turns indexed repository structure into task-shaped answers: potential change-impact sites, source context, and a review of an agent-authored diff.

Prism embeds the Grove code graph. It runs locally as one binary, exposes CLI and MCP interfaces, and requires no hosted service or API token.

Why Prism

Text search is excellent for locating a name. It cannot reliably distinguish references from unrelated text, follow an override family, or enumerate types that implicitly satisfy an external interface. Prism combines full-text search with a typed project graph, then exposes the result through operations that match the question an agent is trying to answer.

Need	Operation
Locate a symbol or exact text	prism search
Gather edit-ready source around known anchors	prism query
Read one file or symbol	prism read / prism lookup
Change a method signature	prism change-impact
Plan a rename	prism rename-plan
Evolve an interface	prism missing-implementations
Check an agent-authored diff	prism verify
Enforce component boundaries	prism arch

Structural results report indexed coverage and known stale, partial, or heuristic evidence. A closed indexed result does not prove that every runtime caller or required edit is known.

Current result

A September 2026 paired Sonnet sample compared native search/read tools with Prism on nine change-impact tasks in Go, Java, TypeScript, and Python. Each cell below is one fresh run, so this table is a release-gate snapshot rather than a variance estimate.

Nine-task aggregate	Native tools	Prism
Mean recall	0.683	0.998
Mean precision	0.770	0.955
Total estimated cost	$3.23	$1.28
Cost relative to native	1.00×	0.40×

Prism matched or improved recall and cost less in every task in this sample. The largest structural case was Grafana's externally declared QueryData interface: Prism found the complete 70-site local family in a deterministic call. Three fresh agent trials all reached 1.0 recall; precision ranged from 0.933 to 0.959.

Repeated trials matter because agent runs vary. The published evidence also includes three paired Jackson JsonNode.get trials: native tools averaged 0.625 recall, 30 turns, and $0.404; Prism averaged 1.0 recall, 8.3 turns, and $0.205. Full per-task results, raw records, oracles, scoring rules, and limitations live in provasign/research.

Install

# Homebrew (macOS or Linux)
brew install provasign/shale/prism

# macOS or Linux installer
curl -fsSL https://raw.githubusercontent.com/provasign/prism/main/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/provasign/prism/main/install.ps1 | iex

# Pin the current release
VERSION=v0.74.1 curl -fsSL https://raw.githubusercontent.com/provasign/prism/main/install.sh | bash

The installer writes to ~/bin by default. Set INSTALL_DIR to choose another directory. Use either Homebrew or the standalone installer as the authoritative installation. If both are present with different versions, prism init and the MCP server report their paths. The standalone installer stops running Prism MCP servers before replacing the binary, verifies the installed version, and removes Prism registrations left by the old global configuration model. After changing installation methods or upgrading Homebrew, run prism cleanup-global, run prism init in each project, choose the harnesses to configure, and restart the coding agent so pinned MCP paths and long-running servers refresh.

Build from source with make build; run the full test suite with make test.

Quick start

From the root of a repository:

prism init .

This detects installed and previously configured harnesses, recommends those as the default, and asks which to configure. It writes prism.yaml, compact project-local MCP configs, and current instruction files while replacing Prism-owned legacy setup. For automation, pass a comma-separated list such as prism init --harness claude,codex .; a first-time non-interactive init never assumes all harnesses. Later runs can use prism init --yes . to reuse the selection recorded in prism.yaml. Windsurf receives AGENTS.md steering only because its documented MCP configuration is user-global, which Prism does not modify. Codex loads the generated .codex/config.toml after the repository is trusted; accept Codex's project-trust prompt, then restart or reload the session.

Use search to find an anchor, then ask the graph for the relationship you need:

prism search QueryData --scope text --exhaustive --files-only
prism change-impact 'QueryDataHandler.QueryData' --format text

prism query --terms ValidateRequest \
  --include graph \
  --format text

prism verify --base main --format text

For MCP-capable agents, prism init exposes one compact prism gateway with six operations:

• search locates symbols and source text.
• query returns budgeted source around named anchors, callers, and tests.
• read reads a known file or range and deduplicates unchanged repeat reads.
• lookup returns known symbol bodies, marking any omitted content.
• change_impact returns indexed declarations, implementation families, and caller candidates.
• verify reviews a diff against indexed potential impact sites.

Run prism mcp --legacy only for compatibility testing with the former six-tool surface; normal and init-generated MCP launches use the compact gateway.

CLI help is authoritative for the complete command and flag list:

prism --help
prism doctor .

Read-guard hook (Claude Code)

prism init --read-guard .      # install
prism init --no-read-guard .   # uninstall

Installs a hook that denies a native Read once prism has already delivered that exact line range earlier in the same session, pointing the agent back at what it already has instead of paying for it twice. Measured (13-task controlled A/B, same tasks run hook-on vs hook-off): ~11% fewer tokens with no change in resolve rate. Claude Code only — hooks are a Claude Code mechanism.

--read-guard writes .claude/hooks/prism_read_tracker.py and .claude/hooks/prism_read_guard.py, and adds one PostToolUse entry (on mcp__prism__prism) and one PreToolUse entry (on Read) to .claude/settings.json. It only ever adds entries — an existing hook you already have on Read or elsewhere is never modified or replaced, prism's just runs alongside it. --no-read-guard removes exactly what --read-guard added: the two script files, only the settings.json entries whose command is prism's own (any other hook on the same matcher is left in place), and the .prism-read-tracker.json state file. Both are standalone actions — running either does not require selecting harnesses or otherwise running the rest of init.

Workflow for coding agents

1. Use prism_lookup for a known symbol or prism_search for an unknown location; batch related names.
2. Use prism_change_impact when callers, overrides, contracts, or other affected sites need checking; a clearly local body-only edit need not call it. Preserve the returned set when used.
3. Use prism_query for related source context or prism_lookup for a known symbol body; inspect omission markers.
4. Use exhaustive text search for wide concept removals and other completeness questions.
5. Run relevant tests. Consider prism_verify for Python, unchecked JavaScript, or PHP contract changes; for TypeScript or checked JavaScript, use it only when affected files lack a complete typecheck. Skip it after a complete build/typecheck of affected Go, Java, Rust, C/C++, or C# targets. It is optional in every language.

prism search --scope text is a real repository text search. The graph adds value after location: callers, implementations, type relationships, tests, architectural edges, and completeness checks.

Architecture and CI

Add boundary rules to prism.yaml:

version: 2
harnesses: "claude,codex"
mcp_surface: "compact"
arch_deny:
  - "internal/cli -> internal/mcp"

Then run:

prism map .
prism arch .
prism verify . --base main

prism arch reports the concrete file:line evidence for each forbidden component edge. prism verify checks the current diff for missed impact sites, new component dependencies, and introduced architecture violations.

Language support

Prism indexes Go, TypeScript/TSX, JavaScript/JSX, Python, Java, Rust, C/C++, C#, PHP, Swift, Kotlin, Objective-C, COBOL, and JCL (via the embedded Grove engine). Semantic depth varies by language and by the native toolchain available in the repository; COBOL and JCL are structural/heuristic only, with no published accuracy oracle yet. prism doctor reports the full per-language indexing/resolution tier and limitations breakdown (Grove's own capability manifest) under its languages key, alongside index/engine status.

Interfaces

• CLI: local interactive use and CI
• MCP over stdio: Claude Code, Cursor, VS Code, Codex, Gemini, OpenCode, and other MCP clients
• HTTP: prism serve --port 8888; see docs/HTTP_API.md
• Go library: see docs/GO_KIT.md

Grove is embedded in the Prism binary. Prism users do not need to install or run a separate graph service.

Security and privacy

Prism analyzes the local working tree and stores its index locally. The default MCP transport is stdio. The optional HTTP server binds to loopback by default. See SECURITY.md and THREAT_MODEL.md for reporting and trust-boundary details.

Contributing

See CONTRIBUTING.md, GOVERNANCE.md, and SUPPORT.md. Accuracy changes should include an oracle-backed regression case; public performance claims should link to reproducible evidence in provasign/research.

License

Apache License 2.0. See LICENSE.