token-saver CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Version Source of Truth

Always check the latest version from GitHub before referencing any version number.

gh release list --limit 1

Never trust package.json, marketplace.json, plugin.json, or any hardcoded version string in the repo — always fetch the current release from GitHub and use that as the authoritative version.

Project Overview

This is a Claude Code MCP plugin that monitors Claude API outputs and fires warnings/errors/alerts when token usage is wasteful. It analyzes outputs for noise patterns, estimates token counts, suppresses logs and repetitive history, and reports cumulative waste statistics.

Core value proposition: In agentic coding sessions, large log outputs, verbose tool results, and repetitive history entries are re-sent on every turn, burning tokens on content nobody reads. This plugin catches these early, fires alerts at configurable thresholds, and auto-suppresses noise to keep context lean.

Engineering Mindset

All code in this repo follows BEST_PRACTICES.md. Read it before writing any code. Key rules that affect every file:

• stdout is the MCP wire — never console.log() in tool handlers, use stderr
• Every tool handler must catch all errors and return { isError: true, ... } — never throw
• Every tool must define outputSchema — no schema, no merge
• The irony rule: a token-saver plugin that floods context has failed at its core mission — tool responses must be small and structured

Cross-Platform Requirements

This plugin runs on Linux, macOS, and Windows. Every code path and every test must pass on all three. CI runs a 9-job matrix (3 OS × 3 Node versions).

Rules — always follow these

Topic	Wrong	Correct
Path construction	dir + '/' + file	path.join(dir, file)
Home directory	~ or process.env.HOME	os.homedir()
Temp directory	'/tmp'	os.tmpdir()
Config path	hardcoded string	path.join(os.homedir(), '.claude', 'settings.json')
Line endings	\r\n	\n (.gitattributes enforces LF on all platforms)
Process signals	SIGTERM only	SIGINT + SIGTERM (SIGTERM is not available on Windows)
File permissions	fs.chmod(...) alone	guard with if (process.platform !== 'win32')
Shell commands	sh -c ...	avoid; use Node fs/child_process with shell: true only when necessary