tokenzero 0.1.0__tar.gz → 0.1.1__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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: tokenzero
3
- Version: 0.1.0
3
+ Version: 0.1.1
4
4
  Summary: Zero Token Waste - AST Code Skeletonizer & Live AI Monitor for Coding Agents
5
5
  License-Expression: MIT
6
6
  Keywords: tokenzero,tokens,ai-agents,ast,antigravity,claude,cursor,optimization,mcp
@@ -19,68 +19,67 @@ Requires-Dist: httpx>=0.27.0
19
19
  Requires-Dist: tiktoken>=0.7.0
20
20
  Dynamic: license-file
21
21
 
22
- # ⚡ TokenZero
22
+ # TokenZero
23
23
 
24
- **Zero Token Waste for AI Coding Agents (Antigravity, Claude Code, Cursor, Codex).**
24
+ [![PyPI version](https://img.shields.io/pypi/v/tokenzero.svg)](https://pypi.org/project/tokenzero/)
25
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
26
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
25
27
 
26
- TokenZero cuts AI coding token consumption by **70% to 96%** without sacrificing intelligence or code accuracy. It acts as an automated AST code skeletonizer, live real-time token monitor, and tool call interceptor.
28
+ **Zero Token Waste for AI Coding Agents (Antigravity, Claude Code, Cursor, Codex).**
27
29
 
28
- ---
30
+ TokenZero cuts AI coding token consumption by 70% to 73% without sacrificing intelligence or code accuracy. It acts as an automated AST code skeletonizer, live real-time token monitor, and tool call interceptor.
29
31
 
30
- ## 🎯 The Problem TokenZero Solves
32
+ ## The Problem TokenZero Solves
31
33
 
32
34
  When AI agents inspect codebases, they routinely load entire 500–2,000 line source files just to read a single 15-line function.
33
- - **Without TokenZero**: Reading 15 functions across 5 files consumes **~40,000–60,000 tokens**.
34
- - **With TokenZero**: Agents inspect the AST skeletal map and execute targeted partial line-range reads (`StartLine` & `EndLine`), consuming **~2,500–5,000 tokens** (an **85–95% direct reduction**).
35
-
36
- ---
35
+ - Without TokenZero: Reading 15 functions across 5 files consumes ~40,000–60,000 tokens.
36
+ - With TokenZero: Agents inspect the AST skeletal map and execute targeted partial line-range reads (StartLine & EndLine), consuming ~2,500–5,000 tokens (a 70% to 73% direct reduction).
37
37
 
38
- ## ✨ Features
38
+ ## Features
39
39
 
40
- - **🌐 Multi-Language AST Skeletonizer**:
41
- - Python (`.py` via Python AST)
42
- - JavaScript & TypeScript (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs` via structural brace-tracking parser)
43
- - Go (`.go`)
44
- - **⚡ Real-Time Lifecycle Hooks (<2ms)**:
45
- - Intercepts agent tool calls (`read_file`, `edit_file`, `run_command`) on-the-fly via `.agents/hooks.json`.
40
+ - Multi-Language AST Skeletonizer:
41
+ - Python (.py via Python AST)
42
+ - JavaScript & TypeScript (.js, .jsx, .ts, .tsx, .mjs, .cjs via structural brace-tracking parser)
43
+ - Go (.go)
44
+ - Real-Time Lifecycle Hooks (<2ms):
45
+ - Intercepts agent tool calls (read_file, edit_file, run_command) on-the-fly via .agents/hooks.json.
46
46
  - Blocks automated edit popups from IDE diff viewers.
47
47
  - Zero performance overhead.
48
- - **🖥️ Live Activity Dashboard (`tokenzero watch`)**:
49
- - Pure terminal table view showing each file inspection, function targeted, lines read, and **Tokens Used**.
50
- - **ROI & Savings Comparison**: Compares unoptimized token consumption against TokenZero usage and displays exact dollar savings.
51
- - **🧹 Universal Clean Removal (`tokenzero remove`)**:
48
+ - Live Activity Dashboard (tokenzero watch):
49
+ - Pure terminal table view showing each file inspection, function targeted, lines read, and Tokens Used.
50
+ - ROI & Savings Comparison: Compares unoptimized token consumption against TokenZero usage and displays exact dollar savings.
51
+ - Universal Clean Removal (tokenzero remove):
52
52
  - One-command uninstaller that restores the project to its exact original state.
53
- - **🗜️ Standalone Compression Proxy (`tokenzero proxy`)**:
53
+ - Standalone Compression Proxy (tokenzero proxy):
54
54
  - OpenAI-compatible local HTTP proxy for automated prompt payload compression.
55
55
 
56
- ---
57
-
58
- ## 🚀 Quick Start
56
+ ## Quick Start
59
57
 
60
58
  ### 1. Installation
61
59
 
62
- Install globally using `pipx` or standard `pip`:
60
+ Install globally using pipx or standard pip:
63
61
 
64
62
  ```bash
65
- # Recommended: Global CLI installation via pipx
66
- pipx install git+https://github.com/your-username/tokenzero.git
63
+ pip install tokenzero
64
+ ```
67
65
 
68
- # Or install from source:
69
- git clone https://github.com/your-username/tokenzero.git
70
- cd tokenzero
71
- pip install -e .
66
+ Or via pipx:
67
+
68
+ ```bash
69
+ pipx install tokenzero
72
70
  ```
73
71
 
74
72
  ### 2. One-Time Universal Setup
75
73
 
76
- Automatically configure **Google Antigravity**, **Cursor IDE**, **Claude Desktop**, and **Claude Code** with 1 command:
74
+ Automatically configure Google Antigravity, Cursor IDE, Claude Desktop, and Claude Code with 1 command:
77
75
 
78
76
  ```bash
79
77
  tokenzero setup
80
78
  ```
81
- *(Note: If you skip this, running `tokenzero init` or `tokenzero watch` in any project will also auto-configure all your installed AI agents silently on first run!)*
82
79
 
83
- TokenZero registers the Model Context Protocol (MCP) server across your system. **Zero files are added to your project directories!**
80
+ (Note: If you skip this, running tokenzero init or tokenzero watch in any project will also auto-configure all your installed AI agents silently on first run).
81
+
82
+ TokenZero registers the Model Context Protocol (MCP) server across your system. Zero files are added to your project directories.
84
83
 
85
84
  ### 3. Initialize in Any Project (Zero-File Mode)
86
85
 
@@ -91,9 +90,9 @@ cd /path/to/your/project
91
90
  tokenzero init
92
91
  ```
93
92
 
94
- TokenZero indexes the AST code skeleton into your global cache (`~/.tokenzero/cache/`). Your Git repository remains **100% clean with zero untracked files**!
93
+ TokenZero indexes the AST code skeleton into your global cache (~/.tokenzero/cache/). Your Git repository remains 100% clean with zero untracked files.
95
94
 
96
- *(Optional: Use `tokenzero init --local` if you prefer repository-specific rules with auto `.gitignore`).*
95
+ (Optional: Use tokenzero init --local if you prefer repository-specific rules with auto .gitignore).
97
96
 
98
97
  ### 4. Live Monitor
99
98
 
@@ -103,17 +102,9 @@ Open a second terminal or split pane and run:
103
102
  tokenzero watch
104
103
  ```
105
104
 
106
- Watch live tool calls stream in real time as your AI agent inspects and edits code!
107
-
108
- ```bash
109
- tokenzero watch
110
- ```
111
-
112
- Watch live tool calls stream in real time as your AI agent inspects and edits code!
113
-
114
- ---
105
+ Watch live tool calls stream in real time as your AI agent inspects and edits code.
115
106
 
116
- ## 📊 Live Dashboard Preview
107
+ ## Live Dashboard Preview
117
108
 
118
109
  ```text
119
110
  ┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
@@ -127,16 +118,14 @@ Watch live tool calls stream in real time as your AI agent inspects and edits co
127
118
  │ 2026-11-15 23:12:49 │ READ │ WRITEUP_2_PAGES.md:L1-L60 │ 60 / 161 lines │ ~420 tokens │
128
119
  └─────────────────────┴──────────┴────────────────────────────────────────────────┴──────────────────┴─────────────────┘
129
120
 
130
- ╭──────────────────────────────── 📊 TokenZero ROI & Savings Comparison ────────────────────────────────╮
131
- │ Activity: 28 events across 18 files | 🔴 Actual Cost (Without TokenZero): 29,534 tokens ($0.0738) ➜ │
132
- │ 🟢 Used (With TokenZero): 8,064 tokens ($0.0202) │
133
- │ 💰 Net Impact: Saved +21,470 tokens (72.7% reduction) • You Saved $0.0537 USD! │
121
+ ╭──────────────────────────────── TokenZero ROI & Savings Comparison ───────────────────────────────────╮
122
+ │ Activity: 28 events across 18 files | Actual Cost (Without TokenZero): 29,534 tokens ($0.0738) ➜ │
123
+ │ Used (With TokenZero): 8,064 tokens ($0.0202) │
124
+ │ Net Impact: Saved +21,470 tokens (72.7% reduction) • You Saved $0.0537 USD! │
134
125
  ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯
135
126
  ```
136
127
 
137
- ---
138
-
139
- ## 🛠️ CLI Reference
128
+ ## CLI Reference
140
129
 
141
130
  | Command | Description |
142
131
  | :--- | :--- |
@@ -144,16 +133,12 @@ Watch live tool calls stream in real time as your AI agent inspects and edits co
144
133
  | `tokenzero watch [path]` | Starts live real-time terminal monitor for AI tool events. |
145
134
  | `tokenzero stats [path] [--once]` | Prints summary audit report and savings metrics. |
146
135
  | `tokenzero mcp` | Starts Model Context Protocol (MCP) stdio server for native AI tool calling. |
147
- | `tokenzero remove [path]` | Completely cleans up `.tokenzero/`, rules, and hooks from the repo. |
148
- | `tokenzero proxy` | Starts local FastAPI token optimization proxy on `http://127.0.0.1:8080`. |
149
-
150
- *(Note: `tokensqueeze` is also retained as a backwards-compatible alias for all commands).*
136
+ | `tokenzero remove [path]` | Completely cleans up .tokenzero/, rules, and hooks from the repo. |
137
+ | `tokenzero proxy` | Starts local FastAPI token optimization proxy on http://127.0.0.1:8080. |
151
138
 
152
- ---
139
+ ## Model Context Protocol (MCP) Integration
153
140
 
154
- ## 🔌 Model Context Protocol (MCP) Integration
155
-
156
- TokenZero supports the standard Model Context Protocol (MCP). To connect TokenZero directly to **Claude Code**, **Claude Desktop**, or **Cursor**:
141
+ TokenZero supports the standard Model Context Protocol (MCP). To connect TokenZero directly to Claude Code, Claude Desktop, or Cursor:
157
142
 
158
143
  Add to your `claude_desktop_config.json` or `.cursor/mcp.json`:
159
144
 
@@ -170,11 +155,9 @@ Add to your `claude_desktop_config.json` or `.cursor/mcp.json`:
170
155
 
171
156
  Now your AI assistant can invoke:
172
157
  - `tokenzero_get_repo_map`: Instant AST symbol inspection before reading code.
173
- - `tokenzero_read_lines`: Target specific line numbers (`start_line` to `end_line`), saving 80–95% tokens.
158
+ - `tokenzero_read_lines`: Target specific line numbers (start_line to end_line), saving 70% to 73% tokens.
174
159
  - `tokenzero_get_stats`: Live savings metrics and ROI tracking.
175
160
 
176
- ---
177
-
178
- ## 📄 License
161
+ ## License
179
162
 
180
163
  MIT License. Free and open source for all developers and teams.
@@ -1,65 +1,64 @@
1
- # ⚡ TokenZero
1
+ # TokenZero
2
2
 
3
- **Zero Token Waste for AI Coding Agents (Antigravity, Claude Code, Cursor, Codex).**
3
+ [![PyPI version](https://img.shields.io/pypi/v/tokenzero.svg)](https://pypi.org/project/tokenzero/)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
4
6
 
5
- TokenZero cuts AI coding token consumption by **70% to 96%** without sacrificing intelligence or code accuracy. It acts as an automated AST code skeletonizer, live real-time token monitor, and tool call interceptor.
7
+ **Zero Token Waste for AI Coding Agents (Antigravity, Claude Code, Cursor, Codex).**
6
8
 
7
- ---
9
+ TokenZero cuts AI coding token consumption by 70% to 73% without sacrificing intelligence or code accuracy. It acts as an automated AST code skeletonizer, live real-time token monitor, and tool call interceptor.
8
10
 
9
- ## 🎯 The Problem TokenZero Solves
11
+ ## The Problem TokenZero Solves
10
12
 
11
13
  When AI agents inspect codebases, they routinely load entire 500–2,000 line source files just to read a single 15-line function.
12
- - **Without TokenZero**: Reading 15 functions across 5 files consumes **~40,000–60,000 tokens**.
13
- - **With TokenZero**: Agents inspect the AST skeletal map and execute targeted partial line-range reads (`StartLine` & `EndLine`), consuming **~2,500–5,000 tokens** (an **85–95% direct reduction**).
14
-
15
- ---
14
+ - Without TokenZero: Reading 15 functions across 5 files consumes ~40,000–60,000 tokens.
15
+ - With TokenZero: Agents inspect the AST skeletal map and execute targeted partial line-range reads (StartLine & EndLine), consuming ~2,500–5,000 tokens (a 70% to 73% direct reduction).
16
16
 
17
- ## ✨ Features
17
+ ## Features
18
18
 
19
- - **🌐 Multi-Language AST Skeletonizer**:
20
- - Python (`.py` via Python AST)
21
- - JavaScript & TypeScript (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs` via structural brace-tracking parser)
22
- - Go (`.go`)
23
- - **⚡ Real-Time Lifecycle Hooks (<2ms)**:
24
- - Intercepts agent tool calls (`read_file`, `edit_file`, `run_command`) on-the-fly via `.agents/hooks.json`.
19
+ - Multi-Language AST Skeletonizer:
20
+ - Python (.py via Python AST)
21
+ - JavaScript & TypeScript (.js, .jsx, .ts, .tsx, .mjs, .cjs via structural brace-tracking parser)
22
+ - Go (.go)
23
+ - Real-Time Lifecycle Hooks (<2ms):
24
+ - Intercepts agent tool calls (read_file, edit_file, run_command) on-the-fly via .agents/hooks.json.
25
25
  - Blocks automated edit popups from IDE diff viewers.
26
26
  - Zero performance overhead.
27
- - **🖥️ Live Activity Dashboard (`tokenzero watch`)**:
28
- - Pure terminal table view showing each file inspection, function targeted, lines read, and **Tokens Used**.
29
- - **ROI & Savings Comparison**: Compares unoptimized token consumption against TokenZero usage and displays exact dollar savings.
30
- - **🧹 Universal Clean Removal (`tokenzero remove`)**:
27
+ - Live Activity Dashboard (tokenzero watch):
28
+ - Pure terminal table view showing each file inspection, function targeted, lines read, and Tokens Used.
29
+ - ROI & Savings Comparison: Compares unoptimized token consumption against TokenZero usage and displays exact dollar savings.
30
+ - Universal Clean Removal (tokenzero remove):
31
31
  - One-command uninstaller that restores the project to its exact original state.
32
- - **🗜️ Standalone Compression Proxy (`tokenzero proxy`)**:
32
+ - Standalone Compression Proxy (tokenzero proxy):
33
33
  - OpenAI-compatible local HTTP proxy for automated prompt payload compression.
34
34
 
35
- ---
36
-
37
- ## 🚀 Quick Start
35
+ ## Quick Start
38
36
 
39
37
  ### 1. Installation
40
38
 
41
- Install globally using `pipx` or standard `pip`:
39
+ Install globally using pipx or standard pip:
42
40
 
43
41
  ```bash
44
- # Recommended: Global CLI installation via pipx
45
- pipx install git+https://github.com/your-username/tokenzero.git
42
+ pip install tokenzero
43
+ ```
46
44
 
47
- # Or install from source:
48
- git clone https://github.com/your-username/tokenzero.git
49
- cd tokenzero
50
- pip install -e .
45
+ Or via pipx:
46
+
47
+ ```bash
48
+ pipx install tokenzero
51
49
  ```
52
50
 
53
51
  ### 2. One-Time Universal Setup
54
52
 
55
- Automatically configure **Google Antigravity**, **Cursor IDE**, **Claude Desktop**, and **Claude Code** with 1 command:
53
+ Automatically configure Google Antigravity, Cursor IDE, Claude Desktop, and Claude Code with 1 command:
56
54
 
57
55
  ```bash
58
56
  tokenzero setup
59
57
  ```
60
- *(Note: If you skip this, running `tokenzero init` or `tokenzero watch` in any project will also auto-configure all your installed AI agents silently on first run!)*
61
58
 
62
- TokenZero registers the Model Context Protocol (MCP) server across your system. **Zero files are added to your project directories!**
59
+ (Note: If you skip this, running tokenzero init or tokenzero watch in any project will also auto-configure all your installed AI agents silently on first run).
60
+
61
+ TokenZero registers the Model Context Protocol (MCP) server across your system. Zero files are added to your project directories.
63
62
 
64
63
  ### 3. Initialize in Any Project (Zero-File Mode)
65
64
 
@@ -70,9 +69,9 @@ cd /path/to/your/project
70
69
  tokenzero init
71
70
  ```
72
71
 
73
- TokenZero indexes the AST code skeleton into your global cache (`~/.tokenzero/cache/`). Your Git repository remains **100% clean with zero untracked files**!
72
+ TokenZero indexes the AST code skeleton into your global cache (~/.tokenzero/cache/). Your Git repository remains 100% clean with zero untracked files.
74
73
 
75
- *(Optional: Use `tokenzero init --local` if you prefer repository-specific rules with auto `.gitignore`).*
74
+ (Optional: Use tokenzero init --local if you prefer repository-specific rules with auto .gitignore).
76
75
 
77
76
  ### 4. Live Monitor
78
77
 
@@ -82,17 +81,9 @@ Open a second terminal or split pane and run:
82
81
  tokenzero watch
83
82
  ```
84
83
 
85
- Watch live tool calls stream in real time as your AI agent inspects and edits code!
86
-
87
- ```bash
88
- tokenzero watch
89
- ```
90
-
91
- Watch live tool calls stream in real time as your AI agent inspects and edits code!
92
-
93
- ---
84
+ Watch live tool calls stream in real time as your AI agent inspects and edits code.
94
85
 
95
- ## 📊 Live Dashboard Preview
86
+ ## Live Dashboard Preview
96
87
 
97
88
  ```text
98
89
  ┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
@@ -106,16 +97,14 @@ Watch live tool calls stream in real time as your AI agent inspects and edits co
106
97
  │ 2026-11-15 23:12:49 │ READ │ WRITEUP_2_PAGES.md:L1-L60 │ 60 / 161 lines │ ~420 tokens │
107
98
  └─────────────────────┴──────────┴────────────────────────────────────────────────┴──────────────────┴─────────────────┘
108
99
 
109
- ╭──────────────────────────────── 📊 TokenZero ROI & Savings Comparison ────────────────────────────────╮
110
- │ Activity: 28 events across 18 files | 🔴 Actual Cost (Without TokenZero): 29,534 tokens ($0.0738) ➜ │
111
- │ 🟢 Used (With TokenZero): 8,064 tokens ($0.0202) │
112
- │ 💰 Net Impact: Saved +21,470 tokens (72.7% reduction) • You Saved $0.0537 USD! │
100
+ ╭──────────────────────────────── TokenZero ROI & Savings Comparison ───────────────────────────────────╮
101
+ │ Activity: 28 events across 18 files | Actual Cost (Without TokenZero): 29,534 tokens ($0.0738) ➜ │
102
+ │ Used (With TokenZero): 8,064 tokens ($0.0202) │
103
+ │ Net Impact: Saved +21,470 tokens (72.7% reduction) • You Saved $0.0537 USD! │
113
104
  ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯
114
105
  ```
115
106
 
116
- ---
117
-
118
- ## 🛠️ CLI Reference
107
+ ## CLI Reference
119
108
 
120
109
  | Command | Description |
121
110
  | :--- | :--- |
@@ -123,16 +112,12 @@ Watch live tool calls stream in real time as your AI agent inspects and edits co
123
112
  | `tokenzero watch [path]` | Starts live real-time terminal monitor for AI tool events. |
124
113
  | `tokenzero stats [path] [--once]` | Prints summary audit report and savings metrics. |
125
114
  | `tokenzero mcp` | Starts Model Context Protocol (MCP) stdio server for native AI tool calling. |
126
- | `tokenzero remove [path]` | Completely cleans up `.tokenzero/`, rules, and hooks from the repo. |
127
- | `tokenzero proxy` | Starts local FastAPI token optimization proxy on `http://127.0.0.1:8080`. |
128
-
129
- *(Note: `tokensqueeze` is also retained as a backwards-compatible alias for all commands).*
115
+ | `tokenzero remove [path]` | Completely cleans up .tokenzero/, rules, and hooks from the repo. |
116
+ | `tokenzero proxy` | Starts local FastAPI token optimization proxy on http://127.0.0.1:8080. |
130
117
 
131
- ---
118
+ ## Model Context Protocol (MCP) Integration
132
119
 
133
- ## 🔌 Model Context Protocol (MCP) Integration
134
-
135
- TokenZero supports the standard Model Context Protocol (MCP). To connect TokenZero directly to **Claude Code**, **Claude Desktop**, or **Cursor**:
120
+ TokenZero supports the standard Model Context Protocol (MCP). To connect TokenZero directly to Claude Code, Claude Desktop, or Cursor:
136
121
 
137
122
  Add to your `claude_desktop_config.json` or `.cursor/mcp.json`:
138
123
 
@@ -149,11 +134,9 @@ Add to your `claude_desktop_config.json` or `.cursor/mcp.json`:
149
134
 
150
135
  Now your AI assistant can invoke:
151
136
  - `tokenzero_get_repo_map`: Instant AST symbol inspection before reading code.
152
- - `tokenzero_read_lines`: Target specific line numbers (`start_line` to `end_line`), saving 80–95% tokens.
137
+ - `tokenzero_read_lines`: Target specific line numbers (start_line to end_line), saving 70% to 73% tokens.
153
138
  - `tokenzero_get_stats`: Live savings metrics and ROI tracking.
154
139
 
155
- ---
156
-
157
- ## 📄 License
140
+ ## License
158
141
 
159
142
  MIT License. Free and open source for all developers and teams.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "tokenzero"
7
- version = "0.1.0"
7
+ version = "0.1.1"
8
8
  description = "Zero Token Waste - AST Code Skeletonizer & Live AI Monitor for Coding Agents"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -27,7 +27,6 @@ dependencies = [
27
27
 
28
28
  [project.scripts]
29
29
  tokenzero = "squeeze:main"
30
- tokensqueeze = "squeeze:main"
31
30
 
32
31
  [tool.setuptools]
33
32
  py-modules = ["squeeze", "scanner", "proxy", "mcp_server"]
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: tokenzero
3
- Version: 0.1.0
3
+ Version: 0.1.1
4
4
  Summary: Zero Token Waste - AST Code Skeletonizer & Live AI Monitor for Coding Agents
5
5
  License-Expression: MIT
6
6
  Keywords: tokenzero,tokens,ai-agents,ast,antigravity,claude,cursor,optimization,mcp
@@ -19,68 +19,67 @@ Requires-Dist: httpx>=0.27.0
19
19
  Requires-Dist: tiktoken>=0.7.0
20
20
  Dynamic: license-file
21
21
 
22
- # ⚡ TokenZero
22
+ # TokenZero
23
23
 
24
- **Zero Token Waste for AI Coding Agents (Antigravity, Claude Code, Cursor, Codex).**
24
+ [![PyPI version](https://img.shields.io/pypi/v/tokenzero.svg)](https://pypi.org/project/tokenzero/)
25
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
26
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
25
27
 
26
- TokenZero cuts AI coding token consumption by **70% to 96%** without sacrificing intelligence or code accuracy. It acts as an automated AST code skeletonizer, live real-time token monitor, and tool call interceptor.
28
+ **Zero Token Waste for AI Coding Agents (Antigravity, Claude Code, Cursor, Codex).**
27
29
 
28
- ---
30
+ TokenZero cuts AI coding token consumption by 70% to 73% without sacrificing intelligence or code accuracy. It acts as an automated AST code skeletonizer, live real-time token monitor, and tool call interceptor.
29
31
 
30
- ## 🎯 The Problem TokenZero Solves
32
+ ## The Problem TokenZero Solves
31
33
 
32
34
  When AI agents inspect codebases, they routinely load entire 500–2,000 line source files just to read a single 15-line function.
33
- - **Without TokenZero**: Reading 15 functions across 5 files consumes **~40,000–60,000 tokens**.
34
- - **With TokenZero**: Agents inspect the AST skeletal map and execute targeted partial line-range reads (`StartLine` & `EndLine`), consuming **~2,500–5,000 tokens** (an **85–95% direct reduction**).
35
-
36
- ---
35
+ - Without TokenZero: Reading 15 functions across 5 files consumes ~40,000–60,000 tokens.
36
+ - With TokenZero: Agents inspect the AST skeletal map and execute targeted partial line-range reads (StartLine & EndLine), consuming ~2,500–5,000 tokens (a 70% to 73% direct reduction).
37
37
 
38
- ## ✨ Features
38
+ ## Features
39
39
 
40
- - **🌐 Multi-Language AST Skeletonizer**:
41
- - Python (`.py` via Python AST)
42
- - JavaScript & TypeScript (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs` via structural brace-tracking parser)
43
- - Go (`.go`)
44
- - **⚡ Real-Time Lifecycle Hooks (<2ms)**:
45
- - Intercepts agent tool calls (`read_file`, `edit_file`, `run_command`) on-the-fly via `.agents/hooks.json`.
40
+ - Multi-Language AST Skeletonizer:
41
+ - Python (.py via Python AST)
42
+ - JavaScript & TypeScript (.js, .jsx, .ts, .tsx, .mjs, .cjs via structural brace-tracking parser)
43
+ - Go (.go)
44
+ - Real-Time Lifecycle Hooks (<2ms):
45
+ - Intercepts agent tool calls (read_file, edit_file, run_command) on-the-fly via .agents/hooks.json.
46
46
  - Blocks automated edit popups from IDE diff viewers.
47
47
  - Zero performance overhead.
48
- - **🖥️ Live Activity Dashboard (`tokenzero watch`)**:
49
- - Pure terminal table view showing each file inspection, function targeted, lines read, and **Tokens Used**.
50
- - **ROI & Savings Comparison**: Compares unoptimized token consumption against TokenZero usage and displays exact dollar savings.
51
- - **🧹 Universal Clean Removal (`tokenzero remove`)**:
48
+ - Live Activity Dashboard (tokenzero watch):
49
+ - Pure terminal table view showing each file inspection, function targeted, lines read, and Tokens Used.
50
+ - ROI & Savings Comparison: Compares unoptimized token consumption against TokenZero usage and displays exact dollar savings.
51
+ - Universal Clean Removal (tokenzero remove):
52
52
  - One-command uninstaller that restores the project to its exact original state.
53
- - **🗜️ Standalone Compression Proxy (`tokenzero proxy`)**:
53
+ - Standalone Compression Proxy (tokenzero proxy):
54
54
  - OpenAI-compatible local HTTP proxy for automated prompt payload compression.
55
55
 
56
- ---
57
-
58
- ## 🚀 Quick Start
56
+ ## Quick Start
59
57
 
60
58
  ### 1. Installation
61
59
 
62
- Install globally using `pipx` or standard `pip`:
60
+ Install globally using pipx or standard pip:
63
61
 
64
62
  ```bash
65
- # Recommended: Global CLI installation via pipx
66
- pipx install git+https://github.com/your-username/tokenzero.git
63
+ pip install tokenzero
64
+ ```
67
65
 
68
- # Or install from source:
69
- git clone https://github.com/your-username/tokenzero.git
70
- cd tokenzero
71
- pip install -e .
66
+ Or via pipx:
67
+
68
+ ```bash
69
+ pipx install tokenzero
72
70
  ```
73
71
 
74
72
  ### 2. One-Time Universal Setup
75
73
 
76
- Automatically configure **Google Antigravity**, **Cursor IDE**, **Claude Desktop**, and **Claude Code** with 1 command:
74
+ Automatically configure Google Antigravity, Cursor IDE, Claude Desktop, and Claude Code with 1 command:
77
75
 
78
76
  ```bash
79
77
  tokenzero setup
80
78
  ```
81
- *(Note: If you skip this, running `tokenzero init` or `tokenzero watch` in any project will also auto-configure all your installed AI agents silently on first run!)*
82
79
 
83
- TokenZero registers the Model Context Protocol (MCP) server across your system. **Zero files are added to your project directories!**
80
+ (Note: If you skip this, running tokenzero init or tokenzero watch in any project will also auto-configure all your installed AI agents silently on first run).
81
+
82
+ TokenZero registers the Model Context Protocol (MCP) server across your system. Zero files are added to your project directories.
84
83
 
85
84
  ### 3. Initialize in Any Project (Zero-File Mode)
86
85
 
@@ -91,9 +90,9 @@ cd /path/to/your/project
91
90
  tokenzero init
92
91
  ```
93
92
 
94
- TokenZero indexes the AST code skeleton into your global cache (`~/.tokenzero/cache/`). Your Git repository remains **100% clean with zero untracked files**!
93
+ TokenZero indexes the AST code skeleton into your global cache (~/.tokenzero/cache/). Your Git repository remains 100% clean with zero untracked files.
95
94
 
96
- *(Optional: Use `tokenzero init --local` if you prefer repository-specific rules with auto `.gitignore`).*
95
+ (Optional: Use tokenzero init --local if you prefer repository-specific rules with auto .gitignore).
97
96
 
98
97
  ### 4. Live Monitor
99
98
 
@@ -103,17 +102,9 @@ Open a second terminal or split pane and run:
103
102
  tokenzero watch
104
103
  ```
105
104
 
106
- Watch live tool calls stream in real time as your AI agent inspects and edits code!
107
-
108
- ```bash
109
- tokenzero watch
110
- ```
111
-
112
- Watch live tool calls stream in real time as your AI agent inspects and edits code!
113
-
114
- ---
105
+ Watch live tool calls stream in real time as your AI agent inspects and edits code.
115
106
 
116
- ## 📊 Live Dashboard Preview
107
+ ## Live Dashboard Preview
117
108
 
118
109
  ```text
119
110
  ┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
@@ -127,16 +118,14 @@ Watch live tool calls stream in real time as your AI agent inspects and edits co
127
118
  │ 2026-11-15 23:12:49 │ READ │ WRITEUP_2_PAGES.md:L1-L60 │ 60 / 161 lines │ ~420 tokens │
128
119
  └─────────────────────┴──────────┴────────────────────────────────────────────────┴──────────────────┴─────────────────┘
129
120
 
130
- ╭──────────────────────────────── 📊 TokenZero ROI & Savings Comparison ────────────────────────────────╮
131
- │ Activity: 28 events across 18 files | 🔴 Actual Cost (Without TokenZero): 29,534 tokens ($0.0738) ➜ │
132
- │ 🟢 Used (With TokenZero): 8,064 tokens ($0.0202) │
133
- │ 💰 Net Impact: Saved +21,470 tokens (72.7% reduction) • You Saved $0.0537 USD! │
121
+ ╭──────────────────────────────── TokenZero ROI & Savings Comparison ───────────────────────────────────╮
122
+ │ Activity: 28 events across 18 files | Actual Cost (Without TokenZero): 29,534 tokens ($0.0738) ➜ │
123
+ │ Used (With TokenZero): 8,064 tokens ($0.0202) │
124
+ │ Net Impact: Saved +21,470 tokens (72.7% reduction) • You Saved $0.0537 USD! │
134
125
  ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯
135
126
  ```
136
127
 
137
- ---
138
-
139
- ## 🛠️ CLI Reference
128
+ ## CLI Reference
140
129
 
141
130
  | Command | Description |
142
131
  | :--- | :--- |
@@ -144,16 +133,12 @@ Watch live tool calls stream in real time as your AI agent inspects and edits co
144
133
  | `tokenzero watch [path]` | Starts live real-time terminal monitor for AI tool events. |
145
134
  | `tokenzero stats [path] [--once]` | Prints summary audit report and savings metrics. |
146
135
  | `tokenzero mcp` | Starts Model Context Protocol (MCP) stdio server for native AI tool calling. |
147
- | `tokenzero remove [path]` | Completely cleans up `.tokenzero/`, rules, and hooks from the repo. |
148
- | `tokenzero proxy` | Starts local FastAPI token optimization proxy on `http://127.0.0.1:8080`. |
149
-
150
- *(Note: `tokensqueeze` is also retained as a backwards-compatible alias for all commands).*
136
+ | `tokenzero remove [path]` | Completely cleans up .tokenzero/, rules, and hooks from the repo. |
137
+ | `tokenzero proxy` | Starts local FastAPI token optimization proxy on http://127.0.0.1:8080. |
151
138
 
152
- ---
139
+ ## Model Context Protocol (MCP) Integration
153
140
 
154
- ## 🔌 Model Context Protocol (MCP) Integration
155
-
156
- TokenZero supports the standard Model Context Protocol (MCP). To connect TokenZero directly to **Claude Code**, **Claude Desktop**, or **Cursor**:
141
+ TokenZero supports the standard Model Context Protocol (MCP). To connect TokenZero directly to Claude Code, Claude Desktop, or Cursor:
157
142
 
158
143
  Add to your `claude_desktop_config.json` or `.cursor/mcp.json`:
159
144
 
@@ -170,11 +155,9 @@ Add to your `claude_desktop_config.json` or `.cursor/mcp.json`:
170
155
 
171
156
  Now your AI assistant can invoke:
172
157
  - `tokenzero_get_repo_map`: Instant AST symbol inspection before reading code.
173
- - `tokenzero_read_lines`: Target specific line numbers (`start_line` to `end_line`), saving 80–95% tokens.
158
+ - `tokenzero_read_lines`: Target specific line numbers (start_line to end_line), saving 70% to 73% tokens.
174
159
  - `tokenzero_get_stats`: Live savings metrics and ROI tracking.
175
160
 
176
- ---
177
-
178
- ## 📄 License
161
+ ## License
179
162
 
180
163
  MIT License. Free and open source for all developers and teams.
@@ -1,3 +1,2 @@
1
1
  [console_scripts]
2
- tokensqueeze = squeeze:main
3
2
  tokenzero = squeeze:main
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes