CodePrism

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.

Why CodePrism

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.

What CodePrism Does

• Indexes your codebase using tree-sitter AST parsing (Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, Ruby, PHP)
• Maintains a live knowledge graph — updated incrementally when files change
• 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

Installation

pip install codeprism-ai

Python 3.12+ required.

Optional: semantic search (heavier install, enables embedding-based symbol search)

pip install "codeprism-ai[embeddings]"

Quickstart

1. Index your project

codeprism index /path/to/your/project

This builds the knowledge graph and stores it in a local SQLite database. On a 50,000-line codebase this takes about 10–20 seconds. Subsequent updates are incremental and instant.

2. Connect your AI agent

Pick the agent you use:

Claude Code

codeprism setup claude --project /path/to/your/project

Then restart Claude Code. CodePrism appears automatically as an MCP server.

Codex

codeprism setup codex --project /path/to/your/project

Then start a new Codex session (accept the trust prompt for the project).

Cursor

codeprism setup cursor --project /path/to/your/project

Then restart Cursor.

Every setup also writes the CodePrism usage guide to AGENTS.md, the shared instructions file most coding agents read. Claude Code gets a thin CLAUDE.md that imports it.

Any MCP-compatible agent (manual)

codeprism serve /path/to/your/project

This starts the MCP server on stdio. Point your agent's MCP config at codeprism serve <path>.

3. That's it

Your agent can now call tools like get_context, get_impact, scan_diff, and record_write instead of reading raw files.

Integrations

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 (network, for remote agents).

Auto-setup for Claude Code and Cursor:

codeprism index /path/to/project
codeprism setup claude --project /path/to/project   # or: setup codex / setup cursor
# Restart your editor

Python 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.

CLI Reference

Indexing

# Index a project (first run or full rebuild)
codeprism index /path/to/project

# Index only specific languages
codeprism index /path/to/project --languages python,typescript

Querying

# Get structured context for a symbol
codeprism context payments/processor.py::process_payment

# 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
codeprism search "handle_authentication"

# File-level summary
codeprism summary payments/processor.py

# Graph statistics
codeprism stats
codeprism stats --verbose    # per-file breakdown

Security scanning

# 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 commit range
codeprism scan . --diff HEAD~1..HEAD
codeprism scan . --diff main..feature-branch

Exit codes: 0 = PASS, 2 = BLOCK (use in CI pipelines).

Watch mode

# Keep the graph in sync with file changes (foreground process)
codeprism watch /path/to/project

MCP server

# Stdio transport (for Claude Code, Cursor, Continue)
codeprism serve /path/to/project

# SSE transport (for remote or network agents)
codeprism serve /path/to/project --transport sse --port 8765

Security Gate

CodePrism scans every proposed file write before it reaches disk. The scanner runs six detector categories:

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.py

Use in CI to block PRs that introduce new security issues:

codeprism scan --diff HEAD~1..HEAD || exit 1

Use Cases

AI pair programmer context

Your 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

Pre-write security check

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.

Impact analysis before refactoring

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.

Session-aware long agent chains

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"

Supported Languages

Configuration

Create a .codeprism.toml in your project root to customize behavior:

[codeprism]
languages = ["python", "typescript"]
enable_embeddings = false
enable_security_gate = true
watch_debounce_ms = 500

[codeprism.security]
block_on_secrets = true
warn_on_weak_crypto = true
check_new_dependencies = true
ignore_paths = ["tests/fixtures/", "*.example.*"]

[codeprism.mcp]
transport = "stdio"
port = 8765

Benchmarks

CodePrism is benchmarked on token reduction and answer accuracy across real-world codebases.

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): 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.

Full methodology, per-task breakdown, and reproduction instructions: docs/benchmark-results.md

Documentation

Contributing

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.

License

MIT — see LICENSE.

Acknowledgements

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.