DEV Community

Darshan K
Darshan K

Posted on

I Built a CLI That Caught 33,531 Tokens of Startup Bloat in My Agent Project

#ai #devops #cli #python

One afternoon I looked at my Claude Code agent and realized: I have no idea how many tokens load on startup. Skills scattered across .agents/skills/, global instructions in CLAUDE.md, reference files nobody asked for — it all adds up invisibly.

So I built trimr — a CLI that tells you exactly how much token bloat you have at startup, and automatically migrates your skills to a progressive-disclosure architecture.

The Problem

Your Claude Code agent loads every skill file on startup. All of them. Whether you need them or not.

Even a "lean" project can burn 30K+ tokens before you type a single message. But you can't see it, so you optimize in the dark.

What I Found in My Own Project 

$ trimr audit ./my-agent
Enter fullscreen mode Exit fullscreen mode 
📊 trimr audit — ./my-agent
──────────────────────────────────────────────────
Skill files (21 found)
  Ungated (globally loaded):   21 skills    ~33,531 tokens at startup
  Vaultable:                   21 skills    eligible for migration

Startup token cost
  Current:                     ~33,531 tokens
  After migration:             ~2,100 tokens
  Reduction:                   93.7%

Violations (31)
  [WARN]  .agents\skills\adapt\SKILL.md       | Ungated skill eligible for migration
  [WARN]  .agents\skills\animate\SKILL.md     | Ungated skill eligible for migration
  [WARN]  .agents\skills\critique\SKILL.md    | Ungated skill eligible for migration
  [WARN]  .agents\skills\frontend-design\SKILL.md | Ungated skill eligible for migration
  ... 17 more

Run `trimr migrate ./my-agent` to auto-fix.
──────────────────────────────────────────────────
Enter fullscreen mode Exit fullscreen mode

33,531 tokens. Gone before my agent processed a single word.

How It Works

The fix is progressive disclosure: instead of loading every skill at startup, you load a 100-token metadata stub (name + description). The full skill body only loads when the agent actually needs it.

Before migration:
  Agent starts → loads all 21 skills (33,531 tokens)

After migration:
  Agent starts → loads 21 metadata stubs (2,100 tokens)
  Agent needs "critique" skill → loads it on demand (2,468 tokens)
  Everything else: never loaded
Enter fullscreen mode Exit fullscreen mode

trimr audit finds the bloat:

  • Ungated skills loaded globally
  • Oversized global instruction files (CLAUDE.md, AGENTS.md, .cursorrules)
  • Hidden system prompts in JSON/YAML/TOML configs
  • Malformed YAML frontmatter that breaks skill routing silently

trimr migrate auto-fixes it:

  • Moves ungated skills to .vault/skills/
  • Generates pointer files so the agent knows where to find things
  • Truncates bloated global files while preserving frontmatter
  • --dry-run shows exactly what will change before touching anything

Installation 

pip install trimr
Enter fullscreen mode Exit fullscreen mode

Try It 

# See what you've got
trimr audit ./your-agent

# Preview the fix
trimr migrate ./your-agent --dry-run

# Apply it
trimr migrate ./your-agent

# Verify
trimr audit ./your-agent
Enter fullscreen mode Exit fullscreen mode

Who It's For

Optimized for Claude Code and Cursor IDE projects using markdown-based SKILL.md files.

Not for Langchain/OpenAI/Anthropic Workbench — different architecture, different problem.

The Numbers

  • Before: 33,531 tokens at startup
  • After: ~2,100 tokens (21 skills × 100 token L1 metadata)
  • Reduction: 93.7%

These are real numbers from a real audit on my own project. Your mileage will vary depending on skill size and count — run the audit to find out what you're actually burning.

GitHub: https://github.com/rushdarshan/trimr

PyPI: https://pypi.org/project/trimr/

Built because token budgets matter and most people have no idea what they're spending at startup.

Top comments (0)