---

name: cost-optimization description: Manage Claude Code API costs - token strategies, model selection, monitoring. Use when concerned about API spend, optimizing token usage, choosing models for tasks, or setting up cost monitoring. Covers /cost command, batching strategies, and budget management. version: 1.0.0 author: Claude Code SDK tags: [cost, optimization, tokens, budget]

Cost Optimization

Reduce Claude Code API costs while maintaining quality through smart token management, model selection, and monitoring.

Quick Reference

Understanding Costs

How API Costs Work

Claude Code costs are based on tokens:

• Input tokens: Everything Claude reads (prompts, files, context)
• Output tokens: Everything Claude generates (responses, code)
• Cached tokens: Reduced rate for repeated context

Model Pricing (Relative)

Rule of thumb: Opus is ~15x more expensive than Haiku for the same tokens.

What Consumes Tokens

The /cost Command

Basic Usage

Copy> /cost

Shows:

• Session token usage (input/output)
• Estimated cost for current session
• Context window usage percentage

When to Check

• Before starting large tasks
• After reading multiple files
• When responses slow down
• Every 15-20 exchanges
• Before deciding to /compact vs /clear

Interpreting Results

The /stats Command

View usage statistics over time:

Copy> /stats

Date Range Filtering (2.1.6+): Press r to cycle between:

• Last 7 days
• Last 30 days
• All time

Shows:

• Total tokens used (input/output)
• Number of sessions
• Cost breakdown by period
• Model usage distribution

MCP Tool Search Auto Mode (2.1.7+)

When you have many MCP tools configured, their descriptions can consume significant context space. Version 2.1.7 introduces automatic MCP tool deferral:

How It Works

• Trigger: When MCP tool descriptions exceed 10% of context window
• Behavior: Tools are deferred and discovered via MCPSearch instead of loaded upfront
• Default: Enabled for all users

Cost Impact

Disabling Auto Mode

If you need all MCP tools loaded upfront (e.g., for specific workflows):

Copy// settings.json
{
  "disallowedTools": ["MCPSearch"]
}

Note: Only disable if you have few MCP tools or specifically need immediate tool availability.

Token Reduction Strategies

1. Selective File Reading

Expensive:

Copy> Read the entire src/ directory to understand the codebase

Efficient:

Copy> @src/api/users.ts @src/types/user.ts - I need to modify the user API

2. Use Grep Before Read

Expensive:

Copy> Find all files that use the AuthService class
[Claude reads many files to find them]

Efficient:

Copy> grep for "AuthService" in src/, then I'll look at the most relevant ones

3. Targeted @ Mentions

4. Limit Output Verbosity

Copy> Analyze this file and give me a brief summary of the key functions

vs

Copy> Explain every line of this file

5. Batch Related Operations

Expensive (multiple turns):

Copy> Read file A
> Now modify line 10
> Now read file B
> Modify line 20

Efficient (single turn):

Copy> In file A, update the getUserById function to handle null.
> In file B, add the new UserNotFound error type.
> Run the tests after both changes.

/compact vs /clear

When to /compact

Use /compact when:

• Context is 70%+ full
• You want to continue the same task
• Need to preserve decisions and progress
• Responses are slowing down

Cost impact: Reduces ongoing costs by 50-80%

When to /clear

Use /clear when:

• Switching to unrelated task
• Previous context is irrelevant
• Starting fresh approach
• Maximum cost savings needed

Cost impact: Resets to zero (but loses all context)

Decision Matrix

Model Selection

Quick Guide

Switching Models

Set model in skill frontmatter:

Copy---
model: haiku
---

Or request model in prompt:

Copy> Using Haiku, list all TypeScript files in src/

Cost Comparison Example

Task: Review 10 files for security issues

Best strategy: Use Haiku for initial scan, escalate to Opus for detailed review of potential issues.

Efficient Prompting

Reduce Token Count

Be Specific

Token-heavy:

Copy> I have this function that gets users from the database and I want
> to add some caching because it's being called too often and making
> the app slow. Can you help me figure out a good caching strategy?

Efficient:

Copy> Add Redis caching to getUserById in @src/api/users.ts.
> TTL: 5 minutes. Invalidate on user update.

Use Checklists

Copy> Implement user search:
> - [ ] Add search endpoint
> - [ ] Add debounced input
> - [ ] Handle empty results
> Run tests when done.

Clearer than long paragraph descriptions.

Batching Strategies

Batch Similar Operations

Instead of multiple turns:

Copy> Add logging to function A
[response]
> Add logging to function B
[response]
> Add logging to function C

Single turn:

Copy> Add consistent logging to functions A, B, and C in @src/utils.ts
> Use format: logger.info("[FunctionName] action", { params })

Batch Read-Modify Cycles

Copy> Review @src/api/*.ts for missing error handling.
> Add try-catch with proper logging to any functions that need it.
> Summarize changes made.

When NOT to Batch

• Complex, interdependent changes
• When you need to verify each step
• Exploratory work
• Learning a new codebase

Budget Management

Setting Expectations

Cost Controls

1. Monitor actively: Check /cost regularly
2. Set mental limits: "I'll compact at $X"
3. Use appropriate models: Haiku for exploration
4. Plan sessions: Know scope before starting

Daily/Weekly Tracking

Copy> /cost
[Note the total]

Track across sessions to understand your patterns.

Subagent Cost Efficiency

Why Subagents Help

Subagents have isolated context:

• Main context stays lean
• Exploratory work doesn't pollute
• Can use cheaper models

Cost-Efficient Agent Pattern

Copy---
name: explorer
model: haiku
tools: Read, Glob, Grep
---
Explore and summarize. Return only key findings.

Delegation Examples

Common Wasteful Patterns

Reference Files

Quick Decisions