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.

🔌 MCP Server Available

Promptheus includes a built-in Model Context Protocol (MCP) server for integration with AI toolchains. Start it with promptheus mcp and connect with MCP-compatible clients. Learn more in the documentation.

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

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

General Settings

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

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

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

Review the question displayed at the top of the panel (e.g., "Question 1 of 5")
Select your answer by clicking the appropriate option or typing your response
Navigate questions - some questions may influence which follow-up questions appear
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 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

GitHub Issues: Report bugs or request features
Documentation: Full CLI and technical docs
CLI Help: Run promptheus --help for command reference

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