CodeShave
⚡ Try CodeShave Live in Your Browser (Zero Install Required)
Paste your code and test real-time token reduction across Python, TypeScript, Go, Rust, Java, C++ right now:
👉 https://jaideepkrishna2008-ui.github.io/codeshave/
High-speed, deterministic AST & structural code context compressor for AI coding assistants and LLMs.
Reduces prompt tokens by 60% to 85% across all major programming languages while preserving valid syntax, type signatures, interfaces, and class hierarchies.
⚡ Terminal Demo
🎯 Why CodeShave?
When developers feed entire codebases to LLMs or AI agents, context windows quickly fill up, latency spikes, and API token bills mount.
Traditional approaches either:
- Truncate files blindly, breaking syntax trees, references, and imports.
- Rely on costly, slow LLMs to summarize code before prompting.
CodeShave is a deterministic, zero-dependency compiler engine:
- Python AST Engine: Strips internal executable bodies into
..., preserving full decorators, types, docstrings, classes, and__all__. - Universal Multi-Language Engine: Strips execution loops inside
{ ... }into{ /* ... */ }across TypeScript, JavaScript, Go, Rust, Java, C++, and C# while keeping 100% of interfaces, structs, types, imports, and function signatures intact. - Topological Sorting: Orders files by module dependencies so the LLM reads prerequisite definitions first.
- Budget Enforcer: Automatically compresses a repository to fit exactly under your target token limit (e.g.
--budget 32000). - Turnkey MCP Server: Seamlessly integrates with Claude Desktop, Cursor, Windsurf, and Antigravity.
🌐 Supported Languages
CodeShave natively supports the world's most popular programming languages out of the box with zero external dependencies:
| Language | Extensions | Compression Engine | Preserved Constructs |
|---|---|---|---|
| Python | .py, .pyw |
Python Native AST | Classes, methods, docstrings, type annotations, decorators, __all__ |
| TypeScript | .ts, .tsx |
Structural Scanner | Interfaces, type aliases, enums, class methods, JSDoc, exports |
| JavaScript | .js, .jsx, .mjs, .cjs |
Structural Scanner | ES6 classes, arrow functions, exported modules, constructor signatures |
| Go | .go |
Structural Scanner | type Struct struct, type Interface interface, method receivers, func |
| Rust | .rs |
Structural Scanner | struct, enum, trait, impl blocks, pub fn signatures |
| Java | .java |
Structural Scanner | Packages, classes, interfaces, generic types, method signatures |
| C / C++ | .c, .cpp, .h, .hpp |
Structural Scanner | Header #include, struct, class, method/function declarations |
| C# | .cs |
Structural Scanner | Namespaces, classes, interfaces, properties, method headers |
| Kotlin & Scala | .kt, .scala |
Structural Scanner | Classes, traits, data classes, function signatures |
| Swift & Dart | .swift, .dart |
Structural Scanner | Protocols, extensions, classes, functions |
| PHP | .php |
Structural Scanner | Namespaces, classes, interfaces, function signatures |
| Ruby | .rb |
Indentation Scanner | Classes, modules, def ... end signatures |
| Shell / Bash | .sh, .bash, .zsh |
Lexical Scanner | Function headers, environment variables, commands |
🏗️ Architecture
🚀 Quickstart
Installation
Install globally from PyPI:
pip install codeshave
Or install directly from GitHub:
pip install git+https://github.com/jaideepkrishna2008-ui/codeshave.git
⚡ CLI Usage
# 📋 One-Click Clipboard Copy: Compress and copy directly to OS clipboard
codeshave clip ./src
codeshave clip ./src/service.ts
# -> Copied to clipboard! Ready to paste into ChatGPT, Claude, or Cursor!
# 📦 Pack entire multi-language repository into an LLM context bundle
codeshave pack ./src -o llm_context.md
# 🎯 Filter by language (e.g. only TypeScript and Go)
codeshave pack ./src --lang ts,go -o context.md
# 🏷️ Generate Claude-optimized XML bundle with live savings metrics
codeshave pack ./src --format xml --stats -o llm_context.xml
# 💰 Enforce strict token budget ceiling (auto-prunes to fit under 32k tokens)
codeshave pack ./src --budget 32000 -o prompt_context.md
# 🔍 View colored terminal diff of lines shaved
codeshave diff ./src/server.go
# 📄 Inspect a single file's compressed skeleton
codeshave inspect ./src/services/billing.ts
🔌 AI Assistant & Editor Integration (MCP Server)
CodeShave runs as a turnkey Model Context Protocol (MCP) server over standard I/O (stdio). This allows AI coding assistants to automatically invoke CodeShave and compress source code before analyzing it, saving up to 85% on prompt tokens.
1. Claude Desktop
Add to your claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"codeshave": {
"command": "codeshave",
"args": ["mcp"]
}
}
}
2. Cursor IDE
- Open Cursor Settings $\rightarrow$ Features $\rightarrow$ MCP.
- Click + Add New MCP Server.
- Configure:
- Name:
codeshave - Type:
command - Command:
codeshave mcp
- Name:
Alternatively, add to .cursor/mcp.json in your workspace:
{
"mcpServers": {
"codeshave": {
"command": "codeshave",
"args": ["mcp"]
}
}
}
3. Windsurf Editor
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"codeshave": {
"command": "codeshave",
"args": ["mcp"]
}
}
}
4. Google Antigravity
In your Antigravity MCP configuration (~/.gemini/antigravity/mcp_config.json or project settings):
{
"mcpServers": {
"codeshave": {
"command": "codeshave",
"args": ["mcp"]
}
}
}
5. VS Code (Copilot & Cline / Roo Code)
In .vscode/mcp.json or Cline MCP settings:
{
"mcpServers": {
"codeshave": {
"command": "codeshave",
"args": ["mcp"]
}
}
}
⚡ Triggering CodeShave: @ Mentions, / Slash Commands & Auto-Rules
❓ Why Doesn't My AI Use MCP Tools Automatically?
Many developers install an MCP server and wonder: "Why is my AI assistant still reading raw files or using custom scripts instead of calling CodeShave?"
AI models (Claude 3.7/3.5, GPT-4o, Gemini, Cursor Composer, Windsurf Cascade) naturally have tool inertia—they default to generic built-in tools (read_file or terminal commands) that they were trained on, frequently dumping 5,000+ to 20,000+ line files into the context window and burning hundreds of thousands of tokens unnecessarily.
With CodeShave, you can control your assistant in two simple ways:
- Interactive Triggering: Use
@codeshaveor/codeshavedirectly in chat when prompting. - 100% Automated Hands-Free Rules: Add a 1-line rule file to your repository so the AI always defaults to CodeShave on Turn 1 without needing any manual mention!
🕹️ Universal AI Trigger & Command Matrix
| AI Assistant / IDE | Interactive Command (@ / /) |
How to Trigger in Chat | 100% Hands-Free Rule File | What Happens Under the Hood |
|---|---|---|---|---|
| Cursor IDE | @codeshave |
Type @codeshave in Composer / Chat |
.cursorrules |
Cursor attaches CodeShave MCP tools directly to the context bundle |
| Windsurf (Cascade) | @codeshave |
Type @ in Cascade chat input |
.windsurfrules |
Cascade displays shave_file tool call card before reading files |
| Google Antigravity | /codeshave or @codeshave |
Type /codeshave slash command |
GEMINI.md |
Activates /codeshave skill, compressing files with 90%+ token reduction |
| GitHub Copilot / VS Code | /codeshave or @workspace |
Native slash command via prompt file | .github/copilot-instructions.md |
Executes custom prompt and invokes shave_file across workspace |
| Claude Desktop | Natural Prompt / 🔨 Tray | Click 🔨 Hammer Icon / prompt naturally | CLAUDE.md |
Claude invokes shave_file before generating reasoning output |
1. Cursor IDE (@codeshave & .cursorrules)
- Interactive Usage:
In Cursor Composer (
Ctrl+I/Cmd+I) or Chat (Ctrl+L/Cmd+L), type@codeshave:> @codeshave inspect this repository and list all API endpoints
Cursor autocompletes the MCP tool and bindsshave_fileandshave_codedirectly. - Zero-Prompt Automation:
Create
.cursorrulesin your project root:# .cursorrules Always prioritize calling the `codeshave` MCP tool (`shave_file` or `shave_code`) when analyzing, searching, or exploring source code files. This loads the structural AST skeleton (90%+ token savings) before reading specific implementation ranges.
2. Windsurf Editor (@codeshave & .windsurfrules)
- Interactive Usage:
In the Cascade chat bar, type
@to open the context selector and choosecodeshave:> @codeshave analyze the auth pipeline in src/services/auth.ts
- Zero-Prompt Automation:
Create
.windsurfrulesin your project root:# .windsurfrules When exploring project architecture or scanning files across Python, TypeScript, Go, Rust, Java, C++, and C#, always invoke CodeShave MCP (`shave_file`) first. Never dump full raw multi-thousand-line files into context when a structural skeleton is sufficient.
3. Google Antigravity (/codeshave & GEMINI.md)
- Interactive Usage:
Type
/codeshavedirectly in the Antigravity chat input:> /codeshave explore src/ and summarize the database layer
Antigravity immediately executes the/codeshaveskill, compressing all targeted files down to syntax-valid AST skeletons in ~150ms. - Zero-Prompt Automation:
Add to your
GEMINI.md(or workspace rules):# GEMINI.md Always prioritize calling the `codeshave` MCP (`shave_file` or `shave_code`) or activating `/codeshave` when analyzing or exploring code files to inspect AST skeletons (90%+ savings) before reading raw lines.
4. GitHub Copilot & VS Code (/codeshave Prompt & Instructions)
- Custom Slash Command:
VS Code supports custom prompt files. Create
.github/prompts/codeshave.prompt.md:--- name: codeshave description: Shave and compress code AST skeletons to reduce context tokens by 85%+ --- Use the codeshave MCP server (`shave_file` or `shave_code`) to inspect structural AST skeletons across workspace files before reading full raw implementation bodies into context.
Typing/codeshavein Copilot Chat will now execute this prompt natively! - Zero-Prompt Automation:
Create
.github/copilot-instructions.mdin your repo:# .github/copilot-instructions.md When analyzing, reviewing, or exploring files in this repository, always call the CodeShave MCP server tools (`shave_file` or `shave_code`) first to save up to 85% of context window tokens.
5. Claude Desktop (🔨 Tool Tray & CLAUDE.md)
- Interactive Usage:
- Open Claude Desktop and confirm the 🔨 (Hammer icon) in the bottom right corner displays
codeshave (2 tools). - Prompt Claude naturally:
> Use codeshave to shave src/server.go and analyze its handlers.
- Open Claude Desktop and confirm the 🔨 (Hammer icon) in the bottom right corner displays
- Zero-Prompt Automation:
Create
CLAUDE.mdin your project root:# CLAUDE.md Always prioritize calling the `codeshave` MCP tools (`shave_file` or `shave_code`) when analyzing or exploring code to preserve full types and signatures while keeping context lean.
📦 Ready-to-Use Drop-in Rule Pack
You can copy these pre-configured rule files directly into your existing repositories:
.cursorrules— Cursor IDE auto-compression rule.windsurfrules— Windsurf Cascade auto-compression ruleGEMINI.md— Google Antigravity & Gemini ruleCLAUDE.md— Claude Desktop project guideline.github/copilot-instructions.md— GitHub Copilot instruction.github/prompts/codeshave.prompt.md— Custom/codeshavecommand for Copilot Chat
🐍 Python SDK
from codeshave import compress_code, compute_savings
# Compresses any language (Python, TypeScript, Go, Rust, Java, etc.)
code = open("UserService.ts").read()
skeleton = compress_code(code, filename_or_ext="UserService.ts")
report = compute_savings(code, skeleton)
print(skeleton)
print(report.summary_line())
# -> Original: 4,520 tokens | Skeleton: 790 tokens | Saved: 3,730 tokens (-82.5%)
📊 Token Savings Benchmark
| Source Language | Original Tokens | CodeShave Skeleton | Reduction | Syntax Preservation |
|---|---|---|---|---|
| Python (Data Models & API) | 134,069 t | 15,393 t | 88.5% | ✅ 100% Valid AST |
| TypeScript (React & Services) | 12,450 t | 2,180 t | 82.5% | ✅ Interfaces & Signatures |
| Go (HTTP API & Router) | 8,920 t | 1,420 t | 84.1% | ✅ Structs & Receivers |
| Rust (Engine & Impl) | 14,200 t | 2,450 t | 82.7% | ✅ Traits & Fn Signatures |
| Java (Enterprise Services) | 18,300 t | 3,100 t | 83.1% | ✅ Classes & Types |
| C++ (Core Algorithms) | 11,500 t | 2,050 t | 82.2% | ✅ Headers & Declarations |
💖 Sponsorship & Backing
If CodeShave saves you tokens, reduces your LLM API bills, or accelerates your AI agent workflow, consider supporting ongoing open-source development:
- Buy Me A Coffee: https://buymeacoffee.com/jaideep.360
- GitHub Sponsors: https://github.com/sponsors/jaideepkrishna2008-ui
📄 License
Created by Jaideep Krishna A (@jaideepkrishna2008-ui). Licensed under the MIT License.
Metadata
Release files for codeshave 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| codeshave-0.2.0.tar.gz | 30.4 kB | Without provenance | Details for codeshave-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| codeshave-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for codeshave-0.2.0-py3-none-any.whl |
Total release size: 54.5 kB
Release files / codeshave-0.2.0.tar.gz
| Download URL | codeshave-0.2.0.tar.gz |
|---|---|
| Size | 30.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
71dbb61d30fb9c1fad1f5d2665810b3d90967d5f5281ece04bbe95268b0cb637
|
|
BLAKE2b-256 checksum How to use checksums |
12df4a39ebc593e2d03ab97012ac2fa78eaef9c9406044cfbc19799b019f2df9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.11
|
Release files / codeshave-0.2.0-py3-none-any.whl
| Download URL | codeshave-0.2.0-py3-none-any.whl |
|---|---|
| Size | 24.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dd0a82fdba9ecdedd726ee2936d1a1f182d93726e57b591d878a1fd699f120c0
|
|
BLAKE2b-256 checksum How to use checksums |
7a4c7887cd7790cf712f26ef9244fd2073425a3358935d1115466a708adf5cbd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.11
|
Security for codeshave 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.