Skip to main content

CodeShave

CodeShave Banner

High-speed, deterministic AST code context compressor for AI coding assistants and local LLMs.
Reduces prompt tokens by 60% to 80% while preserving valid syntax, type signatures, and class hierarchies.


⚡ Terminal Demo

CodeShave CLI Demonstration


🎯 Why CodeShave?

When developers feed large directories to LLMs or AI agents, context windows quickly fill up, latency spikes, and API token bills mount.

Traditional approaches either:

  1. Truncate files blindly, breaking syntax trees and references.
  2. Rely on costly, slow LLMs to summarize code before prompting.

CodeShave uses Python's native Abstract Syntax Tree (AST) engine to deterministically transform code into clean interface skeletons:

  • Strips implementation logic inside functions and replaces with ....
  • Preserves all class structures, inheritance, and attributes.
  • Retains parameter type annotations, defaults, and return types.
  • Maintains decorators, docstrings, and module-level exports.
  • Formats context blocks into Markdown, Claude-optimized XML, or JSON.

🏗️ Architecture

CodeShave Architecture Diagram


🚀 Quickstart

Installation

Install directly via pip from GitHub:

pip install git+https://github.com/jaideepkrishna2008-ui/codeshave.git

Or clone for local development:

git clone https://github.com/jaideepkrishna2008-ui/codeshave.git
cd codeshave
pip install -e .

⚡ CLI Commands

# 📋 One-Click Clipboard Copy: Compress and copy directly to clipboard
codeshave clip ./src
codeshave clip ./src/models.py
# -> Copied to clipboard! Ready to paste directly into ChatGPT, Claude, or Cursor!

# 📦 Pack directory into an LLM context bundle
codeshave pack ./src -o llm_context.md

# 🏷️ Generate Claude-optimized XML bundle with live savings statistics
codeshave pack ./src --format xml --stats -o llm_context.xml

# 🔍 Inspect a single file's compressed skeleton
codeshave inspect ./src/services/billing.py

🔌 Model Context Protocol (MCP) Integration

CodeShave runs as a turnkey MCP Server over standard I/O, allowing Claude Desktop, Cursor, and Windsurf to automatically compress files on the fly before reasoning:

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "codeshave": {
      "command": "codeshave",
      "args": ["mcp"]
    }
  }
}

Python API

from codeshave import compress_source, compute_savings

raw_code = open("service.py").read()
skeleton = compress_source(raw_code, preserve_docstrings=True)
report = compute_savings(raw_code, skeleton)

print(skeleton)
print(report.summary_line())

📊 Token Savings Benchmark

Source Type Original Tokens CodeShave Skeleton Reduction Syntax Status
Data Models 3,460 t 920 t 73.4% ✅ Valid AST
API Endpoints 4,210 t 780 t 81.5% ✅ Valid AST
Business Logic 6,840 t 1,120 t 83.6% ✅ Valid AST
Utility Scripts 1,000 t 400 t 60.0% ✅ Valid AST

💖 Sponsorship & Backing

If CodeShave saves you tokens, reduces your API bills, or accelerates your agent workflow, consider supporting ongoing open-source development:

Buy Me A Coffee    Sponsor on GitHub


📄 License

Created by Jaideep Krishna A (@jaideepkrishna2008-ui). Licensed under the Apache License 2.0 or MIT equivalent open-source terms.

Metadata

Release files for codeshave 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for codeshave 0.1.0
File Size Uploaded Provenance Actions
codeshave-0.1.0.tar.gz 15.6 kB Without provenance Details for codeshave-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for codeshave 0.1.0
File Interpreter ABI Platform Actions
codeshave-0.1.0-py3-none-any.whl Python 3 none any Details for codeshave-0.1.0-py3-none-any.whl

Total release size: 30.5 kB

Release files / codeshave-0.1.0.tar.gz

Download URL codeshave-0.1.0.tar.gz
Size 15.6 kB
Tags Source
SHA-256 checksum
How to use checksums
504257391c69103ab57ec77de1064408b22fe8c19e5a608ef57bbb839aeaf6aa
BLAKE2b-256 checksum
How to use checksums
3826466d4ba016c85fb49bb591032392eac40bc37f989a57cd2a8dea6d5fcb94
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.1.0-py3-none-any.whl

Download URL codeshave-0.1.0-py3-none-any.whl
Size 14.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
07125c730c2f4c927c5012aa8b4ba102c887f8932b60eb75694c33c6e73ff4fa
BLAKE2b-256 checksum
How to use checksums
0ca9dc5edf9711d8a440da0541485fd54404263fa91534fea7d99d140716102a
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.1.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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page