promptfit

Turn vague requests into structured Claude Code tickets — using a local LLM.

Stop burning agent turns on ambiguous prompts. promptfit runs a one-liner request through a local model and hands Claude Code a clear, testable ticket instead of a guess.

pf 'fix the login button on mobile' | claude -p

Why

A vague prompt makes the agent explore before it can act: read files, grep, infer scope, sometimes redo work. A structured ticket — concrete files, ordered steps, testable acceptance criteria, explicit out-of-scope — collapses that exploration into a direct implementation pass.

| | Vague Prompt | Structured Ticket | |---|---|---| | Agent work before acting | Explores, guesses scope | Goes straight to the change | | Accuracy | Hit or miss | Targeted | | Where the clarifying work happens | Expensive cloud agent | Free local model |

The refinement runs locally (Ollama), so structuring costs nothing. Actual token savings vary by task and codebase — measure on your own prompts rather than trusting a fixed percentage.

Install

npm install -g @wecko-ai/promptfit

Requires Ollama running locally (or any OpenAI-compatible API).

# Start Ollama
ollama serve

# Pull the recommended model
ollama pull qwen3:8b

Quick Start

# Refine a prompt
pf 'fix the login button on mobile'

# Pipe directly to Claude Code
pf 'add dark mode to settings page' | claude -p

# Include file context for sharper, file:line-aware tickets
pf 'fix the nav dropdown' --context src/components/Nav.tsx

Usage

Usage: pf [options] [prompt...]

Turn vague requests into structured Claude Code tickets

Options:
  -V, --version          output the version number
  -c, --context <files>  files to include as context
  -m, --model <model>    LLM model to use (default: "qwen3:8b")
  --api-url <url>        LLM API base URL (default: "http://localhost:11434")
  --api-key <key>        API key (for OpenAI-compatible APIs)
  --json                 output as JSON instead of markdown
  -i, --interactive      ask clarifying questions before generating
  -h, --help             display help for command

Examples

# With file context
pf 'refactor the auth flow' --context src/auth.ts src/middleware.ts

# Use a specific model
pf 'add pagination' --model llama3.1:8b

# Cloud API fallback
pf 'fix login' --api-url https://api.openai.com/v1 --api-key sk-xxx --model gpt-4o-mini

# JSON output (for integrations)
pf 'fix login' --json

# Interactive mode — asks clarifying questions first
pf 'fix login' -i

# Read prompt from stdin
echo 'add search to the dashboard' | pf

# Full pipeline: refine → execute
pf 'add rate limiting to the API' --context src/routes/ | claude -p

Output Format

## Task: Fix mobile login button not responding to taps

### Context
- Read CLAUDE.md and src/components/LoginButton.tsx before changing anything.
- Login button is unresponsive on mobile viewports — likely a touch-target or z-index issue.

### Requirements
- Button responds to taps on all mobile devices.
- Touch target meets the 44x44px minimum accessibility guideline.

### Steps
1. Inspect LoginButton.tsx for z-index/padding → verify in DevTools device emulation.
2. Fix the touch target → verify tap works on iOS Safari and Chrome Android.

### Acceptance Criteria
- [ ] Button responds to tap on iOS Safari and Chrome Android
- [ ] Touch target is at least 44x44px
- [ ] No overlapping element blocks the button
- [ ] Works in portrait and landscape

### Do NOT
- Restyle unrelated buttons
- Change the auth logic — this is a tap/layout fix only

How It Works

┌──────────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Vague prompt    │────▶│  Local LLM   │────▶│  Structured     │
│  "fix login btn" │     │  (Ollama)    │     │  ticket.md      │
└──────────────────┘     └──────────────┘     └────────┬────────┘
                                                        │
       ┌────────────────────────────────────────────────┘
       ▼
┌──────────────────┐     ┌──────────────┐
│  Claude Code     │────▶│  Clean code  │
│                  │     │  changes     │
└──────────────────┘     └──────────────┘

1. You type a vague request.
2. pf sends it to a local LLM (free, private, fast).
3. The LLM structures it into a Claude-Code-ready ticket with testable acceptance criteria.
4. The ticket is piped to Claude Code, which implements with precision.

Claude Code Integration

Use promptfit as a native /refine slash command inside Claude Code.

# Install CLI + slash command
npm install -g @wecko-ai/promptfit && bash <(curl -s https://raw.githubusercontent.com/Wecko-ai/promptfit/main/install-command.sh)

# Or manually
cp commands/refine.md .claude/commands/refine.md

Then, in Claude Code:

/refine fix the login button on mobile

Claude Code runs pf on your prompt, then uses the structured ticket as the implementation spec and follows the acceptance criteria.

The slash command lives in commands/refine.md; the skill definition is in skills/prompt-refinement/skill.md.

Supported Models

Any Ollama model works. Recommended:

| Model | Size | Speed | Quality | |---|---|---|---| | qwen3:8b | 4.9 GB | Fast | Great (default) | | qwen3:14b | 9.0 GB | Medium | Excellent | | llama3.1:8b | 4.7 GB | Fast | Good | | gemma3:12b | 8.1 GB | Medium | Great | | mistral:7b | 4.1 GB | Fast | Good |

ollama pull qwen3:8b    # Recommended default

Contributing

git clone https://github.com/Wecko-ai/promptfit.git
cd promptfit
npm install
npm run build
node dist/cli.js 'test prompt'

PRs welcome. Keep it minimal — the whole tool is under 500 lines.

License

MIT — a wecko.ai project.