Promptheus Web UI Guide

Welcome to Promptheus, your AI-powered prompt optimization tool. The web interface makes it easy to transform basic prompts into detailed, effective instructions for language models.

💡 What is Promptheus?

Promptheus analyzes your prompts and intelligently asks clarifying questions to help you create better, more precise instructions for AI models. It supports multiple AI providers including Google Gemini, Anthropic Claude, OpenAI GPT, Groq, Alibaba Qwen, and Zhipu GLM.

Quick Start

Launching the Web UI

Start the Promptheus web interface by running:

promptheus web

This will:

  • Start a local web server (typically on port 8000)
  • Automatically open your default browser
  • Display the Promptheus interface
✅ System Requirements

Promptheus works on Windows, macOS, and Linux. You need Python 3.10 or higher and at least one AI provider API key.

Your First Prompt

Promptheus home screen with blank prompt input
Main interface with provider/model selectors, mode and style controls, and an empty prompt/optimized result panel

When you first open Promptheus, you'll see a clean interface with:

📝 Input Area

Large text field where you enter your initial prompt

⚙️ Mode Selector

Choose how Promptheus processes your input (Auto, Always Ask, or Skip Questions)

🔧 Provider Controls

Select your AI provider and model from the top navigation

📊 Output Panel

View your optimized prompt with options to tweak or copy

Initial Setup

Before optimizing prompts, you need to configure at least one AI provider with an API key.

Accessing Settings

  1. Click the Settings button in the top-right corner of the interface
  2. Navigate to the API Keys section where you can configure your provider credentials
  3. Enter your API key for at least one provider
  4. Click Save to store your configuration

General Settings

General settings with history toggle
Settings panel showing the global history toggle and API key section entry point

Use General settings to control app-wide behaviors:

  • History toggle: Enable or disable saving prompt refinements locally
  • Privacy: Turn history off when working with sensitive content
  • Settings access: Jump directly to provider-specific configurations from here

API Keys Configuration

API key entry fields for Google Gemini and OpenAI
API key form with masked inputs and dedicated save actions for Google Gemini and OpenAI credentials

The settings panel allows you to configure API keys for all supported providers. You can:

  • Add multiple providers: Configure keys for Google Gemini, OpenAI, Anthropic Claude, Groq, Qwen, and GLM
  • View saved keys: Previously configured keys are displayed (masked for security)
  • Update keys: Easily replace or update existing API keys
  • Test connection: The interface shows which provider is currently active

Getting API Keys

Here's where to obtain API keys for each provider:

Google Gemini

AI Studio - Free tier available with generous limits

Anthropic Claude

Anthropic Console - Advanced reasoning capabilities

OpenAI

OpenAI Platform - GPT-4 and other models

Groq

Groq Console - Ultra-fast inference speeds

Alibaba Qwen

DashScope - Chinese language expertise

Zhipu GLM

GLM Console - Alternative Chinese models

🔒 Security Note

API keys are stored locally on your machine. Promptheus never sends your keys to external servers except to the provider's own API endpoints.

System Status

Provider readiness and model counts
Validation view listing provider readiness, available model counts, and cache refresh controls

The System Status tab summarizes your configured providers:

  • Readiness: Confirms whether each provider key is valid
  • Model counts: Shows how many models are available for each provider
  • Latency hints: Displays the last validation time in milliseconds
  • Cache controls: Refresh the cached model list or validate all providers at once

Provider Selection

Use the dropdown menus in the top navigation bar to select your AI provider and model:

  • Provider dropdown: Choose from configured providers (Anthropic, OpenAI, Google, etc.)
  • Model dropdown: Select a specific model (e.g., claude-opus-4-0, gpt-4o, gemini-2.0-flash)
💡 Choosing a Provider

Different providers excel at different tasks. Google Gemini offers excellent free tier limits, Anthropic Claude provides superior reasoning, and OpenAI GPT is well-balanced for most use cases.

Provider Dropdown Interface

Provider and model selector bar
Top bar selectors for provider, model, connection status, and quick access to settings

The provider dropdown interface shows all configured providers:

🤖 Google Gemini

Models: gemini-2.0-flash, gemini-1.5-pro, gemini-1.5-flash

🧠 Anthropic Claude

Models: claude-3-5-sonnet, claude-3-opus, claude-3-5-haiku

⚡ OpenAI GPT

Models: gpt-4o, gpt-4-turbo, gpt-3.5-turbo

🚀 Groq

Models: llama-3.3-70b, mixtral-8x7b, llama-3.1-8b

🌟 Qwen

Models: qwen-max, qwen-plus, qwen-turbo

🔥 GLM

Models: glm-4-plus, glm-4-air, glm-4v

Optimization Modes

Promptheus offers three optimization modes to control how your prompts are processed:

🤖 Auto Mode (Recommended)

Intelligently detects your task type and decides whether to ask clarifying questions. For analysis tasks (research, explanation), it skips questions and directly optimizes. For generation tasks (writing, creation), it asks relevant questions to improve quality.

❓ Always Ask Mode

Forces Promptheus to generate and ask clarifying questions regardless of task type. Useful when you want maximum refinement and are willing to answer detailed questions.

⚡ Skip Questions Mode

Bypasses the question-asking phase and directly optimizes your prompt. Best for quick optimizations or when you've already provided detailed requirements.

Question Flow

Questionnaire overlay during prompt optimization
Interactive questionnaire guiding prompt refinement with progress tracking and required fields

When Promptheus determines that questions would improve your prompt, it presents an interactive questionnaire:

Question Types

  • Multiple Choice: Select from predefined options (e.g., target age range, tone, format)
  • Text Input: Provide free-form answers for open-ended questions
  • Checkbox Lists: Select multiple applicable options

Answering Questions

  1. Review the question displayed at the top of the panel (e.g., "Question 1 of 5")
  2. Select your answer by clicking the appropriate option or typing your response
  3. Navigate questions - some questions may influence which follow-up questions appear
  4. Submit answers - once complete, Promptheus processes your responses
💡 Question Quality

Promptheus uses AI to generate contextual questions specific to your prompt. Questions for a "write a story" prompt will be completely different from a "explain a concept" prompt.

The interface shows:

  • Progress indicator (Question X of Y)
  • Current question text with required field markers (*)
  • Cancel button to abort the process
  • Processing status while the AI generates your optimized prompt

Working with Results

After processing, Promptheus displays your optimized prompt in the output panel. The result includes:

Output Features

  • Enhanced Prompt: Your original prompt transformed into a detailed, effective instruction
  • Structured Requirements: Clear sections outlining requirements, constraints, and expectations
  • Context Integration: Answers from clarifying questions seamlessly incorporated

Available Actions

📋 Copy Button

Instantly copy the optimized prompt to your clipboard for use in other applications or AI tools

✏️ Tweak Button

Refine the result further by asking additional questions or providing more context

🔄 Start Over

Clear everything and begin with a fresh prompt

🚀 Optimize Prompt

Run the optimization again with different settings or modes

✅ What Makes a Good Optimized Prompt?

A well-optimized prompt is specific, includes relevant context, sets clear expectations, defines the desired format, and specifies any constraints or requirements.

History Management

Promptheus automatically saves all your prompt optimizations, making it easy to revisit and reuse previous work.

History page with pagination controls
History view showing saved prompts, provider/model details, and clear history plus pagination controls

Accessing History

History functionality allows you to:

  • View all previously optimized prompts
  • See both original and refined versions
  • Review which provider and model was used
  • Track when each optimization was created
  • Load past prompts for further refinement

History Features

  • Pagination: Navigate through history with customizable items per page (10, 20, or 50)
  • Timestamp: Each entry shows when it was created
  • Task Type: Identifies whether it was an analysis or generation task
  • Provider Info: Records which AI provider and model generated the optimization
💾 Local Storage

History is stored locally on your machine in platform-specific directories (~/.promptheus on Unix-like systems, %APPDATA%/promptheus on Windows).

History Interface

The history interface provides easy access to your previous work:

🔍 Quick Access

Located in the navigation for instant access to your prompt library

📋 Detailed View

See original prompts alongside their optimized versions

🗂️ Smart Organization

Chronological ordering with filtering options

🔄 One-Click Load

Quickly load any previous prompt for re-optimization

Use Cases & Examples

Promptheus excels at various prompt optimization scenarios:

Content Creation

Scenario: Writing a Blog Post

Basic prompt: "Write a blog post about cloud computing"

Promptheus asks: Target audience? Technical level? Preferred length? Key topics? Tone?

Result: "Write a 1500-word blog post for IT professionals (intermediate level) explaining cloud computing fundamentals. Cover IaaS, PaaS, and SaaS with practical examples. Use a professional but accessible tone. Include an introduction hook, 3-4 main sections, and a conclusion with actionable takeaways."

Technical Documentation

Scenario: API Documentation

Basic prompt: "Document this API"

Promptheus asks: Target readers? Required sections? Code examples? Authentication details?

Result: "Create comprehensive API documentation for backend developers. Include: endpoint descriptions, request/response schemas with examples, authentication flow, error codes with explanations, rate limiting details, and working code samples in Python and JavaScript."

Data Analysis

Scenario: Code Review

Basic prompt: "Review this code for security issues"

Mode: Skip Questions (analysis task)

Result: "Conduct a comprehensive security review of the provided code focusing on: SQL injection vulnerabilities, XSS risks, authentication/authorization flaws, sensitive data exposure, input validation issues. For each finding, provide severity rating, location, explanation, and remediation guidance."

Creative Writing

Scenario: Short Story (from screenshots)

Basic prompt: "Write a short, futuristic story for a young adult audience about a teenager who discovers an AI that can dream. The story should have a hopeful tone and be around 500 words."

Promptheus asks: Age range? Narrative perspective? Character traits? Story elements?

Result: Detailed specifications including first-person narrative, 13-15 year old target readers, AI personality traits, philosophical themes, romance subplot, and specific story requirements.

Frequently Asked Questions

How do I switch between providers?

Use the Provider dropdown in the top navigation bar. You can switch at any time, even between optimizations. Make sure you have configured an API key for the provider you want to use.

What happens if I don't answer all the questions?

Required questions (marked with *) must be answered. Optional questions can be skipped. The optimization quality improves with more complete answers, but Promptheus will work with whatever information you provide.

Can I use the optimized prompt with a different AI model?

Absolutely! Optimized prompts work with any language model. Copy the result and use it with ChatGPT, Claude, Gemini, or any other AI assistant. The optimization focuses on clarity and structure, which benefits all models.

How is my data stored?

All data (API keys, prompt history) is stored locally on your machine. Promptheus only communicates with AI provider APIs to process your prompts. No data is sent to Promptheus servers (there are none!).

Which mode should I use?

Auto Mode is recommended for most users. It intelligently decides when questions are helpful. Use Always Ask when you want maximum refinement, and Skip Questions when you need quick optimizations or your prompt is already detailed.

Can I edit the optimized prompt?

Yes! After copying the optimized prompt, you can edit it in any text editor or AI interface. You can also use the "Tweak" button to refine it further within Promptheus.

What's the difference between providers?

Each provider has unique strengths: Google Gemini offers excellent free tier; Claude excels at reasoning and following instructions; OpenAI GPT is well-balanced; Groq provides fastest responses; Qwen/GLM are optimized for Chinese language.

How do I clear my history?

History can be cleared using the CLI command promptheus history --clear or by accessing the history management features in the web interface (if implemented).

Troubleshooting

Common Issues

Web UI won't start

Solution:

  • Check if port 8000 is already in use: lsof -i :8000 (Unix) or netstat -ano | findstr :8000 (Windows)
  • Try specifying a different port: promptheus web --port 8080
  • Ensure Promptheus is properly installed: pip install --upgrade promptheus
API key not working

Solution:

  • Verify the key is copied correctly without extra spaces
  • Check if the key is active in your provider's console
  • Ensure you have sufficient credits/quota with the provider
  • Try testing with a different provider to isolate the issue
Optimization fails or times out

Solution:

  • Check your internet connection
  • Verify provider API status (check provider's status page)
  • Try a different provider or model
  • Reduce prompt complexity if it's very long
  • Check rate limits on your API key
Questions not appearing

Possible reasons:

  • Mode is set to "Skip Questions" - change to "Auto" or "Always Ask"
  • Your prompt type was detected as analysis (Auto mode) - try "Always Ask" mode
  • The AI determined no questions were needed - this is normal for some prompts
Browser doesn't open automatically

Solution:

  • Manually navigate to the URL shown in terminal (usually http://127.0.0.1:8000)
  • Use promptheus web --no-browser flag to suppress automatic opening
  • Check if your default browser is set correctly

Getting Help

📞 Support Resources

Made with ⚗️ by the Promptheus team | GitHub | Full Documentation