ContextPrism (prism)

ContextPrism distills codebases into high-density AST skeletons for AI coding agents (Claude Code, Cursor, Codex, OpenCode, Antigravity).

Instead of sending full implementation bodies, loop iterations, and boilerplate to LLM context windows, ContextPrism extracts interfaces, type definitions, class schemas, exported function signatures, and docstrings.

                    ┌─────────────────────────┐
                    │     Raw Codebase        │
                    │   (100,000+ tokens)     │
                    └───────────┬─────────────┘
                                │
                        [ ContextPrism ]
                        (AST Distillation)
                                │
                    ┌───────────▼─────────────┐
                    │    Distilled Context    │
                    │   (~15,000 tokens)      │
                    │   - 70% to 85% Savings  │
                    │   - 100% Type Contracts │
                    └─────────────────────────┘

Key Features

• Multi-Language AST Distillation: Native parsers for TypeScript, JavaScript, Python, Go, Rust, and generic C-family languages.
• Token Budget Allocator: Specify --budget 8000 to dynamically compress non-target files while keeping focused files at full fidelity.
• Multi-Format Context: Generate Anthropic/Gemini XML <codebase>, standard Markdown, compact plain text, or structured JSON.
• Built-in Model Context Protocol (MCP): Run prism mcp to connect directly with Cursor, Claude Desktop, and Antigravity.
• AST-Enriched Git Diffs: Run prism diff to pair git diffs with structural signatures of modified files.
• Local Web Visualizer: Run prism ui to launch an interactive dashboard with live code comparison and token metrics.

Installation

Run directly with npx or install globally:

# Direct execution without install
npx contextprism pack

# Global install
npm install -g contextprism

Quick Start

1. Pack Codebase into an AI Context Prompt

# Default XML format for Claude or Gemini
prism pack

# Save to file
prism pack -o context.xml

# Set a strict 10,000 token budget
prism pack --budget 10000 -o prompt.xml

# Focus on specific files while skeletonizing the rest
prism pack --focus src/auth/login.ts -o prompt.xml

# Export as Markdown
prism pack -f markdown -o context.md

2. View Token Footprint Tree

prism tree

Output:

├── src/
│   ├── ast/
│   │   ├── extractor.ts [222 tokens] (skeleton)
│   │   └── ts-parser.ts [163 tokens] (skeleton)
│   ├── core/
│   │   ├── budgeter.ts [408 tokens] (skeleton)
│   │   └── scanner.ts [720 tokens] (skeleton)
Total: 34 files, 15.0k distilled tokens (33.6k raw)

3. Inspect a Single File Skeleton

prism ast src/ast/ts-parser.ts

Output:

// ContextPrism AST Skeleton: src/ast/ts-parser.ts
// Tokens: 163 tokens (was 1.8k tokens, -91%)

import ts from 'typescript';
export interface TsSkeletonOptions {
    preserveDocstrings?: boolean;
    preserveImports?: boolean;
    preservePrivateMembers?: boolean;
}
export function extractTsSkeleton(code: string, fileName = 'source.ts', options: TsSkeletonOptions = {}): string { /* ... */ }

4. Benchmark Token Savings

prism bench

Output:

┌────────────────────────┬─────────────┬─────────────┬──────────────┬─────────────┐
│ Compression Mode       │ Total Size  │ Est. Tokens │ Token Saving │ Claude Cost │
├────────────────────────┼─────────────┼─────────────┼──────────────┼─────────────┤
│ 1. Raw Source Code     │    101.7 KB │ 33.6k tokens │           0% │   $0.100668 │
│ 2. Light (No Comments) │    101.6 KB │ 33.5k tokens │           0% │   $0.100542 │
│ 3. AST Skeleton        │     45.0 KB │ 15.0k tokens │          55% │   $0.045045 │
│ 4. Types & Interfaces  │     26.4 KB │ 9.1k tokens │          73% │   $0.027291 │
└────────────────────────┴─────────────┴─────────────┴──────────────┴─────────────┘

5. Launch Interactive Web Dashboard

prism ui

Opens a local web interface at http://localhost:4100 with real-time token gauges, side-by-side AST comparison, and one-click context generation.

MCP Server Configuration

Add ContextPrism as a tool server in your claude_desktop_config.json, Cursor, or Antigravity MCP settings:

{
  "mcpServers": {
    "context-prism": {
      "command": "npx",
      "args": ["-y", "contextprism", "mcp"]
    }
  }
}

Exposed MCP Tools

| Tool | Parameters | Description | | :--- | :--- | :--- | | prism_get_codebase_context | directory, budget_tokens, focus_files, mode, format | Returns AST-distilled codebase context | | prism_get_file_skeleton | file_path, mode | Returns structural skeleton of a single file | | prism_get_file_tree | directory | Returns token-annotated project directory tree |

Programmatic API

You can use ContextPrism directly in your own scripts:

import { scanDirectory, applyTokenBudget, packageCodebase, extractTsSkeleton } from 'contextprism';

// 1. Scan directory
const files = scanDirectory('./src');

// 2. Distill with token budget
const budgetResult = applyTokenBudget(files, {
  budgetTokens: 8000,
  defaultLevel: 'skeleton',
  focusFiles: ['src/index.ts']
});

// 3. Format as XML prompt
const xmlPrompt = packageCodebase(budgetResult, { format: 'xml' });
console.log(xmlPrompt);

Supported File Types

| Language | Extracted AST Elements | | :--- | :--- | | TypeScript / JS | Interfaces, type aliases, enums, class structures, method signatures, exports, JSDoc | | Python | Classes, method signatures, decorators, type hints, docstrings, top-level constants | | Go | Package headers, struct definitions, interfaces, function signatures | | Rust | Structs, enums, traits, impl blocks, method signatures | | JSON | Structure schemas, compacted large arrays, key maps | | Generic (C/C++, Java, PHP, C#) | Class headers, method signatures, public declarations |

Development

# Clone repository
git clone https://github.com/mewsyy/context-prism.git
cd context-prism

# Install dependencies
npm install

# Run tests
npm test

# Build package
npm run build

License

MIT