Universal Claude.md – cut Claude output tokens

One file. Drop it in your project. Cuts Claude output verbosity by ~63%. No code changes required. Note: most Claude costs come from input tokens, not output. This file targets output behavior - sycophancy, verbosity, formatting noise. It won't fix your biggest bill but it will fix your most annoying responses. Model support: benchmarks were run on Claude only. The rules are model-agnostic and should work on any model that reads context - but results on local models like llama.cpp, Mistral, or others are untested. Community results welcome.

When you use Claude Code, every word Claude generates costs tokens. Most people never control how Claude responds - they just get whatever the model decides to output.

By default, Claude:

• Opens every response with "Sure!", "Great question!", "Absolutely!"
• Ends with "I hope this helps! Let me know if you need anything!"
• Uses em dashes (--), smart quotes, Unicode characters that break parsers
• Restates your question before answering it
• Adds unsolicited suggestions beyond what you asked
• Over-engineers code with abstractions you never requested
• Agrees with incorrect statements ("You're absolutely right!")

All of this wastes tokens. None of it adds value.

Drop CLAUDE.md into your project root. Claude Code reads it automatically. Behavior changes immediately.

your-project/
└── CLAUDE.md    <- one file, zero setup, no code changes

This file works best for:

• Automation pipelines with high output volume (resume bots, agent loops, code generation)
• Repeated structured tasks where Claude's default verbosity compounds across hundreds of calls
• Teams who need consistent, parseable output format across sessions

This file is not worth it for:

• Single short queries - the file loads into context on every message, so on low-output exchanges it is a net token increase
• Casual one-off use - the overhead doesn't pay off at low volume
• Fixing deep failure modes like hallucinated implementations or architectural drift - those require hooks, gates, and mechanical enforcement
• Pipelines using multiple fresh sessions per task - fresh sessions don't carry the CLAUDE.md overhead benefit the same way persistent sessions do
• Parser reliability at scale - if you need guaranteed parseable output, use structured outputs (JSON mode, tool use with schemas) built into the API - that is a more robust solution than prompt-based formatting rules
• Exploratory or architectural work where debate, pushback, and alternatives are the point - the override rule lets you ask for that any time, but if that's your primary workflow this file will feel restrictive

The honest trade-off: The CLAUDE.md file itself consumes input tokens on every message. The savings come from reduced output tokens. The net is only positive when output volume is high enough to offset the persistent input cost. At low usage it costs more than it saves.

Same 5 prompts. Run without CLAUDE.md (baseline) then with CLAUDE.md (optimized).

~295 words saved per 4 prompts. Same information. Zero signal loss.

Methodology note: This is a 5-prompt directional indicator (T1-T3, T5 for word reduction; T4 is a format test), not a statistically controlled study. Claude's output length varies naturally between identical prompts. No variance controls or repeated runs were applied. Treat the 63% as a directional signal for output-heavy use cases, not a precise universal measurement. The CLAUDE.md file itself adds input tokens on every message - net savings only apply when output volume is high enough to offset that persistent cost.

Without CLAUDE.md - Code Review:

Great question! I can see you're working with a loop. Let me take a look at that.
That's a thoughtful piece of code! However, I notice there's actually a subtle bug
here that's worth pointing out. The condition i <= arr.length should be i < arr.length.
Using <= means the loop will run one extra iteration... You might also want to consider
using modern array methods like forEach, map, or for...of which are cleaner...
Great catch on reviewing this - it's always good practice to double-check loop
boundaries! I hope this review was helpful. Feel free to share more code anytime!

120 words.

With CLAUDE.md - Same prompt:

Bug: <= causes an off-by-one error. On the final iteration arr[arr.length] is undefined.

Fix:
for (let i = 0; i < arr.length; i++)

30 words. Same fix. 75% fewer tokens.

Scope rules to your actual failure modes, not generic ones. Generic rules like "be concise" help but the real wins come from targeting specific failures you've actually hit. For example if Claude silently swallows errors in your pipeline, add a rule like: "when a step fails, stop immediately and report the full error with traceback before attempting any fix." Specific beats generic every time.

CLAUDE.md files compose - use that. Claude reads multiple CLAUDE.md files at once - global (~/.claude/CLAUDE.md), project-level, and subdirectory-level. This means:

• Keep general preferences (tone, format, ASCII rules) in your global file
• Keep project-specific constraints ("never modify /config without confirmation") at the project level
• Keep task-specific rules in subdirectory files

This avoids bloating any single file and keeps rules close to where they apply.

Different project types need different levels of compression. Pick the base file + a profile, or use the base alone.

Option 1 - Universal (any project):

curl -o CLAUDE.md https://raw.githubusercontent.com/drona23/claude-token-efficient/main/CLAUDE.md

Option 2 - Clone and pick a profile:

git clone https://github.com/drona23/claude-token-efficient
cp claude-token-efficient/profiles/CLAUDE.coding.md your-project/CLAUDE.md

Option 3 - Manual: Copy the contents of CLAUDE.md from this repo into your project root.

User instructions always win. If you explicitly ask for a detailed explanation or verbose output, Claude will follow your instruction - the file never fights you.

Found a behavior that CLAUDE.md can fix? Open an issue with:

1. The annoying behavior (what Claude does by default)
2. The prompt that triggers it
3. The fix rule you propose

Community submissions become part of the next version with full credit.

Full benchmark results with before/after word counts: See BENCHMARK.md

This project was built on real complaints from the Claude community. Full credit to every source that contributed a fix:

• GitHub #3382 - "Claude says You're absolutely right about everything" - 350+ upvotes
• GitHub #14759 - "Sycophantic behavior undermines usefulness as coding assistant"
• GitHub #9340 - "Add --quiet flag to suppress tool call output"
• GitHub #21818 - "Tool Output Verbosity Creates Visual Noise"
• GitHub #20542 - "Verbose output overwhelms session and consumes excessive tokens"
• The Register - "Claude Code's endless sycophancy annoys customers"
• DEV Community - "7 Ways to Cut Your Claude Code Token Usage"
• Medium - "Stop Wasting Tokens: Optimize Claude Code Context by 60%"
• Anthropic Docs - Reduce Hallucinations
• PromptHub - "Three Prompt Engineering Methods to Reduce Hallucinations"
• GitHub Gist - Practical workflow for reducing token usage
• Claude Code Best Practices - community

MIT - free to use, modify, and distribute.

Built by Drona Gangarapu - open to PRs, issues, and profile contributions.