\n\n# ClaudeTokenSAP\n\n### A Claude Code marketplace for leaner context, sharper build starts, and smarter long-running sessions\n\n
\n \n \n \n \n \n
\n\n
\n \n \n \n \n
\n\n
\n \n \n
\n\n
\n\n---\n\n> **ClaudeTokenSAP** is a Claude Code plugin marketplace.\n>\n> Its first plugin, **Token Optimizer**, improves how Claude Code handles vague build prompts, oversized file reads, and long sessions.\n>\n> It is built to reduce context waste **without** making Claude feel dumber, more generic, or overly interruptive.\n\nThe core idea is simple:\n\n- ask better questions before coding when the request is vague\n- stop huge noisy reads before they flood context\n- summarize useful file reads in a compact way\n- preserve lightweight session memory around compaction\n- log what happened so the workflow can be tuned over time\n\n---\n\n## Why teams use it\n\n### Context efficiency comparison\n\n| Workflow | What usually happens | Token impact |\n|---|---|---|\n| Vague build prompt | Claude starts coding too early, then backtracks | High waste |\n| Token Optimizer enabled | Claude asks focused clarifying questions first | Lower waste |\n| Large noisy log read | Raw bulk floods context | Very high waste |\n| Token Optimizer enabled | Full read is blocked and narrowed | 50–80% lower in repetitive cases |\n| Large JSON read | Full structure gets dumped into session | High waste |\n| Token Optimizer enabled | Shape, keys, counts, and summaries are used first | 40–75% lower in good-fit cases |\n| Long coding session | Context drifts after compaction | Hidden waste |\n| Token Optimizer enabled | Lightweight continuity is preserved | Better session quality |\n\n### Approximate token-saving ranges\n\n| Input type | Typical optimization | Approximate reduction |\n|---|---|---|\n| Repetitive logs | Collapse noise, surface real failures | 60–85% |\n| Large JSON | Shape/key summary instead of full bulk | 40–75% |\n| Repeated file reads | Prevent duplicate noisy context | 20–50% |\n| Vague build starts | Clarify before scaffolding | Often large downstream savings |\n| Search-heavy sessions | Compress broad match output | 60–80% |\n\n> In highly repetitive cases, reductions can exceed **70%**, but savings vary by workflow, file type, prompt quality, and session behavior.\n\n---\n\n## Why this exists\n\nClaude Code is strongest when context contains **signal**, not bulk.\n\nIn real development workflows, context gets wasted by things like:\n\n- prompts such as `create a calculator`\n- large logs where only a few lines matter\n- big JSON files where only the shape or a few keys matter\n- repeated file reads that dump raw bulk into the session\n- long conversations that lose thread after compaction\n\nThat creates three practical problems:\n\n1. **Higher token usage**\n2. **Lower reasoning quality**\n3. **More time wasted clarifying build direction after code has already started**\n\n**Token Optimizer** is designed to intervene at exactly those points.\n\n---\n\n## What’s new in v2.3.7\n\nVersion `2.3.7` makes onboarding questions fully dynamic. The hook now calls Claude Haiku to generate 3–7 custom questions tailored to the exact prompt — skipping what’s already obvious. \"Create a React dashboard with PostgreSQL\" won’t ask about framework or database. Falls back to the 11 static intent sets (v2.3.6) when the API is unavailable.\n\n## What’s new in v2.3.6\n\nVersion `2.3.6` makes onboarding questions context-aware. The hook now classifies the user’s intent (trading strategy, ML model, CLI tool, bot, game, library, etc.) and asks domain-specific questions. \"Create a trading strategy\" now asks about market, timeframe, language, data source, and output format — not \"What type of app are you building?\".\n\n## What’s new in v2.3.5\n\nVersion `2.3.5` fixes onboarding re-triggering on every new session. The hook now writes `.claude/CLAUDE.md`, `.claude/settings.json`, and `.claudeignore` itself at completion — no longer relying on Claude to do it. This makes the \"already onboarded\" guard reliable.\n\n## What’s new in v2.3.4\n\nVersion `2.3.4` registers the secret detector hook so it actively scans every user prompt for API keys, tokens, and `.env` assignments before they reach Claude.\n\n## What’s new in v2.3.3\n\nVersion `2.3.3` fixes the flow issues where Claude goes silent after onboarding, loops indefinitely instead of announcing completion, and requires Ctrl+O to see responses.\n\n### Flow control fixes\n- **Visible output mandate**: All hooks now inject \"ALWAYS produce visible text output\" - Claude never goes silent.\n- **Completion signal**: Verification guard, response rules, and onboarding all instruct Claude to say \"Done. [summary]. Ready to test.\" then STOP.\n- **Non-blocking follow-ups**: Follow-up gap detection (prompts 2-4) no longer blocks the user’s request. Changed from \"ask before executing\" to \"fill in when convenient.\"\n- **Reduced directive noise**: CLAUDE.md reminders changed from every 3 prompts to every 5. Compact reminder deferred to after current task. Session banner has explicit FLOW CONTROL section.\n\n### Previous (v2.3.0) additions\n- **Verification Before Completion** - Stop hook enforces evidence-based verification.\n- **Systematic Debugging (4-phase)** - Error loop guard injects root cause → pattern → hypothesis → fix protocol.\n- **Model Selection, Parallel Dispatch, TDD** - Session banner rules for cost optimization and quality.\n- **Deferred onboarding file creation** - No leftover files on API failure.\n\n### Previous (v2.2.x) improvements\n\n### Token budget tracking\nEstimates token consumption across all operations (reads, prompts, bash, search). Progressive warnings at 60% and 80% capacity. Strategic compaction triggers at 70% budget instead of naive prompt counting.\n\n### Error loop detection\nPostToolUse hook on Bash monitors repeated error patterns. Normalizes errors by stripping timestamps, paths, and numbers, then intervenes after 3 identical failures with actionable guidance to break the loop.\n\n### Search result compression\nGrep results with 40+ matches are grouped by file with match counts. Glob results are grouped by directory. This reduces search output by 60–80% while preserving the most relevant matches.\n\n### Duplicate read prevention\nTracks every file read per session. Warns when a file has been read 3+ times. Integrates with the read guard to reduce redundant context consumption.\n\n### Binary file blocking\nInstantly blocks reads on binary files (`.png`, `.jpg`, `.exe`, `.zip`, `.mp4`, `.pdf`, `.woff2`, etc.). They waste tokens and are not useful as text.\n\n### Structured post-compact briefing\nAfter compaction, injects a structured resume briefing with token budget status, efficiency metrics from all subsystems, architecture change summary, and file modification categories.\n\n### Previous (v2.1.0) improvements\n\n- Smart prompt analysis with auto-detected defaults and contextual onboarding hints\n- Write/edit tracking categorizes every file modification\n- Follow-up gap detection on prompts 2–4\n- Enriched compaction memory with architecture signals\n\n### Previous (v2.0.2) improvements\n\n#### Clarification gate for vague build prompts\nIf a user prompt is underspecified, the plugin pushes Claude to ask focused follow-up questions **before** writing code.\n\nThe questions are:\n\n- compact\n- OpenCode-style\n- limited to missing details only\n- capped at 4 questions\n- always include **Custom** as the last option\n\n#### Read guard for large noisy files\nLarge full-file reads for noisy files such as `.log`, `.json`, `.csv`, `.txt`, `.jsonl`, `.ndjson`, `.lock`, and `.map` are blocked when they would likely waste context.\n\nInstead of dumping the whole file, Claude is guided toward narrower strategies such as:\n\n- reading only relevant lines\n- inspecting structure first\n- focusing on errors, keys, columns, or repeated patterns\n\n#### Post-read summaries\nAfter a useful `Read`, the plugin adds compact summaries for:\n\n- logs\n- JSON\n- CSV / TSV\n- generic text files\n\n#### PreCompact and PostCompact hooks\nThe plugin now keeps a lightweight memory layer around Claude Code compaction.\n\nThis helps long sessions preserve useful recent state such as:\n\n- recent events\n- recent file-read summaries\n- high-signal debug activity\n\n#### Repo summary at session start\nAt session start, Claude gets a short repo-level file-type summary so it gets project shape without scanning the whole workspace.\n\n#### Debug logging and telemetry foundation\nHook activity is written to a local temp log so you can validate behavior and measure the impact of optimizations over time.\n\n---\n\n## What Token Optimizer actually does\n\nToken Optimizer is not a general IDE plugin.\n\nIt is a **context optimizer and build-start gatekeeper** for Claude Code.\n\nThat means it focuses on five things:\n\n### 1. Clarify before building\nWhen the user asks Claude to build something but leaves out important details, the plugin can stop the build from starting too early.\n\nFor example, if the prompt is:\n\n```text\ncreate a calculator\n```\n\nClaude is guided to ask for missing details such as:\n\n- platform\n- scope\n- UI direction\n- must-have features\n\nIf the prompt is already specific enough, Claude proceeds normally.\n\n### 2. Prevent wasteful full-file reads\nIf Claude attempts a full read on a large noisy file, the plugin blocks it and provides a better strategy.\n\nInstead of flooding context, Claude is nudged to:\n\n- inspect structure first\n- read only relevant sections\n- summarize repeated or low-signal content\n\n### 3. Add compact summaries after useful reads\nWhen a file read is still worth doing, the plugin adds a summary layer so Claude reasons over a smaller, clearer representation.\n\nExamples:\n\n- **logs** → counts, repeated lines, high-signal lines\n- **JSON** → root type, top-level keys, object/array shape\n- **CSV / TSV** → column names and approximate row count\n- **text** → approximate size and line count\n\n### 4. Preserve memory around compaction\nLong coding sessions can drift when Claude compacts context.\n\nThe plugin adds lightweight pre/post compaction notes so important recent signals are less likely to disappear.\n\n### 5. Provide a fast repo snapshot on new sessions\nOn session start, Claude gets a quick top-level repository summary based on file extensions. This helps it orient faster in a new repo.\n\n---\n\n## Hook lifecycle\n\nThe current plugin uses **6 active hooks**.\n\n| Hook | Purpose |\n|---|---|\n| `SessionStart` | Adds policy guidance, debug log location, and a lightweight repo file summary |\n| `UserPromptSubmit` | Logs prompt shape and runs the Sonnet-based clarification gate for vague build prompts |\n| `PreToolUse (Read)` | Blocks oversized noisy full-file reads and suggests narrower read strategies |\n| `PostToolUse (Read)` | Adds compact summaries for logs, JSON, CSV/TSV, and text |\n| `PreCompact` | Captures recent high-signal session activity before compaction |\n| `PostCompact` | Adds a small summary after compaction for continuity |\n\n---\n\n## Why this is useful in practice\n\nMost developers do not lose context because they lack model intelligence.\n\nThey lose it because the session is full of things like:\n\n- repeated logs\n- overscoped file reads\n- underspecified feature requests\n- re-explaining the repo shape every time\n\nWithout optimization, Claude spends more context **reading raw bulk**.\n\nWith optimization, Claude spends more context **thinking about the problem**.\n\nThat is the practical difference.\n\n---\n\n## Example flows\n\n### Example 1: vague build request\n\n#### Input\n\n```text\ncreate a calculator\n```\n\n#### Result\n\nInstead of jumping into code immediately, Claude is encouraged to ask compact clarification questions such as:\n\n1. What platform should this target?\n - Web\n - Android\n - iOS\n - Desktop\n - OpenCode\n - Custom\n\n2. What kind of calculator is it?\n - Basic\n - Scientific\n - With history\n - With keyboard support\n - Custom\n\nThis prevents low-quality default scaffolding when the request is clearly underspecified.\n\n---\n\n### Example 2: large noisy log file\n\n#### Input\n\nClaude attempts to fully read a very large `.log` file.\n\n#### Result\n\nThe plugin intelligently blocks full noisy reads and returns focused guidance instead.\n\n## Example\n\n**Command:** `create a calculator`\n\n
\n \n
\n\nInstead of reading the entire log or pasted output, it recommends a narrower strategy:\n\n1. Search for `ERROR`, `WARN`, `FATAL`, `exception`, `timeout`, or stack traces first.\n2. Read only the surrounding lines that contain the actual failure.\n3. Collapse repetitive INFO/debug noise into counts or recurring patterns.\n\nThis preserves the real signal and prevents unnecessary context waste.\n\n**Token usage:** only **~1.5K tokens** instead of consuming large context windows with noisy logs.\n\n---\n\n### Example 3: compact JSON summary after read\n\n#### Input\n\nClaude reads a JSON file that is useful but still large enough to be noisy.\n\n#### Result\n\nThe plugin adds a compact summary such as:\n\n```text\nToken Optimizer summary for config.json:\n- root type: object\n- top-level keys: settings, services, routes\n- services: array (12 items)\n- routes: object with keys auth, admin, public\n- Prefer targeted key/section reads for exact values instead of re-reading the full JSON.\n```\n\n---\n\n### Example 4: compaction continuity\n\nWhen Claude Code compacts a long session, Token Optimizer can add summaries such as:\n\n```text\nToken Optimizer pre-compact summary:\nRecent events:\n- file_read_compress\n- read_guard_check\n- prompt_preprocess\n```\n\nand then:\n\n```text\nToken Optimizer post-compact summary:\nTotal events logged this session: 27\n```\n\nThis helps the session keep recent high-signal memory without dragging forward raw bulk.\n\n---\n\n## Token savings: what to claim honestly\n\nToken Optimizer is built to reduce waste, but savings depend heavily on the input type.\n\nThe safest way to describe it is:\n\n> It can reduce token usage substantially on noisy logs, oversized JSON, repeated file reads, and vague build starts. In highly repetitive cases, reductions can exceed 70%, but savings vary by workflow and input quality.\n\nThat wording is strong **and** defensible.\n\nDo **not** promise a flat 70% reduction for every session.\n\n---\n\n## Installation\n\n### 1. Add the marketplace\n\n```bash\nclaude plugin marketplace add https://github.com/satyamamarpandey/ClaudeTokenSAP.git\n```\n\n### 2. Install the plugin\n\n```bash\nclaude plugin install token-optimizer@claudetokensap-marketplace\n```\n\n### Need even more optimization?\n\nFor deeper session optimization, advanced context shaping, and stronger plugin configuration patterns, see:\n\n**https://github.com/satyamamarpandey/OptiClaude**\n\n### 3. Restart Claude Code\n\nRestart Claude Code once so the hooks load cleanly for the next session.\n\n---\n\n## Quick start\n\nAfter installation, you do not need a new workflow.\n\nJust use Claude Code normally.\n\nTypical examples:\n\n- ask Claude to build something\n- inspect logs\n- read large JSON files\n- work through long development sessions\n\nThe plugin runs in the background and adjusts the context flow automatically.\n\n---\n\n## Requirements\n\n| Requirement | Status |\n|---|---|\n| Claude Code | Required |\n| Node.js 18+ | Required |\n| Manual setup after install | Not required |\n\n---\n\n## Supported platforms\n\n| Platform | Status |\n|---|---|\n| Windows | Supported |\n| macOS | Supported |\n| Linux | Supported |\n\nThe plugin uses cross-platform Node-based hook scripts and simple filesystem logic, so it is designed to work across all three major operating systems.\n\n---\n\n## Repository structure\n\n```text\nClaudeTokenSAP/\n├── .claude-plugin/\n│ └── marketplace.json\n├── plugins/\n│ └── ClaudeTokenSAP/\n│ ├── .claude-plugin/\n│ │ └── plugin.json\n│ ├── hooks/\n│ │ ├── hooks.json\n│ │ ├── instructions_loaded.js\n│ │ ├── prompt_preprocess.js\n│ │ ├── read_guard.js\n│ │ ├── file_read_compress.js\n│ │ ├── precompact.js\n│ │ └── postcompact.js\n│ └── lib/\n│ └── debug-log.js\n├── README.md\n├── CHANGELOG.md\n├── CONTRIBUTING.md\n├── LICENSE\n└── SECURITY.md\n```\n\n### Structure overview\n\n| Path | Purpose |\n|---|---|\n| `.claude-plugin/marketplace.json` | Marketplace index |\n| `plugins/ClaudeTokenSAP/.claude-plugin/plugin.json` | Plugin identity, version, and metadata |\n| `plugins/ClaudeTokenSAP/hooks/hooks.json` | Hook registration |\n| `plugins/ClaudeTokenSAP/hooks/` | Runtime hook entry points |\n| `plugins/ClaudeTokenSAP/lib/debug-log.js` | Shared debug logging utility |\n\n---\n\n## Design principles\n\n### Preserve signal, not bulk\nThe plugin should reduce noise without flattening important meaning.\n\n### Ask before building when the prompt is vague\nBad defaults cost more than a quick focused clarification round.\n\n### Block waste early\nThe cheapest token is the one that never enters context.\n\n### Stay lightweight\nThe plugin should not spend large amounts of model budget trying to save budget.\n\n### Stay useful during long sessions\nCompaction should not reset the session’s working memory every time.\n\n### Remain cross-platform\nThe same marketplace and hook flow should work across Windows, macOS, and Linux.\n\n---\n\n## Typical use cases\n\n### Build requests\n- stop vague prompts from turning into low-quality scaffolds\n- ask the missing questions first\n- reduce backtracking later\n\n### Debugging sessions\n- avoid flooding context with huge logs\n- surface real errors faster\n- collapse repeated noise\n\n### Data-heavy workflows\n- summarize large JSON and CSV reads\n- preserve shape and high-signal structure\n- encourage targeted follow-up reads\n\n### Long-running sessions\n- keep lightweight continuity around compaction\n- retain a better sense of recent actions and session state\n\n### New repos and unfamiliar codebases\n- give Claude a quick repo-level file-type overview at session start\n- reduce the time spent re-orienting in each new session\n\n---\n\n## Troubleshooting\n\n\nThe plugin is installed but does not seem active\n\nCheck the following:\n\n- Claude Code was restarted after install or update\n- the plugin name used during install is correct\n- the plugin appears as enabled in `/plugin`\n- the marketplace was refreshed after version changes\n\n\n\n\nThe old plugin name still shows an error\n\nIf you previously installed an older plugin entry such as `ClaudeTokenSAP@claudetokensap-marketplace`, uninstall that stale entry and keep only:\n\n```text\ntoken-optimizer@claudetokensap-marketplace\n```\n\n\n\n\nLarge reads are being blocked too often\n\nThat usually means Claude is attempting full-file reads where targeted reads would be better.\n\nThe current behavior is intentional. The plugin is biased toward narrower reads on noisy large files.\n\n\n\n\nI want to verify the hooks are firing\n\nCheck the temp debug log created by `debug-log.js`.\n\nThat log records hook activity and is the easiest way to confirm:\n\n- session start\n- prompt preprocessing\n- read guard checks\n- read summaries\n- compaction hooks\n\n\n\n---\n\n## Development notes\n\nThe current plugin is intentionally narrow.\n\nIt is not trying to be:\n\n- an IDE replacement\n- a linter\n- a full repo automation framework\n- a code generator by itself\n\nIt is specifically built to improve **Claude Code session quality** by controlling how context enters and survives the session.\n\n### Strong next extension ideas\n\n- search-first policy before large reads\n- file hash tracking for smarter summaries\n- repo map cache beyond top-level file extensions\n- per-file-type telemetry and reduction reporting\n- subagent budget control\n- framework-aware repo instructions\n\n---\n\n## FAQ\n\n### Does it rewrite my real files?\nNo. It changes how content is handled in Claude Code hooks. It does not rewrite workspace files just to save tokens.\n\n### Does it always ask clarification questions?\nNo. It asks only when the request is still underspecified enough that starting to code would likely be wasteful.\n\n### Does it work for new Claude Code sessions automatically?\nYes. Once installed and enabled, the hooks run automatically in new sessions.\n\n### Can it help with large files?\nYes. That is one of its main jobs. It is especially useful for noisy logs, large JSON, CSV-like data, and other bulky text files where full reads are wasteful.\n\n### Can it save 70% of token usage?\nSometimes, yes, especially on highly repetitive or noisy inputs. But that should be treated as a best-case scenario, not a guaranteed universal number.\n\n---\n\n## License\n\nThis project is licensed under the **MIT License**.\n\n---\n\n## Author\n\nBuilt and maintained by **[Satyam Pandey](https://github.com/satyamamarpandey)**.\n\n---\n\n
\n\n### ClaudeTokenSAP\n\n**Less waste. Better signal. Smarter Claude Code sessions.**\n\n
![\"Install](\"https://img.shields.io/badge/install-2%20commands-111827?style=for-the-badge\"){kind=icon}
![\"Context](\"https://img.shields.io/badge/token%20focus-context%20efficiency-16a34a?style=for-the-badge\"){kind=icon}
![\"Version](\"https://img.shields.io/badge/version-v2.3.7-2563eb?style=for-the-badge\"){kind=icon}
![\"Windows](\"https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-0f766e?style=for-the-badge\"){kind=icon}
![\"Node](\"https://img.shields.io/badge/node-%E2%89%A5%2018-7c3aed?style=for-the-badge\"){kind=icon}
![\"Claude](\"https://img.shields.io/badge/Marketplace-Claude%20Code-111827?style=flat-square\"){kind=icon}
![\"token-optimizer\"](\"https://img.shields.io/badge/Plugin-token--optimizer-16a34a?style=flat-square\"){kind=icon}
![\"6](\"https://img.shields.io/badge/Hooks-6%20active-f59e0b?style=flat-square\"){kind=icon}
![\"Cross](\"https://img.shields.io/badge/Design-cross--platform-2563eb?style=flat-square\"){kind=icon}
![\"License\"](\"https://img.shields.io/badge/license-MIT-green\"){kind=icon}
![\"Stars\"](\"https://img.shields.io/github/stars/satyamamarpandey/ClaudeTokenSAP\")