claude-code-optimizer v1.0.1

Scripts, CLAUDE.md template, and env vars to cut Claude Code token usage and cost. Official-docs-aligned baseline + tuned overlay. Reverse-engineered internals are marked unverified.

Version: see VERSION. Source of truth for voice: https://github.com/carlosduplar/caveman-output-style-claude-code (synced v1.2.0).

Quickstart

Prerequisites: PowerShell 7 (Windows) or Bash (Linux/macOS/WSL2)

Clone and run (default: tuned profile + max privacy):

# Windows
git clone https://github.com/carlosduplar/claude-code-optimizer.git
.\claude-code-optimizer\scripts\windows\optimize-claude.ps1

# Linux/macOS
git clone https://github.com/carlosduplar/claude-code-optimizer.git
./claude-code-optimizer/scripts/linux/optimize-claude.sh

Copy the CLAUDE.md template to your project root:

cp claude-code-optimizer/CLAUDE.md ./CLAUDE.md

Tested: Windows PowerShell 7.6, Ubuntu WSL2

Profiles

tuned is the default profile.

What It Optimizes

Cache savings only realized on hit. Output-style savings are voice-only; code/tool calls unchanged. Percentages in older docs were illustrative, not benchmarks.

Configuration Reference

All optimizer-managed runtime configuration is written to ~/.claude/settings.json.

Optimizer CLI

Environment Variables

Canonical cache control is now promptCacheTtl: 1h in settings.json (v2.1.242+). ENABLE_PROMPT_CACHING_1H=1 is kept for older CLI compatibility. BASH_MAX_OUTPUT_LENGTH is overridden by bashOutputMaxChars setting if set — optimizer sets env only.

Feature Enable (runtime, public builds)

Feature Disable (runtime, public builds)

Plus settings key promptCacheTtl: 1h (tuned, v2.1.242+).

Internal / Anthropic-only (⚠️ ant-only — requires USER_TYPE=ant)

CLAUDE.md Template

See CLAUDE.md. Contains compressed behavioral anchors for communication style, principles, workflow, and documentation. Copy to project root. For voice, prefer the caveman output style below — CLAUDE.md is a user message, output style is system-prompt level and persists without dilution.

Implemented Hooks

Caveman Output Style

Installed from assets/output-styles/ (synced from caveman-output-style-claude-code v1.2.0 — do not hand-edit; update assets instead) to ~/.claude/output-styles/:

• caveman.md (name: caveman, lowercase — value is case-sensitive, Caveman falls back to Default)
• caveman-ultra.md (maximum terseness, symbols over words, prose-only abbreviations)

Both set keep-coding-instructions: true (full system prompt only; no effect on short prompt unless CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT=0). Applies to main conversation + forks, not subagents. Changing styles invalidates prompt cache on first message after switch.

Voice-only savings: prose shrinks, code/paths/errors/commands verbatim. No measured % claimed.

Set via "outputStyle": "caveman" in settings.json (optimizer default) or --output-style caveman-ultra|none. Switch mid-session with /output-style <name> (applies next message; v2.1.251+; CLI requires v2.1.269+). Takes effect on restart if files were created mid-session.

Keepalive

Keepalive is reminder-based (SessionStart) and manual by design. Background claude -p pings create separate sessions with different prefixes and do not reliably keep the main conversation cache warm. Prefer active use; after >TTL idle expect one uncached turn. See docs/prompt-caching.md.

Hook Runtime Verification

Use runtime checks (not only config checks) to confirm hook events are firing:

• Linux/macOS/WSL: ./scripts/linux/test-hooks-runtime.sh
• Windows: .\scripts\windows\test-hooks-runtime.ps1

Bash Auto-Approve Defaults

Default install includes a conservative read-only metadata allowlist (listing/location/git metadata/version/help/package metadata). Higher-risk content-read patterns are added only with --unsafe-auto-approve.

How It Works

These optimizations target the three largest cost drivers: prompt cache misses, verbose output, and large input files.

Internals Reference

Reverse-engineered from alleged source analysis. Not official Anthropic documentation. Build-time feature flags cannot be enabled in public binaries.

Contributing

This documentation is derived from source code analysis. To contribute:

1. Focus on undocumented internals not in official docs
2. Include specific file paths and line numbers
3. Cite source code references
4. Submit PRs to carlosduplar/claude-code-optimizer

Legal

See docs/LEGAL.md for legal disclaimer and copyright notice.