codeshave 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- codeshave-0.1.0/PKG-INFO +158 -0
- codeshave-0.1.0/README.md +150 -0
- codeshave-0.1.0/codeshave/__init__.py +24 -0
- codeshave-0.1.0/codeshave/__main__.py +8 -0
- codeshave-0.1.0/codeshave/cli.py +270 -0
- codeshave-0.1.0/codeshave/clipboard.py +77 -0
- codeshave-0.1.0/codeshave/estimator.py +68 -0
- codeshave-0.1.0/codeshave/formatters.py +85 -0
- codeshave-0.1.0/codeshave/graph.py +75 -0
- codeshave-0.1.0/codeshave/mcp.py +153 -0
- codeshave-0.1.0/codeshave/parser.py +179 -0
- codeshave-0.1.0/codeshave.egg-info/PKG-INFO +158 -0
- codeshave-0.1.0/codeshave.egg-info/SOURCES.txt +19 -0
- codeshave-0.1.0/codeshave.egg-info/dependency_links.txt +1 -0
- codeshave-0.1.0/codeshave.egg-info/entry_points.txt +2 -0
- codeshave-0.1.0/codeshave.egg-info/top_level.txt +1 -0
- codeshave-0.1.0/pyproject.toml +18 -0
- codeshave-0.1.0/setup.cfg +4 -0
- codeshave-0.1.0/tests/test_cli.py +53 -0
- codeshave-0.1.0/tests/test_estimator.py +17 -0
- codeshave-0.1.0/tests/test_parser.py +80 -0
codeshave-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: codeshave
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Deterministic AST code context compressor for AI coding assistants and local models
|
|
5
|
+
Author-email: Jaideep Krishna A <jaideepkrishna2008@gmail.com>
|
|
6
|
+
Requires-Python: >=3.10
|
|
7
|
+
Description-Content-Type: text/markdown
|
|
8
|
+
|
|
9
|
+
# CodeShave
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<img src="assets/banner.svg" alt="CodeShave Banner" width="100%">
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
<p align="center">
|
|
16
|
+
<b>High-speed, deterministic AST code context compressor for AI coding assistants and local LLMs.</b><br>
|
|
17
|
+
Reduces prompt tokens by 60% to 80% while preserving valid syntax, type signatures, and class hierarchies.
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## ⚡ Terminal Demo
|
|
23
|
+
|
|
24
|
+
<p align="center">
|
|
25
|
+
<img src="assets/demo.svg" alt="CodeShave CLI Demonstration" width="100%">
|
|
26
|
+
</p>
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 🎯 Why CodeShave?
|
|
31
|
+
|
|
32
|
+
When developers feed large directories to LLMs or AI agents, context windows quickly fill up, latency spikes, and API token bills mount.
|
|
33
|
+
|
|
34
|
+
Traditional approaches either:
|
|
35
|
+
1. Truncate files blindly, breaking syntax trees and references.
|
|
36
|
+
2. Rely on costly, slow LLMs to summarize code before prompting.
|
|
37
|
+
|
|
38
|
+
**CodeShave** uses Python's native Abstract Syntax Tree (AST) engine to deterministically transform code into clean interface skeletons:
|
|
39
|
+
- Strips implementation logic inside functions and replaces with `...`.
|
|
40
|
+
- Preserves all class structures, inheritance, and attributes.
|
|
41
|
+
- Retains parameter type annotations, defaults, and return types.
|
|
42
|
+
- Maintains decorators, docstrings, and module-level exports.
|
|
43
|
+
- Formats context blocks into Markdown, Claude-optimized XML, or JSON.
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## 🏗️ Architecture
|
|
48
|
+
|
|
49
|
+
<p align="center">
|
|
50
|
+
<img src="assets/architecture.svg" alt="CodeShave Architecture Diagram" width="100%">
|
|
51
|
+
</p>
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## 🚀 Quickstart
|
|
56
|
+
|
|
57
|
+
### Installation
|
|
58
|
+
|
|
59
|
+
Install directly via `pip` from GitHub:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
pip install git+https://github.com/jaideepkrishna2008-ui/codeshave.git
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Or clone for local development:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
git clone https://github.com/jaideepkrishna2008-ui/codeshave.git
|
|
69
|
+
cd codeshave
|
|
70
|
+
pip install -e .
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### ⚡ CLI Commands
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
# 📋 One-Click Clipboard Copy: Compress and copy directly to clipboard
|
|
77
|
+
codeshave clip ./src
|
|
78
|
+
codeshave clip ./src/models.py
|
|
79
|
+
# -> Copied to clipboard! Ready to paste directly into ChatGPT, Claude, or Cursor!
|
|
80
|
+
|
|
81
|
+
# 📦 Pack directory into an LLM context bundle
|
|
82
|
+
codeshave pack ./src -o llm_context.md
|
|
83
|
+
|
|
84
|
+
# 🏷️ Generate Claude-optimized XML bundle with live savings statistics
|
|
85
|
+
codeshave pack ./src --format xml --stats -o llm_context.xml
|
|
86
|
+
|
|
87
|
+
# 🔍 Inspect a single file's compressed skeleton
|
|
88
|
+
codeshave inspect ./src/services/billing.py
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## 🔌 Model Context Protocol (MCP) Integration
|
|
94
|
+
|
|
95
|
+
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:
|
|
96
|
+
|
|
97
|
+
Add to your `claude_desktop_config.json`:
|
|
98
|
+
|
|
99
|
+
```json
|
|
100
|
+
{
|
|
101
|
+
"mcpServers": {
|
|
102
|
+
"codeshave": {
|
|
103
|
+
"command": "codeshave",
|
|
104
|
+
"args": ["mcp"]
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### Python API
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
from codeshave import compress_source, compute_savings
|
|
114
|
+
|
|
115
|
+
raw_code = open("service.py").read()
|
|
116
|
+
skeleton = compress_source(raw_code, preserve_docstrings=True)
|
|
117
|
+
report = compute_savings(raw_code, skeleton)
|
|
118
|
+
|
|
119
|
+
print(skeleton)
|
|
120
|
+
print(report.summary_line())
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## 📊 Token Savings Benchmark
|
|
126
|
+
|
|
127
|
+
| Source Type | Original Tokens | CodeShave Skeleton | Reduction | Syntax Status |
|
|
128
|
+
| :--- | :--- | :--- | :--- | :--- |
|
|
129
|
+
| Data Models | 3,460 t | 920 t | **73.4%** | ✅ Valid AST |
|
|
130
|
+
| API Endpoints | 4,210 t | 780 t | **81.5%** | ✅ Valid AST |
|
|
131
|
+
| Business Logic | 6,840 t | 1,120 t | **83.6%** | ✅ Valid AST |
|
|
132
|
+
| Utility Scripts | 1,000 t | 400 t | **60.0%** | ✅ Valid AST |
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## 💖 Sponsorship & Backing
|
|
137
|
+
|
|
138
|
+
If CodeShave saves you tokens, reduces your API bills, or accelerates your agent workflow, consider supporting ongoing open-source development:
|
|
139
|
+
|
|
140
|
+
<p align="left">
|
|
141
|
+
<a href="https://buymeacoffee.com/jaideep.360" target="_blank">
|
|
142
|
+
<img src="https://img.shields.io/badge/Buy%20Me%20A%20Coffee-jaideep.360-orange?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me A Coffee" />
|
|
143
|
+
</a>
|
|
144
|
+
|
|
145
|
+
<a href="https://github.com/sponsors/jaideepkrishna2008-ui" target="_blank">
|
|
146
|
+
<img src="https://img.shields.io/badge/Sponsor%20on%20GitHub-jaideepkrishna2008--ui-ea4aaa?style=for-the-badge&logo=github-sponsors" alt="Sponsor on GitHub" />
|
|
147
|
+
</a>
|
|
148
|
+
</p>
|
|
149
|
+
|
|
150
|
+
* **Buy Me A Coffee**: [https://buymeacoffee.com/jaideep.360](https://buymeacoffee.com/jaideep.360)
|
|
151
|
+
* **GitHub Sponsors**: [https://github.com/sponsors/jaideepkrishna2008-ui](https://github.com/sponsors/jaideepkrishna2008-ui)
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## 📄 License
|
|
156
|
+
|
|
157
|
+
Created by **Jaideep Krishna A** ([@jaideepkrishna2008-ui](https://github.com/jaideepkrishna2008-ui)).
|
|
158
|
+
Licensed under the Apache License 2.0 or MIT equivalent open-source terms.
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# CodeShave
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img src="assets/banner.svg" alt="CodeShave Banner" width="100%">
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<b>High-speed, deterministic AST code context compressor for AI coding assistants and local LLMs.</b><br>
|
|
9
|
+
Reduces prompt tokens by 60% to 80% while preserving valid syntax, type signatures, and class hierarchies.
|
|
10
|
+
</p>
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## ⚡ Terminal Demo
|
|
15
|
+
|
|
16
|
+
<p align="center">
|
|
17
|
+
<img src="assets/demo.svg" alt="CodeShave CLI Demonstration" width="100%">
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 🎯 Why CodeShave?
|
|
23
|
+
|
|
24
|
+
When developers feed large directories to LLMs or AI agents, context windows quickly fill up, latency spikes, and API token bills mount.
|
|
25
|
+
|
|
26
|
+
Traditional approaches either:
|
|
27
|
+
1. Truncate files blindly, breaking syntax trees and references.
|
|
28
|
+
2. Rely on costly, slow LLMs to summarize code before prompting.
|
|
29
|
+
|
|
30
|
+
**CodeShave** uses Python's native Abstract Syntax Tree (AST) engine to deterministically transform code into clean interface skeletons:
|
|
31
|
+
- Strips implementation logic inside functions and replaces with `...`.
|
|
32
|
+
- Preserves all class structures, inheritance, and attributes.
|
|
33
|
+
- Retains parameter type annotations, defaults, and return types.
|
|
34
|
+
- Maintains decorators, docstrings, and module-level exports.
|
|
35
|
+
- Formats context blocks into Markdown, Claude-optimized XML, or JSON.
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## 🏗️ Architecture
|
|
40
|
+
|
|
41
|
+
<p align="center">
|
|
42
|
+
<img src="assets/architecture.svg" alt="CodeShave Architecture Diagram" width="100%">
|
|
43
|
+
</p>
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## 🚀 Quickstart
|
|
48
|
+
|
|
49
|
+
### Installation
|
|
50
|
+
|
|
51
|
+
Install directly via `pip` from GitHub:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pip install git+https://github.com/jaideepkrishna2008-ui/codeshave.git
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Or clone for local development:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
git clone https://github.com/jaideepkrishna2008-ui/codeshave.git
|
|
61
|
+
cd codeshave
|
|
62
|
+
pip install -e .
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### ⚡ CLI Commands
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
# 📋 One-Click Clipboard Copy: Compress and copy directly to clipboard
|
|
69
|
+
codeshave clip ./src
|
|
70
|
+
codeshave clip ./src/models.py
|
|
71
|
+
# -> Copied to clipboard! Ready to paste directly into ChatGPT, Claude, or Cursor!
|
|
72
|
+
|
|
73
|
+
# 📦 Pack directory into an LLM context bundle
|
|
74
|
+
codeshave pack ./src -o llm_context.md
|
|
75
|
+
|
|
76
|
+
# 🏷️ Generate Claude-optimized XML bundle with live savings statistics
|
|
77
|
+
codeshave pack ./src --format xml --stats -o llm_context.xml
|
|
78
|
+
|
|
79
|
+
# 🔍 Inspect a single file's compressed skeleton
|
|
80
|
+
codeshave inspect ./src/services/billing.py
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## 🔌 Model Context Protocol (MCP) Integration
|
|
86
|
+
|
|
87
|
+
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:
|
|
88
|
+
|
|
89
|
+
Add to your `claude_desktop_config.json`:
|
|
90
|
+
|
|
91
|
+
```json
|
|
92
|
+
{
|
|
93
|
+
"mcpServers": {
|
|
94
|
+
"codeshave": {
|
|
95
|
+
"command": "codeshave",
|
|
96
|
+
"args": ["mcp"]
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Python API
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
from codeshave import compress_source, compute_savings
|
|
106
|
+
|
|
107
|
+
raw_code = open("service.py").read()
|
|
108
|
+
skeleton = compress_source(raw_code, preserve_docstrings=True)
|
|
109
|
+
report = compute_savings(raw_code, skeleton)
|
|
110
|
+
|
|
111
|
+
print(skeleton)
|
|
112
|
+
print(report.summary_line())
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## 📊 Token Savings Benchmark
|
|
118
|
+
|
|
119
|
+
| Source Type | Original Tokens | CodeShave Skeleton | Reduction | Syntax Status |
|
|
120
|
+
| :--- | :--- | :--- | :--- | :--- |
|
|
121
|
+
| Data Models | 3,460 t | 920 t | **73.4%** | ✅ Valid AST |
|
|
122
|
+
| API Endpoints | 4,210 t | 780 t | **81.5%** | ✅ Valid AST |
|
|
123
|
+
| Business Logic | 6,840 t | 1,120 t | **83.6%** | ✅ Valid AST |
|
|
124
|
+
| Utility Scripts | 1,000 t | 400 t | **60.0%** | ✅ Valid AST |
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## 💖 Sponsorship & Backing
|
|
129
|
+
|
|
130
|
+
If CodeShave saves you tokens, reduces your API bills, or accelerates your agent workflow, consider supporting ongoing open-source development:
|
|
131
|
+
|
|
132
|
+
<p align="left">
|
|
133
|
+
<a href="https://buymeacoffee.com/jaideep.360" target="_blank">
|
|
134
|
+
<img src="https://img.shields.io/badge/Buy%20Me%20A%20Coffee-jaideep.360-orange?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me A Coffee" />
|
|
135
|
+
</a>
|
|
136
|
+
|
|
137
|
+
<a href="https://github.com/sponsors/jaideepkrishna2008-ui" target="_blank">
|
|
138
|
+
<img src="https://img.shields.io/badge/Sponsor%20on%20GitHub-jaideepkrishna2008--ui-ea4aaa?style=for-the-badge&logo=github-sponsors" alt="Sponsor on GitHub" />
|
|
139
|
+
</a>
|
|
140
|
+
</p>
|
|
141
|
+
|
|
142
|
+
* **Buy Me A Coffee**: [https://buymeacoffee.com/jaideep.360](https://buymeacoffee.com/jaideep.360)
|
|
143
|
+
* **GitHub Sponsors**: [https://github.com/sponsors/jaideepkrishna2008-ui](https://github.com/sponsors/jaideepkrishna2008-ui)
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## 📄 License
|
|
148
|
+
|
|
149
|
+
Created by **Jaideep Krishna A** ([@jaideepkrishna2008-ui](https://github.com/jaideepkrishna2008-ui)).
|
|
150
|
+
Licensed under the Apache License 2.0 or MIT equivalent open-source terms.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"""
|
|
2
|
+
CodeShave
|
|
3
|
+
============
|
|
4
|
+
High-speed, zero-loss AST code context compressor for AI coding assistants and LLMs.
|
|
5
|
+
Reduces prompt tokens by 60-80% while retaining 100% syntactically valid Python code.
|
|
6
|
+
|
|
7
|
+
Author: Jaideep Krishna A (@jaideepkrishna2008-ui)
|
|
8
|
+
License: MIT
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from codeshave.parser import compress_source, extract_symbols
|
|
12
|
+
from codeshave.estimator import estimate_tokens, compute_savings
|
|
13
|
+
from codeshave.graph import DependencyResolver
|
|
14
|
+
from codeshave.formatters import format_bundle
|
|
15
|
+
|
|
16
|
+
__version__ = "0.1.0"
|
|
17
|
+
__all__ = [
|
|
18
|
+
"compress_source",
|
|
19
|
+
"extract_symbols",
|
|
20
|
+
"estimate_tokens",
|
|
21
|
+
"compute_savings",
|
|
22
|
+
"DependencyResolver",
|
|
23
|
+
"format_bundle",
|
|
24
|
+
]
|
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
"""
|
|
2
|
+
CLI interface for CodeShave.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
import argparse
|
|
8
|
+
import sys
|
|
9
|
+
import time
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
from typing import List
|
|
12
|
+
|
|
13
|
+
from codeshave import __version__
|
|
14
|
+
from codeshave.clipboard import copy_to_clipboard
|
|
15
|
+
from codeshave.estimator import compute_savings, estimate_tokens
|
|
16
|
+
from codeshave.formatters import FileContextItem, format_bundle
|
|
17
|
+
from codeshave.graph import DependencyResolver
|
|
18
|
+
from codeshave.mcp import run_mcp_server
|
|
19
|
+
from codeshave.parser import compress_source
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
DEFAULT_EXCLUDES = {
|
|
23
|
+
".git",
|
|
24
|
+
".venv",
|
|
25
|
+
"venv",
|
|
26
|
+
"env",
|
|
27
|
+
"__pycache__",
|
|
28
|
+
".pytest_cache",
|
|
29
|
+
".mypy_cache",
|
|
30
|
+
".ruff_cache",
|
|
31
|
+
"build",
|
|
32
|
+
"dist",
|
|
33
|
+
"node_modules",
|
|
34
|
+
"tests",
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def find_python_files(target: Path, excludes: set[str]) -> List[Path]:
|
|
39
|
+
"""Recursively finds all Python files excluding common build/test folders."""
|
|
40
|
+
if target.is_file():
|
|
41
|
+
return [target]
|
|
42
|
+
|
|
43
|
+
found: List[Path] = []
|
|
44
|
+
for p in sorted(target.rglob("*.py")):
|
|
45
|
+
parts = set(p.parts)
|
|
46
|
+
if parts.intersection(excludes):
|
|
47
|
+
continue
|
|
48
|
+
found.append(p)
|
|
49
|
+
return found
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def handle_pack(args: argparse.Namespace) -> int:
|
|
53
|
+
target = Path(args.path).resolve()
|
|
54
|
+
if not target.exists():
|
|
55
|
+
sys.stderr.write(f"Error: Target path '{args.path}' does not exist.\n")
|
|
56
|
+
return 1
|
|
57
|
+
|
|
58
|
+
start_time = time.perf_counter()
|
|
59
|
+
excludes = DEFAULT_EXCLUDES.copy()
|
|
60
|
+
if args.exclude:
|
|
61
|
+
for ex in args.exclude.split(","):
|
|
62
|
+
excludes.add(ex.strip())
|
|
63
|
+
|
|
64
|
+
files = find_python_files(target, excludes)
|
|
65
|
+
if not files:
|
|
66
|
+
sys.stderr.write("No Python files found to process.\n")
|
|
67
|
+
return 1
|
|
68
|
+
|
|
69
|
+
# Dependency resolution ordering
|
|
70
|
+
if target.is_dir() and not args.no_sort:
|
|
71
|
+
resolver = DependencyResolver(target)
|
|
72
|
+
files = resolver.sort_files_by_dependency(files)
|
|
73
|
+
|
|
74
|
+
items: List[FileContextItem] = []
|
|
75
|
+
total_orig_tokens = 0
|
|
76
|
+
total_comp_tokens = 0
|
|
77
|
+
|
|
78
|
+
if args.stats or not args.output:
|
|
79
|
+
sys.stderr.write(f"\n⚡ CodeShave v{__version__} — AST Structural Compressor\n")
|
|
80
|
+
sys.stderr.write(f"Scanning: {target}\n\n")
|
|
81
|
+
header = f"{'FILE':<45} {'ORIGINAL':<12} {'SKELETON':<12} {'SAVINGS':<10}"
|
|
82
|
+
sys.stderr.write(header + "\n")
|
|
83
|
+
sys.stderr.write("─" * len(header) + "\n")
|
|
84
|
+
|
|
85
|
+
for f in files:
|
|
86
|
+
rel_path = f.relative_to(target) if target.is_dir() else f.name
|
|
87
|
+
try:
|
|
88
|
+
content = f.read_text(encoding="utf-8")
|
|
89
|
+
compressed = compress_source(
|
|
90
|
+
content,
|
|
91
|
+
preserve_docstrings=not args.no_docs,
|
|
92
|
+
preserve_private=not args.no_private,
|
|
93
|
+
)
|
|
94
|
+
orig_t = estimate_tokens(content)
|
|
95
|
+
comp_t = estimate_tokens(compressed)
|
|
96
|
+
|
|
97
|
+
total_orig_tokens += orig_t
|
|
98
|
+
total_comp_tokens += comp_t
|
|
99
|
+
|
|
100
|
+
items.append(
|
|
101
|
+
FileContextItem(
|
|
102
|
+
relative_path=str(rel_path).replace("\\", "/"),
|
|
103
|
+
original_code=content,
|
|
104
|
+
compressed_code=compressed,
|
|
105
|
+
original_tokens=orig_t,
|
|
106
|
+
compressed_tokens=comp_t,
|
|
107
|
+
)
|
|
108
|
+
)
|
|
109
|
+
|
|
110
|
+
pct = ((1.0 - comp_t / orig_t) * 100.0) if orig_t > 0 else 0.0
|
|
111
|
+
if args.stats or not args.output:
|
|
112
|
+
path_str = str(rel_path).replace("\\", "/")
|
|
113
|
+
if len(path_str) > 43:
|
|
114
|
+
path_str = "..." + path_str[-40:]
|
|
115
|
+
sys.stderr.write(
|
|
116
|
+
f"{path_str:<45} {orig_t:>8,} t {comp_t:>8,} t {pct:>8.1f}%\n"
|
|
117
|
+
)
|
|
118
|
+
except Exception as exc:
|
|
119
|
+
sys.stderr.write(f"Skipping {rel_path}: {exc}\n")
|
|
120
|
+
|
|
121
|
+
elapsed_ms = (time.perf_counter() - start_time) * 1000.0
|
|
122
|
+
saved = max(0, total_orig_tokens - total_comp_tokens)
|
|
123
|
+
overall_pct = (saved / total_orig_tokens * 100.0) if total_orig_tokens > 0 else 0.0
|
|
124
|
+
dollars_saved = (saved / 1_000_000.0) * 3.00
|
|
125
|
+
|
|
126
|
+
if args.stats or not args.output:
|
|
127
|
+
sys.stderr.write("─" * len(header) + "\n")
|
|
128
|
+
sys.stderr.write(
|
|
129
|
+
f"TOTALS ({len(items)} files in {elapsed_ms:.1f}ms):\n"
|
|
130
|
+
f" • Original: {total_orig_tokens:,} tokens\n"
|
|
131
|
+
f" • Compressed: {total_comp_tokens:,} tokens\n"
|
|
132
|
+
f" • Reduction: {saved:,} tokens saved ({overall_pct:.1f}% savings)\n"
|
|
133
|
+
f" • Est. Value: ${dollars_saved:.4f} per prompt call\n\n"
|
|
134
|
+
)
|
|
135
|
+
|
|
136
|
+
bundled = format_bundle(items, output_format=args.format)
|
|
137
|
+
|
|
138
|
+
if args.output:
|
|
139
|
+
out_p = Path(args.output).resolve()
|
|
140
|
+
out_p.parent.mkdir(parents=True, exist_ok=True)
|
|
141
|
+
out_p.write_text(bundled, encoding="utf-8")
|
|
142
|
+
sys.stderr.write(f"✔ Bundle saved successfully to: {out_p}\n")
|
|
143
|
+
else:
|
|
144
|
+
sys.stdout.write(bundled)
|
|
145
|
+
|
|
146
|
+
return 0
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def handle_clip(args: argparse.Namespace) -> int:
|
|
150
|
+
"""Compresses file or directory and copies directly to OS clipboard."""
|
|
151
|
+
target = Path(args.path).resolve()
|
|
152
|
+
if not target.exists():
|
|
153
|
+
sys.stderr.write(f"Error: Target path '{args.path}' does not exist.\n")
|
|
154
|
+
return 1
|
|
155
|
+
|
|
156
|
+
if target.is_file():
|
|
157
|
+
content = target.read_text(encoding="utf-8")
|
|
158
|
+
compressed = compress_source(content, preserve_docstrings=not args.no_docs)
|
|
159
|
+
report = compute_savings(content, compressed)
|
|
160
|
+
formatted = f"# File: {target.name}\n```python\n{compressed}\n```\n"
|
|
161
|
+
copied = copy_to_clipboard(formatted)
|
|
162
|
+
if copied:
|
|
163
|
+
sys.stderr.write(
|
|
164
|
+
f"✔ Copied to clipboard! {report.summary_line()} "
|
|
165
|
+
f"(-{report.reduction_percentage:.1f}%)\n"
|
|
166
|
+
f"Ready to paste into ChatGPT, Claude, or Cursor.\n"
|
|
167
|
+
)
|
|
168
|
+
return 0
|
|
169
|
+
else:
|
|
170
|
+
sys.stdout.write(formatted)
|
|
171
|
+
return 0
|
|
172
|
+
else:
|
|
173
|
+
# Directory pack into markdown and copy
|
|
174
|
+
files = find_python_files(target, DEFAULT_EXCLUDES)
|
|
175
|
+
if not files:
|
|
176
|
+
sys.stderr.write("No Python files found.\n")
|
|
177
|
+
return 1
|
|
178
|
+
items = []
|
|
179
|
+
total_orig = 0
|
|
180
|
+
total_comp = 0
|
|
181
|
+
for f in files:
|
|
182
|
+
rel = f.relative_to(target)
|
|
183
|
+
code = f.read_text(encoding="utf-8")
|
|
184
|
+
comp = compress_source(code, preserve_docstrings=not args.no_docs)
|
|
185
|
+
ot = estimate_tokens(code)
|
|
186
|
+
ct = estimate_tokens(comp)
|
|
187
|
+
total_orig += ot
|
|
188
|
+
total_comp += ct
|
|
189
|
+
items.append(FileContextItem(str(rel), code, comp, ot, ct))
|
|
190
|
+
|
|
191
|
+
bundle = format_bundle(items, output_format="md")
|
|
192
|
+
saved = max(0, total_orig - total_comp)
|
|
193
|
+
pct = (saved / total_orig * 100.0) if total_orig > 0 else 0.0
|
|
194
|
+
copy_to_clipboard(bundle)
|
|
195
|
+
sys.stderr.write(
|
|
196
|
+
f"✔ Copied {len(items)} files to clipboard! "
|
|
197
|
+
f"({total_orig:,} t -> {total_comp:,} t, -{pct:.1f}% saved)\n"
|
|
198
|
+
f"Ready to paste directly into LLM prompt.\n"
|
|
199
|
+
)
|
|
200
|
+
return 0
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
def handle_inspect(args: argparse.Namespace) -> int:
|
|
204
|
+
target = Path(args.path).resolve()
|
|
205
|
+
if not target.is_file():
|
|
206
|
+
sys.stderr.write(f"Error: Target '{args.path}' must be an existing file.\n")
|
|
207
|
+
return 1
|
|
208
|
+
|
|
209
|
+
content = target.read_text(encoding="utf-8")
|
|
210
|
+
compressed = compress_source(content, preserve_docstrings=not args.no_docs)
|
|
211
|
+
report = compute_savings(content, compressed)
|
|
212
|
+
|
|
213
|
+
sys.stdout.write(f"# Compressed AST Skeleton for {target.name}\n")
|
|
214
|
+
sys.stdout.write(f"# {report.summary_line()}\n\n")
|
|
215
|
+
sys.stdout.write(compressed + "\n")
|
|
216
|
+
return 0
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def main() -> None:
|
|
220
|
+
parser = argparse.ArgumentParser(
|
|
221
|
+
prog="codeshave",
|
|
222
|
+
description="⚡ CodeShave: Zero-loss AST code context compressor for AI coding assistants.",
|
|
223
|
+
)
|
|
224
|
+
parser.add_argument("-v", "--version", action="version", version=f"codeshave {__version__}")
|
|
225
|
+
subparsers = parser.add_subparsers(dest="command", required=True)
|
|
226
|
+
|
|
227
|
+
# Pack command
|
|
228
|
+
pack_p = subparsers.add_parser("pack", help="Compress codebase directory into an LLM context bundle")
|
|
229
|
+
pack_p.add_argument("path", help="Source file or directory to compress")
|
|
230
|
+
pack_p.add_argument("-o", "--output", help="Output file path (default: stdout)")
|
|
231
|
+
pack_p.add_argument(
|
|
232
|
+
"-f",
|
|
233
|
+
"--format",
|
|
234
|
+
choices=["md", "xml", "json"],
|
|
235
|
+
default="md",
|
|
236
|
+
help="Context bundle format (default: md)",
|
|
237
|
+
)
|
|
238
|
+
pack_p.add_argument("--no-docs", action="store_true", help="Omit docstrings for maximum token savings")
|
|
239
|
+
pack_p.add_argument("--no-private", action="store_true", help="Omit private functions (_func)")
|
|
240
|
+
pack_p.add_argument("--no-sort", action="store_true", help="Disable dependency topological ordering")
|
|
241
|
+
pack_p.add_argument("--exclude", help="Comma-separated directories to exclude")
|
|
242
|
+
pack_p.add_argument("--stats", action="store_true", help="Force display of summary metrics")
|
|
243
|
+
|
|
244
|
+
# Clip command
|
|
245
|
+
clip_p = subparsers.add_parser("clip", help="Compress and copy directly to OS clipboard (ready to paste)")
|
|
246
|
+
clip_p.add_argument("path", help="Source file or directory to compress and copy")
|
|
247
|
+
clip_p.add_argument("--no-docs", action="store_true", help="Omit docstrings")
|
|
248
|
+
|
|
249
|
+
# Inspect command
|
|
250
|
+
inspect_p = subparsers.add_parser("inspect", help="Inspect compressed skeleton of a single file")
|
|
251
|
+
inspect_p.add_argument("path", help="Target Python file")
|
|
252
|
+
inspect_p.add_argument("--no-docs", action="store_true", help="Omit docstrings")
|
|
253
|
+
|
|
254
|
+
# MCP command
|
|
255
|
+
subparsers.add_parser("mcp", help="Launch Model Context Protocol (MCP) stdio server")
|
|
256
|
+
|
|
257
|
+
args = parser.parse_args()
|
|
258
|
+
|
|
259
|
+
if args.command == "pack":
|
|
260
|
+
sys.exit(handle_pack(args))
|
|
261
|
+
elif args.command == "clip":
|
|
262
|
+
sys.exit(handle_clip(args))
|
|
263
|
+
elif args.command == "inspect":
|
|
264
|
+
sys.exit(handle_inspect(args))
|
|
265
|
+
elif args.command == "mcp":
|
|
266
|
+
run_mcp_server()
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
if __name__ == "__main__":
|
|
270
|
+
main()
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Zero-dependency cross-platform clipboard copy utility.
|
|
3
|
+
Works on Windows (ctypes Win32), macOS (pbcopy), and Linux (wl-copy / xclip).
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
import sys
|
|
7
|
+
import subprocess
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def copy_to_clipboard(text: str) -> bool:
|
|
11
|
+
"""Copies text to the system clipboard without requiring third-party packages."""
|
|
12
|
+
if sys.platform == "win32":
|
|
13
|
+
try:
|
|
14
|
+
import ctypes
|
|
15
|
+
from ctypes import wintypes
|
|
16
|
+
|
|
17
|
+
user32 = ctypes.windll.user32
|
|
18
|
+
kernel32 = ctypes.windll.kernel32
|
|
19
|
+
|
|
20
|
+
GMEM_MOVEABLE = 0x0002
|
|
21
|
+
CF_UNICODETEXT = 13
|
|
22
|
+
|
|
23
|
+
user32.OpenClipboard.argtypes = [wintypes.HWND]
|
|
24
|
+
user32.OpenClipboard.restype = wintypes.BOOL
|
|
25
|
+
user32.CloseClipboard.argtypes = []
|
|
26
|
+
user32.CloseClipboard.restype = wintypes.BOOL
|
|
27
|
+
user32.EmptyClipboard.argtypes = []
|
|
28
|
+
user32.EmptyClipboard.restype = wintypes.BOOL
|
|
29
|
+
user32.SetClipboardData.argtypes = [wintypes.UINT, wintypes.HANDLE]
|
|
30
|
+
user32.SetClipboardData.restype = wintypes.HANDLE
|
|
31
|
+
|
|
32
|
+
kernel32.GlobalAlloc.argtypes = [wintypes.UINT, ctypes.c_size_t]
|
|
33
|
+
kernel32.GlobalAlloc.restype = wintypes.HGLOBAL
|
|
34
|
+
kernel32.GlobalLock.argtypes = [wintypes.HGLOBAL]
|
|
35
|
+
kernel32.GlobalLock.restype = ctypes.c_void_p
|
|
36
|
+
kernel32.GlobalUnlock.argtypes = [wintypes.HGLOBAL]
|
|
37
|
+
kernel32.GlobalUnlock.restype = wintypes.BOOL
|
|
38
|
+
|
|
39
|
+
encoded = text.encode("utf-16le") + b"\x00\x00"
|
|
40
|
+
h_mem = kernel32.GlobalAlloc(GMEM_MOVEABLE, len(encoded))
|
|
41
|
+
if not h_mem:
|
|
42
|
+
return False
|
|
43
|
+
|
|
44
|
+
ptr = kernel32.GlobalLock(h_mem)
|
|
45
|
+
if not ptr:
|
|
46
|
+
return False
|
|
47
|
+
|
|
48
|
+
ctypes.memmove(ptr, encoded, len(encoded))
|
|
49
|
+
kernel32.GlobalUnlock(h_mem)
|
|
50
|
+
|
|
51
|
+
if not user32.OpenClipboard(None):
|
|
52
|
+
return False
|
|
53
|
+
|
|
54
|
+
user32.EmptyClipboard()
|
|
55
|
+
user32.SetClipboardData(CF_UNICODETEXT, h_mem)
|
|
56
|
+
user32.CloseClipboard()
|
|
57
|
+
return True
|
|
58
|
+
except Exception:
|
|
59
|
+
pass
|
|
60
|
+
|
|
61
|
+
# Fallback to standard CLI utilities
|
|
62
|
+
commands = []
|
|
63
|
+
if sys.platform == "darwin":
|
|
64
|
+
commands = [["pbcopy"]]
|
|
65
|
+
else:
|
|
66
|
+
commands = [["wl-copy"], ["xclip", "-selection", "clipboard"], ["xsel", "--clipboard", "--input"]]
|
|
67
|
+
|
|
68
|
+
for cmd in commands:
|
|
69
|
+
try:
|
|
70
|
+
proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, close_fds=True)
|
|
71
|
+
proc.communicate(input=text.encode("utf-8"))
|
|
72
|
+
if proc.returncode == 0:
|
|
73
|
+
return True
|
|
74
|
+
except Exception:
|
|
75
|
+
continue
|
|
76
|
+
|
|
77
|
+
return False
|