claude-context-lint 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 claude-context-lint contributors
+
+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,135 @@
+# claude-context-lint
+
+> Audit your Claude Code setup and find exactly where tokens are being wasted.
+
+[![Built by Claude Code](https://img.shields.io/badge/Built%20by-Claude%20Code-blueviolet)](https://claude.ai/code)
+[![npm version](https://img.shields.io/npm/v/claude-context-lint)](https://www.npmjs.com/package/claude-context-lint)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Every Claude Code conversation starts with overhead: your CLAUDE.md files, skill descriptions, MCP tool schemas, and the base system prompt all consume context tokens **before you type a single word**. This tool makes that invisible cost visible.
+
+## Quick Start
+
+```bash
+npx claude-context-lint
+```
+
+Or install globally:
+
+```bash
+npm install -g claude-context-lint
+claude-context-lint
+```
+
+## Example Output
+
+```
+  Claude Code Context Audit
+  ────────────────────────────────────────────────────
+  CLAUDE.md                1,240 tokens     █░░░░░░░░░░░░░░░░░░░
+    CLAUDE.md                          1,240 tokens
+
+  Skills (32 loaded)       4,800 tokens     ████░░░░░░░░░░░░░░░░  MEDIUM
+    Listing overhead (per-turn):    4,800 tokens
+    Full content (on invocation):   89,200 tokens
+    ⚠ 3 near-duplicate skills detected (−420 tokens)
+    api-helper                   120 listing      3,200 full
+    db-migrate                   105 listing      2,800 full
+    test-runner                   98 listing      1,950 full
+    ... and 29 more
+
+  MCP Servers (3)          14,100 tokens    █████████░░░░░░░░░░░  CRITICAL
+    postgres               6,600 tokens   (22 tools) [always loaded]
+    filesystem             1,800 tokens   (6 tools)  [always loaded]
+    memory                 1,200 tokens   (4 tools)  [always loaded]
+
+  System Prompt            8,500 tokens     █████░░░░░░░░░░░░░░░ (base overhead)
+  ────────────────────────────────────────────────────
+  TOTAL OVERHEAD:        28,640 tokens
+  Context Limit:         200,000 tokens
+  Used Before Input:     14.3% ████░░░░░░░░░░░░░░░░░░░░░░░░░░
+
+  TOP RECOMMENDATIONS
+  ────────────────────────────────────────────────────
+  1. Enable ToolSearch for "postgres" MCP (22 tools)
+     −6,270 tokens
+  2. Shorten 12 verbose skill descriptions
+     −1,840 tokens
+  3. Consolidate 3 near-duplicate skills
+     −420 tokens
+
+  Potential savings: 8,530 tokens (29.8% reduction)
+```
+
+## What It Scans
+
+| Category | What it finds | How it counts |
+|----------|---------------|---------------|
+| **CLAUDE.md** | Project + parent dirs + `~/.claude/CLAUDE.md` | Exact token estimate of each file |
+| **Skills** | All `.claude/skills/**/SKILL.md` files | **Listing tokens** (per-turn cost of name+description) and **full tokens** (on-invocation cost) |
+| **MCP Servers** | `.mcp.json` + `settings.json` configs | Tool count × estimated tokens per schema |
+| **System Prompt** | Claude Code's base instructions | Fixed estimate (~8,500 tokens) |
+
+### Skill Token Accounting
+
+Claude Code doesn't inject full skill content every turn. It injects a **listing** (skill name + description one-liner) into the system prompt, and only loads the **full SKILL.md** when invoked. This tool reports both:
+
+- **Listing tokens**: Your per-turn cost (what matters for context efficiency)
+- **Full tokens**: What loads when a skill is triggered (matters for complex conversations)
+
+### Duplicate Detection
+
+Skills with >75% word overlap in their descriptions are flagged as near-duplicates. Uses Jaccard similarity on word sets, filtering stop words under 3 characters.
+
+### MCP Tool Estimation
+
+MCP tool schemas average ~300 tokens each. Tools deferred via ToolSearch cost only ~15 tokens (just the name). The tool checks your `settings.json` permissions to detect which tools are deferred vs always-loaded, and estimates overhead accordingly.
+
+## Options
+
+```
+Usage: claude-context-lint [options]
+
+Options:
+  -p, --path <path>     Project path to audit (default: current directory)
+  -c, --context <size>  Context window size: opus, sonnet, haiku, opus-1m,
+                        or a number (default: "opus" = 200K)
+  --json                Output as JSON (structured data on stdout)
+  -V, --version         Output version number
+  -h, --help            Display help
+```
+
+### Examples
+
+```bash
+# Audit current directory
+claude-context-lint
+
+# Audit a specific project
+claude-context-lint --path ~/my-project
+
+# Check overhead against 1M context window
+claude-context-lint --context opus-1m
+
+# Get machine-readable output for scripting
+claude-context-lint --json | jq '.percentUsed'
+```
+
+## Why This Matters
+
+Research shows that heavy Claude Code users can burn **15-30% of their context window** on setup overhead before any conversation begins. Common culprits:
+
+- **MCP servers with all tools always-loaded** instead of deferred via ToolSearch
+- **Verbose skill descriptions** that repeat information
+- **Near-duplicate skills** with overlapping trigger patterns
+- **Large CLAUDE.md files** that could be compressed
+
+This overhead is invisible — Claude Code's `/context` command doesn't break it down. This tool does.
+
+## Attribution
+
+This project was entirely designed, written, and published by [Claude Code](https://claude.ai/code).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { scanClaudeMd } from './scanners/claude-md.js';
+import { scanSkills } from './scanners/skills.js';
+import { scanMcp } from './scanners/mcp.js';
+import { generateRecommendations } from './recommendations.js';
+import { printReport } from './reporter.js';
+const CONTEXT_LIMITS = {
+    'opus': 200_000,
+    'sonnet': 200_000,
+    'haiku': 200_000,
+    'opus-1m': 1_000_000,
+};
+function estimateSystemPrompt() {
+    // Claude Code injects: system prompt + built-in tool schemas + env/git info
+    // Built-in tools: Bash, Read, Write, Edit, Glob, Grep, Agent, Skill, ToolSearch,
+    // TaskCreate, TaskUpdate, WebFetch, WebSearch, NotebookEdit, etc. (~15 tools)
+    return {
+        estimatedTokens: 8500,
+        breakdown: [
+            { label: 'Core instructions', tokens: 2800 },
+            { label: 'Built-in tool schemas (~15)', tokens: 3200 },
+            { label: 'Git/commit/PR rules', tokens: 1200 },
+            { label: 'Tone, style, env info', tokens: 800 },
+            { label: 'Memory system instructions', tokens: 500 },
+        ],
+    };
+}
+function runAudit(projectPath, contextLimit) {
+    const claudeMd = scanClaudeMd(projectPath);
+    const skills = scanSkills(projectPath);
+    const mcp = scanMcp(projectPath);
+    const systemPrompt = estimateSystemPrompt();
+    const totalTokens = claudeMd.totalTokens + skills.totalTokens + mcp.totalTokens + systemPrompt.estimatedTokens;
+    return {
+        claudeMd,
+        skills,
+        mcp,
+        systemPrompt,
+        totalTokens,
+        contextLimit,
+        percentUsed: (totalTokens / contextLimit) * 100,
+    };
+}
+const program = new Command();
+program
+    .name('claude-context-lint')
+    .description('Audit your Claude Code setup and find where tokens are being wasted')
+    .version('0.1.0')
+    .option('-p, --path <path>', 'Project path to audit', process.cwd())
+    .option('-c, --context <size>', 'Context window size (opus, sonnet, haiku, opus-1m, or number)', 'opus')
+    .option('--json', 'Output as JSON')
+    .action((opts) => {
+    try {
+        const projectPath = opts.path;
+        let contextLimit;
+        if (opts.context in CONTEXT_LIMITS) {
+            contextLimit = CONTEXT_LIMITS[opts.context];
+        }
+        else {
+            const parsed = parseInt(opts.context, 10);
+            contextLimit = isNaN(parsed) ? 200_000 : parsed;
+        }
+        const result = runAudit(projectPath, contextLimit);
+        const recommendations = generateRecommendations(result);
+        if (opts.json) {
+            // JSON mode: only structured data on stdout
+            console.log(JSON.stringify({ ...result, recommendations }, null, 2));
+        }
+        else {
+            printReport(result, recommendations);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Error: ${msg}\n`);
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/recommendations.d.ts

@@ -0,0 +1,2 @@
+import type { AuditResult, Recommendation } from './types.js';
+export declare function generateRecommendations(result: AuditResult): Recommendation[];

package/dist/recommendations.js

@@ -0,0 +1,82 @@
+export function generateRecommendations(result) {
+    const recs = [];
+    let priority = 0;
+    // MCP: suggest enabling ToolSearch/deferred loading for large servers
+    for (const server of result.mcp.servers) {
+        if (!server.isDeferred && server.toolCount > 5) {
+            const savings = server.toolCount * (300 - 15);
+            recs.push({
+                priority: ++priority,
+                action: `Enable ToolSearch for "${server.name}" MCP (${server.toolCount} tools)`,
+                savings,
+                detail: `Add tool permissions to defer loading. Each tool schema is ~300 tokens; deferred tools cost ~15 tokens each.`,
+            });
+        }
+    }
+    // Skills: flag duplicates
+    if (result.skills.duplicates.length > 0) {
+        recs.push({
+            priority: ++priority,
+            action: `Consolidate ${result.skills.duplicates.length} near-duplicate skill${result.skills.duplicates.length > 1 ? 's' : ''}`,
+            savings: result.skills.duplicateTokenSavings,
+            detail: result.skills.duplicates
+                .sort((a, b) => b.similarity - a.similarity)
+                .slice(0, 5)
+                .map(d => `  "${d.skill1}" ↔ "${d.skill2}" (${(d.similarity * 100).toFixed(0)}% similar)`)
+                .join('\n'),
+        });
+    }
+    // Skills: flag large listing descriptions (>50 listing tokens = very long description)
+    const largeListings = result.skills.skills.filter(s => s.tokens > 50).sort((a, b) => b.tokens - a.tokens);
+    if (largeListings.length > 0) {
+        const top = largeListings.slice(0, 5);
+        const savings = largeListings.reduce((sum, s) => sum + Math.floor(s.tokens * 0.4), 0);
+        recs.push({
+            priority: ++priority,
+            action: `Shorten ${largeListings.length} verbose skill descriptions`,
+            savings,
+            detail: top
+                .map(s => `  ${s.name}: ${s.tokens} listing tokens (${s.fullTokens.toLocaleString()} full)`)
+                .join('\n'),
+        });
+    }
+    // Skills: flag very large full content (>3000 tokens on invocation)
+    const heavySkills = result.skills.skills.filter(s => s.fullTokens > 3000).sort((a, b) => b.fullTokens - a.fullTokens);
+    if (heavySkills.length > 0) {
+        recs.push({
+            priority: ++priority,
+            action: `${heavySkills.length} skills load >3,000 tokens when invoked`,
+            savings: 0,
+            detail: heavySkills
+                .slice(0, 5)
+                .map(s => `  ${s.name}: ${s.fullTokens.toLocaleString()} tokens on invocation`)
+                .join('\n') + '\n  Consider splitting or compressing these skills.',
+        });
+    }
+    // CLAUDE.md: flag large files
+    const largeMd = result.claudeMd.files.filter(f => f.tokens > 1000).sort((a, b) => b.tokens - a.tokens);
+    if (largeMd.length > 0) {
+        const savings = largeMd.reduce((sum, f) => sum + Math.floor(f.tokens * 0.2), 0);
+        recs.push({
+            priority: ++priority,
+            action: `Compress CLAUDE.md (${result.claudeMd.totalTokens.toLocaleString()} tokens)`,
+            savings,
+            detail: largeMd
+                .map(f => `  ${f.filePath}: ${f.tokens.toLocaleString()} tokens`)
+                .join('\n'),
+        });
+    }
+    // Overall: flag if total overhead is >20% of context
+    if (result.percentUsed > 20) {
+        recs.push({
+            priority: ++priority,
+            action: `Total overhead is ${result.percentUsed.toFixed(1)}% — target <15%`,
+            savings: 0,
+            detail: `${result.totalTokens.toLocaleString()} tokens consumed before any conversation begins.`,
+        });
+    }
+    // Sort by savings descending
+    recs.sort((a, b) => b.savings - a.savings);
+    recs.forEach((r, i) => (r.priority = i + 1));
+    return recs;
+}

package/dist/reporter.d.ts

@@ -0,0 +1,2 @@
+import type { AuditResult, Recommendation } from './types.js';
+export declare function printReport(result: AuditResult, recommendations: Recommendation[]): void;

package/dist/reporter.js

@@ -0,0 +1,107 @@
+import chalk from 'chalk';
+const BAR_WIDTH = 20;
+function bar(ratio, width = BAR_WIDTH) {
+    const clamped = Math.min(Math.max(ratio, 0), 1);
+    const filled = Math.round(clamped * width);
+    const empty = width - filled;
+    return chalk.green('█'.repeat(filled)) + chalk.gray('░'.repeat(empty));
+}
+function severityBadge(tokens, total) {
+    const pct = total > 0 ? (tokens / total) * 100 : 0;
+    let severity;
+    if (pct > 40)
+        severity = 'CRITICAL';
+    else if (pct > 25)
+        severity = 'HIGH';
+    else if (pct > 10)
+        severity = 'MEDIUM';
+    else
+        severity = 'LOW';
+    const colors = {
+        CRITICAL: chalk.bgRed.white.bold,
+        HIGH: chalk.red.bold,
+        MEDIUM: chalk.yellow,
+        LOW: chalk.green,
+    };
+    return colors[severity](` ${severity} `);
+}
+function padRight(str, len) {
+    return str.length >= len ? str : str + ' '.repeat(len - str.length);
+}
+function fmt(n) {
+    return n.toLocaleString();
+}
+export function printReport(result, recommendations) {
+    const { claudeMd, skills, mcp, systemPrompt } = result;
+    const total = Math.max(result.totalTokens, 1);
+    console.log('');
+    console.log(chalk.bold.cyan('  Claude Code Context Audit'));
+    console.log(chalk.gray('  ' + '─'.repeat(52)));
+    // CLAUDE.md
+    console.log(`  ${padRight('CLAUDE.md', 24)} ${padRight(fmt(claudeMd.totalTokens) + ' tokens', 16)} ${bar(claudeMd.totalTokens / total)}`);
+    for (const f of claudeMd.files) {
+        const label = f.label || f.filePath;
+        console.log(chalk.gray(`    ${padRight(label, 34)} ${fmt(f.tokens)} tokens`));
+    }
+    // Skills — show listing overhead (per-turn cost)
+    const fullSkillTokens = skills.skills.reduce((s, sk) => s + sk.fullTokens, 0);
+    console.log('');
+    console.log(`  ${padRight(`Skills (${skills.skills.length} loaded)`, 24)} ${padRight(fmt(skills.totalTokens) + ' tokens', 16)} ${bar(skills.totalTokens / total)} ${severityBadge(skills.totalTokens, total)}`);
+    console.log(chalk.gray(`    Listing overhead (per-turn):    ${fmt(skills.totalTokens)} tokens`));
+    console.log(chalk.gray(`    Full content (on invocation):   ${fmt(fullSkillTokens)} tokens`));
+    if (skills.duplicates.length > 0) {
+        console.log(chalk.yellow(`    ⚠ ${skills.duplicates.length} near-duplicate skill${skills.duplicates.length > 1 ? 's' : ''} detected (−${fmt(skills.duplicateTokenSavings)} tokens)`));
+    }
+    // Top 5 largest by listing tokens
+    const topSkills = [...skills.skills].sort((a, b) => b.tokens - a.tokens).slice(0, 5);
+    for (const s of topSkills) {
+        console.log(chalk.gray(`    ${padRight(s.name, 28)} ${padRight(fmt(s.tokens) + ' listing', 16)} ${fmt(s.fullTokens)} full`));
+    }
+    if (skills.skills.length > 5) {
+        console.log(chalk.gray(`    ... and ${skills.skills.length - 5} more`));
+    }
+    // MCP Servers
+    console.log('');
+    console.log(`  ${padRight(`MCP Servers (${mcp.servers.length})`, 24)} ${padRight(fmt(mcp.totalTokens) + ' tokens', 16)} ${bar(mcp.totalTokens / total)} ${severityBadge(mcp.totalTokens, total)}`);
+    for (const s of mcp.servers) {
+        const tag = s.isDeferred ? chalk.green(' [deferred]') : chalk.yellow(' [always loaded]');
+        console.log(chalk.gray(`    ${padRight(s.name, 22)} ${padRight(fmt(s.estimatedTokens) + ' tokens', 14)} (${s.toolCount} tools)${tag}`));
+    }
+    if (mcp.servers.length === 0) {
+        console.log(chalk.gray('    No MCP servers configured'));
+    }
+    // System prompt
+    console.log('');
+    console.log(`  ${padRight('System Prompt', 24)} ${padRight(fmt(systemPrompt.estimatedTokens) + ' tokens', 16)} ${bar(systemPrompt.estimatedTokens / total)} ${chalk.gray('(base overhead)')}`);
+    // Total
+    console.log(chalk.gray('  ' + '─'.repeat(52)));
+    console.log(chalk.bold(`  TOTAL OVERHEAD:        ${fmt(result.totalTokens)} tokens`));
+    console.log(`  Context Limit:         ${fmt(result.contextLimit)} tokens`);
+    const pctBar = bar(result.percentUsed / 100, 30);
+    const pctColor = result.percentUsed > 25 ? chalk.red : result.percentUsed > 15 ? chalk.yellow : chalk.green;
+    console.log(`  Used Before Input:     ${pctColor(result.percentUsed.toFixed(1) + '%')} ${pctBar}`);
+    // Recommendations
+    if (recommendations.length > 0) {
+        console.log('');
+        console.log(chalk.bold.cyan('  TOP RECOMMENDATIONS'));
+        console.log(chalk.gray('  ' + '─'.repeat(52)));
+        for (const rec of recommendations.slice(0, 8)) {
+            const savingsStr = rec.savings > 0 ? chalk.green(`−${fmt(rec.savings)} tokens`) : '';
+            console.log(`  ${chalk.bold.white(String(rec.priority) + '.')} ${rec.action}`);
+            if (savingsStr)
+                console.log(`     ${savingsStr}`);
+            if (rec.detail) {
+                for (const line of rec.detail.split('\n')) {
+                    console.log(chalk.gray(`     ${line}`));
+                }
+            }
+        }
+        const totalSavings = recommendations.reduce((sum, r) => sum + r.savings, 0);
+        if (totalSavings > 0) {
+            const reductionPct = ((totalSavings / result.totalTokens) * 100).toFixed(1);
+            console.log('');
+            console.log(chalk.bold.green(`  Potential savings: ${fmt(totalSavings)} tokens (${reductionPct}% reduction)`));
+        }
+    }
+    console.log('');
+}

package/dist/scanners/claude-md.d.ts

@@ -0,0 +1,6 @@
+import type { ClaudeMdResult } from '../types.js';
+/**
+ * Find all CLAUDE.md files in the project and user home directory.
+ * Claude Code loads: project CLAUDE.md, parent dirs' CLAUDE.md, ~/.claude/CLAUDE.md
+ */
+export declare function scanClaudeMd(projectPath: string): ClaudeMdResult;

package/dist/scanners/claude-md.js

@@ -0,0 +1,53 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { countTokens } from '../tokenizer.js';
+const CLAUDE_MD_NAMES = ['CLAUDE.md', 'CLAUDE.local.md'];
+/**
+ * Find all CLAUDE.md files in the project and user home directory.
+ * Claude Code loads: project CLAUDE.md, parent dirs' CLAUDE.md, ~/.claude/CLAUDE.md
+ */
+export function scanClaudeMd(projectPath) {
+    const files = [];
+    // Project-level CLAUDE.md files (walk up to 3 parent dirs)
+    let dir = path.resolve(projectPath);
+    const visited = new Set();
+    for (let i = 0; i < 4; i++) {
+        if (visited.has(dir))
+            break;
+        visited.add(dir);
+        for (const name of CLAUDE_MD_NAMES) {
+            const filePath = path.join(dir, name);
+            if (fs.existsSync(filePath)) {
+                const content = fs.readFileSync(filePath, 'utf-8');
+                files.push({
+                    filePath: filePath,
+                    tokens: countTokens(content),
+                    label: name,
+                });
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // Global ~/.claude/CLAUDE.md
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    if (home) {
+        for (const name of CLAUDE_MD_NAMES) {
+            const globalPath = path.join(home, '.claude', name);
+            if (fs.existsSync(globalPath) && !visited.has(path.dirname(globalPath))) {
+                const content = fs.readFileSync(globalPath, 'utf-8');
+                files.push({
+                    filePath: globalPath,
+                    tokens: countTokens(content),
+                    label: `~/.claude/${name}`,
+                });
+            }
+        }
+    }
+    return {
+        files,
+        totalTokens: files.reduce((sum, f) => sum + f.tokens, 0),
+    };
+}

package/dist/scanners/mcp.d.ts

@@ -0,0 +1,6 @@
+import type { McpResult } from '../types.js';
+/**
+ * Scan MCP server configurations from .mcp.json and settings.json files.
+ * Estimates token overhead based on tool count heuristics.
+ */
+export declare function scanMcp(projectPath: string): McpResult;

package/dist/scanners/mcp.js

@@ -0,0 +1,125 @@
+import * as fs from 'fs';
+import * as path from 'path';
+// Average tokens per MCP tool definition (name + description + parameter schema)
+const TOKENS_PER_TOOL = 300;
+// Tokens for a deferred/ToolSearch tool (just the name, no schema)
+const TOKENS_PER_DEFERRED_TOOL = 15;
+function readJsonSafe(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+// Known tool counts for common MCP servers
+const KNOWN_SERVERS = {
+    'postgres': 22,
+    'postgresql': 22,
+    '@henkey/postgres': 22,
+    '@anthropic/mcp-postgres': 22,
+    'serena': 28,
+    'gmail': 2,
+    'claude_ai_gmail': 2,
+    'claude_ai_google_calendar': 3,
+    'google-calendar': 3,
+    'slack': 8,
+    'github': 15,
+    'filesystem': 6,
+    'brave-search': 2,
+    'puppeteer': 8,
+    'sqlite': 12,
+    'memory': 4,
+    'fetch': 2,
+    'sequential-thinking': 1,
+    'gemini-proxy': 5,
+    'gemini': 5,
+};
+/**
+ * Scan MCP server configurations from .mcp.json and settings.json files.
+ * Estimates token overhead based on tool count heuristics.
+ */
+export function scanMcp(projectPath) {
+    const allMcpServers = {};
+    const allowedTools = new Set();
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    // 1. Read .mcp.json files (primary MCP config location)
+    const mcpJsonPaths = [
+        path.join(projectPath, '.mcp.json'),
+        path.join(projectPath, '.mcp.local.json'),
+    ];
+    if (home) {
+        mcpJsonPaths.push(path.join(home, '.claude', '.mcp.json'));
+    }
+    for (const mp of mcpJsonPaths) {
+        const config = readJsonSafe(mp);
+        if (config?.mcpServers) {
+            Object.assign(allMcpServers, config.mcpServers);
+        }
+    }
+    // 2. Read settings.json for MCP servers defined there + allowed tools
+    const settingsPaths = [
+        path.join(projectPath, '.claude', 'settings.json'),
+        path.join(projectPath, '.claude', 'settings.local.json'),
+    ];
+    if (home) {
+        settingsPaths.push(path.join(home, '.claude', 'settings.json'));
+        settingsPaths.push(path.join(home, '.claude', 'settings.local.json'));
+    }
+    for (const sp of settingsPaths) {
+        const settings = readJsonSafe(sp);
+        if (!settings)
+            continue;
+        if (settings.mcpServers) {
+            Object.assign(allMcpServers, settings.mcpServers);
+        }
+        if (settings.permissions?.allow) {
+            for (const t of settings.permissions.allow)
+                allowedTools.add(t);
+        }
+        if (settings.allowedTools) {
+            for (const t of settings.allowedTools)
+                allowedTools.add(t);
+        }
+    }
+    // 3. Build server info
+    const servers = [];
+    for (const [name, config] of Object.entries(allMcpServers)) {
+        let toolCount = 10; // default estimate
+        const nameLower = name.toLowerCase();
+        // Match against config key name first (most reliable), then command string
+        if (nameLower in KNOWN_SERVERS) {
+            toolCount = KNOWN_SERVERS[nameLower];
+        }
+        else {
+            const cmdLower = [config.command || '', ...(config.args || [])].join(' ').toLowerCase();
+            for (const [knownName, count] of Object.entries(KNOWN_SERVERS)) {
+                if (cmdLower.includes(knownName)) {
+                    toolCount = count;
+                    break;
+                }
+            }
+        }
+        // Check deferred status from allowed tools
+        const mcpPrefix = `mcp__${name}__`;
+        const hasWildcard = allowedTools.has(`${mcpPrefix}*`) || allowedTools.has('*:**');
+        const specificAllowed = [...allowedTools].filter(t => t.startsWith(mcpPrefix) && !t.includes('*'));
+        const alwaysLoaded = hasWildcard ? toolCount : specificAllowed.length;
+        const deferred = Math.max(0, toolCount - alwaysLoaded);
+        const estimatedTokens = (alwaysLoaded * TOKENS_PER_TOOL) + (deferred * TOKENS_PER_DEFERRED_TOOL);
+        servers.push({
+            name,
+            toolCount,
+            estimatedTokens,
+            isDeferred: deferred > 0,
+        });
+    }
+    const totalTokens = servers.reduce((sum, s) => sum + s.estimatedTokens, 0);
+    const potentialSavings = servers.reduce((sum, s) => {
+        if (!s.isDeferred) {
+            return sum + (s.toolCount * TOKENS_PER_TOOL) - (s.toolCount * TOKENS_PER_DEFERRED_TOOL);
+        }
+        return sum;
+    }, 0);
+    return { servers, totalTokens, potentialSavings };
+}

package/dist/scanners/skills.d.ts

@@ -0,0 +1,11 @@
+import type { SkillsResult } from '../types.js';
+/**
+ * Scan all skill files in .claude/skills/ (project + global).
+ *
+ * Token accounting:
+ * - "listing tokens": The skill name + description one-liner injected into every system prompt
+ * - "full tokens": The complete SKILL.md content, only loaded when the skill is invoked
+ *
+ * The per-turn overhead is the LISTING tokens, not the full content.
+ */
+export declare function scanSkills(projectPath: string): SkillsResult;

package/dist/scanners/skills.js

@@ -0,0 +1,83 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import fg from 'fast-glob';
+import { countTokens, wordSimilarity } from '../tokenizer.js';
+const DUPLICATE_THRESHOLD = 0.75;
+function parseSkillFrontmatter(content) {
+    const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!match)
+        return { name: '', description: '' };
+    const fm = match[1];
+    const name = fm.match(/name:\s*["']?(.+?)["']?\s*$/m)?.[1] || '';
+    const description = fm.match(/description:\s*["']?(.+?)["']?\s*$/m)?.[1] || '';
+    return { name, description };
+}
+/**
+ * Scan all skill files in .claude/skills/ (project + global).
+ *
+ * Token accounting:
+ * - "listing tokens": The skill name + description one-liner injected into every system prompt
+ * - "full tokens": The complete SKILL.md content, only loaded when the skill is invoked
+ *
+ * The per-turn overhead is the LISTING tokens, not the full content.
+ */
+export function scanSkills(projectPath) {
+    const skills = [];
+    const searchDirs = [
+        path.join(projectPath, '.claude', 'skills'),
+    ];
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    if (home) {
+        searchDirs.push(path.join(home, '.claude', 'skills'));
+    }
+    for (const dir of searchDirs) {
+        if (!fs.existsSync(dir))
+            continue;
+        const files = fg.sync('**/SKILL.md', { cwd: dir, absolute: true, followSymbolicLinks: false });
+        for (const filePath of files) {
+            let content;
+            try {
+                content = fs.readFileSync(filePath, 'utf-8');
+            }
+            catch {
+                continue; // skip unreadable files
+            }
+            const { name, description } = parseSkillFrontmatter(content);
+            const skillName = name || path.basename(path.dirname(filePath));
+            const desc = description || content.slice(0, 200);
+            // The listing line that appears in every system prompt:
+            // "- skillName: description text here..."
+            const listingLine = `- ${skillName}: ${desc}`;
+            const listingTokens = countTokens(listingLine);
+            skills.push({
+                name: skillName,
+                description: desc,
+                filePath,
+                tokens: listingTokens,
+                fullTokens: countTokens(content),
+            });
+        }
+    }
+    // Detect duplicates via description similarity
+    const duplicates = [];
+    for (let i = 0; i < skills.length; i++) {
+        for (let j = i + 1; j < skills.length; j++) {
+            const sim = wordSimilarity(skills[i].description, skills[j].description);
+            if (sim >= DUPLICATE_THRESHOLD) {
+                duplicates.push({
+                    skill1: skills[i].name,
+                    skill2: skills[j].name,
+                    similarity: sim,
+                    potentialSavings: Math.min(skills[i].tokens, skills[j].tokens),
+                });
+            }
+        }
+    }
+    const duplicateTokenSavings = duplicates.reduce((sum, d) => sum + d.potentialSavings, 0);
+    return {
+        skills,
+        totalTokens: skills.reduce((sum, s) => sum + s.tokens, 0),
+        duplicates,
+        duplicateTokenSavings,
+    };
+}

package/dist/tokenizer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Approximate token count for Claude's tokenizer.
+ * Uses word-boundary splitting with length-based sub-word estimation.
+ * Accuracy: within ~10% of actual BPE tokenization for English/code.
+ */
+export declare function countTokens(text: string): number;
+/**
+ * Jaccard similarity on word sets — used for skill duplicate detection.
+ */
+export declare function wordSimilarity(a: string, b: string): number;

package/dist/tokenizer.js

@@ -0,0 +1,42 @@
+/**
+ * Approximate token count for Claude's tokenizer.
+ * Uses word-boundary splitting with length-based sub-word estimation.
+ * Accuracy: within ~10% of actual BPE tokenization for English/code.
+ */
+export function countTokens(text) {
+    if (!text)
+        return 0;
+    // Split on whitespace first, then sub-split on code-significant characters
+    // (BPE tokenizers split on these boundaries too)
+    const words = text.split(/\s+/).flatMap(w => w.split(/[-_/@.]+/)).filter(w => w.length > 0);
+    let tokens = 0;
+    for (const word of words) {
+        if (word.length <= 4) {
+            tokens += 1;
+        }
+        else if (word.length <= 8) {
+            tokens += 2;
+        }
+        else {
+            tokens += Math.ceil(word.length / 4);
+        }
+    }
+    return tokens;
+}
+/**
+ * Jaccard similarity on word sets — used for skill duplicate detection.
+ */
+export function wordSimilarity(a, b) {
+    const setA = new Set(a.toLowerCase().split(/\W+/).filter(w => w.length > 2));
+    const setB = new Set(b.toLowerCase().split(/\W+/).filter(w => w.length > 2));
+    if (setA.size === 0 && setB.size === 0)
+        return 1;
+    if (setA.size === 0 || setB.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const word of setA) {
+        if (setB.has(word))
+            intersection++;
+    }
+    return intersection / (setA.size + setB.size - intersection);
+}

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+export interface TokenCount {
+    tokens: number;
+    filePath: string;
+    label?: string;
+}
+export interface ClaudeMdResult {
+    files: TokenCount[];
+    totalTokens: number;
+}
+export interface SkillInfo {
+    name: string;
+    description: string;
+    filePath: string;
+    tokens: number;
+    fullTokens: number;
+}
+export interface DuplicatePair {
+    skill1: string;
+    skill2: string;
+    similarity: number;
+    potentialSavings: number;
+}
+export interface SkillsResult {
+    skills: SkillInfo[];
+    totalTokens: number;
+    duplicates: DuplicatePair[];
+    duplicateTokenSavings: number;
+}
+export interface McpServerInfo {
+    name: string;
+    toolCount: number;
+    estimatedTokens: number;
+    isDeferred: boolean;
+}
+export interface McpResult {
+    servers: McpServerInfo[];
+    totalTokens: number;
+    potentialSavings: number;
+}
+export interface SystemPromptResult {
+    estimatedTokens: number;
+    breakdown: {
+        label: string;
+        tokens: number;
+    }[];
+}
+export interface AuditResult {
+    claudeMd: ClaudeMdResult;
+    skills: SkillsResult;
+    mcp: McpResult;
+    systemPrompt: SystemPromptResult;
+    totalTokens: number;
+    contextLimit: number;
+    percentUsed: number;
+}
+export interface Recommendation {
+    priority: number;
+    action: string;
+    savings: number;
+    detail: string;
+}
+export type Severity = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "claude-context-lint",
+  "version": "0.1.0",
+  "description": "Audit your Claude Code setup and find where tokens are being wasted",
+  "type": "module",
+  "bin": {
+    "claude-context-lint": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "tsc"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "context-window",
+    "token-optimization",
+    "linter",
+    "cli",
+    "mcp",
+    "skills",
+    "anthropic",
+    "ai-tools"
+  ],
+  "author": "Claude Code <noreply@anthropic.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/skibidiskib/claude-context-lint.git"
+  },
+  "homepage": "https://github.com/skibidiskib/claude-context-lint#readme",
+  "bugs": {
+    "url": "https://github.com/skibidiskib/claude-context-lint/issues"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "fast-glob": "^3.3.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ]
+}