Context Optimizer - Pro Workflow

Overview

Context Optimizer helps you manage your context window and token budget effectively. It provides strategies for proactive compaction, MCP audits, subagent delegation, and CLAUDE.md optimization.

The “dumb zone” is real. When context >90%, Claude’s responses degrade. Compact before you reach it.

Quick Diagnosis

Check Current Usage

Run /context to see current usage

Compact if >70%

Compact now before quality degrades

Emergency Compact if >90%

You’re in the “dumb zone” — compact immediately

Optimization Strategies

Immediate Actions

Action	Saves	When
`/compact`	30-50% context	At task boundaries
Disable unused MCPs	~5% per MCP	When switching domains
Use subagents for exploration	Keeps main context clean	Heavy search/read tasks
Fresh session via `/resume`	100% reset	When starting unrelated work

Configuration

Set proactive auto-compaction:

{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
  }
}

Default auto-compact triggers at ~95%. Override to 50% for proactive compaction before quality degrades.

Context Discipline Rules

1. Read Before Edit

Always read files before editing. Builds accurate context.Bad:

User: Add error handling to utils.ts
Claude: [Edits without reading]

Good:

User: Add error handling to utils.ts
Claude: [Reads file first, then edits]

2. Compact at Task Boundaries

Manual compact between major tasksGood compact points:

After planning, before execution
After completing a feature
When context >70%
Before switching task domains

/compact

3. Disable Unused MCPs

Keep <10 MCPs enabled, <80 tools total

# List active MCPs
/mcp

# Disable unused
# (via settings or .mcp.json)

Each MCP adds overhead to every request.

4. Summarize Explorations

After exploring code, summarize findingsInstead of:

50 file reads in context

Do:

Explore with subagent
Subagent returns summary
Main session stays clean

5. Delegate High-Volume Tasks

Use subagents to isolate high-volume outputDelegate to subagents:

Test suite output
Large file exploration
Documentation generation
Log analysis

Main session context stays clean.

Context Compaction

How It Works

Auto-compacts at ~95% capacity (keeps long-running agents alive)
Configure earlier: CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50
PreCompact hooks save state before compaction
Subagents auto-compact independently from main session

Manual Compaction

# Compact now
/compact

# Check usage first
/context

Before Compact
After Compact

Context: 145,000 / 200,000 tokens (72.5%)

Messages: 47
Tool calls: 23
Files read: 18

Context: 68,000 / 200,000 tokens (34%)

Compacted 47 messages to summary
Retained recent conversation
Preserved key decisions

MCP Audit

Keep <10 MCPs enabled, <80 tools total.

Essential MCPs

context7

Live documentation lookup

playwright

Browser automation (token-efficient)

github

PRs, issues, code search

Audit Process

# List active MCPs
/mcp

# Count total tools
# Goal: <80 tools

Remove:

MCPs used <1x per week
Overlapping functionality (e.g., 2 database MCPs)
Development-only MCPs in production sessions

Keep:

Essential for current project domain
Used >3x per session
No alternatives available

Prompt Engineering for Efficiency

Scoped Prompts

"Fix the code"

Vague prompts force Claude to read everything. Scoped prompts target specific areas.

Provide Constraints

"Refactor the API"

Constraints prevent unnecessary exploration.

Give Acceptance Criteria

"Add rate limiting"

Clear criteria reduce back-and-forth.

Subagent Delegation

Heavy operations that generate lots of output should go to subagents:

Test Suite Output

---
name: test-runner
tools: ["Bash"]
background: true
---

Run the test suite and report:
- Pass/fail status
- Failed tests with error messages
- Coverage percentage

Don't include full output in main session.

Large File Exploration

---
name: scout
tools: ["Read", "Glob", "Grep"]
background: true
isolation: worktree
---

Explore the codebase and find:
- Relevant files
- Similar patterns
- Dependencies

Return summary only, not full file contents.

Documentation Generation

---
name: documenter
tools: ["Read", "Write"]
context: fork
---

Generate documentation for the API.
Work in isolated context, don't pollute main session.

Log Analysis

---
name: log-analyzer
tools: ["Read", "Grep"]
background: true
---

Analyze error logs and find:
- Most common errors
- Patterns by timestamp
- Affected endpoints

Return summary only.

The main session stays clean while subagents handle the volume.

Context Budget Planning

Plan your context usage by phase:

Phase	Target Usage	Action If Over
Planning	< 20%	Keep plans concise
Implementation	< 60%	Compact between files
Testing	< 80%	Delegate to subagent
Review	< 90%	Start fresh session

If you hit 90% during implementation, you’re doing too much in one session. Compact or break into smaller tasks.

CLAUDE.md Optimization

Size Guidelines

Root CLAUDE.md: < 60 lines ideal, < 150 max
Package-level: Move package-specific info here
CLAUDE.local.md: Personal preferences
Remove: Obvious or rapidly-changing information

Split Memory Architecture

.claude/
├── CLAUDE.md          # Entry point (<60 lines)
├── AGENTS.md          # Workflow rules
├── SOUL.md            # Style preferences
└── LEARNED.md         # Auto-populated learnings

Benefits:

Keeps root file concise
Modular, easy to maintain
Learnings don’t clutter core instructions

When Context Is Degraded

Signs

Claude repeats itself or forgets earlier context
Responses become generic or lose project-specific knowledge
Tool calls start failing for reasons that worked earlier
“I don’t recall” or “I don’t have that information”

Fix

Manual Compact

/compact

Often fixes degradation immediately.

Fresh Session (If Still Bad)

/resume

Starts new session with clean context, loads recent history.

Reduce Size (Recurring Issues)

Shrink CLAUDE.md
Disable unused MCPs
Use CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50

Examples

Example 1: Proactive Compaction

User: Check context usage

Claude: Current context: 142,000 / 200,000 tokens (71%)

⚠️ Approaching auto-compact threshold. Recommend manual compact now.

User: /compact

Claude: Compacting context...

✓ Context reduced: 142,000 → 65,000 tokens (32.5%)

Retained:
- Last 10 messages
- Key decisions from this session
- Current task context

Ready to continue.

Example 2: MCP Audit

User: Why is Claude feeling slow?

Claude: Checking configuration...

Active MCPs: 14
Total tools: 127

⚠️ High MCP count (recommend <10)
⚠️ High tool count (recommend <80)

Unused MCPs (last 7 days):
- postgres-mcp (0 calls)
- redis-mcp (0 calls)
- docker-mcp (1 call)
- kubernetes-mcp (0 calls)

Recommendation: Disable unused MCPs

Should I create a minimal MCP config?

Example 3: Subagent Delegation

User: Run the full test suite

Claude: Test suites generate high output. Using subagent...

[Spawns test-runner subagent in background]

Subagent running: npm test
Main session context stays clean.

[2 minutes later]

Subagent report:
✓ Tests: 245 passed, 3 failed
✗ Failures:
  - auth.test.ts:42 "should rate limit login"
  - api.test.ts:18 "should handle timeout"
  - db.test.ts:55 "should rollback transaction"

Coverage: 87%

[Full output not in main session context]

Should I fix the failing tests?

Integration with Pro Workflow

Pro Workflow

Context discipline is a core pattern

Parallel Worktrees

Worktrees isolate context by task

Orchestrate

Subagents keep research phase context clean

Insights

Track context usage patterns over time

Best Practices

Compact at 50%, Not 95%

Don’t wait for auto-compact. Manual compact at 50% keeps quality high.

Start Sessions Clean

Use /resume to start fresh with relevant history, not /reopen with full context.

One Domain Per Session

Don’t work on auth, then database, then UI in one session. Context gets muddy.

Delegate Heavy Operations

Tests, logs, large file reads — all go to subagents. Main session for high-level decisions.

Troubleshooting

Context Always Full

Check:

CLAUDE.md size (<60 lines?)
Active MCP count (<10?)
Auto-compact percentage (set to 50%?)
Are you reading too many files without summarizing?

Auto-Compact Not Triggering

Verify:

{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
  }
}

Default is 95% — too late for quality.

Subagents Not Helping

Ensure:

Subagent has background: true
Subagent returns summary, not full output
Main session doesn’t read subagent’s tool outputs

Next Steps

Master Pro Workflow

Context discipline is a core pillar

Try Parallel Worktrees

Isolate context by task with worktrees

Learn Orchestrate

Multi-phase development with clean context

View All Skills

Explore the complete skill system

Get Started

Core Concepts

Skills

Agents

Commands

Hooks & Events

Configuration

Guides

​Overview

​Quick Diagnosis

​Optimization Strategies

​Immediate Actions

​Configuration

​Context Discipline Rules

​Context Compaction

​How It Works

​Manual Compaction

​MCP Audit

​Essential MCPs

context7

playwright

github

​Audit Process

​Prompt Engineering for Efficiency

​Scoped Prompts

​Provide Constraints

​Give Acceptance Criteria

​Subagent Delegation

​Context Budget Planning

​CLAUDE.md Optimization

​Size Guidelines

​Split Memory Architecture

​When Context Is Degraded

​Signs

​Fix

​Examples

​Example 1: Proactive Compaction

​Example 2: MCP Audit

​Example 3: Subagent Delegation

​Integration with Pro Workflow

Pro Workflow

Parallel Worktrees

Orchestrate

Insights

​Best Practices

​Troubleshooting

​Context Always Full

​Auto-Compact Not Triggering

​Subagents Not Helping

​Next Steps

Master Pro Workflow

Try Parallel Worktrees

Learn Orchestrate

View All Skills

Build docs developers (and LLMs) love

Overview

Quick Diagnosis

Optimization Strategies

Immediate Actions

Configuration

Context Discipline Rules

Context Compaction

How It Works

Manual Compaction

MCP Audit

Essential MCPs

Audit Process

Prompt Engineering for Efficiency

Scoped Prompts

Provide Constraints

Give Acceptance Criteria

Subagent Delegation

Context Budget Planning

CLAUDE.md Optimization

Size Guidelines

Split Memory Architecture

When Context Is Degraded

Signs

Fix

Examples

Example 1: Proactive Compaction

Example 2: MCP Audit

Example 3: Subagent Delegation

Integration with Pro Workflow

Best Practices

Troubleshooting

Context Always Full

Auto-Compact Not Triggering

Subagents Not Helping

Next Steps