Claude Code Token Optimizer 🛡️💸

A framework-agnostic setup to stop Claude Code (CLI) token bleeding and bypass rate limits for under $5.

---

The Problem: The Hallucinated .claudeignore

Many guides suggest using a .claudeignore file, but it is an un-enforced AI hallucination ignored by the Claude Code terminal harness.

Without native boundaries, a simple prompt like "Fix the alignment" triggers recursive file-scans. The agent silently processes hundreds of thousands of hidden tokens in node_modules, build outputs (.next, dist), and lockfiles, quickly draining your API budget.

---

The Solution: "Hands & Brains" Split-Stack Workflow

Divide your AI interactions into two distinct layers:

1. The Brains (Browser Sandbox): Conduct architectural planning, schema debates, and debugging using DeepSeek R1 via OpenRouter for $0.00.
2. The Hands (Local CLI Agent): Restrict Claude Code strictly to execution (writing code, running tests, committing). Claude Code leverages OpenRouter prompt caching, making repetitive scans 90% cheaper ($0.30/1M tokens instead of $3.00).

---

Repository Structure

├── .claude/
│   └── settings.json     # Project-scoped token firewall & script presets
├── .gitignore            # Keeps personal local overrides offline
└── CLAUDE.md             # Universal agent behavior contract

---

Setup & Implementation

1. The Real Token Firewall (.claude/settings.json)

Claude Code evaluates permissions sequentially: deny → ask → allow. Copy this template into your project root to block file leaks while preserving developer flow:

{
  "permissions": {
    "deny": [
      "Read(.env*)",
      "Read(**/node_modules/**)",
      "Read(**/.next/**)",
      "Read(**/dist/**)",
      "Read(pnpm-lock.yaml)",
      "Write(.env*)",
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ],
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(pnpm install:*)",
      "Bash(pnpm typecheck:*)",
      "Bash(pnpm build:*)",
      "Bash(timeout 15 pnpm dev:*)",
      "Bash(pkill:*)",
      "Bash(pnpm list:*)",
      "Bash(pnpm add:*)",
      "Bash(pnpm tsc:*)",
      "Bash(pnpm dev)",
      "Bash(ls:*)",
      "Bash(lsof:*)"
    ]
  }
}

2. Guard Against Key Leaks (.gitignore)

Commit shared project rules via settings.json, but add settings.local.json to your .gitignore so your private API keys are never exposed:

node_modules/
.pnpm-store/
.yarn/
*.log

# Personal Claude Code settings override (Contains local API keys)
.claude/settings.local.json

3. Universal Behavior Contract (CLAUDE.md)

Add this to your root directory to instruct Claude Code to auto-detect your package manager and stop writing long textual explanations:

# Global Behavior Contract

## Operational Environment
- Check the root directory for lockfiles (`pnpm-lock.yaml`, `bun.lockb`, `yarn.lock`, `package-lock.json`) and use the corresponding package manager.
- Read `package.json` dynamically for script definitions.

## Token Optimization
- **Concise Interactions**: Do not explain your code logic or list structural summaries. Modify the file, verify the build passes, and report the clean diff.
- **Conceptual Boundary**: If a task requires broad design choices or deep debugging, halt execution and instruct the user to use the free browser planning sandbox.

---

The 3-Step Micro-Budget Loop

1. Blueprint for $0: Brainstorm architectures in your browser sandbox. End your prompt with: "Give me a concise code blueprint. Do not rewrite whole files."

2. Execute Locally: Copy the blueprint into your terminal:

claude "Apply the configuration from this sandbox blueprint to /src/App.tsx and run pnpm build." --model claude-sonnet-4-6

3. Flush History: After a sub-task compiles successfully, clear your rolling chat history tax by typing:

/clear

---

License

Licensed under the MIT License. Feel free to fork, modify, and drop this directly into your projects.

---

💡 Built in Public: Engineered while bootstrapping Spoken Kitchen, an AI-native multi-lingual family recipe transcription engine, to maintain maximum velocity on a micro-budget.