ai-magic-prompt 0.4.0

TUI app that enriches prompts using Groq API and project context

Magic Prompt

A TUI and CLI tool that enriches short, vague prompts into detailed, structured prompts using Groq API and your project's actual file structure and codebase.

Features

• 📁 Project-Aware: Scans your project's file structure, config files, and extracts code signatures
• 🧠 AI-Powered: Uses Groq's fast LLM API to intelligently expand prompts
• ⚡ Real-Time Streaming: Watch the enriched prompt generate in real-time
• 🖥️ Dual Mode: Interactive TUI or headless CLI for shell scripting
• 🗂️ Workspace Management: Save and switch between multiple project workspaces
• 🎯 Dynamic Model Selection: Automatically fetch and select from available Groq models
• 📊 Status Bar: Real-time display of current mode, model, and settings

Installation

From PyPI

pip install ai-magic-prompt

Or with uv:

uv tool install ai-magic-prompt

Raycast Extension

The easiest way to install the Raycast extension is using the built-in command:

# Print the script to your terminal
magic-prompt --install-raycast

# Or save it directly to your Raycast scripts folder
magic-prompt --install-raycast ~/path/to/raycast/scripts

This will generate a script that automatically uses your current magic-prompt installation.

From Source

git clone https://github.com/arterialist/magic-prompt.git
cd magic-prompt
pip install -e .

Setup

Get your Groq API key from console.groq.com/keys.

Set it as an environment variable:

export GROQ_API_KEY=gsk_...

Configuration

Magic Prompt saves your preferences in ~/.config/magic-prompt/config.json. You can configure these via the CLI:

Model Selection

Set your preferred Groq model (default: llama-3.3-70b-versatile):

magic-prompt --model llama-3.1-8b-instant

Debounce Time

Adjust the real-time enrichment delay in milliseconds (default: 800):

magic-prompt --debounce 500

Default Directory

Save your current project directory as the default:

magic-prompt --save-dir .

View Current Config

magic-prompt --show-config

Or create a .env file in your project directory:

GROQ_API_KEY=your_api_key_here

Usage

Headless CLI Mode

Run from anywhere as a shell command:

# Basic usage - enrich a prompt
magic-prompt "add user authentication"

# Pipe prompt from stdin
echo "add logging" | magic-prompt

# Specify project directory
magic-prompt -d /path/to/project "refactor the API"

# Quiet mode - only output result (good for piping)
magic-prompt -q "add tests" > enriched.md

CLI Options

Option	Description
-d, --directory	Project directory (default: from config or cwd)
-t, --tui	Launch interactive TUI mode
-q, --quiet	Only output result, no progress
--debounce MS	Set debounce time for real-time mode
--save-dir DIR	Save default directory for future runs
--show-config	Show current configuration

Interactive TUI Mode

magic-prompt --tui
# OR just run without arguments:
magic-prompt

1. Enter your project's root directory path
2. Type a short prompt (e.g., "add user authentication")
3. Watch the enriched, project-aware prompt stream in real-time
4. Press Ctrl+Y to copy the enriched prompt

TUI Keyboard Shortcuts

Key	Action
Enter	Submit prompt
Ctrl+T	Toggle real-time
Ctrl+Y	Copy to clipboard
Ctrl+U	Clear Input
Ctrl+L	Clear Output
Ctrl+R	Rescan project
Ctrl+S	Open Settings
Ctrl+M	Cycle enrichment mode
Ctrl+W	Manage workspaces
Ctrl+D	Cycle through workspaces
Ctrl+Q	Quit

How It Works

1. Scans your project directory structure
2. Extracts docstrings, function signatures, and imports
3. Sends context + your prompt to Groq's LLM
4. Streams an enriched version that references actual files and APIs

License

GNU General Public License v3.0 - see LICENSE for details.