High Idle Usage: ~12k tokens

[kzbruh]

The plugin consumes ~12,373 tokens just sitting idle. It is dominating the context window compared to all other tools combined.

Example breakdown:

Provider	Idle tokens	% of controllable
compound-engineering	~12,373	74%
Supabase MCP	~4,994	30%
superpowers	~860	5%

Top Offenders to Trim:

• Agent Definitions (~9.2k tokens): The registered agents are extremely heavy.
• spec-flow-analyzer: 527t
• design-iterator: 526t
• figma-design-sync: 496t

Moreover, enabling it forces all 28 agents and 15 skills into context immediately, with no granular control to disable unused components.

[terry-li-hm]

I ran a detailed token audit of my Claude Code setup and the CE plugin agent descriptions are the single largest contributor after built-in tool definitions.

My measurements:

• 29 agent descriptions (frontmatter only): ~12,341 chars / ~3K tokens
• Full agent .md files: ~173KB / ~43K tokens (loaded when spawning, so less critical)
• The descriptions are embedded in the Task tool definition, sent with every API call

For context, my full system prompt breakdown:

Component	~Tokens
Built-in tool definitions	~15K
CE agent descriptions	~3K
CE skills/commands listing	~2K
CLAUDE.md (custom)	~4K
Other MCP tools	~8K

The agent descriptions are verbose because they include full <example> blocks. Trimming examples from the frontmatter descriptions alone would likely halve the overhead.

Workaround I'm using: A shell script on zsh startup that deletes irrelevant agent .md files from the plugin cache (Rails reviewers, Figma tools, etc. — 13 of 29 agents). They reappear on plugin update, the script re-removes them. Crude but effective.

What would actually help:

1. A plugin.json field like excludeAgents: [...] that Claude Code's plugin loader respects (upstream CC change)
2. Or the approach in Add configurable review agents via .local.md settings #124 — per-project config that controls which agents are available
3. Shorter frontmatter descriptions (move examples to the agent body, not the description field)

Option 3 is the quickest win and backward-compatible — the description only needs to tell Claude when to use the agent, not provide full examples of the conversation flow.

[kieranklaassen]

It's on my radar to make them shorter yes

[klook-tech-khiryezhou]

Hi, which tools you guys used to calculate the token usage?

[Yash-xoxo]

Hey @kzbruh and @terry-li-hm,

This is a great analysis - 12k tokens idle is rough, especially when most of it is agent descriptions you might never use.

Token Counting Tools

@klook-tech-khiryezhou - For measuring token usage:

• tiktoken (Python): pip install tiktoken
• js-tiktoken (Node): npm install js-tiktoken
• OpenAI tokenizer (web): https://platform.openai.com/tokenizer
• Claude Code debug mode: Shows token counts in logs

Quick script:

import tiktoken
enc = tiktoken.encoding_for_model("gpt-4")
tokens = enc.encode(your_text)
print(f"Tokens: {len(tokens)}")

Immediate Wins

@kieranklaassen - here's the low-hanging fruit to trim agent descriptions:

1. Move Examples Out of Descriptions

<!-- Before (in frontmatter) -->
description: |
  Analyzes spec files...
  
  <example>
  [100+ lines of conversation]
  </example>

<!-- After -->
description: Analyzes spec files and suggests improvements

<!-- Put examples in the agent body instead -->

This alone should cut ~50% of the description tokens.

2. Remove Redundant Agent Listings

Some agents like spec-flow-analyzer, design-iterator, figma-design-sync are very domain-specific. Most users won't need them. Consider:

• Making them opt-in via config
• Shipping them as separate plugin add-ons
• Or at minimum, trimming their descriptions to 1-2 sentences

3. Lazy-Load Agent Details

Instead of loading all 28 agent descriptions on startup:

// Current: all agents in Task tool definition
Task tool definition: [agent1 full desc, agent2 full desc, ...]

// Better: lightweight listing
Task tool definition: [agent1: "1-line summary", agent2: "1-line summary", ...]

// Load full description only when agent is invoked

Long-term Solutions

Option A: Selective Agent Loading (Best UX)

// .claude/config.json
{
  "compound-engineering": {
    "enabledAgents": ["code-review", "bug-fixer", "doc-writer"]
  }
}

Requires Claude Code upstream changes, but provides granular control.

Option B: Plugin Splitting (from #63)

Split into focused plugins:

• @every/compound-core (essential agents only)
• @every/compound-design (Figma, design tools)
• @every/compound-rails (Rails-specific reviewers)

Users install what they need.

Option C: Smart Defaults

Ship with a "minimal" set of agents (8-10 most common), make the rest opt-in.

Immediate Action Items

1. Quick fix (this week):

   • Strip <example> blocks from frontmatter descriptions
   • Move examples to agent body markdown
   • Expected savings: ~6k tokens

2. Short term (next sprint):

   • Implement .local.md settings per Add configurable review agents via .local.md settings #124
   • Let users disable agents per-project

3. Long term:

   • Work with Claude Code team on excludeAgents config
   • Or split into focused plugins

@terry-li-hm's workaround is smart but shouldn't be necessary. Let's fix this properly.

Happy to help with a PR for option 1 (moving examples) if that's the direction you want to go!

[kieranklaassen]

its 3k now, I think thats ok