compress-claude 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# compress-claude
+
+Compression proxy for Claude Code. Extends sessions and reduces token usage by 60-90%.
+
+## Install
+
+```bash
+npm install -g compress-claude
+```
+
+## Usage
+
+### Generate Context Files
+```bash
+# Scan your project and generate CLAUDE.md + ai-docs/
+compress-claude
+```
+
+### Start Compression Proxy
+```bash
+# Start the proxy (intercepts Claude Code API calls)
+compress-claude --proxy
+
+# With custom port
+compress-claude --proxy --port 5000
+```
+
+### Learn from Sessions
+```bash
+# Analyze past sessions and extract error-fix patterns
+compress-claude --learn
+```
+
+### Install Hooks
+```bash
+# Auto-learn hook + peak hours warning
+compress-claude --hooks
+```
+
+## What Gets Compressed
+
+The proxy compresses verbose tool outputs that waste tokens:
+- npm install/build logs (keeps errors only)
+- Test output (keeps PASS/FAIL summary)
+- Docker build logs (keeps step results)
+- pip install output (keeps errors)
+
+**Never compressed:** File reads, grep results, file edits - these need full content.
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| --proxy | Start compression proxy |
+| --port N | Proxy port (default: 4800) |
+| --learn | Analyze sessions for patterns |
+| --hooks | Install Claude Code hooks |
+| --doctor | Diagnose token waste |
+| --force | Overwrite existing files |
+| --dry-run | Preview without writing |
+| --verbose | Detailed output |
+| --help | Show help |
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,17 @@
+export interface CLIOptions {
+    force?: boolean;
+    dryRun?: boolean;
+    config?: boolean;
+    learn?: boolean;
+    proxy?: boolean;
+    hooks?: boolean;
+    doctor?: boolean;
+    inject?: string;
+    license?: string;
+    help?: boolean;
+    port?: number;
+    verbose?: boolean;
+}
+export declare function parseArgs(argv: string[]): CLIOptions;
+export declare function showHelp(): void;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+exports.showHelp = showHelp;
+const colors_1 = require("./utils/colors");
+function parseArgs(argv) {
+    const opts = {};
+    opts.force = argv.includes('--force') || argv.includes('-f');
+    opts.dryRun = argv.includes('--dry-run');
+    opts.config = argv.includes('--config') || argv.includes('-c');
+    opts.learn = argv.includes('--learn') || argv.includes('-l');
+    opts.proxy = argv.includes('--proxy') || argv.includes('-p');
+    opts.hooks = argv.includes('--hooks');
+    opts.doctor = argv.includes('--doctor') || argv.includes('-d');
+    opts.help = argv.includes('--help') || argv.includes('-h');
+    opts.verbose = argv.includes('--verbose') || argv.includes('-v');
+    // --inject "text"
+    let injectIdx = argv.indexOf('--inject');
+    if (injectIdx < 0)
+        injectIdx = argv.indexOf('-i');
+    if (injectIdx >= 0 && injectIdx + 1 < argv.length) {
+        opts.inject = argv[injectIdx + 1];
+    }
+    // activate <key>
+    const activateIdx = argv.indexOf('activate');
+    if (activateIdx >= 0 && activateIdx + 1 < argv.length) {
+        opts.license = argv[activateIdx + 1];
+    }
+    // --port <number>
+    const portIdx = argv.indexOf('--port');
+    if (portIdx >= 0 && portIdx + 1 < argv.length) {
+        const parsed = parseInt(argv[portIdx + 1], 10);
+        if (!isNaN(parsed)) {
+            opts.port = parsed;
+        }
+    }
+    return opts;
+}
+function showHelp() {
+    console.log((0, colors_1.bold)('Usage:') + '  npx compress-claude [options]\n');
+    console.log((0, colors_1.bold)('Generate context:'));
+    console.log('  ' + (0, colors_1.cyan)('(no flags)'.padEnd(22)) + 'Scan project and generate 4-layer context system');
+    console.log('  ' + (0, colors_1.cyan)('--force, -f'.padEnd(22)) + 'Overwrite existing files');
+    console.log('  ' + (0, colors_1.cyan)('--dry-run'.padEnd(22)) + 'Preview what would be generated');
+    console.log('  ' + (0, colors_1.cyan)('--config, -c'.padEnd(22)) + 'Update personal defaults (~/.compress-claude/defaults.json)\n');
+    console.log((0, colors_1.bold)('License:'));
+    console.log('  ' + (0, colors_1.cyan)('activate <key>'.padEnd(22)) + 'Activate your license key');
+    console.log('  ' + (0, colors_1.cyan)('deactivate'.padEnd(22)) + 'Remove license from this machine\n');
+    console.log((0, colors_1.bold)('Token saving (built-in, zero dependencies):'));
+    console.log('  ' + (0, colors_1.cyan)('--proxy, -p'.padEnd(22)) + 'Start compression proxy (saves 60-90% on tool outputs)');
+    console.log('  ' + (0, colors_1.cyan)('--learn, -l'.padEnd(22)) + 'Learn from past sessions, write fixes to CLAUDE.md');
+    console.log('  ' + (0, colors_1.cyan)('--learn --all'.padEnd(22)) + 'Learn from ALL projects');
+    console.log('  ' + (0, colors_1.cyan)('--stats, -s'.padEnd(22)) + 'Token usage stats for this project');
+    console.log('  ' + (0, colors_1.cyan)('--doctor, -d'.padEnd(22)) + 'Diagnose token waste and suggest fixes');
+    console.log('  ' + (0, colors_1.cyan)('--inject, -i "text"'.padEnd(22)) + 'Inject a learning Claude will always see');
+    console.log('  ' + (0, colors_1.cyan)('--hooks'.padEnd(22)) + 'Install auto-learn hook + peak hours warning');
+    console.log('  ' + (0, colors_1.cyan)('--api-proxy'.padEnd(22)) + 'Generate production API proxy (model routing, caching, compression)\n');
+    console.log((0, colors_1.bold)('Proxy setup (one-time):'));
+    console.log('  ' + (0, colors_1.cyan)('compress-claude activate cc_live_...') + (0, colors_1.gray)(' # activate license'));
+    console.log('  ' + (0, colors_1.cyan)('compress-claude --proxy') + (0, colors_1.gray)('              # run in separate terminal'));
+    console.log('  ' + (0, colors_1.cyan)('export ANTHROPIC_BASE_URL=http://localhost:8787') + (0, colors_1.gray)('  # add to .bashrc\n'));
+    console.log((0, colors_1.bold)('What gets generated:'));
+    console.log('  CLAUDE.md              Layer 1 -- always loaded (~400 tokens)');
+    console.log('  ai-docs/*.md           Layer 2 -- domain context, load per session');
+    console.log('  ai-docs/PROMPTS.md     Layer 3 -- pattern library index');
+    console.log('  ai-docs/prompts/*.md   Layer 3 -- Build/Verify/Debug per pattern');
+    console.log('  ai-docs/skills/*.md    Supporting -- role personas (frontend/backend/devops)');
+    console.log('  ai-docs/security.md    Supporting -- OWASP + STRIDE for your stack');
+    console.log('  ai-docs/HANDOVER.md    Extra -- resume sessions cheaply');
+    console.log('  ai-docs/MISTAKES.md    Extra -- never repeat the same error');
+    console.log('  ai-docs/TOKEN-RULES.md Extra -- keep Claude lean and direct\n');
+}
+//# sourceMappingURL=cli.js.map

package/dist/doctor.d.ts

@@ -0,0 +1,2 @@
+export declare function runDoctor(cwd?: string): Promise<void>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.js

@@ -0,0 +1,191 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDoctor = runDoctor;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const http = __importStar(require("http"));
+const colors_1 = require("./utils/colors");
+const tokens_1 = require("./utils/tokens");
+async function runDoctor(cwd) {
+    const dir = cwd || process.cwd();
+    console.log('\n' + (0, colors_1.boldCyan)('claude-context --doctor') + '\n');
+    const issues = [];
+    const suggestions = [];
+    // 1. Check if CLAUDE.md exists
+    const claudeMdPath = path.join(dir, 'CLAUDE.md');
+    if (!fs.existsSync(claudeMdPath)) {
+        issues.push({
+            severity: 'high',
+            text: 'No CLAUDE.md found. Run `npx claude-context` to generate one.',
+        });
+    }
+    else {
+        const claudeSize = fs.readFileSync(claudeMdPath, 'utf8').length;
+        const claudeTokens = (0, tokens_1.estimateTokens)(fs.readFileSync(claudeMdPath, 'utf8'));
+        if (claudeTokens > 2000) {
+            issues.push({
+                severity: 'medium',
+                text: `CLAUDE.md is ${claudeTokens} tokens. Keep it under 1000 for Layer 1 -- move details to ai-docs/.`,
+            });
+        }
+        else {
+            suggestions.push(`CLAUDE.md is lean (${claudeTokens} tokens) -- good.`);
+        }
+    }
+    // 2. Check global CLAUDE.md
+    const globalClaudeMd = path.join(os.homedir(), '.claude', 'CLAUDE.md');
+    if (fs.existsSync(globalClaudeMd)) {
+        const globalSize = (0, tokens_1.estimateTokens)(fs.readFileSync(globalClaudeMd, 'utf8'));
+        if (globalSize > 3000) {
+            issues.push({
+                severity: 'medium',
+                text: `~/.claude/CLAUDE.md is ${globalSize} tokens. Large global instructions burn tokens in every project.`,
+            });
+        }
+    }
+    // 3. Check if proxy is running
+    try {
+        await new Promise((resolve) => {
+            const req = http.get('http://localhost:8787/health', (res) => {
+                suggestions.push('Compression proxy is running on :8787 -- tool outputs are being compressed.');
+                res.resume();
+                resolve();
+            });
+            req.on('error', () => {
+                issues.push({
+                    severity: 'high',
+                    text: 'Compression proxy not running. Start it: `npx claude-context --proxy`',
+                });
+                resolve();
+            });
+            req.setTimeout(1000, () => {
+                req.destroy();
+                resolve();
+            });
+        });
+    }
+    catch {
+        issues.push({
+            severity: 'high',
+            text: 'Compression proxy not running. Tool outputs are flooding your context.',
+        });
+    }
+    // 4. Check ANTHROPIC_BASE_URL
+    if (!process.env.ANTHROPIC_BASE_URL || !process.env.ANTHROPIC_BASE_URL.includes('localhost')) {
+        issues.push({
+            severity: 'high',
+            text: 'ANTHROPIC_BASE_URL not set to localhost. Add to ~/.bashrc: export ANTHROPIC_BASE_URL=http://localhost:8787',
+        });
+    }
+    else {
+        suggestions.push('ANTHROPIC_BASE_URL points to proxy -- compression is active.');
+    }
+    // 5. Peak hours check
+    const now = new Date();
+    const estHour = parseInt(new Date(now.toLocaleString('en-US', { timeZone: 'America/New_York' })).getHours().toString(), 10);
+    if (estHour >= 10 && estHour < 16) {
+        issues.push({
+            severity: 'low',
+            text: `Currently peak hours (${estHour}:00 EST). Anthropic throttles rate limits 10AM-4PM EST. Consider working off-peak for heavy sessions.`,
+        });
+    }
+    else {
+        suggestions.push(`Off-peak hours (${estHour}:00 EST) -- rate limits are more generous.`);
+    }
+    // 6. Check ai-docs exist
+    if (!fs.existsSync(path.join(dir, 'ai-docs'))) {
+        issues.push({
+            severity: 'low',
+            text: 'No ai-docs/ directory. Run `npx claude-context` to generate domain docs and pattern library.',
+        });
+    }
+    // 7. Check MISTAKES.md
+    if (fs.existsSync(path.join(dir, 'ai-docs', 'MISTAKES.md'))) {
+        suggestions.push('MISTAKES.md exists -- Claude checks this before repeating errors.');
+    }
+    // 8. Check TOKEN-RULES.md
+    if (fs.existsSync(path.join(dir, 'ai-docs', 'TOKEN-RULES.md'))) {
+        suggestions.push('TOKEN-RULES.md exists -- Claude stays lean and direct.');
+    }
+    // Display results
+    const highCount = issues.filter((i) => i.severity === 'high').length;
+    const medCount = issues.filter((i) => i.severity === 'medium').length;
+    const lowCount = issues.filter((i) => i.severity === 'low').length;
+    if (issues.length === 0) {
+        console.log((0, colors_1.boldGreen)('No issues found. Your token setup looks solid.\n'));
+    }
+    else {
+        console.log((0, colors_1.bold)('Issues found: ') +
+            (highCount > 0 ? (0, colors_1.red)(`${highCount} critical`) : '') +
+            (medCount > 0 ? ' ' + (0, colors_1.yellow)(`${medCount} medium`) : '') +
+            (lowCount > 0 ? ' ' + (0, colors_1.gray)(`${lowCount} low`) : '') +
+            '\n');
+        for (const issue of issues) {
+            const icon = issue.severity === 'high'
+                ? (0, colors_1.red)('!!')
+                : issue.severity === 'medium'
+                    ? (0, colors_1.yellow)(' !')
+                    : (0, colors_1.gray)(' -');
+            console.log('  ' + icon + ' ' + issue.text);
+        }
+    }
+    if (suggestions.length > 0) {
+        console.log('\n' + (0, colors_1.bold)('Status:'));
+        for (const suggestion of suggestions) {
+            console.log('  ' + (0, colors_1.green)('+') + ' ' + suggestion);
+        }
+    }
+    // Score
+    const maxScore = 100;
+    let score = maxScore - highCount * 20 - medCount * 10 - lowCount * 5;
+    score = Math.max(0, Math.min(100, score));
+    const scoreColor = score >= 80 ? colors_1.boldGreen : score >= 50 ? colors_1.boldYellow : colors_1.red;
+    console.log('\n' + (0, colors_1.bold)('Token efficiency score: ') + scoreColor(`${score}/100`));
+    if (score < 80) {
+        console.log('\n' + (0, colors_1.bold)('Quick wins:'));
+        if (!process.env.ANTHROPIC_BASE_URL || !process.env.ANTHROPIC_BASE_URL.includes('localhost')) {
+            console.log('  1. ' + (0, colors_1.cyan)('npx claude-context --proxy') + '  (start in separate terminal)');
+            console.log('     ' + (0, colors_1.cyan)('export ANTHROPIC_BASE_URL=http://localhost:8787') + '  (add to shell rc)');
+        }
+        if (!fs.existsSync(claudeMdPath)) {
+            console.log('  2. ' + (0, colors_1.cyan)('npx claude-context') + '  (generate context system)');
+        }
+        console.log('  3. ' + (0, colors_1.cyan)('npx claude-context --learn') + '  (learn from past mistakes)');
+    }
+    console.log('');
+}
+//# sourceMappingURL=doctor.js.map

package/dist/generator.d.ts

@@ -0,0 +1,35 @@
+import { StackInfo } from './scanner';
+export interface GeneratorOptions {
+    force?: boolean;
+    dryRun?: boolean;
+}
+export interface Answers {
+    domains?: string[];
+    alwaysDocs?: string[];
+    conventions?: string[];
+    alwaysUse?: string[];
+    preferredOrm?: string;
+    deployment?: string;
+    gitFlow?: boolean;
+    never?: string[];
+    [key: string]: unknown;
+}
+interface FileEntry {
+    filename: string;
+    label: string;
+    key?: string;
+}
+declare function claudeMd(stack: StackInfo, answers: Answers): string;
+declare const ALL_DOMAIN_DOCS: FileEntry[];
+declare const SKILL_FILES: FileEntry[];
+declare const EXTRA_FILES: FileEntry[];
+declare function getDomainFiles(stack: StackInfo, answers: Answers): FileEntry[];
+declare function generateDomainDoc(filename: string, stack: StackInfo): string;
+declare function generatePromptFile(filename: string, stack: StackInfo): string;
+declare function getPromptFiles(stack: StackInfo, answers: Answers): FileEntry[];
+declare function generateSkillFile(filename: string): string;
+declare function generateExtraFile(filename: string, stack: StackInfo): string;
+export declare function generateContextFiles(projectDir: string, stack: StackInfo, options: GeneratorOptions, answers?: Answers): void;
+export { claudeMd, generateDomainDoc, getDomainFiles, ALL_DOMAIN_DOCS, generatePromptFile, getPromptFiles, generateSkillFile, SKILL_FILES, generateExtraFile, EXTRA_FILES, };
+export type { FileEntry };
+//# sourceMappingURL=generator.d.ts.map