Stop feeding your AI agent the whole codebase. Give it a graph.
CodePrism builds a persistent knowledge graph of your project — every function, class, import, and data-flow relationship — and exposes it to any AI coding agent via the Model Context Protocol (MCP). Instead of your agent reading 40 files to understand one function, it queries the graph and gets exactly what it needs in under 200 tokens.
| Without CodePrism | With CodePrism |
|---|---|
| Agent reads 30–50 files per task | Agent queries the graph — 1–3 targeted calls |
| 8,000–40,000 tokens per context window | 200–800 tokens for equivalent context |
| Agent re-reads the same files repeatedly | Session overlay tracks what's already been read |
| Security issues discovered after the write | Security gate runs before every write |
| Entire codebase re-sent on every file change | Incremental graph update in milliseconds |
Token reduction target: 60–80% on large codebases.
Averaged 91% across 3 real-world repos (psf/requests, pallets/flask, encode/httpx). See docs/benchmark-results.md for full results.
- Indexes your codebase using tree-sitter AST parsing (Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, Ruby, PHP)
- Maintains a knowledge graph per project — built automatically in the background the first time
you open a project, refreshed incrementally on every start, and honouring your
.gitignore - Answers precise structural questions: callers, callees, impact, dependencies, data flow
- Guards every write with a security scanner — secrets, injection, weak crypto, and more
- Tracks agent sessions — what was read, what was written, undo support
- Serves all of the above via MCP to Claude Code, Cursor, and any MCP-compatible agent
pip install codeprism-aiPython 3.12+ required.
Optional: semantic search (heavier install, enables embedding-based symbol search)
pip install "codeprism-ai[embeddings]"Run setup once per agent. For Claude Code and Codex, --global configures the agent for every
project on your machine; without it, only the project you pass with --project (default: the
current directory) is configured.
Claude Code
codeprism setup claude --global # every project
codeprism setup claude # this project only (writes .mcp.json)Then restart Claude Code and run /mcp to check that codeprism is connected.
Codex
codeprism setup codex --global # every project (~/.codex/config.toml)
codeprism setup codex # this project only (.codex/config.toml, trusted projects)Then start a new Codex session.
Cursor
codeprism setup cursor --project /path/to/your/projectThen restart Cursor. Cursor entries are tied to one project path, so run setup for each project.
Every setup also writes the CodePrism usage guide to AGENTS.md in the project, the shared
instructions file most coding agents read. Claude Code gets a thin CLAUDE.md that imports it.
Windsurf, Continue.dev and Zed are configured by hand, see INTEGRATIONS.md. Their setup
commands write to locations those tools don't document and can overwrite a config file they cannot parse
(#42, #43), so don't use them yet.
Any MCP-compatible agent (manual)
codeprism serve # serves the project containing the current directory
codeprism serve /path/to/your/projectThis starts the MCP server on stdio. Point your agent's MCP config at that command.
When the server starts in a project it builds the index in the background the first time, and
refreshes it on every later start. With a global setup it finds the project for you (the nearest
folder with a .git or .codeprism.toml); a project-level setup serves the path it was given. Ask get_graph_stats: index_status is indexing, then ready. Your home folder is
never indexed.
To build the index yourself, for CI or to pre-build a large repository:
codeprism index /path/to/your/projectIndexing this repository (123 files, about 20,000 lines) takes about a second. A synthetic 2-million-line monorepo takes about 40 seconds on a 12-core machine, and later runs only re-parse changed files.
Your agent can now call tools like get_context, get_impact, scan_diff, and record_write
instead of reading raw files.
Changes you make in your editor while a session is running are not seen by the server until it restarts, unless they go through CodePrism's own write tools (#35).
CodePrism works with every major AI editor and agent framework via the Model Context Protocol (MCP). Two transports are supported: stdio (local, default) and SSE (HTTP on 127.0.0.1).
| Agent / Tool | Auto-setup | Transport |
|---|---|---|
| Claude Code | codeprism setup claude |
stdio |
| Codex | codeprism setup codex |
stdio |
| Cursor | codeprism setup cursor |
stdio |
| Windsurf | manual config (see INTEGRATIONS.md) | stdio |
| Continue.dev | manual config (see INTEGRATIONS.md) | stdio |
| Zed | manual config (see INTEGRATIONS.md) | stdio |
| VS Code + GitHub Copilot | manual config | stdio |
| Cody (Sourcegraph) | manual config | stdio |
| Any HTTP agent | codeprism serve --transport sse |
SSE |
| Python library | from codeprism import CodePrism |
library |
| GitHub Actions / CI | codeprism scan --diff |
CLI |
| Pre-commit hook | .pre-commit-config.yaml |
CLI |
Auto-setup for Claude Code, Codex and Cursor:
codeprism setup claude --global # or: setup codex --global / setup cursor --project .
# Restart your editorPython library (no MCP layer):
from codeprism import CodePrism, SecurityGate
async with CodePrism("/path/to/project") as prism:
await prism.index()
ctx = await prism.get_context("payments/processor.py", "process_payment")
impact = await prism.get_impact("payments/processor.py", "process_payment")
gate = SecurityGate()
report = await gate.check_write("payments/processor.py", new_content)
if report.is_blocked:
raise ValueError(report.issues[0].description)For detailed per-editor config, Docker Compose setup, CI pipelines, and OpenAI Agents SDK examples, see INTEGRATIONS.md.
# Register CodePrism with an agent: claude | codex | cursor | windsurf | continue | zed
codeprism setup claude --global # user level, serves every project (claude, codex)
codeprism setup claude --project /path/repo # one projectsetup also writes AGENTS.md (and a thin CLAUDE.md for Claude Code) into the project. Only
the Claude Code and Codex user-level entries follow the project you open; the others are tied to
one path. Windsurf, Continue.dev and Zed: use the manual configuration in
INTEGRATIONS.md.
# Index a project (first run, or refresh: only changed files are re-parsed)
codeprism index /path/to/project
# Only some languages (default: all ten)
codeprism index /path/to/project --languages python,typescript
# Re-parse everything / set parser processes (0 = one per CPU core, the default) / add embeddings
codeprism index /path/to/project --force
codeprism index /path/to/project --workers 4
codeprism index /path/to/project --embeddingsFiles that git ignores are skipped. After an upgrade that changes the index format, the next run re-parses everything once, automatically.
# Get structured context for a symbol (paths are relative to --project, default: current directory)
codeprism context payments/processor.py::process_payment --depth 2
# Transitive impact analysis
codeprism impact payments/processor.py::process_payment
# Who calls this function?
codeprism callers payments/processor.py::process_payment
# Search for a symbol by name (substring), optionally by kind: function | class | variable
codeprism search "handle_authentication" --kind function
# File-level summary
codeprism summary payments/processor.py
# Graph statistics
codeprism stats
codeprism stats --verbose # per-file breakdown
codeprism stats --jsonGive enough of the path to be unique (api/utils.py, not utils.py). The MCP tools and CLI
callers, context, impact and summary commands report ambiguous paths with candidate files
and a hint to use a longer path. These CLI commands write lookup errors to stderr and exit with
status 1 for an unindexed file, ambiguous path or unknown symbol. callers prints "No callers
found" and exits successfully only when the symbol exists and has no callers.
# Write a self-contained, interactive HTML view of the graph
codeprism visualize /path/to/project --out graph.html# Scan a single file
codeprism scan payments/processor.py
# Scan every indexed file in the project
codeprism scan --all --project /path/to/project
# Scan only the files changed in a git range (no index needed)
codeprism scan . --diff HEAD~1..HEAD
codeprism scan . --diff main..feature-branch
codeprism scan . --diff HEAD # everything changed since HEAD, including staged filesExit codes: 0 = PASS or WARN, 2 = BLOCK (use in CI pipelines).
# Keep the on-disk index in sync with file changes (foreground process)
codeprism watch /path/to/projectwatch updates the index on disk. A running MCP server keeps its own in-memory copy and does not
reload it (#35).
get_file_map(project_path="", limit=200, offset=0) returns file roles under the served
project root by default. Pass a project-relative directory such as src, or an absolute
directory, to narrow it. Files are sorted by path; limit accepts 1-1000 and offset skips
that many files. total_files and total_symbols count the whole selected directory,
while truncated is true whenever the page omits files (including earlier pages).
A directory with no indexed files returns an error. To read the next page, increase
offset by limit. Python callers of QueryEngine.get_file_map can use limit=None
for a complete map; internal CLI statistics and summaries do this.
# stdio (Claude Code, Codex, Cursor, ...). With no path: the project containing the current directory
codeprism serve
codeprism serve /path/to/project
# Don't build/refresh the index in the background
codeprism serve --no-auto-index
# SSE transport
codeprism serve /path/to/project --transport sse --port 8765The MCP search_symbol tool ranks substring matches by exact name, then prefix, then other
matches, with stable name/file ordering. Its limit defaults to 50 and accepts 1-500.
kind and project_path filters apply before this limit; the response includes count
(returned matches), total (all filtered matches) and truncated (whether any were cut).
For example, search_symbol("run", kind="function", limit=100) can return more matches;
narrow the query or filters when truncated is true. With semantic embeddings enabled,
search keeps its existing 20-neighbor cap and ignores limit; that response has
count/matches only because a complete total and truncated are unavailable.
The SSE server listens on 127.0.0.1 only and has no built-in authentication; there is no --host
option yet (#45). To reach it from another machine, use an SSH tunnel or a reverse proxy on
the same host (see INTEGRATIONS.md).
CodePrism scans every proposed file write before it reaches disk. The scanner runs six detector categories:
| Detector | What it catches | Severity |
|---|---|---|
| Secrets | Hardcoded passwords, API keys, AWS credentials, GitHub tokens, OpenAI keys | BLOCK |
| Injection | SQL injection via f-strings or string concat, eval(), exec(), shell=True |
BLOCK / WARN |
| Weak crypto | MD5, SHA-1, DES, RC4, non-cryptographic random for secrets |
WARN |
| Env var exposure | Printing or returning os.environ contents |
WARN |
| Unsafe dependencies | pickle, unsafe yaml.load, marshal, dynamic __import__ |
BLOCK / WARN |
| Code safety | Bare except:, silent exception swallowing, debugger breakpoints |
WARN |
Severity rules:
- BLOCK — write is rejected; content never reaches disk
- WARN — write proceeds but the issue is surfaced to the agent
- INFO — logged only
Scan a file manually:
codeprism scan payments/processor.pyUse in CI to block PRs that introduce new security issues:
codeprism scan --diff HEAD~1..HEAD || exit 1Your AI agent is editing a large payment processing module. Without CodePrism it reads 15 files to understand the call graph. With CodePrism:
Agent: get_context("payments/processor.py", "charge_card", depth=2)
← 340 tokens: the function signature, its 3 callers, its 6 callees, the types it uses
Before the agent writes a file that handles user authentication:
Agent: scan_diff(original_content, proposed_content, "auth/login.py")
← status: BLOCK, issues: [Hardcoded API key on line 42]
The write is stopped before the key ever touches disk.
Before renaming a core utility function:
Agent: get_impact("utils/hash.py", "compute_checksum")
← severity: HIGH, direct_dependents: 12 functions, affected_test_files: ["tests/test_payments.py", ...]
The agent knows the full blast radius before making any changes.
In a multi-step agentic workflow, the agent tracks what it has already read:
Agent: get_session_context("sess_abc123")
← "3 reads across 2 files, 1 write to payments/processor.py — no need to re-fetch"
| Language | Status | Features |
|---|---|---|
| Python | Full | Functions, classes, imports, type hints, async, decorators |
| JavaScript | Full | Functions, classes, ES modules, CommonJS require |
| TypeScript | Full | + interfaces, type aliases, generics |
| Go | Full | Functions, structs, interfaces, packages |
| Rust | Full | Functions, structs, traits, impl blocks |
| Java | Full | Classes, interfaces, methods, annotations, generics |
| C | Full | Functions, structs, typedefs, includes |
| C++ | Full | Classes, methods, inheritance, templates, namespaces |
| Ruby | Full | Modules, classes, instance/singleton methods, visibility |
| PHP | Full | Namespaces, classes, traits, interfaces, methods |
Known limitations
- Calls are linked by following imports for Python only; in other languages they are linked
by name, so a common name (
stringify,Split,add) can link to the wrong project function (#37). - Methods or class attributes with the same name in different classes of one Python file share one symbol (#34).
- Python definitions inside
try/ifblocks are not indexed (#39).
See docs/architecture.md for the full list.
The MCP server's startup index, codeprism index and the index_project MCP tool read an optional
.codeprism.toml in the project root. Explicit indexing flags or tool arguments override the file;
omitted options inherit it. For example, index --languages python overrides the configured language
list, and --embeddings / --no-embeddings override enable_embeddings. The MCP tool likewise accepts
embeddings=true or embeddings=false; omitting it preserves the file's setting.
Parser workers keep their entry-point defaults: CLI and MCP indexing use one process per CPU core
(parse_workers = 0), while library callers default to in-process parsing (parse_workers = 1).
Use index --workers N to override the CLI worker count.
[codeprism]
languages = ["python", "typescript"] # default: all ten supported languages
respect_gitignore = true # skip files git ignores (default: true)
auto_index = true # build/refresh the index in the background (default: true)
enable_embeddings = false # semantic search (needs codeprism-ai[embeddings])
[codeprism.security]
# Glob patterns matched against each file's ABSOLUTE path
ignore_paths = ["*/tests/fixtures/*", "*.example.*"]
[codeprism.embeddings]
model = "all-MiniLM-L6-v2"
device = "cpu"ignore_paths entries are glob patterns matched against the full path, so use a leading * for
folders: "tests/fixtures/" alone matches nothing.
The index lives in your platform's user-data directory (one SQLite file per project), not in the repository.
Some keys that appeared in earlier examples (enable_security_gate, watch_debounce_ms,
security.block_on_secrets, security.warn_on_weak_crypto, security.check_new_dependencies and
the [codeprism.mcp] section) are accepted but currently have no effect.
CodePrism is benchmarked on token reduction and answer accuracy across real-world codebases. Token numbers below were re-measured on v0.1.11; the LLM-judged accuracy figures are from v0.1.7.
| Corpus | Avg baseline | Avg CodePrism | Reduction |
|---|---|---|---|
| Fixture project (tiny, 2 files) | 270 tokens | 206 tokens | 24% |
| psf/requests v2.32.3 | 6,406 tokens | 714 tokens | 88.9% |
| pallets/flask 3.0.3 | 9,558 tokens | 805 tokens | 91.6% |
| encode/httpx 0.27.2 | 12,685 tokens | 857 tokens | 93.2% |
The fixture numbers are low because on tiny files (135–380 tokens), JSON response overhead can exceed the raw file size. On real-world files (5k–17k token baselines) the savings are always substantial — averaging 91% across 3 production codebases.
Accuracy (LLM-as-judge, v0.1.7): CodePrism matches or beats the baseline on 2 of 3 corpora — requests CP 0.87 vs BL 0.86, httpx CP 0.70 vs BL 0.68. Flask gap (0.64 vs 0.77) is concentrated in 2 tasks with ground truth calibration issues.
Call-link accuracy (Python, v0.1.11). Cross-file call precision is 1.00 on requests, flask,
httpx and CodePrism (it was 0.68–0.96 before calls followed imports), with recall 0.90–1.00.
Calls within a single file are less exact: precision 0.67–0.85 and recall 0.72–0.81 on the three
corpora, mostly self.method() calls that need type information.
Full methodology, per-task breakdown, and reproduction instructions: docs/benchmark-results.md
| Doc | What it covers |
|---|---|
| docs/benchmark-results.md | Benchmark methodology, all run results, reproduction steps |
| docs/architecture.md | System design, data flow, key design decisions |
| docs/changelog.md | Version history and release notes |
| INTEGRATIONS.md | Per-editor setup, Docker Compose, CI, OpenAI Agents SDK |
| CONTRIBUTING.md | Dev environment, coding standards, PR process |
Support continued development of CodePrism - the knowledge graph that helps AI agents understand your codebase with 91% token reduction.
Why sponsor?
- Keep it free and open source
- Fund new features and language support
- Get priority support and feature requests
- Support the AI agent ecosystem
See SPONSORS.md for detailed tiers and benefits.
CodePrism includes a built-in skill that teaches AI agents to use the knowledge graph effectively. The skill is automatically installed when you run codeprism setup <agent>.
What the skill does:
- Teaches agents to query the graph instead of reading files
- 91% token reduction on large codebases
- Security scanning before every write
- Smart context caching to avoid re-fetching
Learn more:
Platform listings:
- SkillsMP - 3M+ skills indexed
- SkillAgent - 15K+ skills directory
- agentskill.sh - 275K+ skills marketplace
We welcome contributions of all kinds — bug fixes, new language parsers, additional security detectors, documentation improvements, and more.
Read the Contributing Guide for:
- How to set up the development environment
- Coding and testing standards
- The PR and review process
- How to add new security detectors or language parsers
Read the Code of Conduct before participating in any community space.
MIT — see LICENSE.
Built on tree-sitter for fast, accurate parsing; NetworkX for graph operations; FastMCP for the MCP server; and Pydantic for data validation. Security patterns informed by OWASP Top 10 and CWE.