Promptheus: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Installation and Setup

# Install in development mode
pip install -e .

# Or use the traditional setup.py approach
python setup.py develop

Running the Application

# Run the CLI tool
promptheus "Your prompt here"

# Run via Python module
python -m promptheus.main "Your prompt here"

# Interactive mode (REPL-style)
promptheus

# Skip questions mode (improve prompt directly)
promptheus -s "Your prompt"
promptheus --skip-questions "Your prompt"

# Refine mode (force questions)
promptheus -r "Your prompt"

# Different output formats
promptheus -o plain "Your prompt"   # Default: plain text
promptheus -o json "Your prompt"    # JSON output

# Pipe integration examples
promptheus "Write a story" | claude exec           # Chain with other AI tools
claude "$(promptheus 'Create a haiku')"            # Command substitution
promptheus "Explain Docker" | tee output.txt       # Save and display (auto-quiet)
echo "topic" | promptheus | cat > result.txt       # Chain transformations
promptheus -o json "schema" | jq '.prompt'         # JSON processing

Testing

# Run automated tests
pytest -q

# Manual smoke tests
promptheus --skip-questions "Test prompt"
python -m promptheus.main --skip-questions "Smoke test"

# Test different input methods
promptheus -f test_prompt.txt
promptheus @test_prompt.txt
cat test_prompt.txt | promptheus

# Environment validation
promptheus validate --providers gemini
promptheus validate --test-connection

Development Utilities

# Code formatting
black .

# Check for linting issues (if available)
python -m flake8 src/promptheus/ --ignore=E501,W503

# Type checking (if available)
python -m mypy src/promptheus/

Architecture Overview

Core Components

Main Application (src/promptheus/main.py)

• Entry point and CLI interface using argparse
• Implements adaptive interaction model that detects task types (analysis vs generation)
• Handles interactive loop mode (REPL) for continuous prompt processing
• Manages the question-answer-refinement workflow
• Contains the core process_single_prompt() orchestrator function
• Supports history commands: promptheus history, /history, /load <n>, /clear-history