Context Budget Optimizer

Аудит и сокращение накладных расходов токенов в Claude Code. Выявляет раздувание в агентах, навыках и MCP-серверах, чтобы освободить контекстное окно и повысить производительность ИИ.

Продуктивность и workflow ★ 172,010 GitHub (172,010 ★)

Context Budget — это специализированный диагностический инструмент для Claude Code, который выявляет разрастание токенов среди агентов, навыков, MCP-серверов и правил проекта. Выполняя многофазную инвентаризацию и классификацию каждого загруженного компонента, он предлагает практические рекомендации по снижению накладных расходов, предотвращению снижения производительности и максимальному увеличению доступного окна контекста для реальных задач кодирования. Этот инструмент необходим разработчикам, управляющим сложными конфигурациями с множеством инструментов и пользовательских инструкций, которые хотят, чтобы их ИИ-ассистент оставался быстрым, отзывчивым и точным.

Ключевые особенности

01Приоритизированные отчеты об оптимизации с оценкой экономии токенов

02Оценка накладных расходов MCP-серверов и предложения по замене на CLI

03172 010 звёзд на GitHub

04Автоматический аудит потребления токенов для агентов, навыков и правил

05Анализ свободного пространства контекста для планирования будущих расширений инструментов

06Обнаружение избыточных компонентов и раздутых описаний в frontmatter

Сценарии использования

01Диагностика медленных сессий Claude Code или снижения качества вывода

02Аудит накладных расходов контекста после добавления нескольких новых MCP-серверов или навыков

03Планирование сложных конфигураций проектов для соблюдения ограничений окна токенов модели

name	context-budget
description	Audits Claude Code context window consumption across agents, skills, MCP servers, and rules. Identifies bloat, redundant components, and produces prioritized token-savings recommendations.
origin	ECC

Context Budget

Analyze token overhead across every loaded component in a Claude Code session and surface actionable optimizations to reclaim context space.

When to Use

Session performance feels sluggish or output quality is degrading
You've recently added many skills, agents, or MCP servers
You want to know how much context headroom you actually have
Planning to add more components and need to know if there's room
Running /context-budget command (this skill backs it)

How It Works

Phase 1: Inventory

Scan all component directories and estimate token consumption:

Agents (agents/*.md)

Count lines and tokens per file (words × 1.3)
Extract description frontmatter length
Flag: files >200 lines (heavy), description >30 words (bloated frontmatter)

Skills (skills/*/SKILL.md)

Count tokens per SKILL.md
Flag: files >400 lines
Check for duplicate copies in .agents/skills/ — skip identical copies to avoid double-counting

Rules (rules/**/*.md)

Count tokens per file
Flag: files >100 lines
Detect content overlap between rule files in the same language module

MCP Servers (.mcp.json or active MCP config)

Count configured servers and total tool count
Estimate schema overhead at ~500 tokens per tool
Flag: servers with >20 tools, servers that wrap simple CLI commands (gh, git, npm, supabase, vercel)

CLAUDE.md (project + user-level)

Count tokens per file in the CLAUDE.md chain
Flag: combined total >300 lines

Phase 2: Classify

Sort every component into a bucket:

Bucket	Criteria	Action
Always needed	Referenced in CLAUDE.md, backs an active command, or matches current project type	Keep
Sometimes needed	Domain-specific (e.g. language patterns), not referenced in CLAUDE.md	Consider on-demand activation
Rarely needed	No command reference, overlapping content, or no obvious project match	Remove or lazy-load

Phase 3: Detect Issues

Identify the following problem patterns:

Bloated agent descriptions — description >30 words in frontmatter loads into every Task tool invocation
Heavy agents — files >200 lines inflate Task tool context on every spawn
Redundant components — skills that duplicate agent logic, rules that duplicate CLAUDE.md
MCP over-subscription — >10 servers, or servers wrapping CLI tools available for free
CLAUDE.md bloat — verbose explanations, outdated sections, instructions that should be rules

Phase 4: Report

Produce the context budget report:

Context Budget Report
═══════════════════════════════════════

Total estimated overhead: ~XX,XXX tokens
Context model: Claude Sonnet (200K window)
Effective available context: ~XXX,XXX tokens (XX%)

Component Breakdown:
┌─────────────────┬────────┬───────────┐
│ Component       │ Count  │ Tokens    │
├──────��──────────┼────────┼───────────┤
│ Agents          │ N      │ ~X,XXX    │
│ Skills          │ N      │ ~X,XXX    │
│ Rules           │ N      │ ~X,XXX    │
│ MCP tools       │ N      │ ~XX,XXX   │
│ CLAUDE.md       │ N      │ ~X,XXX    │
└─────────────────┴────────┴───────────┘

WARNING: Issues Found (N):
[ranked by token savings]

Top 3 Optimizations:
1. [action] → save ~X,XXX tokens
2. [action] → save ~X,XXX tokens
3. [action] → save ~X,XXX tokens

Potential savings: ~XX,XXX tokens (XX% of current overhead)

In verbose mode, additionally output per-file token counts, line-by-line breakdown of the heaviest files, specific redundant lines between overlapping components, and MCP tool list with per-tool schema size estimates.

Examples

Basic audit

User: /context-budget
Skill: Scans setup → 16 agents (12,400 tokens), 28 skills (6,200), 87 MCP tools (43,500), 2 CLAUDE.md (1,200)
       Flags: 3 heavy agents, 14 MCP servers (3 CLI-replaceable)
       Top saving: remove 3 MCP servers → -27,500 tokens (47% overhead reduction)

Verbose mode

User: /context-budget --verbose
Skill: Full report + per-file breakdown showing planner.md (213 lines, 1,840 tokens),
       MCP tool list with per-tool sizes, duplicated rule lines side by side

Pre-expansion check

User: I want to add 5 more MCP servers, do I have room?
Skill: Current overhead 33% → adding 5 servers (~50 tools) would add ~25,000 tokens → pushes to 45% overhead
       Recommendation: remove 2 CLI-replaceable servers first to stay under 40%

Best Practices

Token estimation: use words × 1.3 for prose, chars / 4 for code-heavy files
MCP is the biggest lever: each tool schema costs ~500 tokens; a 30-tool server costs more than all your skills combined
Agent descriptions are loaded always: even if the agent is never invoked, its description field is present in every Task tool context
Verbose mode for debugging: use when you need to pinpoint the exact files driving overhead, not for regular audits
Audit after changes: run after adding any agent, skill, or MCP server to catch creep early

🧠 Что это

Context Budget Optimizer — это диагностический инструмент для Claude Code, который анализирует, сколько токенов контекстного окна потребляют все загруженные компоненты: агенты, навыки, MCP-серверы, правила и файлы CLAUDE.md. Он выявляет «раздутые» или избыточные элементы и выдаёт ранжированный список рекомендаций по сокращению расхода токенов. Это позволяет разработчику осознанно управлять контекстным бюджетом, избегая деградации качества ответов и замедления работы.

⚙️ Как работает

1. Инвентаризация компонентов

Сначала утилита сканирует все каталоги и оценивает потребление токенов для каждого типа компонентов:

Агенты (agents/*.md): подсчёт строк и токенов (слова × 1.3), проверка длины описания в frontmatter. Флаг: файлы >200 строк (тяжёлые), описание >30 слов (раздутый frontmatter).
Навыки (skills/*/SKILL.md): подсчёт токенов, флаг >400 строк. Дубликаты в .agents/skills/ не учитываются дважды.
Правила (rules/**/*.md): подсчёт токенов, флаг >100 строк, обнаружение пересечений содержимого между файлами правил одного языкового модуля.
MCP-серверы (.mcp.json или активная конфигурация): подсчёт серверов и общего числа инструментов, оценка накладных расходов схемы (~500 токенов на инструмент). Флаг: серверы с >20 инструментами, а также серверы, оборачивающие простые CLI-команды (gh, git, npm, supabase, vercel).
CLAUDE.md (проектный + пользовательский): подсчёт токенов, флаг при суммарном объёме >300 строк.

2. Классификация по необходимости

Каждый компонент помещается в одну из трёх категорий:

Всегда нужен — упомянут в CLAUDE.md, поддерживает активную команду или соответствует текущему типу проекта.
Иногда нужен — доменно-специфичен (например, языковые паттерны), не упомянут в CLAUDE.md. Рекомендуется активировать по запросу.
Редко нужен — нет ссылок на команды, дублирующееся содержимое или очевидное несоответствие проекту. Рекомендуется удалить или загружать лениво.

3. Выявление проблемных паттернов

Утилита ищет следующие типичные проблемы:

Раздутые описания агентов — описание >30 слов в frontmatter загружается при каждом вызове Task tool.
Тяжёлые агенты — файлы >200 строк раздувают контекст при каждом спавне.
Избыточные компоненты — навыки, дублирующие логику агентов, или правила, дублирующие CLAUDE.md.
Чрезмерная подписка MCP — >10 серверов или серверы, оборачивающие бесплатные CLI-утилиты.
Раздутый CLAUDE.md — многословные объяснения, устаревшие разделы, инструкции, которые должны быть правилами.

4. Формирование отчёта

Результат — структурированный отчёт с таблицей потребления токенов по категориям, списком найденных проблем (ранжированных по потенциальной экономии) и топ-3 рекомендациями. Пример:

Context Budget Report
═══════════════════════════════════════
Total estimated overhead: ~63,300 tokens
Context model: Claude Sonnet (200K window)
Effective available context: ~136,700 tokens (68%)

Component Breakdown:
┌─────────────────┬────────┬───────────┐
│ Component       │ Count  │ Tokens    │
├─────────────────┼────────┼───────────┤
│ Agents          │ 16     │ 12,400    │
│ Skills          │ 28     │ 6,200     │
│ Rules           │ 12     │ 3,000     │
│ MCP tools       │ 87     │ 43,500    │
│ CLAUDE.md       │ 2      │ 1,200     │
└─────────────────┴────────┴───────────┘

WARNING: Issues Found (5):
Top 3 Optimizations:
1. Remove 3 CLI-replaceable MCP servers → save ~27,500 tokens
2. Trim agent descriptions >30 words → save ~1,800 tokens
3. Merge duplicate rules → save ~900 tokens

В verbose-режиме (--verbose) дополнительно выводятся: пофайловая разбивка токенов, построчный анализ самых тяжёлых файлов, конкретные дублирующиеся строки и список MCP-инструментов с оценкой размера схемы каждого.

🎯 Когда использовать

Производительность сессии упала — ответы стали медленными или качество ухудшилось.
Недавно добавлено много компонентов — навыки, агенты, MCP-серверы.
Планируете расширение — хотите понять, есть ли место для новых компонентов.
Перед добавлением новых MCP-серверов — проверка, не превысит ли overhead допустимый порог (рекомендуется <40%).
Регулярные аудиты — после каждого значительного изменения конфигурации.

💡 Важно знать

MCP — самый мощный рычаг экономии: каждый инструмент стоит ~500 токенов схемы; сервер с 30 инструментами может потреблять больше, чем все навыки вместе взятые.
Описания агентов загружаются всегда — даже если агент не вызывается, его поле description присутствует в контексте каждого вызова Task tool.
Оценка токенов: для прозы используйте слова × 1.3, для кода — символы / 4.
Verbose-режим предназначен для отладки, не для регулярных проверок.
Аудит после изменений — лучшая практика для предотвращения незаметного разрастания контекста.

Установка одной командой.

npx skillfish add affaan-m/everything-claude-code context-budget

Источник: https://mcpmarket.com/tools/skills/context-budget-optimizer