{"_id":"@ambiad3s/token-optimizer-mcp","name":"@ambiad3s/token-optimizer-mcp","dist-tags":{"latest":"5.0.2"},"versions":{"5.0.2":{"name":"@ambiad3s/token-optimizer-mcp","version":"5.0.2","mcpName":"io.github.ooples/token-optimizer-mcp","description":"Intelligent context window optimization for Claude Code - store content externally via caching and compression, freeing up your context window for what matters","main":"dist/server/index.js","types":"dist/server/index.d.ts","bin":{"token-optimizer-mcp":"dist/server/index.js","token-optimizer-daemon":"dist/server/daemon.js"},"scripts":{"postinstall":"node scripts/postinstall.cjs","build":"tsc && npm run copy:assets","copy:assets":"node -e \"require('fs').cpSync('src/dashboard/public','dist/dashboard/public',{recursive:true})\"","start":"node dist/server/index.js","dev":"tsc --watch","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build && npm test","test":"node --experimental-vm-modules node_modules/jest/bin/jest.js","test:watch":"node --experimental-vm-modules node_modules/jest/bin/jest.js --watch","test:ci":"node --experimental-vm-modules node_modules/jest/bin/jest.js --ci --coverage --maxWorkers=2","test:coverage":"node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage","test:integration":"node --experimental-vm-modules node_modules/jest/bin/jest.js tests/integration","test:unit":"node --experimental-vm-modules node_modules/jest/bin/jest.js tests/unit","test:benchmark":"node --experimental-vm-modules node_modules/jest/bin/jest.js tests/benchmarks","dashboard":"node dist/server/web-server.js","dashboard:dev":"tsc -p tsconfig.dashboard.json && npm run copy:assets && node dist/server/web-server.js","dashboard:build":"tsc -p tsconfig.dashboard.json && npm run copy:assets","lint":"eslint src --ext .ts,.js","lint:fix":"eslint src --ext .ts,.js --fix","format":"prettier --write 'src/**/*.{ts,js,json}'","format:check":"prettier --check 'src/**/*.{ts,js,json}'","validate":"node scripts/validate-package.js"},"repository":{"type":"git","url":"git+https://github.com/ooples/token-optimizer-mcp.git"},"keywords":["mcp","model-context-protocol","claude","claude-code","token-optimization","caching","compression","ai","llm","context-management","prompt-optimization"],"author":{"name":"ooples"},"license":"MIT","type":"module","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"exports":{".":{"require":"./dist/server/index.js","import":"./dist/server/index.js","types":"./dist/server/index.d.ts"}},"engines":{"node":">=18.0.0","npm":">=9.0.0"},"bugs":{"url":"https://github.com/ooples/token-optimizer-mcp/issues"},"homepage":"https://github.com/ooples/token-optimizer-mcp#readme","devDependencies":{"@commitlint/cli":"^19.6.0","@commitlint/config-conventional":"^19.6.0","@semantic-release/changelog":"^6.0.3","@semantic-release/commit-analyzer":"^13.0.0","@semantic-release/git":"^10.0.1","@semantic-release/github":"^11.0.0","@semantic-release/npm":"^13.1.3","@semantic-release/release-notes-generator":"^14.0.1","@types/better-sqlite3":"^7.6.13","@types/body-parser":"^1.19.6","@types/conventional-commits-parser":"^5.0.1","@types/cors":"^2.8.19","@types/express":"^5.0.3","@types/express-serve-static-core":"^5.1.0","@types/http-errors":"^2.0.5","@types/jest":"^30.0.0","@types/json-schema":"^7.0.15","@types/mime":"^3.0.4","@types/node":"^24.7.2","@types/normalize-package-data":"^2.4.4","@types/qs":"^6.14.0","@types/range-parser":"^1.2.7","@types/send":"^1.2.0","@types/serve-static":"^1.15.9","@types/tar-stream":"^3.1.4","@typescript-eslint/eslint-plugin":"^8.46.1","@typescript-eslint/parser":"^8.46.1","conventional-changelog-conventionalcommits":"^8.0.0","eslint":"^9.38.0","eslint-config-prettier":"^10.1.8","jest":"^30.2.0","prettier":"^3.6.2","semantic-release":"^25.0.2","ts-jest":"^29.4.5","typescript":"^5.9.3"},"dependencies":{"@modelcontextprotocol/sdk":"^1.26.0","async-mutex":"^0.5.0","better-sqlite3":"^12.4.1","cors":"^2.8.5","diff":"^8.0.2","express":"^5.1.0","glob":"^11.1.0","lru-cache":"^11.2.2","tiktoken":"^1.0.22","zod":">=3.25.0 <5"},"gitHead":"85d6f46389dcd4ebfe2e1a9b9e9c635ffce2cef2","_id":"@ambiad3s/token-optimizer-mcp@5.0.2","_nodeVersion":"22.22.1","_npmVersion":"9.2.0","dist":{"integrity":"sha512-+KQPQTszIH+O6V5xxcQjuUMCxMTOjS9OYuDX4X0sOIx4Qe1Pyo6KMELFlpLrMPGoWA4fQPHcw+080K7D62IDWQ==","shasum":"9a9b37e5d193f5a78ae140aad8a21fba406f028d","tarball":"https://registry.npmjs.org/@ambiad3s/token-optimizer-mcp/-/token-optimizer-mcp-5.0.2.tgz","fileCount":664,"unpackedSize":5955070,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBW1pgAEib2pz+1oheB4xchTFnMMVVQAJ7vz1MlZcPHBAiEA2AyHp2VCH7AP3tr4wci/s8UNYlMJi0daBB6vt4HbZGg="}]},"_npmUser":{"name":"ambiad3s","email":"ambiad3s@gmail.com"},"directories":{},"maintainers":[{"name":"ambiad3s","email":"ambiad3s@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/token-optimizer-mcp_5.0.2_1780017529162_0.42839359223184026"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-29T01:18:49.023Z","5.0.2":"2026-05-29T01:18:49.365Z","modified":"2026-05-29T01:18:49.550Z"},"maintainers":[{"name":"ambiad3s","email":"ambiad3s@gmail.com"}],"description":"Intelligent context window optimization for Claude Code - store content externally via caching and compression, freeing up your context window for what matters","homepage":"https://github.com/ooples/token-optimizer-mcp#readme","keywords":["mcp","model-context-protocol","claude","claude-code","token-optimization","caching","compression","ai","llm","context-management","prompt-optimization"],"repository":{"type":"git","url":"git+https://github.com/ooples/token-optimizer-mcp.git"},"author":{"name":"ooples"},"bugs":{"url":"https://github.com/ooples/token-optimizer-mcp/issues"},"license":"MIT","readme":"# Token Optimizer MCP\n\n> Intelligent token optimization through caching, compression, and smart tooling for Claude Code and Claude Desktop\n\n## Overview\n\nToken Optimizer MCP is a Model Context Protocol (MCP) server that reduces context window usage by 60-90% through intelligent caching, compression, and smart tool replacements. By storing compressed content externally in SQLite and providing optimized alternatives to standard tools, the server helps you maximize your available context window.\n\n**Production Results**: 60-90% token reduction across 38,000+ operations in real-world usage.\n\n## Key Features\n\n- **Smart Tool Replacements**: Automatic optimization for Read, Grep, Glob, and more\n- **Context Window Optimization**: Store content externally to free up context space\n- **High Compression**: Brotli compression (2-4x typical, up to 82x for repetitive content)\n- **Persistent Caching**: SQLite-based cache that persists across sessions\n- **Accurate Token Counting**: Uses tiktoken for precise token measurements\n- **61 Specialized Tools**: File operations, API caching, database optimization, monitoring, and more\n- **Zero External Dependencies**: Completely offline operation\n- **Production Ready**: Built with TypeScript for reliability\n\n## Installation\n\n### Quick Install (Recommended)\n\n#### Windows\n\n```powershell\n# Run PowerShell as Administrator, then:\nSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser\n\n# Install globally (hooks install automatically!)\nnpm install -g @ooples/token-optimizer-mcp\n```\n\n#### macOS / Linux\n\n```bash\n# Install globally (hooks install automatically!)\nnpm install -g @ooples/token-optimizer-mcp\n```\n\nThat's it! The postinstall script will automatically:\n1. ✅ Install token-optimizer-mcp globally via npm\n2. ✅ Auto-detect and configure all installed AI tools (Claude Desktop, Cursor, Cline, etc.)\n3. ✅ Set up automatic token optimization on every tool call\n4. ✅ Configure workspace trust and execution permissions\n\n**Result**: 60-90% token reduction across all operations!\n\n**Note**: If automatic installation is skipped (e.g., in CI environments), you can manually run the installer:\n- Windows: `powershell -ExecutionPolicy Bypass -File install-hooks.ps1`\n- macOS/Linux: `bash install-hooks.sh`\n\n### Manual Configuration\n\nFor detailed platform-specific installation instructions, see [docs/HOOKS-INSTALLATION.md](./docs/HOOKS-INSTALLATION.md).\n\n## Available Tools (65 Total)\n\n### Core Caching & Optimization (8 tools)\n\n<details>\n<summary>Click to expand</summary>\n\n- **optimize_text** - Compress and cache text (primary tool for token reduction)\n- **get_cached** - Retrieve previously cached text\n- **compress_text** - Compress text using Brotli\n- **decompress_text** - Decompress Brotli-compressed text\n- **count_tokens** - Count tokens using tiktoken (GPT-4 tokenizer)\n- **analyze_optimization** - Analyze text and get optimization recommendations\n- **get_cache_stats** - View cache hit rates and compression ratios\n- **clear_cache** - Clear all cached data\n\n**Usage Example**:\n```typescript\n// Cache large content to remove it from context window\noptimize_text({\n  text: \"Large API response or file content...\",\n  key: \"api-response-key\",\n  quality: 11\n})\n// Result: 60-90% token reduction\n```\n\n</details>\n\n### Smart File Operations (10 tools)\n\n<details>\n<summary>Click to expand</summary>\n\nOptimized replacements for standard file tools with intelligent caching and diff-based updates:\n\n- **smart_read** - Read files with 80% token reduction through caching and diffs\n- **smart_write** - Write files with verification and change tracking\n- **smart_edit** - Line-based file editing with diff-only output (90% reduction)\n- **smart_grep** - Search file contents with match-only output (80% reduction)\n- **smart_glob** - File pattern matching with path-only results (75% reduction)\n- **smart_diff** - Git diffs with diff-only output (85% reduction)\n- **smart_branch** - Git branch listing with structured JSON (60% reduction)\n- **smart_log** - Git commit history with smart filtering (75% reduction)\n- **smart_merge** - Git merge management with conflict analysis (80% reduction)\n- **smart_status** - Git status with status-only output (70% reduction)\n\n**Usage Example**:\n```typescript\n// Read a file with automatic caching\nsmart_read({ path: \"/path/to/file.ts\" })\n// First read: full content\n// Subsequent reads: only diff (80% reduction)\n```\n\n</details>\n\n### API & Database Operations (10 tools)\n\n<details>\n<summary>Click to expand</summary>\n\nIntelligent caching and optimization for external data sources:\n\n- **smart_api_fetch** - HTTP requests with caching and retry logic (83% reduction on cache hits)\n- **smart_cache_api** - API response caching with TTL/ETag/event-based strategies\n- **smart_database** - Database queries with connection pooling and caching (83% reduction)\n- **smart_sql** - SQL query analysis with optimization suggestions (83% reduction)\n- **smart_schema** - Database schema analysis with intelligent caching\n- **smart_graphql** - GraphQL query optimization with complexity analysis (83% reduction)\n- **smart_rest** - REST API analysis with endpoint discovery (83% reduction)\n- **smart_orm** - ORM query optimization with N+1 detection (83% reduction)\n- **smart_migration** - Database migration tracking (83% reduction)\n- **smart_websocket** - WebSocket connection management with message tracking\n\n**Usage Example**:\n```typescript\n// Fetch API with automatic caching\nsmart_api_fetch({\n  method: \"GET\",\n  url: \"https://api.example.com/data\",\n  ttl: 300\n})\n// Cached responses: 95% token reduction\n```\n\n</details>\n\n### Build & Test Operations (10 tools)\n\n<details>\n<summary>Click to expand</summary>\n\nDevelopment workflow optimization with intelligent caching:\n\n- **smart_build** - TypeScript builds with diff-based change detection\n- **smart_test** - Test execution with incremental test selection\n- **smart_lint** - ESLint with incremental analysis and auto-fix\n- **smart_typecheck** - TypeScript type checking with caching\n- **smart_install** - Package installation with dependency analysis\n- **smart_docker** - Docker operations with layer analysis\n- **smart_logs** - Log aggregation with pattern filtering\n- **smart_network** - Network diagnostics with anomaly detection\n- **smart_processes** - Process monitoring with resource tracking\n- **smart_system_metrics** - System resource monitoring with performance recommendations\n\n**Usage Example**:\n```typescript\n// Run tests with caching\nsmart_test({\n  onlyChanged: true,  // Only test changed files\n  coverage: true\n})\n```\n\n</details>\n\n### Advanced Caching (10 tools)\n\n<details>\n<summary>Click to expand</summary>\n\nEnterprise-grade caching strategies with 87-92% token reduction:\n\n- **smart_cache** - Multi-tier cache (L1/L2/L3) with 6 eviction strategies (90% reduction)\n- **cache_warmup** - Intelligent cache pre-warming with schedule support (87% reduction)\n- **cache_analytics** - Real-time dashboards and trend analysis (88% reduction)\n- **cache_benchmark** - Performance testing and strategy comparison (89% reduction)\n- **cache_compression** - 6 compression algorithms with adaptive selection (89% reduction)\n- **cache_invalidation** - Dependency tracking and pattern-based invalidation (88% reduction)\n- **cache_optimizer** - ML-based recommendations and bottleneck detection (89% reduction)\n- **cache_partition** - Sharding and consistent hashing (87% reduction)\n- **cache_replication** - Distributed replication with conflict resolution (88% reduction)\n- **predictive_cache** - ML-based predictive caching with ARIMA/LSTM (91% reduction)\n\n**Usage Example**:\n```typescript\n// Configure multi-tier cache\nsmart_cache({\n  operation: \"configure\",\n  evictionStrategy: \"LRU\",\n  l1MaxSize: 1000,\n  l2MaxSize: 10000\n})\n```\n\n</details>\n\n### Monitoring & Dashboards (7 tools)\n\n<details>\n<summary>Click to expand</summary>\n\nComprehensive monitoring with 88-92% token reduction through intelligent caching:\n\n- **alert_manager** - Multi-channel alerting (email, Slack, webhook) with routing (89% reduction)\n- **metric_collector** - Time-series metrics with multi-source support (88% reduction)\n- **monitoring_integration** - External platform integration (Prometheus, Grafana, Datadog) (87% reduction)\n- **custom_widget** - Dashboard widgets with template caching (88% reduction)\n- **data_visualizer** - Interactive visualizations with SVG optimization (92% reduction)\n- **health_monitor** - System health checks with state compression (91% reduction)\n- **log_dashboard** - Log analysis with pattern detection (90% reduction)\n\n**Usage Example**:\n```typescript\n// Create an alert\nalert_manager({\n  operation: \"create-alert\",\n  alertName: \"high-cpu-usage\",\n  channels: [\"slack\", \"email\"],\n  threshold: { type: \"above\", value: 80 }\n})\n```\n\n</details>\n\n### System Operations (6 tools)\n\n<details>\n<summary>Click to expand</summary>\n\nSystem-level operations with smart caching:\n\n- **smart_cron** - Scheduled task management (cron/Windows Task Scheduler) (85% reduction)\n- **smart_user** - User and permission management across platforms (86% reduction)\n- **smart_ast_grep** - Structural code search with AST indexing (83% reduction)\n- **get_session_stats** - Session-level token usage statistics\n- **analyze_project_tokens** - Project-wide token analysis and cost estimation\n- **optimize_session** - Compress large file operations from current session\n\n**Usage Example**:\n```typescript\n// View session token usage\nget_session_stats({})\n// Result: Detailed breakdown of token usage by tool\n```\n\n</details>\n\n## How It Works\n\n\n\n### Token Analytics (4 tools)\n\n<details>\n<summary>Click to expand</summary>\n\nGranular token usage analytics for pinpointing optimization opportunities:\n\n- **get_hook_analytics** - Token usage breakdown by hook phase (PreToolUse, PostToolUse, etc.)\n- **get_action_analytics** - Token usage breakdown by tool/action (Read, Write, Grep, etc.)\n- **get_mcp_server_analytics** - Token usage breakdown by MCP server (token-optimizer, filesystem, etc.)\n- **export_analytics** - Export analytics data in JSON or CSV format with filtering\n\n**Usage Example**:\n```typescript\n// Get per-hook analytics\nget_hook_analytics({\n  startDate: \"2025-01-01T00:00:00Z\",\n  endDate: \"2025-12-31T23:59:59Z\"\n})\n// Result: Shows which hooks consume the most tokens\n\n// Get per-action analytics\nget_action_analytics({})\n// Result: Shows which tools use the most tokens\n\n// Export analytics as CSV\nexport_analytics({\n  format: \"csv\",\n  hookPhase: \"PreToolUse\"\n})\n// Result: CSV export filtered by PreToolUse hook\n```\n\n**Key Features**:\n- Per-hook phase tracking (PreToolUse, PostToolUse, SessionStart, etc.)\n- Per-action tracking (Read, Write, count_tokens, etc.)\n- Per-MCP-server tracking (token-optimizer, filesystem, GitHub, etc.)\n- Date range filtering\n- JSON and CSV export\n- Persistent storage with SQLite\n- Zero performance impact (async batched writes)\n\n</details>\n\n### Global Hooks System (7-Phase Optimization)\n\nWhen global hooks are installed, token-optimizer-mcp runs automatically on **every tool call**:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Phase 1: PreToolUse - Tool Replacement                      │\n│ ├─ Read   → smart_read   (80% token reduction)             │\n│ ├─ Grep   → smart_grep   (80% token reduction)             │\n│ └─ Glob   → smart_glob   (75% token reduction)             │\n└─────────────────────────────────────────────────────────────┘\n                          ↓\n┌─────────────────────────────────────────────────────────────┐\n│ Phase 2: Input Validation - Cache Lookups                   │\n│ └─ get_cached checks if operation was already done          │\n└─────────────────────────────────────────────────────────────┘\n                          ↓\n┌─────────────────────────────────────────────────────────────┐\n│ Phase 3: PostToolUse - Output Optimization                  │\n│ ├─ optimize_text for large outputs                          │\n│ └─ compress_text for repeated content                       │\n└─────────────────────────────────────────────────────────────┘\n                          ↓\n┌─────────────────────────────────────────────────────────────┐\n│ Phase 4: Session Tracking                                   │\n│ └─ Log all operations to operations-{sessionId}.csv         │\n└─────────────────────────────────────────────────────────────┘\n                          ↓\n┌─────────────────────────────────────────────────────────────┐\n│ Phase 5: UserPromptSubmit - Prompt Optimization             │\n│ └─ Optimize user prompts before sending to API              │\n└─────────────────────────────────────────────────────────────┘\n                          ↓\n┌─────────────────────────────────────────────────────────────┐\n│ Phase 6: PreCompact - Pre-Compaction Optimization           │\n│ └─ Optimize before Claude Code compacts the conversation    │\n└─────────────────────────────────────────────────────────────┘\n                          ↓\n┌─────────────────────────────────────────────────────────────┐\n│ Phase 7: Metrics & Reporting                                │\n│ └─ Track token reduction metrics and generate reports       │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## Production Performance\n\nBased on 38,000+ operations in real-world usage:\n\n| Tool Category | Avg Token Reduction | Cache Hit Rate |\n|--------------|-------------------|----------------|\n| File Operations | 60-90% | >80% |\n| API Responses | 83-95% | >75% |\n| Database Queries | 83-90% | >70% |\n| Build/Test Output | 70-85% | >65% |\n\n**Per-Session Savings**: 300K-700K tokens (worth $0.90-$2.10 at $3/M tokens)\n\n## Usage Examples\n\n### Basic Caching\n\n```typescript\n// Cache large content to remove from context window\nconst result = await optimize_text({\n  text: \"Large API response or file content...\",\n  key: \"cache-key\",\n  quality: 11\n});\n// Result: Original tokens removed, only cache key remains (~50 tokens)\n\n// Retrieve later\nconst cached = await get_cached({ key: \"cache-key\" });\n// Result: Full original content restored\n```\n\n### Smart File Reading\n\n```typescript\n// First read: full content\nawait smart_read({ path: \"/src/app.ts\" });\n\n// Subsequent reads: only changes (80% reduction)\nawait smart_read({ path: \"/src/app.ts\" });\n```\n\n### API Caching\n\n```typescript\n// First request: fetch and cache\nawait smart_api_fetch({\n  method: \"GET\",\n  url: \"https://api.example.com/data\",\n  ttl: 300\n});\n\n// Subsequent requests: cached (95% reduction)\nawait smart_api_fetch({\n  method: \"GET\",\n  url: \"https://api.example.com/data\"\n});\n```\n\n### Session Analysis\n\n```typescript\n// View token usage for current session\nawait get_session_stats({});\n// Result: Breakdown by tool, operation, and savings\n\n// Analyze entire project\nawait analyze_project_tokens({\n  projectPath: \"/path/to/project\"\n});\n// Result: Cost estimation and optimization opportunities\n```\n\n## Technology Stack\n\n- **Runtime**: Node.js 20+\n- **Language**: TypeScript\n- **Database**: SQLite (better-sqlite3)\n- **Token Counting**: tiktoken (GPT-4 tokenizer)\n- **Compression**: Brotli (built-in Node.js)\n- **Caching**: Multi-tier LRU/LFU/FIFO caching\n- **Protocol**: MCP SDK (@modelcontextprotocol/sdk)\n\n## Supported AI Tools\n\nThe automated installer detects and configures token-optimizer-mcp for:\n\n- ✅ **Claude Code** - CLI with global hooks integration\n- ✅ **Claude Desktop** - Native desktop application\n- ✅ **Cursor IDE** - AI-first code editor\n- ✅ **Cline** - VS Code extension (formerly Claude Dev)\n- ✅ **GitHub Copilot** - VS Code with MCP support\n- ✅ **Windsurf IDE** - AI-powered development environment\n\n**No manual configuration needed** - the installer automatically detects and configures all installed tools!\n\n## Documentation\n\n- **[Detailed Tool Reference](./docs/TOOLS.md)** - Complete documentation for all 61 tools\n- **[Installation Guide](./docs/HOOKS-INSTALLATION.md)** - Platform-specific installation instructions\n- **[Contributing Guide](./docs/CONTRIBUTING.md)** - Development setup and contribution guidelines\n\n## Performance Characteristics\n\n- **Compression Ratio**: 2-4x typical (up to 82x for repetitive content)\n- **Context Window Savings**: 60-90% average across all operations\n- **Cache Hit Rate**: >80% in typical usage\n- **Operation Overhead**: <10ms for cache operations (optimized from 50-70ms)\n- **Compression Speed**: ~1ms per KB of text\n- **Hook Overhead**: <10ms per operation (7x improvement from in-memory optimizations)\n\n### Performance Optimizations\n\nThe PowerShell hooks have been optimized to reduce overhead from 50-70ms to <10ms through:\n\n- **In-Memory Session State**: Session data kept in memory instead of disk I/O on every operation\n- **Batched Log Writes**: Operation logs buffered and flushed every 5 seconds or 100 operations\n- **Lazy Persistence**: Disk writes only occur when necessary (session end, optimization, reports)\n\n### Environment Variables\n\nControl hook behavior with these environment variables:\n\n#### Performance Controls\n\n- **`TOKEN_OPTIMIZER_USE_FILE_SESSION`** (default: `false`)\n  - Set to `true` to revert to file-based session tracking (legacy mode)\n  - Use if you encounter issues with in-memory session state\n  - Example: `$env:TOKEN_OPTIMIZER_USE_FILE_SESSION = \"true\"`\n\n- **`TOKEN_OPTIMIZER_SYNC_LOG_WRITES`** (default: `false`)\n  - Set to `true` to disable batched log writes\n  - Forces immediate writes to disk (slower but more resilient)\n  - Use for debugging or if logs are being lost\n  - Example: `$env:TOKEN_OPTIMIZER_SYNC_LOG_WRITES = \"true\"`\n\n- **`TOKEN_OPTIMIZER_DEBUG_LOGGING`** (default: `true`)\n  - Set to `false` to disable DEBUG-level logging\n  - Reduces log file size and improves performance\n  - INFO/WARN/ERROR logs still written\n  - Example: `$env:TOKEN_OPTIMIZER_DEBUG_LOGGING = \"false\"`\n\n#### Development Path\n\n- **`TOKEN_OPTIMIZER_DEV_PATH`**\n  - Path to local development installation\n  - Automatically set to `~/source/repos/token-optimizer-mcp` if not specified\n  - Override for custom development paths\n  - Example: `$env:TOKEN_OPTIMIZER_DEV_PATH = \"C:\\dev\\token-optimizer-mcp\"`\n\n**Performance Impact**: Using in-memory mode (default) provides a 7x improvement in hook overhead:\n- Before: 50-70ms per hook operation\n- After: <10ms per hook operation\n- 85% reduction in hook latency\n\n## Monitoring Token Savings\n\n### Real-Time Session Monitoring\n\n**To view your actual token SAVINGS**, use the `get_session_stats` tool:\n\n```typescript\n// View current session statistics with token savings breakdown\nawait get_session_stats({});\n```\n\n**Output includes:**\n- **Total tokens saved** (this is the actual savings amount!)\n- **Token reduction percentage** (e.g., \"60% reduction\")\n- **Cache hit rate** and **compression ratios**\n- **Breakdown by tool** (Read, Grep, Glob, etc.)\n- **Top 10 most optimized operations** with before/after comparison\n\n**Example Output:**\n```json\n{\n  \"sessionId\": \"abc-123\",\n  \"totalTokensSaved\": 125430,  // ← THIS is your savings!\n  \"tokenReductionPercent\": 68.2,\n  \"originalTokens\": 184000,\n  \"optimizedTokens\": 58570,\n  \"cacheHitRate\": 72.0,\n  \"byTool\": {\n    \"smart_read\": { \"saved\": 45000, \"percent\": 80 },\n    \"smart_grep\": { \"saved\": 32000, \"percent\": 75 }\n  }\n}\n```\n\n### Session Tracking Files\n\nAll operations are automatically tracked in session data files:\n\n**Location**: `~/.claude-global/hooks/data/current-session.txt`\n\n**Format**:\n\n```json\n{\n  \"sessionId\": \"abc-123\",\n  \"sessionStart\": \"20251031-082211\",\n  \"totalOperations\": 1250,      // ← Number of operations\n  \"totalTokens\": 184000,         // ← Cumulative token COUNT\n  \"lastOptimized\": 1698765432,\n  \"savings\": {                   // ← Auto-updated every 10 operations (Issue #113)\n    \"totalTokensSaved\": 125430,  // Tokens saved by compression\n    \"tokenReductionPercent\": 68.2,  // Percentage of tokens saved\n    \"originalTokens\": 184000,    // Original token count before optimization\n    \"optimizedTokens\": 58570,    // Token count after optimization\n    \"cacheHitRate\": 42.5,        // Cache hit rate percentage\n    \"compressionRatio\": 0.32,    // Compression efficiency (lower is better)\n    \"lastUpdated\": \"20251031-092500\"  // Last savings update timestamp\n  }\n}\n```\n\n**New in v1.x**: The `savings` object is now automatically updated every 10 operations, eliminating the need to manually call `get_session_stats()` for real-time monitoring. This provides instant visibility into token optimization performance.\n\n**How it works**:\n- Every 10 operations, the PowerShell hooks automatically call `get_cache_stats()` MCP tool\n- Savings metrics are calculated from cache performance data (compression ratio, original vs compressed sizes)\n- The session file is atomically updated with the latest savings data\n- If the MCP call fails, the update is skipped gracefully without blocking operations\n\n**Note**: For detailed per-operation analysis, use `get_session_stats()`. The session file provides high-level aggregate metrics.\n\n### Project-Wide Analysis\n\nAnalyze token usage across your entire project:\n\n```typescript\n// Analyze project token costs\nawait analyze_project_tokens({\n  projectPath: \"/path/to/project\"\n});\n```\n\n**Provides:**\n- Total token cost estimation\n- Largest files by token count\n- Optimization opportunities\n- Cost projections at current API rates\n\n### Cache Performance\n\nMonitor cache hit rates and storage efficiency:\n\n```typescript\n// View cache statistics\nawait get_cache_stats({});\n```\n\n**Metrics:**\n- Total entries\n- Cache hit rate (%)\n- Average compression ratio\n- Total storage saved\n- Most frequently accessed keys\n\n## Troubleshooting\n\n### Common Issues and Solutions\n\n#### Issue: \"Invalid or malformed JSON\" in Claude Code Settings\n\n**Symptom**: Claude Code shows \"Invalid Settings\" error after running install-hooks\n\n**Cause**: UTF-8 BOM (Byte Order Mark) was added to settings.json files\n\n**Solution**: Upgrade to v3.0.2+ which fixes the BOM issue:\n```bash\nnpm install -g @ooples/token-optimizer-mcp@latest\n```\n\nIf you're already on v3.0.2+, manually remove the BOM:\n```powershell\n# Windows: Remove BOM from settings.json\n$content = Get-Content \"~/.claude/settings.json\" -Raw\n$content = $content -replace '^\\xEF\\xBB\\xBF', ''\n$content | Set-Content \"~/.claude/settings.json\" -Encoding utf8NoBOM\n```\n\n```bash\n# Linux: Remove BOM from settings.json\nsed -i '1s/^\\xEF\\xBB\\xBF//' ~/.claude/settings.json\n\n# macOS: Remove BOM from settings.json (BSD sed requires empty string after -i)\nsed -i '' '1s/^\\xef\\xbb\\xbf//' ~/.claude/settings.json\n```\n\n#### Issue: Hooks Not Working After Installation\n\n**Symptom**: Token optimization not occurring automatically\n\n**Diagnosis**:\n1. Check if hooks are installed:\n   ```powershell\n   # Windows\n   Get-Content ~/.claude/settings.json | ConvertFrom-Json | Select-Object -ExpandProperty hooks\n   ```\n   ```bash\n   # macOS/Linux\n   cat ~/.claude/settings.json | jq .hooks\n   ```\n\n2. Verify dispatcher.ps1 exists:\n   ```powershell\n   # Windows\n   Test-Path ~/.claude-global/hooks/dispatcher.ps1\n   ```\n   ```bash\n   # macOS/Linux\n   [ -f ~/.claude-global/hooks/dispatcher.sh ] && echo \"Exists\" || echo \"Missing\"\n   ```\n\n**Solution**: Re-run the installer:\n```powershell\n# Windows\npowershell -ExecutionPolicy Bypass -File install-hooks.ps1\n```\n```bash\n# macOS/Linux\nbash install-hooks.sh\n```\n\n#### Issue: Low Cache Hit Rate (<50%)\n\n**Symptom**: Session stats show cache hit rate below 50%\n\n**Causes**:\n1. Working with many new files (expected)\n2. Cache was recently cleared\n3. TTL (time-to-live) is too short\n\n**Solutions**:\n1. **Warm up the cache** before starting work:\n   ```typescript\n   await cache_warmup({\n     paths: [\"/path/to/frequently/used/files\"],\n     recursive: true\n   });\n   ```\n\n2. **Increase TTL** for stable APIs:\n   ```typescript\n   await smart_api_fetch({\n     url: \"https://api.example.com/data\",\n     ttl: 3600  // 1 hour instead of default 5 minutes\n   });\n   ```\n\n3. **Check cache size limits**:\n   ```typescript\n   await smart_cache({\n     operation: \"configure\",\n     l1MaxSize: 2000,  // Increase from default 1000\n     l2MaxSize: 20000  // Increase from default 10000\n   });\n   ```\n\n#### Issue: High Memory Usage\n\n**Symptom**: Node.js process using excessive memory\n\n**Cause**: Large cache in memory (L1/L2 tiers)\n\n**Solution**: Configure cache limits:\n```typescript\nawait smart_cache({\n  operation: \"configure\",\n  evictionStrategy: \"LRU\",  // Least Recently Used\n  l1MaxSize: 500,  // Reduce L1 cache\n  l2MaxSize: 5000  // Reduce L2 cache\n});\n```\n\nOr clear the cache:\n```typescript\nawait clear_cache({});\n```\n\n#### Issue: Slow First-Time Operations\n\n**Symptom**: Initial Read/Grep/Glob operations are slow\n\n**Cause**: Cache is empty, building indexes\n\n**Solution**: This is expected behavior. Subsequent operations will be 80-90% faster.\n\nTo pre-warm the cache:\n```typescript\nawait cache_warmup({\n  paths: [\"/src\", \"/tests\", \"/docs\"],\n  recursive: true,\n  schedule: \"startup\"  // Auto-warm on every session start\n});\n```\n\n#### Issue: \"Permission denied\" Errors on Windows\n\n**Symptom**: Cannot write to cache or log files\n\n**Cause**: PowerShell execution policy or file permissions\n\n**Solution**:\n1. **Set execution policy**:\n   ```powershell\n   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser\n   ```\n\n2. **Check file permissions**:\n   ```powershell\n   icacls \"$env:USERPROFILE\\.token-optimizer\"\n   ```\n\n3. **Re-run installer as Administrator** if needed\n\n#### Issue: Cache Files Growing Too Large\n\n**Symptom**: `~/.token-optimizer/cache.db` is >1GB\n\n**Cause**: Caching very large files or many API responses\n\n**Solution**:\n1. **Clear old entries**:\n   ```typescript\n   await clear_cache({ olderThan: 7 });  // Clear entries older than 7 days\n   ```\n\n2. **Reduce cache retention**:\n   ```typescript\n   await smart_cache({\n     operation: \"configure\",\n     defaultTTL: 3600  // 1 hour instead of 7 days\n   });\n   ```\n\n3. **Manually delete cache** (nuclear option):\n   ```bash\n   rm -rf ~/.token-optimizer/cache.db\n   ```\n\n### Getting Help\n\nIf you encounter issues not covered here:\n\n1. **Check the hook logs**: `~/.claude-global/hooks/logs/dispatcher.log`\n2. **Check session data**: `~/.claude-global/hooks/data/current-session.txt`\n3. **File an issue**: [GitHub Issues](https://github.com/ooples/token-optimizer-mcp/issues)\n   - Include debug logs\n   - Include your OS and Node.js version\n   - Include the output of `get_session_stats`\n\n## Limitations\n\n- **Small Text**: Best for content >500 characters (cache overhead on small snippets)\n- **One-Time Content**: No benefit for content that won't be referenced again\n- **Cache Storage**: Automatic cleanup after 7 days to prevent disk usage issues\n- **Token Counting**: Uses GPT-4 tokenizer (approximation for Claude, but close enough)\n\n## License\n\nMIT License - see [LICENSE](./LICENSE) for details\n\n## Author\n\nBuilt for optimal Claude Code token efficiency by the ooples team.\n","readmeFilename":"README.md","_rev":"1-16331bfce64c740a926f434ed8002c52"}