prompt-refiner

English | 中文

Prompt Refiner

A prompt refinement middleware for Claude Code. Intercepts user prompts, reads session context, and produces a clearer, more structured version before Claude processes it.

Two modes of operation:

• CLI mode (prf refine): Interactive TUI with Accept/Edit/Original/Skip review
• Hook mode (Claude Code UserPromptSubmit): Automatic refinement with two-step block review

Supports 47 built-in providers across 5 categories: Official, Domestic (China), Gateway, Coding, and Custom.

Core Workflow

User Input
    |
    v
[Skip Check]         -- /no-refine, short inputs, slash commands, greetings
    |
    v
[Read Transcript]    -- Recent Claude Code session history (.jsonl)
    |                   including thinking, tool calls, and results
    v
[Summarize Context]  -- Heuristic extraction of structured fields
    |                   (Task / Tech stack / Tried / Blocker / Modified / Constraints)
    v
[Refine Prompt]      -- LLM rewrites input with conversation context
    |
    v
[Review / Inject]    -- CLI: TUI review (Accept/Edit/Original/Skip)
                       Hook: block with comparison, user chooses a/e/o

Quick Start

Option A: Claude Code Plugin (Recommended)

# Step 1: Register the marketplace (one-time)
/plugin marketplace add https://github.com/Hav1d/Claude-Code-prompt-refiner

# Step 2: Install the plugin from that marketplace
/plugin install prompt-refiner

Claude Code will prompt you for:

1. Provider — e.g. deepseek, openrouter, claude (default: deepseek)
2. API Key — your provider's API key (stored securely in keychain)
3. Base URL — optional custom endpoint

On first session after install, SessionStart bootstraps Python dependencies automatically. The UserPromptSubmit hook then runs on every prompt — no manual config needed.

Option B: CLI (Standalone)

# Install
cd prompt-refiner
pip install -e ".[dev]"

# First-time setup (pick a provider, enter API key)
prf config set

# Refine a prompt (interactive)
prf refine

# Refine with direct input
prf refine "fix the login bug"

# Pipe input
echo "fix the user creation endpoint" | prf refine

# Continuous mode
prf batch

# Show config
prf config show

Note: The CLI command is prf, not pr. The pr name conflicts with the GNU pr utility.

Commands

Command	Description
prf refine [PROMPT]	Refine a prompt (interactive or with argument)
prf batch	Continuous refinement loop
prf config show	Show current configuration (key masked)
prf config set	Set or update provider via interactive wizard
prf config clear	Remove saved provider config
prf providers list	List all 47 built-in providers
prf providers show ID	Show provider details
prf providers search Q	Search providers by name/ID/notes
prf clear-cache	Clear summarization cache
prf hook EVENT	Hook entry point for Claude Code (legacy, prefer hook_entry.py)

Refine Options

Flag	Description
--config, -c	Path to config file
--no-submit, -n	Don't submit to Claude Code after refinement
--dry-run, -d	Show what would happen without executing
--output, -o	Write final prompt to a file
--skip, -s	Skip refinement entirely
--auto, -a	Auto-accept refined version (no TUI)
--debug	Enable debug logging

Authentication

First-Time Setup

prf config set

Launches an interactive wizard that:

1. Shows all 47 providers grouped by category
2. Lets you pick a provider
3. Prompts for API key (masked input)
4. Optionally lets you customize base URL and model
5. Saves to ~/.prompt-refiner/config.json with 0600 permissions

Credential Resolution Chain

On startup, credentials are resolved in this order (first match wins):

1. Plugin userConfig: CLAUDE_PLUGIN_OPTION_API_KEY env var (set by Claude Code from keychain)
2. Saved config: ~/.prompt-refiner/config.json → active provider's api_key
3. Saved config: ~/.prompt-refiner/config.json → active provider's auth_token
4. Environment: ANTHROPIC_API_KEY env var
5. Environment: ANTHROPIC_AUTH_TOKEN env var (Bearer token)
6. Fallback: ~/.claude/config.json → primaryApiKey (auto-detect)

Graceful Degradation

If no API key is available:

• CLI mode: Skips LLM refinement, applies prefix/suffix only
• Hook mode: Passes through to Claude Code without modification (empty stdout)
• No crashes, no error messages — the tool always works, just without refinement

Managing Credentials

prf config set     # Set or update provider + API key
prf config show    # Show config (key is masked: ********abcd)
prf config clear   # Remove saved provider config

Configuration