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

<p align="center">
  <img src="assets/preview.png" alt="ContextPrism Web Visualizer" width="100%" />
</p>

```
                    ┌─────────────────────────┐
                    │     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:

```bash
# Direct execution without install
npx contextprism pack

# Global install
npm install -g contextprism
```

---

## Quick Start

### 1. Pack Codebase into an AI Context Prompt

```bash
# 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

```bash
prism tree
```

Output:
```text
├── 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

```bash
prism ast src/ast/ts-parser.ts
```

Output:
```typescript
// 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

```bash
prism bench
```

Output:
```text
┌────────────────────────┬─────────────┬─────────────┬──────────────┬─────────────┐
│ 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

```bash
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:

```json
{
  "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:

```typescript
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

```bash
# 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