xithead 1.2.0 → 1.2.2

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.
package/README.md CHANGED
@@ -1,17 +1,18 @@
1
1
  <div align="center">
2
- <img src="https://cdn.xtream-itsolutions.com/u/logo.png" alt="Xtream-ITSolutions UG" width="160" />
3
- <h1>xithead</h1>
4
- <p><strong>Aggressive Claude Context Optimizer — bis zu 95% Token-Einsparung</strong></p>
2
+ <img src="https://cdn.xtream-itsolutions.com/u/logo.png" alt="Xtream-ITSolutions UG" width="140" />
3
+ <br/><br/>
4
+ <h1>⚡ xithead</h1>
5
+ <p><strong>Claude Context Optimizer — bis zu 95% Token-Einsparung, automatisch</strong></p>
5
6
  <p>
6
- <a href="https://pypi.org/project/xithead/"><img src="https://img.shields.io/pypi/v/xithead?color=00d4ff&label=PyPI&style=flat-square" alt="PyPI" /></a>
7
- <a href="https://www.npmjs.com/package/xithead"><img src="https://img.shields.io/npm/v/xithead?color=e879f9&label=npm&style=flat-square" alt="npm" /></a>
7
+ <a href="https://pypi.org/project/xithead/"><img src="https://img.shields.io/pypi/v/xithead?color=00e5ff&label=PyPI&style=flat-square" alt="PyPI" /></a>
8
+ <a href="https://www.npmjs.com/package/xithead"><img src="https://img.shields.io/npm/v/xithead?color=a855f7&label=npm&style=flat-square" alt="npm" /></a>
8
9
  <a href="https://discord.gg/xtream-itsolutions"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord" /></a>
9
- <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-10b981?style=flat-square" alt="License" /></a>
10
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-10b981?style=flat-square" alt="Apache 2.0" /></a>
10
11
  </p>
11
12
  <p>
13
+ <a href="https://xtream-itsolutions.com">🌐 xtream-itsolutions.com</a> ·
12
14
  <a href="https://discord.gg/xtream-itsolutions">💬 Discord</a> ·
13
- <a href="https://github.com/xtream-itsolutions/headroom/issues">🐛 Bug melden</a> ·
14
- <a href="https://github.com/xtream-itsolutions/headroom/issues">✨ Feature anfragen</a>
15
+ <a href="https://github.com/xtream-itsolutions/xithead/issues">🐛 Bug melden</a>
15
16
  </p>
16
17
  </div>
17
18
 
@@ -19,221 +20,168 @@
19
20
 
20
21
  ## Was ist xithead?
21
22
 
22
- **xithead** ist ein Claude-spezifischer Context Optimizer von **Xtream-ITSolutions UG**.
23
- Er sitzt zwischen deiner App und der Claude API, komprimiert Prompts aggressiv und cached Antworten — du sendest weniger Tokens und zahlst deutlich weniger.
23
+ **xithead** ist ein lokaler Proxy von **[Xtream-ITSolutions UG](https://xtream-itsolutions.com)**, der sich zwischen Claude Code und die Anthropic API setzt. Er komprimiert Kontext aggressiv, cached Antworten und dedupliziert identische Requests — vollautomatisch, ohne Code-Änderungen.
24
24
 
25
- - **Drop-in Proxy** — keine Code-Änderungen nötig
26
- - **Immer Sonnet 4.6** — das beste Modell, automatisch gepinnt
27
- - **Ultra-Modus standardmäßig** — 50–95% Einsparung ab dem ersten Request
28
- - **Live Dashboard** — Einsparungen in Echtzeit auf `localhost:8787/dashboard`
29
-
30
- ---
31
-
32
- ## Schnellstart — Windows (empfohlen)
33
-
34
- ```powershell
35
- # PowerShell als Administrator, einmalig:
36
- Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
37
- iex (irm https://raw.githubusercontent.com/xtream-itsolutions/headroom/main/headroom.ps1)
38
25
  ```
39
-
40
- Danach neues Terminal öffnen und loslegen:
41
-
42
- ```powershell
43
- xithead # Claude starten — ultra-aggressiv, 50-95% Einsparung
44
- xithead-proxy # Proxy + Dashboard auf http://localhost:8787/dashboard
45
- xithead-stats # Einsparungen anzeigen
46
- xithead-update # xithead aktualisieren
47
- xithead-help # Alle Befehle
26
+ Claude Code ──► xithead Proxy :8787 ──► Anthropic API
27
+ │ Cache-Control
28
+ │ Context-Trim
29
+ │ Request-Dedup
30
+ └ Live Dashboard
48
31
  ```
49
32
 
50
- > **VS Code:** Terminal mit `Strg+\`` öffnen, PowerShell wählen, `xithead` eingeben — fertig.
33
+ **Ergebnis:** 50–95% weniger Token-Verbrauch, gleiche Qualität.
51
34
 
52
35
  ---
53
36
 
54
37
  ## Installation
55
38
 
56
- ### Python
39
+ ### Windows (empfohlen — ein Befehl, alles automatisch)
57
40
 
58
- ```bash
59
- pip install xithead # nur CLI + Optimizer
60
- pip install "xithead[proxy]" # + Proxy + Dashboard (empfohlen)
41
+ ```powershell
42
+ iex (irm https://raw.githubusercontent.com/xtream-itsolutions/xithead/main/headroom.ps1)
61
43
  ```
62
44
 
63
- ### npm / Node.js
45
+ Das Skript installiert automatisch (ohne Adminrechte):
46
+ - Python 3.12, Node.js, Git (via Winget falls nicht vorhanden)
47
+ - xithead Python-Paket + Proxy-Abhängigkeiten
48
+ - xithead npm CLI + Claude Code
49
+ - Claude Code konfigurieren (`~/.claude/settings.json`)
50
+ - PowerShell-Profil mit allen Hilfsbefehlen
51
+
52
+ Danach nur noch eingeben (optional):
53
+ - Claude Login (Browser oder API-Key)
54
+ - GitHub Token (für Repo-Zugriff in Claude Code)
55
+
56
+ ### npm (Windows / macOS / Linux)
64
57
 
65
58
  ```bash
66
59
  npm install -g xithead
60
+ xithead
67
61
  ```
68
62
 
69
- ---
70
-
71
- ## CLI Befehle
63
+ ### pip (Python direkt)
72
64
 
73
65
  ```bash
74
- xithead proxy # Proxy starten (Port 8787) + Dashboard
75
- xithead optimize "prompt" # Prompt optimieren und Einsparung zeigen
76
- xithead stats # Session-Statistiken
77
- xithead cache stats # Cache-Statistiken
78
- xithead cache clear # Cache leeren
79
- xithead model set claude-sonnet-4-6 # Modell setzen
80
- xithead model show # Aktuelles Modell anzeigen
66
+ pip install "xithead[proxy]"
67
+ python -m xithead.cli.main proxy --port 8787
81
68
  ```
82
69
 
83
70
  ---
84
71
 
85
- ## Features
86
-
87
- | Feature | Beschreibung | Einsparung |
88
- |---------|-------------|------------|
89
- | 🔥 **Prompt Caching** | `cache_control`-Marker automatisch injizieren | Bis 90% auf Cache-Hits |
90
- | 🗜️ **Context Compression** | Redundanz entfernen, Nachrichten deduplizieren | 30–60% weniger Tokens |
91
- | 💾 **Multi-Layer Cache** | RAM + SQLite, SHA-256 Keys, TTL | Wiederholte Calls gratis |
92
- | ✂️ **Context Trim** | Alten Context trimmen (verhindert 400-Fehler) | Spart Input-Tokens |
93
- | 📉 **Verbosity Reduction** | System-Prompts komprimieren | 10–40% Einsparung |
94
- | 📊 **Live Dashboard** | Token- & Kosten-Tracking in Echtzeit | Volle Transparenz |
95
- | 🔌 **Drop-in Proxy** | Keine Code-Änderungen | Funktioniert mit jedem Client |
72
+ ## Benutzung
96
73
 
97
- ---
74
+ ```powershell
75
+ xithead # Claude Code mit Proxy starten (empfohlen)
76
+ xithead proxy # Nur Proxy starten (mit Logs)
77
+ xithead stats # Token-Einsparungen anzeigen
78
+ xithead update # Alles aktualisieren (npm + Python)
79
+ xithead help # Alle Befehle
80
+ ```
98
81
 
99
- ## Einsparungs-Beispiele
82
+ ### PowerShell-Hilfsbefehle (nach Installation)
100
83
 
101
- | Anwendungsfall | Original | Nach xithead | Gespart |
102
- |----------------|----------|--------------|---------|
103
- | Code-Review (wiederholter Kontext) | 50.000 Tokens | 4.000 Tokens | **92%** |
104
- | Chat mit langem System-Prompt | 10.000 Tokens | 2.000 Tokens | **80%** |
105
- | Agentischer Loop (Tool-Ergebnisse) | 100.000 Tokens | 25.000 Tokens | **75%** |
106
- | Einfaches Q&A | 500 Tokens | 400 Tokens | ~20% |
84
+ ```powershell
85
+ xithead-dashboard # Dashboard im Browser öffnen
86
+ xithead-stats # Einsparungen anzeigen
87
+ xithead-update # Alles auf neuestem Stand halten
88
+ xithead-github # GitHub Token + MCP Server einrichten
89
+ xithead-doctor # System-Diagnose
90
+ xithead-help # Alle Befehle
91
+ ```
107
92
 
108
93
  ---
109
94
 
110
- ## Python API
95
+ ## Dashboard
111
96
 
112
- ```python
113
- from xithead import optimize_for_claude
97
+ Das Live-Dashboard läuft automatisch auf `http://localhost:8787/dashboard`:
114
98
 
115
- messages = [{"role": "user", "content": "Sehr langer Prompt hier..."}]
116
- result = optimize_for_claude(messages, model="claude-sonnet-4-6")
99
+ - **Echtzeit-Statistiken** — Token gespart, Kosten, Cache-Hit-Rate
100
+ - **Request-Verlauf** — Token-Verbrauch pro Request als Chart
101
+ - **Einstellungen** — Komprimierungsstärke, Cache-Optionen
102
+ - **Installation** — Quick-Start Guide direkt im Browser
117
103
 
118
- print(f"Tokens gespart: {result.tokens_saved}")
119
- print(f"Kosten gespart: ${result.cost_saved_usd:.4f}")
120
- print(f"Kompression: {result.compression_ratio:.1%}")
121
- print(f"Cache-Hit: {result.cache_hit}")
104
+ ---
122
105
 
123
- # Optimierte messages an Anthropic API übergeben:
124
- # client.messages.create(messages=result.messages, ...)
125
- ```
106
+ ## Wie es funktioniert
126
107
 
127
- ### Konfiguration
128
-
129
- ```python
130
- from xithead.claude_optimizer import ClaudeOptimizer, ClaudeOptimizerConfig
131
-
132
- config = ClaudeOptimizerConfig(
133
- enable_prompt_caching=True,
134
- enable_dedup=True,
135
- enable_verbosity_reduction=True,
136
- enable_context_trim=True,
137
- max_context_tokens=180_000,
138
- cache_ttl_seconds=86400,
139
- )
140
- optimizer = ClaudeOptimizer(config)
141
- result = optimizer.optimize(messages, system="Du bist ein hilfreicher Assistent.", model="claude-sonnet-4-6")
142
- ```
108
+ | Feature | Beschreibung |
109
+ |---|---|
110
+ | **Cache Control** | Anthropic `cache_control` wird automatisch in jeden Request injiziert (bis zu 90% Einsparung bei Wiederholungen) |
111
+ | **Context Trimming** | Lange Konversations-Historien werden aggressiv komprimiert |
112
+ | **Request Deduplication** | Identische gleichzeitige Requests werden zusammengeführt |
113
+ | **429 Retry** | Automatisches Retry mit `Retry-After` Header bei Rate Limits |
114
+ | **SQLite Cache** | Persistenter Cache unter `~/.xithead/cache/` |
143
115
 
144
116
  ---
145
117
 
146
- ## Node.js / JavaScript API
147
-
148
- ```javascript
149
- const { optimize, createOptimizedClient, injectCacheControl } = require('xithead');
150
- const Anthropic = require('@anthropic-ai/sdk');
151
-
152
- // Option 1: Manuell optimieren
153
- const result = optimize({ messages, system, model: 'claude-sonnet-4-6' });
154
- console.log(result.tokensSaved, result.costSavedUsd);
155
-
156
- // Option 2: Wrapped Client (optimiert automatisch jeden Call)
157
- const client = new Anthropic();
158
- const xitClient = createOptimizedClient(client);
159
- const response = await xitClient.messages.create({
160
- model: 'claude-sonnet-4-6',
161
- max_tokens: 1024,
162
- messages: [{ role: 'user', content: 'Hallo!' }],
163
- });
164
- console.log(xitClient.getStats());
118
+ ## Claude Code konfigurieren
119
+
120
+ xithead setzt `~/.claude/settings.json` automatisch während der Installation:
121
+
122
+ ```json
123
+ {
124
+ "env": {
125
+ "ANTHROPIC_BASE_URL": "http://localhost:8787/v1",
126
+ "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "16000",
127
+ "XITHEAD_ENABLE_CACHE_CONTROL": "1",
128
+ "XITHEAD_ENABLE_DEDUP": "1",
129
+ "XITHEAD_ENABLE_CONTEXT_TRIM": "1",
130
+ "HEADROOM_STRENGTH": "aggressive"
131
+ }
132
+ }
165
133
  ```
166
134
 
167
- ---
168
-
169
- ## Proxy-Modus (Zero Code Changes)
135
+ Damit nutzt auch `claude` direkt (ohne `xithead`-Wrapper) den Proxy.
170
136
 
171
- ```bash
172
- # Proxy starten
173
- xithead proxy --port 8787
137
+ ---
174
138
 
175
- # Dashboard öffnen
176
- # → http://localhost:8787/dashboard
139
+ ## GitHub Integration
177
140
 
178
- # Deinen Claude Client auf den Proxy zeigen lassen:
179
- export ANTHROPIC_BASE_URL=http://localhost:8787
180
- claude # oder jede andere App
181
- ```
141
+ Claude Code kann direkt mit GitHub arbeiten (Repos lesen, PRs erstellen, Issues verwalten):
182
142
 
183
- In PowerShell:
184
143
  ```powershell
185
- $env:ANTHROPIC_BASE_URL = "http://localhost:8787"
186
- claude
144
+ xithead-github # GitHub Token eingeben + MCP Server einrichten
187
145
  ```
188
146
 
189
- ---
190
-
191
- ## Wie es funktioniert
192
-
193
- ```
194
- Deine App → xithead Proxy → Optimierter Request → Claude API
195
- │
196
- ├─ Cache-Lookup (API-Call überspringen wenn gecacht)
197
- ├─ Nachrichten-Deduplizierung
198
- ├─ System-Prompt Kompression
199
- ├─ cache_control Marker injizieren
200
- ├─ Context-Window Trim (verhindert 400-Fehler)
201
- └─ Token/Kosten-Tracking
202
- ```
147
+ Token erstellen unter: [github.com/settings/tokens/new](https://github.com/settings/tokens/new)
148
+ Benötigte Scopes: `repo`, `workflow`, `read:org`
203
149
 
204
150
  ---
205
151
 
206
- ## Umgebungsvariablen
152
+ ## Auto-Update
207
153
 
208
- | Variable | Standardwert | Beschreibung |
209
- |----------|-------------|--------------|
210
- | `XITHEAD_MODEL` | `claude-sonnet-4-6` | Claude-Modell |
211
- | `XITHEAD_ENABLE_CACHE_CONTROL` | `1` | Prompt-Caching aktivieren |
212
- | `XITHEAD_ENABLE_DEDUP` | `1` | Nachrichten-Dedup aktivieren |
213
- | `XITHEAD_ENABLE_CONTEXT_TRIM` | `1` | Context-Trim aktivieren |
214
- | `HEADROOM_COMPRESSION_RATIO_TARGET` | `0.3` | Kompressions-Ziel (0.3 = 70%) |
215
- | `HEADROOM_STRENGTH` | `aggressive` | Kompressions-Stärke |
216
- | `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | `2048` | Max. Output-Tokens |
154
+ xithead prüft automatisch alle 6 Stunden auf neue Versionen:
155
+ - Neue npm-Version → stiller Hintergrund-Update
156
+ - Python-Paket → parallel aktualisiert
217
157
 
218
- ---
158
+ Manuelles Update jederzeit:
159
+ ```powershell
160
+ xithead update # oder
161
+ xithead-update # PowerShell-Funktion
162
+ ```
219
163
 
220
- ## Beitragen
164
+ ---
221
165
 
222
- Wir freuen uns über Beiträge! Öffne ein Issue oder Pull Request.
166
+ ## Voraussetzungen
223
167
 
224
- Tritt unserer Community bei: [discord.gg/xtream-itsolutions](https://discord.gg/xtream-itsolutions)
168
+ | Software | Version | Installiert durch |
169
+ |---|---|---|
170
+ | Python | ≥ 3.9 | Winget (automatisch) |
171
+ | Node.js | ≥ 18 | Winget (automatisch) |
172
+ | Claude Code | aktuell | npm (automatisch) |
173
+ | Git | aktuell | Winget (automatisch) |
225
174
 
226
175
  ---
227
176
 
228
177
  ## Lizenz
229
178
 
230
- Apache 2.0 — siehe [LICENSE](LICENSE).
179
+ [Apache 2.0](LICENSE) — © 2026 [Xtream-ITSolutions UG](https://xtream-itsolutions.com)
231
180
 
232
181
  ---
233
182
 
234
183
  <div align="center">
235
- <p>Made with ❤️ by <a href="https://xtream-itsolutions.com"><strong>Xtream-ITSolutions UG</strong></a></p>
236
- <a href="https://discord.gg/xtream-itsolutions">
237
- <img src="https://img.shields.io/badge/Discord-Community_beitreten-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord" />
238
- </a>
184
+ <a href="https://discord.gg/xtream-itsolutions">💬 Discord</a> ·
185
+ <a href="https://xtream-itsolutions.com">🌐 xtream-itsolutions.com</a> ·
186
+ <a href="https://github.com/xtream-itsolutions/xithead">GitHub</a>
239
187
  </div>
@@ -179,7 +179,7 @@ function showBanner(proxyOk) {
179
179
  const white = '\x1b[97m';
180
180
 
181
181
  const proxyLine = proxyOk
182
- ? `${green} ┃ ${greenD}Proxy ${green}${B}aktiv ✓${R}${green} http://localhost:${PROXY_PORT}/v1 ┃${R}`
182
+ ? `${green} ┃ ${greenD}Proxy ${green}${B}aktiv ✓${R}${green} http://localhost:${PROXY_PORT} ┃${R}`
183
183
  : `${yellow} ┃ ${yellow}Proxy direkte Anthropic API (kein Proxy) ┃${R}`;
184
184
 
185
185
  console.log('');
@@ -343,8 +343,13 @@ async function main() {
343
343
  XITHEAD_ENABLE_CONTEXT_TRIM: '1',
344
344
  HEADROOM_STRENGTH: 'aggressive',
345
345
  HEADROOM_COMPRESSION_RATIO_TARGET: '0.3',
346
- ANTHROPIC_BASE_URL: proxyOk ? `${PROXY_URL}/v1` : 'https://api.anthropic.com/v1',
347
346
  };
347
+ // Claude Code haengt /v1/... selbst an — Basis-URL daher OHNE /v1 (wie upstream headroom)
348
+ if (proxyOk) {
349
+ env.ANTHROPIC_BASE_URL = PROXY_URL;
350
+ } else {
351
+ delete env.ANTHROPIC_BASE_URL; // direkte Anthropic-API, Claude nutzt seinen Default
352
+ }
348
353
 
349
354
  const claudeResult = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['claude'], { stdio: 'pipe' });
350
355
  if (claudeResult.status !== 0) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xithead",
3
- "version": "1.2.0",
3
+ "version": "1.2.2",
4
4
  "description": "Aggressive Claude context optimizer - Cut API costs by 50-95%. By Xtream-ITSolutions UG.",
5
5
  "keywords": [
6
6
  "claude",
@@ -16,13 +16,13 @@
16
16
  ],
17
17
  "author": "Xtream-ITSolutions UG <hello@xtream-itsolutions.com>",
18
18
  "license": "Apache-2.0",
19
- "homepage": "https://github.com/xtream-itsolutions/headroom",
19
+ "homepage": "https://github.com/xtream-itsolutions/xithead",
20
20
  "repository": {
21
21
  "type": "git",
22
- "url": "git+https://github.com/xtream-itsolutions/headroom.git"
22
+ "url": "git+https://github.com/xtream-itsolutions/xithead.git"
23
23
  },
24
24
  "bugs": {
25
- "url": "https://github.com/xtream-itsolutions/headroom/issues"
25
+ "url": "https://github.com/xtream-itsolutions/xithead/issues"
26
26
  },
27
27
  "main": "npm/index.js",
28
28
  "types": "npm/index.d.ts",