claude-code-prompt-optimizer

Claude Code Prompt Optimizer

A Claude Code hook that transforms simple prompts into detailed, structured instructions. Add <optimize> to any prompt and it'll expand your request into something Claude can really sink its teeth into.

What It Does

When you tag a prompt with <optimize>, this hook intercepts it and runs it through Claude's extended thinking mode. The result is a fleshed-out version of your original request with:

• Specific implementation steps
• Error handling considerations
• Testing requirements
• Edge cases to watch for

Basically, it does the prompt engineering for you.

Requirements

• Claude Code CLI installed
• Node.js 18+
• One of the following:
  • CLAUDE_CODE_OAUTH_TOKEN (Claude Pro/MAX subscribers)
  • ANTHROPIC_API_KEY (API credit users)
  • Stored OAuth from claude login

Quick Install

git clone https://github.com/johnpsasser/claude-code-prompt-optimizer.git
cd claude-code-prompt-optimizer
npm run install-hook

The installer handles dependencies, auth setup, hook configuration, and verification.

Authentication

The Agent SDK checks for credentials in this order:

Priority	Method	Variable	Best For
1	OAuth token	CLAUDE_CODE_OAUTH_TOKEN	Claude Pro/MAX subscribers
2	API key	ANTHROPIC_API_KEY	API credit users
3	Stored OAuth	(none — uses claude login)	Already logged in

If CLAUDE_CODE_OAUTH_TOKEN is set, the API key is ignored. If neither env var is set, the Agent SDK falls back to stored OAuth credentials from claude login.

Auth resolution is adaptive and can be forced with OPTIMIZER_AUTH:

OPTIMIZER_AUTH	Behavior
auto (default)	An explicit CLAUDE_CODE_OAUTH_TOKEN wins. Inside a Claude Code session with no token, the (often invalid) parent-injected API key is stripped so the CLI uses your stored claude login. Outside Claude Code, a real ANTHROPIC_API_KEY is honored.
oauth	Always strip API keys and use OAuth / stored login.
apikey	Always keep ANTHROPIC_API_KEY (for pure API-credit users).

Setting Up OAuth Token

# Get your token
claude auth token

# Add to shell profile
export CLAUDE_CODE_OAUTH_TOKEN="your-oauth-token"

Setting Up API Key

export ANTHROPIC_API_KEY="sk-ant-api03-..."

Manual Setup

If you prefer to configure things yourself instead of using npm run install-hook:

1. Install Dependencies

git clone https://github.com/johnpsasser/claude-code-prompt-optimizer.git
cd claude-code-prompt-optimizer
npm install

2. Configure Auth

Set one of the environment variables above in your shell profile.

3. Configure the Hook

Add the hook to ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/claude-code-prompt-optimizer/src/hooks/optimize-prompt.sh"
          }
        ]
      }
    ]
  }
}

4. Make Hook Executable

chmod +x src/hooks/optimize-prompt.sh

Test it:

<optimize> write a function to calculate fibonacci numbers

For detailed setup instructions and troubleshooting, see QUICKSTART.md.

Examples

Before:

<optimize> create a REST API

After: The optimizer expands this into specs covering architecture, endpoints, error handling, auth, validation, and testing.

Before:

<optimize> refactor this codebase for better performance

After: You get a structured plan with profiling steps, bottleneck identification, prioritized refactoring targets, and benchmarking criteria.

Configuration

Variable	Description	Default
CLAUDE_CODE_OAUTH_TOKEN	OAuth token for Claude Pro/MAX (optional if logged in)	-
ANTHROPIC_API_KEY	Anthropic API key (used if no OAuth token)	-
OPTIMIZER_AUTH	Auth strategy: auto, oauth, or apikey	auto
OPTIMIZER_MODEL	Override the optimization model	from config
OPTIMIZER_FALLBACK_MODEL	Model to retry with if the primary errors	from config
OPTIMIZER_EFFORT	Reasoning effort: low, medium, high, xhigh, max	from config
OPTIMIZER_TIMEOUT_MS	Abort + fall back to the original prompt after N ms	from config
DEBUG	Enable debug logging	false

Debug logs go to /tmp/claude-code-hook-debug.log.

Config file