claude-code-optimizer
Advanced tools
Optimize Claude Code token usage with smart rules, skills, hooks, and context templates
The #1 toolkit to make Claude Code faster, cheaper, and smarter. 21 skills | 6 rules | 8 hooks | 2 templates — one install.
Get Started | Features | Skills | Author
Every Claude Code session starts the same way — Claude explores your codebase from scratch. It runs 15-40 tool calls just to orient itself, re-reads the same files, misses your conventions, and burns tokens on discovery instead of doing actual work.
You're paying for exploration, not engineering.
Claude Code Optimizer gives Claude a compass instead of a GPS — a layered context system that loads just enough structure, only when relevant.
| Without Optimizer | With Optimizer | |
|---|---|---|
| Tool calls per task | ~20-40 | ~5-10 |
| Session start | Full exploration | Targeted reads |
| Conventions | No awareness | Follows your patterns |
| Architecture | Re-discovers every time | Knows the map |
| Always-on token overhead | Unbounded | ~300 tokens |
One install. Zero config. Immediate savings.
Install it — everything sets up automatically.
npm i -g claude-code-optimizer
That's it. Skills, rules, hooks, and templates are installed to ~/.claude/ automatically.
curl -sL https://raw.githubusercontent.com/huzaifa525/claude-code-optimizer/main/scripts/install.sh | bash
irm https://raw.githubusercontent.com/huzaifa525/claude-code-optimizer/main/scripts/install.ps1 | iex
# npm
npx claude-code-optimizer --uninstall
# curl
curl -sL https://raw.githubusercontent.com/huzaifa525/claude-code-optimizer/main/scripts/uninstall.sh | bash
Copy the templates to your project and fill in your details:
cp ~/.claude/CLAUDE.md.template ./CLAUDE.md
cp ~/.claude/claudeignore.template ./.claudeignore
| Type | Count | Installed To | Purpose |
|---|---|---|---|
| Skills | 21 | ~/.claude/skills/ | Slash commands for every workflow |
| Rules | 6 | ~/.claude/rules/ | Path-scoped conventions that auto-load |
| Hooks | 8 | ~/.claude/hooks/ | Automation scripts that run on their own |
| Templates | 2 | ~/.claude/ | CLAUDE.md + .claudeignore starters |
Skills are commands you invoke inside Claude Code with /skill-name. They run as specialized prompts that guide Claude to work smarter.
| Skill | Purpose | How to Invoke |
|---|---|---|
/explore-area | Deep codebase exploration before changes | /explore-area src/api/ |
/gen-context | Generate fresh project context summary | /gen-context |
/onboard | Full onboarding guide for new developers | /onboard |
/token-check | Session token usage analysis | /token-check |
/optimize-tokens | Web search for latest optimization tips + project analysis | /optimize-tokens |
| Skill | Purpose | How to Invoke |
|---|---|---|
/planning | Persistent markdown planning for complex tasks | Auto-activates on complex tasks |
/plan | Create implementation plan with task breakdown | /plan Add user notifications |
/smart-edit | Pattern-aware code changes | /smart-edit Add delete endpoint |
/tdd | Test-Driven Development cycle | /tdd user login validation |
/fix-issue | Fetch GitHub issue, implement fix, test, commit | /fix-issue 42 |
/debug-error | Analyze error, find root cause, fix | /debug-error Cannot read property of undefined |
/refactor | Refactor code while preserving behavior | /refactor auth middleware |
/migrate | Migrate between frameworks/versions | /migrate React-Router-v5 React-Router-v6 |
| Skill | Purpose | How to Invoke |
|---|---|---|
/commit | Generate conventional commit message and commit | /commit |
/create-pr | Create PR with auto-generated description | /create-pr |
/changelog | Generate changelog from git history | /changelog |
| Skill | Purpose | How to Invoke |
|---|---|---|
/review | Review changes for quality, security, performance | /review |
/security-scan | OWASP top 10, secrets, injection scan | /security-scan |
/perf-check | N+1 queries, memory leaks, bundle size analysis | /perf-check src/api/ |
/dep-check | Outdated/vulnerable dependency check | /dep-check |
/document | Generate docs/JSDoc/docstrings | /document src/utils/ |
Reads entry points, maps imports/exports, identifies patterns, checks tests, and returns a structured summary — all in a forked subagent so exploration tokens don't pollute your main context.
/explore-area src/api/
/explore-area src/components/
Example output:
## Area: src/api/
### Key Files
- routes/index.ts → all routes registered here
- middleware/auth.ts → JWT validation
### Patterns
- One file per resource in routes/
- Zod validation at route level
### Gotchas
- auth middleware is duplicated intentionally (different token validation)
Analyzes package.json, project structure, entry points, framework, git history, and existing CLAUDE.md. Gives Claude a full picture without you explaining it.
/gen-context
Example output:
## Project: my-app
## Stack: Next.js 14, TypeScript, Prisma, PostgreSQL
### Commands
- Dev: npm run dev
- Test: npm test
### Entry Points
- app/layout.tsx → root layout
- lib/db.ts → database connection
### Suggested CLAUDE.md Updates
- Missing: test command documentation
- Missing: deployment flow
Before making any change, it finds similar existing code in your codebase, reads at least 2 examples of the same pattern, checks conventions, then implements matching your exact style.
/smart-edit Add a delete endpoint for users
/smart-edit Add dark mode toggle to settings page
/smart-edit Create a new database migration for adding email field
Analyzes your current session for token efficiency — context usage, MCP servers, conversation length, and optimization tips.
/token-check
Example output:
Session Health Report
---------------------
Context usage: ~120K / 200K
Conversation turns: 23
Suggested action: /compact
Optimization tips:
- 3 files read multiple times (users.ts, auth.ts, db.ts)
- 2 MCP servers unused this session
- CLAUDE.md is 340 lines (recommend < 200)
Automatically creates task_plan.md for complex tasks. Breaks work into steps, tracks progress with checkboxes, and survives across sessions. Auto-activates when a task requires 5+ steps.
Analyzes staged changes (git diff --cached), checks your recent commit style, and generates a conventional commit message (feat:, fix:, refactor:, etc.). Stage your changes with git add, then type /commit.
Runs git diff, reads every changed file, and checks for code quality, security vulnerabilities, performance issues, and convention violations. Returns a structured report with severity levels. Review tokens stay isolated from your main context.
Analyzes ALL commits on your branch (not just the latest), generates a PR title, summary bullets, change list, and test plan checklist. Pushes and creates the PR via gh.
Fetches a GitHub issue, creates a branch, finds relevant code, implements the fix, writes tests, runs them, and commits with the issue number.
/fix-issue 42
Strict TDD — writes a failing test first, implements the minimum code to pass, verifies, then refactors. Repeats until the feature is complete.
Parses an error message or stack trace, traces the root cause through the codebase, checks recent git changes, implements a fix, and verifies.
Runs tests first to establish a baseline, then refactors incrementally. After each change, runs tests again. If anything breaks, reverts immediately.
Scans for OWASP top 10 vulnerabilities — hardcoded secrets, SQL injection, XSS, missing auth, insecure configs, dependency vulnerabilities. Returns a severity-ranked report. Runs in a forked subagent.
Analyzes for N+1 queries, memory leaks, unnecessary re-renders, large bundle imports, missing caching, O(n^2) algorithms, and more. Runs in a forked subagent.
Runs npm audit / pip audit, checks for outdated packages, flags deprecated dependencies, and suggests upgrades with breaking change warnings.
Generates a changelog from git history since the last tag. Groups commits by type (features, fixes, breaking changes). Outputs or updates CHANGELOG.md.
Greps for all usages of the old API/library, creates a migration plan, applies changes file by file, runs tests after each file, and reports what couldn't be auto-migrated.
/migrate Express-v4 Express-v5
/migrate React-Router-v5 React-Router-v6
Generates a complete onboarding guide — project structure, tech stack, dev workflow, code conventions, common tasks, environment variables, and useful commands. Runs in a forked subagent.
Creates a phased implementation plan with task breakdown, file mapping, reference code pointers, dependencies, and risk assessment. Runs in a forked subagent using the Plan agent.
Searches the web for the latest Claude Code token optimization tips, then analyzes your current project setup (CLAUDE.md size, .claudeignore, rules, skills, MCP servers, settings). Returns a scored report with quick wins.
Rules are markdown files in ~/.claude/rules/ that give Claude persistent context about your coding conventions. They use path-scoping — each rule only loads when Claude reads files matching specific patterns, so you don't waste tokens on irrelevant context.
| Rule | Activates When Claude Reads | What It Tells Claude |
|---|---|---|
frontend.md | src/components/**, src/pages/**, **/*.tsx, **/*.jsx | Component structure, styling approach, patterns to follow, what NOT to do |
backend.md | src/api/**, src/routes/**, src/controllers/**, src/services/** | API structure (routes -> controllers -> services), endpoint patterns, error handling |
database.md | src/database/**, src/models/**, prisma/**, **/*.sql | ORM usage, migration rules, query patterns, safety rules |
testing.md | **/*.test.*, **/*.spec.*, tests/** | Test runner, file conventions, what to test, what NOT to test |
skill-router.md | Always active | Maps user intents to skills — "commit this" -> /commit, "review" -> /review, etc. |
How it works: You edit these files with your actual conventions. When Claude opens a .tsx file, frontend.md loads automatically. When Claude is working on backend code, frontend rules stay hidden — zero token cost.
# Edit any rule
code ~/.claude/rules/frontend.md
# Add a new rule
code ~/.claude/rules/security.md
Add paths: frontmatter to scope when it loads:
---
paths:
- "src/api/**"
- "**/*.ts"
---
Your rules here...
Hooks are shell scripts that run automatically at specific moments in Claude Code's lifecycle. They don't need to be invoked — they trigger on their own.
| Hook | Triggers On | What It Does |
|---|---|---|
generate-context.sh | Every session start | Injects recent commits, uncommitted changes, branch, active plan into context |
resume-plan.sh | Every session start | Detects task_plan.md and injects it so /planning continues across sessions |
protect-files.sh | Every file edit/write | Blocks edits to .env, credentials, lock files, .git/, private keys |
block-dangerous.sh | Every bash command | Blocks rm -rf /, git push --force main, DROP TABLE, etc. |
auto-format.sh | After every file edit | Auto-runs prettier/black/gofmt/rustfmt on edited files |
filter-test-output.sh | After test/build/lint commands | Filters verbose output (50+ lines) to summary only |
commit-reminder.sh | When Claude stops responding | Reminds about uncommitted changes, suggests /commit |
auto-setup.sh | Every session start | Auto-generates CLAUDE.md and .claudeignore if missing — detects stack, framework, entry points, commands |
generate-context.shEliminates the "what's the current state?" back-and-forth at the start of every session. Claude instantly knows what you've been working on.
protect-files.shPrevents accidental edits to files that should never be touched by AI.
| Category | Files |
|---|---|
| Environment | .env, .env.local, .env.production |
| Credentials | credentials.json, *.pem, *.key |
| Lock files | package-lock.json, yarn.lock, pnpm-lock.yaml |
| Git | .git/ directory |
filter-test-output.shTest output can be thousands of lines. This saves massive token waste by only feeding Claude the information it actually needs (what passed, what failed). Full output stays in your terminal.
Add to your project's .claude/settings.json:
{
"hooks": {
"SessionStart": [
{
"matcher": "startup",
"hooks": [
{ "type": "command", "command": "bash ~/.claude/hooks/generate-context.sh" }
]
}
],
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "bash ~/.claude/hooks/protect-files.sh" }
]
}
]
}
}
| Stage | What Happens | Token Cost |
|---|---|---|
| Session Start | generate-context.sh hook runs automatically — Claude sees recent commits, changes, branch | ~100 |
| Always Loaded | CLAUDE.md loads — Claude sees commands, entry points, flow diagrams, decisions | ~200 |
| Always Active | .claudeignore blocks node_modules, dist, lock files, .env from being read | 0 |
| On-Demand | Rules load based on what files Claude reads (frontend.md, backend.md, etc.) | ~500 when active |
| Auto Planning | planning skill activates on complex tasks — creates task_plan.md | ~200 |
| User Invoked | 21 skills for commits, reviews, PRs, debugging, security, etc. | 0 in main context (forked) |
| Every Edit | protect-files.sh guards .env, credentials, lock files | ~10 |
Total always-on overhead: ~300 tokens. Everything else loads only when needed.
| Strategy | Token Savings | Effort |
|---|---|---|
| Lean CLAUDE.md with entry points | ~30% | Low |
| Path-scoped rules | ~20% | Medium |
.claudeignore | ~15% | Low |
| Exploration skill (forked) | ~25% | Low |
| Session start hooks | ~10% | Medium |
Code annotations (@claude tags) | ~15% | Medium |
The examples/ directory includes ready-to-use CLAUDE.md templates for popular stacks:
| Stack | Framework | Key Features |
|---|---|---|
| Next.js App | Next.js 14, App Router | Server Actions, Prisma, Tailwind |
| Express API | Express.js | REST, Controllers, Services, JWT Auth |
| Python FastAPI | FastAPI | SQLAlchemy, Alembic, Pydantic v2 |
| Monorepo | Turborepo | pnpm workspaces, shared packages |
Browse them on GitHub.
If this tool saves you tokens (and money), consider giving it a star — it helps others find it too.
We welcome contributions! Whether it's a new skill, a stack-specific template, or a bug fix:
See CONTRIBUTING.md for details.
AI Product Engineer | Medical AI Researcher | Open Source Builder
Building enterprise AI systems at Ruby CRM / CleverFlow (Dubai) — 45+ production features shipped with 99.5% uptime. Passionate about making AI-assisted development faster and more accessible for every developer.
| Website | huzefanalkhedawala.in |
| GitHub | @huzaifa525 |
| huzefanalkheda | |
| HuggingFace | huzaifa525 |
| Medium | huzefanalkheda |
| npm | claude-code-optimizer |
Other projects: Check out my GitHub for more AI/ML tools and research.
If Claude Code Optimizer saves you time and money, star the repo and share it with your team.
MIT License -- Huzefa Nalkheda Wala
FAQs
Optimize Claude Code token usage with smart rules, skills, hooks, and context templates
The npm package claude-code-optimizer receives a total of 4 weekly downloads. As such, claude-code-optimizer popularity was classified as not popular.
We found that claude-code-optimizer demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.
Security News
PHP releases emergency patches for two critical RCE vulnerabilities as agencies urge organizations to take unpatched sites offline.
Threat Research
/Security News
A supply chain attack compromised LiteLLM 1.107.0 on PyPI and Docker, spreading malware that steals cloud credentials, developer secrets, and AI provider keys.