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.
- {tokenzero-0.1.0/tokenzero.egg-info → tokenzero-0.1.1}/PKG-INFO +49 -66
- {tokenzero-0.1.0 → tokenzero-0.1.1}/README.md +48 -65
- {tokenzero-0.1.0 → tokenzero-0.1.1}/pyproject.toml +1 -2
- {tokenzero-0.1.0 → tokenzero-0.1.1/tokenzero.egg-info}/PKG-INFO +49 -66
- {tokenzero-0.1.0 → tokenzero-0.1.1}/tokenzero.egg-info/entry_points.txt +0 -1
- {tokenzero-0.1.0 → tokenzero-0.1.1}/LICENSE +0 -0
- {tokenzero-0.1.0 → tokenzero-0.1.1}/mcp_server.py +0 -0
- {tokenzero-0.1.0 → tokenzero-0.1.1}/proxy.py +0 -0
- {tokenzero-0.1.0 → tokenzero-0.1.1}/scanner.py +0 -0
- {tokenzero-0.1.0 → tokenzero-0.1.1}/setup.cfg +0 -0
- {tokenzero-0.1.0 → tokenzero-0.1.1}/squeeze.py +0 -0
- {tokenzero-0.1.0 → tokenzero-0.1.1}/tests/test_cli.py +0 -0
- {tokenzero-0.1.0 → tokenzero-0.1.1}/tokenzero.egg-info/SOURCES.txt +0 -0
- {tokenzero-0.1.0 → tokenzero-0.1.1}/tokenzero.egg-info/dependency_links.txt +0 -0
- {tokenzero-0.1.0 → tokenzero-0.1.1}/tokenzero.egg-info/requires.txt +0 -0
- {tokenzero-0.1.0 → tokenzero-0.1.1}/tokenzero.egg-info/top_level.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: tokenzero
|
|
3
|
-
Version: 0.1.
|
|
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
|
-
#
|
|
22
|
+
# TokenZero
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
[](https://pypi.org/project/tokenzero/)
|
|
25
|
+
[](https://opensource.org/licenses/MIT)
|
|
26
|
+
[](https://www.python.org/downloads/)
|
|
25
27
|
|
|
26
|
-
|
|
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
|
-
##
|
|
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
|
-
-
|
|
34
|
-
-
|
|
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
|
-
##
|
|
38
|
+
## Features
|
|
39
39
|
|
|
40
|
-
-
|
|
41
|
-
- Python (
|
|
42
|
-
- JavaScript & TypeScript (
|
|
43
|
-
- Go (
|
|
44
|
-
-
|
|
45
|
-
- Intercepts agent tool calls (
|
|
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
|
-
-
|
|
49
|
-
- Pure terminal table view showing each file inspection, function targeted, lines read, and
|
|
50
|
-
-
|
|
51
|
-
-
|
|
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
|
-
-
|
|
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
|
|
60
|
+
Install globally using pipx or standard pip:
|
|
63
61
|
|
|
64
62
|
```bash
|
|
65
|
-
|
|
66
|
-
|
|
63
|
+
pip install tokenzero
|
|
64
|
+
```
|
|
67
65
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
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
|
|
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
|
-
|
|
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 (
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
-
╭────────────────────────────────
|
|
131
|
-
│ Activity: 28 events across 18 files |
|
|
132
|
-
│
|
|
133
|
-
│
|
|
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
|
|
148
|
-
| `tokenzero proxy` | Starts local FastAPI token optimization proxy on
|
|
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
|
-
|
|
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 (
|
|
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
|
-
#
|
|
1
|
+
# TokenZero
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://pypi.org/project/tokenzero/)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
[](https://www.python.org/downloads/)
|
|
4
6
|
|
|
5
|
-
|
|
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
|
-
##
|
|
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
|
-
-
|
|
13
|
-
-
|
|
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
|
-
##
|
|
17
|
+
## Features
|
|
18
18
|
|
|
19
|
-
-
|
|
20
|
-
- Python (
|
|
21
|
-
- JavaScript & TypeScript (
|
|
22
|
-
- Go (
|
|
23
|
-
-
|
|
24
|
-
- Intercepts agent tool calls (
|
|
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
|
-
-
|
|
28
|
-
- Pure terminal table view showing each file inspection, function targeted, lines read, and
|
|
29
|
-
-
|
|
30
|
-
-
|
|
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
|
-
-
|
|
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
|
|
39
|
+
Install globally using pipx or standard pip:
|
|
42
40
|
|
|
43
41
|
```bash
|
|
44
|
-
|
|
45
|
-
|
|
42
|
+
pip install tokenzero
|
|
43
|
+
```
|
|
46
44
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
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
|
|
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
|
-
|
|
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 (
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
-
╭────────────────────────────────
|
|
110
|
-
│ Activity: 28 events across 18 files |
|
|
111
|
-
│
|
|
112
|
-
│
|
|
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
|
|
127
|
-
| `tokenzero proxy` | Starts local FastAPI token optimization proxy on
|
|
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
|
-
|
|
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 (
|
|
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.
|
|
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.
|
|
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
|
-
#
|
|
22
|
+
# TokenZero
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
[](https://pypi.org/project/tokenzero/)
|
|
25
|
+
[](https://opensource.org/licenses/MIT)
|
|
26
|
+
[](https://www.python.org/downloads/)
|
|
25
27
|
|
|
26
|
-
|
|
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
|
-
##
|
|
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
|
-
-
|
|
34
|
-
-
|
|
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
|
-
##
|
|
38
|
+
## Features
|
|
39
39
|
|
|
40
|
-
-
|
|
41
|
-
- Python (
|
|
42
|
-
- JavaScript & TypeScript (
|
|
43
|
-
- Go (
|
|
44
|
-
-
|
|
45
|
-
- Intercepts agent tool calls (
|
|
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
|
-
-
|
|
49
|
-
- Pure terminal table view showing each file inspection, function targeted, lines read, and
|
|
50
|
-
-
|
|
51
|
-
-
|
|
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
|
-
-
|
|
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
|
|
60
|
+
Install globally using pipx or standard pip:
|
|
63
61
|
|
|
64
62
|
```bash
|
|
65
|
-
|
|
66
|
-
|
|
63
|
+
pip install tokenzero
|
|
64
|
+
```
|
|
67
65
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
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
|
|
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
|
-
|
|
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 (
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
-
╭────────────────────────────────
|
|
131
|
-
│ Activity: 28 events across 18 files |
|
|
132
|
-
│
|
|
133
|
-
│
|
|
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
|
|
148
|
-
| `tokenzero proxy` | Starts local FastAPI token optimization proxy on
|
|
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
|
-
|
|
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 (
|
|
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.
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|