Proompter

Transform simple prompts into professional AI interactions with an intuitive web interface

A local web-based GUI wrapper for CLI AI tools like gemini-cli and claude-cli. Proompter provides an interactive middle layer for advanced prompt engineering, allowing you to generate professional prompts using Gemini and execute them with your AI assistant of choice.

🚀 Why Proompter?

• 🎨 Visual Interface: No more switching between terminal and editor - everything in one clean UI
• 🧠 Smart Prompt Engineering: Let AI help you craft better prompts with context awareness
• 🌍 Bilingual Support: Seamless Arabic ↔ English translation for international workflows
• 🔀 Integrated Git: Manage your code changes visually without leaving the interface
• 📝 Session Tracking: Automatic logging of all interactions for future reference
• 🎯 Context Control: Fine-tune which files the AI sees with interactive overrides

⚡ Quick Start

# 1. Install prerequisites
npm install -g gemini-cli @anthropic-ai/claude-cli

# 2. Clone and install
git clone https://github.com/younsabood/Prompt.git
cd Prompt
npm install
npm link

# 3. Run from any project directory
cd /path/to/your/project
proompter

Your browser will open automatically at http://localhost:3000 🎉

✨ Key Features

🎯 Core Functionality

• Interactive Web Interface: Clean, modern UI with persistent text area for prompt management
• Context-Aware: Automatically reads your entire project context (respecting .gitignore)
• Two-Phase Workflow:
  • Phase 1: Generate professional prompts using Gemini with interactive clarification
  • Phase 2: Execute the refined prompt with Gemini or Claude
• Chat Mode: Interactive Q&A mode for conversational AI interactions

🌐 Translation & Localization (v2.0+)

• AI-Powered Translation Layer: Arabic ↔ English translation using gemini-cli for seamless bilingual interactions
• UI-Based Q&A Interceptor: AI questions are intercepted, translated to Arabic, and presented in a clean modal UI popup
• Toggle Translation: Enable/disable translation layer from Settings panel

🔧 Advanced Tools

• Interactive Context Overrides (v2.8): Checkbox-based file selection - include/exclude specific files for single requests independent of .gitignore
• Prompt Templates (v2.8): Ready-to-use templates for common tasks (explain code, find bugs, refactor, write tests)
• Prompt History (v2.2): View, reuse, and manage previously generated prompts
• Context Visualizer (v2.4): View all included/excluded files with real-time filtering

🔀 Git Integration (v2.0+)

• Full Git GUI Panel: Visual interface for complete Git workflow
• Stage/Unstage Files: Individual or bulk file staging with visual indicators
• Commit Management: Write and commit changes directly from the UI
• Diff Viewer: Beautiful syntax-highlighted diff rendering using diff2html
• Push/Pull/Fetch: Complete remote repository operations
• Commit History: Visual log of recent commits with details

💻 Terminal Features

• Real Terminal Emulation: Full interactive terminal support using node-pty and xterm.js
• Tabbed Interface: Manage multiple terminal sessions simultaneously
• Live Interaction: Respond to AI prompts in real-time (e.g., approve file changes with 'y/n')
• Session Logging (v2.7+): Automatic session tracking with full terminal output logs

Prerequisites

Before installing Proompter, ensure you have:

1. Node.js (v16 or higher)
2. gemini-cli (for prompt generation and optional execution)

   npm install -g gemini-cli

3. claude-cli (optional, for Claude execution)

   npm install -g @anthropic-ai/claude-cli

Installation

Method 1: Install from local directory (for development)

# Clone the repository
git clone https://github.com/younsabood/Prompt.git
cd Prompt

# Install dependencies
npm install

# Link globally (makes 'proompter' command available)
npm link

Method 2: Install from npm (once published)

npm install -g proompter

Note: After installation via npm link, you can run proompter from any directory on your system.

Configuration

CLI-Based Architecture (v2.6+)

Proompter uses a CLI-only approach - all AI interactions go through gemini-cli or claude-cli. No API keys are stored in the application itself.

This means:

• ✅ No API keys needed in .env files
• ✅ Use your existing gemini-cli and claude-cli configurations
• ✅ All API key management happens through the CLI tools themselves
• ✅ Translation features work through gemini-cli commands

Settings & Preferences

Translation Toggle:

• Enable/disable the Arabic ↔ English translation layer from the Settings tab
• When enabled: AI questions appear in Arabic in a clean UI modal
• When disabled: AI questions appear directly in the terminal

Context Overrides (v2.8):

• Use the Context tab to view all project files
• Check/uncheck files to include/exclude them for the next prompt generation
• Overrides work independently of .gitignore rules
• Click "Clear Overrides" to reset selections

Port Configuration:

PORT=8080 proompter  # Use custom port (default: 3000)

🔒 Security

Proompter v2.8+ includes comprehensive security hardening:

Security Features

• ✅ Command Injection Prevention: All shell commands properly escaped using shell-escape
• ✅ Input Validation: Joi-based validation for all API endpoints and WebSocket messages
• ✅ Path Traversal Protection: File access restricted to project directory
• ✅ CSRF Protection: Token-based protection for state-changing operations
• ✅ Rate Limiting: Per-IP rate limits (100 req/15min) to prevent DoS attacks
• ✅ Security Headers: Helmet.js with CSP, HSTS, and other protective headers
• ✅ WebSocket Security: Origin validation, message size limits, and rate limiting
• ✅ Session Management: Secure, HTTP-only cookies with strict same-site policy
• ✅ Git Command Whitelist: Only approved Git commands can be executed

Production Deployment

1. Environment Configuration

   # Copy the example environment file
   cp .env.example .env
   
   # Edit .env and set secure values
   NODE_ENV=production
   SESSION_SECRET=<generate-strong-random-string>
   ALLOWED_ORIGINS=https://yourdomain.com

2. Generate Secure Session Secret

   openssl rand -hex 32

3. Enable HTTPS (Required for production)

   • Configure SSL certificates
   • Use a reverse proxy (nginx/Apache)
   • See SECURITY.md for detailed configuration

Security Best Practices

• 🔐 Never commit .env files to version control
• 🔄 Rotate secrets regularly in production
• 🌐 Use HTTPS for all production deployments
• 🛡️ Configure CORS with specific allowed origins
• 📊 Monitor logs for security-related events
• 🔧 Keep dependencies updated: Run npm audit regularly

Detailed Security Documentation

For comprehensive security information, see SECURITY.md:

• Complete security feature documentation
• Deployment best practices
• Network security guidelines
• Monitoring and alerting setup
• Vulnerability disclosure policy

Usage

Starting Proompter

1. Open your terminal/command prompt
2. Navigate to your project directory:

   cd C:\path\to\your\project

3. Run the command:

   proompter

This will:

• Start the local server on http://localhost:3000
• Automatically open your default browser
• Read the project context from the current directory

Workflow

Phase 1: Generate Professional Prompt

1. (Optional) Use a Template: Select from the Prompt Templates dropdown:

   • "Explain this code"
   • "Find bugs in this code"
   • "Refactor this code"
   • "Write unit tests for this"

2. (Optional) Override Context Files:

   • Go to the Context tab
   • Check/uncheck files to include/exclude for this request
   • This works independently of your .gitignore rules

3. Enter your simple prompt in the text area (Arabic or English supported):

   Refactor my main component to include a loading state

4. Click "Generate Professional Prompt"

5. With Translation Layer Enabled (Settings → Enable Translation):

   • Gemini analyzes your project context and generates clarifying questions
   • Questions are automatically intercepted by the AI Translation Layer
   • Questions are translated to Arabic and presented in a clean modal UI popup
   • You answer in Arabic directly in the UI modal
   • Your answers are translated back to English and sent to the AI
   • No need to interact with the terminal for Q&A!

6. With Translation Layer Disabled:

   • Questions appear in Terminal Tab 1
   • Type your response directly in the terminal and press Enter

7. Once Gemini outputs the final professional prompt (marked with FINAL_PROMPT:), you can review it in the text area

   • The prompt is automatically saved to History for future reuse

Phase 2: Execute with AI

1. Ensure the professional prompt is in the text area

2. Select your AI mode:

   • ☑ Use Gemini: Execute with gemini-cli
   • ☑ Use Claude: Execute with claude-cli
   • ☑ Use Chat: Interactive conversation mode with continuous Q&A

3. Click "Execute"

4. A new terminal tab opens showing the AI executing your prompt

5. If the AI asks for permission (e.g., "Apply this change? [y/n]"), type directly in the terminal

6. All interactions are automatically logged to a session file (.proompter-session-*.md)

Using the Git Panel

1. Click the Git Control tab to access the integrated Git GUI

2. View Changes:

   • See all modified, added, and deleted files
   • Click any file to view its diff

3. Stage Files:

   • Click individual checkboxes to stage/unstage specific files
   • Use "Stage All" or "Unstage All" for bulk operations

4. Commit Changes:

   • Write your commit message in the text area
   • Click "Commit Staged Changes"

5. Remote Operations:

   • Push: Upload commits to remote repository
   • Pull: Download and merge remote changes
   • Fetch: Download remote changes without merging

6. View History:

   • Scroll down to see recent commits
   • Click any commit to view its details and diff

Using Prompt History

1. Click the History tab to view all previously generated prompts

2. Reuse a Prompt:

   • Browse your history (most recent first)
   • Click "Use This Prompt" to load it into the text area

3. Delete Entries:

   • Click the 🗑️ icon to remove unwanted history entries

4. History is stored locally in your browser (up to 50 entries)

Additional Features

• New Terminal: Click the + button to spawn a new terminal session
• Switch Tabs: Click on any tab to switch between terminal sessions
• Close Terminals: Click the × on any tab to close that terminal
• View Context: Use the Context tab to see which files are included/excluded
• Settings: Toggle translation and other preferences in the Settings tab

Project Structure

proompter/
├── bin/
│   └── proompter.js                          # Global command entry point
├── lib/
│   ├── api/
│   │   ├── gitApi.js                         # Git operations API (status, log, diff, show, command)
│   │   └── appApi.js                         # App configuration API (context-files endpoint)
│   ├── services/
│   │   ├── CLITranslator.js                  # CLI-based translation (gemini-cli) for Arabic ↔ English
│   │   └── SessionManager.js                 # Session tracking and logging (.proompter-session-*.md)
│   ├── websocket/
│   │   ├── webSocketManager.js               # WebSocket message routing
│   │   └── handlers/
│   │       ├── promptHandler.js              # Prompt generation with Q&A interception
│   │       └── terminalHandler.js            # Terminal spawn/input/resize/close
│   ├── terminalManager.js                    # node-pty terminal management
│   └── contextReader.js                      # Project file reader with .gitignore support + overrides
├── public/
│   ├── js/
│   │   ├── DomManager.js                     # DOM manipulation and UI management
│   │   ├── GitPanel.js                       # Git panel functionality (stage, commit, push/pull)
│   │   ├── PromptPanel.js                    # Prompt panel functionality (generate, execute)
│   │   ├── QAManager.js                      # Q&A modal UI management (translation intercept)
│   │   ├── TerminalUIManager.js              # Terminal UI and xterm.js integration
│   │   ├── WebSocketClient.js                # WebSocket client and message handling
│   │   ├── ContextViewer.js                  # Context tab with file checkboxes (v2.4+)
│   │   ├── HistoryManager.js                 # Prompt history management (v2.2+)
│   │   └── SettingsManager.js                # Settings panel (translation toggle, etc.)
│   ├── index.html                            # Frontend interface with tabbed layout
│   ├── app.js                                # Main application orchestration
│   └── styles.css                            # Styles
├── server.js                                 # Main Express + WebSocket server
├── package.json                              # NPM package configuration (v2.8.0)
└── README.md                                 # This file

How It Works

Context Reading

When you generate a prompt, Proompter:

1. Reads all files in your current directory
2. Parses your .gitignore file
3. Excludes ignored files and common build artifacts (node_modules, dist, etc.)
4. Bundles the context for Gemini to analyze

Terminal Management

• Uses node-pty for real pseudo-terminal (PTY) emulation
• Supports full stdin/stdout/stderr streaming
• Handles interactive prompts (y/n confirmations, etc.)
• Each tab is an independent terminal session

WebSocket Communication

• Real-time bidirectional communication between browser and server
• Streams terminal output to the frontend
• Sends user input from frontend to backend terminals

Custom Ignores

The context reader automatically ignores:

• Everything in your .gitignore
• node_modules/
• .git/
• Build artifacts (dist/, build/, .next/)
• Lock files

To customize, modify lib/contextReader.js:17-28

Troubleshooting

"Command not found: proompter"

Run npm link from the project directory, or ensure the global npm bin directory is in your PATH.

"Failed to spawn terminal"

Ensure you're on a supported platform (Windows, macOS, Linux). On Windows, PowerShell must be available.

"gemini-cli not found"

Install gemini-cli globally:

npm install -g gemini-cli

Browser doesn't open automatically

Manually navigate to http://localhost:3000 in your browser.

Connection errors

• Check that no other service is using port 3000
• Ensure your firewall allows localhost connections
• Try a different port: PORT=8080 proompter

Development

Running in Development Mode

# Install dependencies
npm install

# Start server without global installation
npm start

# In another terminal, open browser to http://localhost:3000

Making Changes

After modifying the code:

• Backend changes require restarting the server (Ctrl+C, then npm start)
• Frontend changes just need a browser refresh

Version History

v2.8.1 - Security Hardening (Phase 1)

• 🔒 CRITICAL: Fixed command injection vulnerabilities
• 🔒 Added comprehensive input validation using Joi
• 🔒 Implemented path traversal protection
• 🔒 Added CSRF protection for state-changing operations
• 🔒 Implemented rate limiting (HTTP and WebSocket)
• 🔒 Added security headers with Helmet.js
• 🔒 Enhanced WebSocket security with origin validation
• 🔒 Secure session management with HTTP-only cookies
• 🔒 Git command whitelist validation
• 📄 Added SECURITY.md with comprehensive security documentation
• 📄 Added .env.example with security configuration

v2.8.0 - Interactive Context & Pro Features

• ✨ Interactive Context Overrides with checkbox-based file selection
• ✨ Prompt Templates for common tasks
• ✨ Improved Session Logging with full terminal output
• 🔧 Enhanced Context tab with Clear Overrides button

v2.7.0 - Session Management

• ✨ Automatic session tracking and logging
• 🐛 Fixed model consistency issues
• 📝 Session files saved as .proompter-session-*.md

v2.6.0 - CLI Migration

• 🔄 Migrated from Gemini API to CLI-only approach
• ✅ No API keys needed in .env files
• 🔧 Translation now uses gemini-cli commands

v2.4.0 - Chat Mode & Context Visualizer

• ✨ Chat Mode for interactive Q&A conversations
• ✨ Context Visualizer tab showing included/excluded files
• 🎨 Enhanced UI with better file organization

v2.3.0 - UI Layout Refactor

• 🎨 Major UI overhaul with tabbed interface
• 🔧 Separated control panel from tools area
• ✨ Added Terminal, Git, Context, History, and Settings tabs

v2.2.0 - History & Settings

• ✨ Prompt History panel with save/load/delete
• ✨ Settings panel with translation toggle
• 💾 LocalStorage-based persistence (up to 50 entries)

v2.0.0 - Translation & Git Integration

• ✨ AI-Powered Translation Layer (Arabic ↔ English)
• ✨ UI-Based Q&A Interceptor with modal popups
• ✨ Full Git GUI Panel with visual diff viewer
• 🎨 Modern, polished UI design

v1.0.0 - Initial Release

• ✨ Two-phase workflow (Generate → Execute)
• ✨ Context-aware prompt engineering
• ✨ Real terminal emulation with xterm.js
• ✨ Support for gemini-cli and claude-cli

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Credits

Built with:

• Express.js - Web server
• ws - WebSocket implementation
• node-pty - Pseudo-terminal emulation
• xterm.js - Terminal UI in the browser
• ignore - .gitignore parsing
• simple-git - Git operations in Node.js
• diff2html - Beautiful diff rendering
• dotenv - Environment configuration
• helmet - Security headers middleware
• joi - Input validation
• shell-escape - Command injection prevention
• express-rate-limit - Rate limiting
• express-session - Session management

Note: This tool works with gemini-cli and/or claude-cli. Ensure your AI CLI tools are properly configured before using Proompter. No separate API keys are needed in Proompter itself - all authentication happens through the CLI tools.