ai-magic-prompt

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

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

How It Works

1. Scans your project directory structure
2. Extracts docstrings, function signatures, and imports
3. Retrieves the most relevant files based on your prompt (configurable)
4. Sends context + your prompt to Groq's LLM
5. Streams an enriched version that references actual files and APIs

Retrieval Modes

Magic Prompt uses intelligent file retrieval to select the most relevant files from your project context before sending to the LLM. This is especially important for monorepos and large projects where including all files would exceed context limits.

Available Modes

Setting Retrieval Mode

CLI (one-time):

magic-prompt --retrieval heuristic "add user auth"

Config (persistent):

# In TUI: Press Ctrl+R to cycle through modes
# Or edit ~/.config/magic-prompt/config.json:
{
  "retrieval_mode": "tfidf"
}

Working Principle

TF-IDF Mode (Hybrid):

• Computes TF-IDF vectors for all files based on path, docstrings, functions, and classes
• Blends TF-IDF similarity (5%) with heuristic scoring (95%)
• Produces relevance percentages shown in the LLM context (e.g., [95% relevant])

Heuristic Mode:

• Matches query keywords against file paths, function names, and class names
• Boosts exact path segment matches
• Considers file recency (recently modified files rank higher)

None Mode:

• Includes all scanned files up to max_files limit
• No filtering or ranking applied
• Use only for small projects where context fits

Recommendations

Configuration Options

{
  "retrieval_mode": "tfidf", // "tfidf" | "heuristic" | "none"
  "top_k_files": 20, // Max files to include in context
  "max_files": 5000, // Max files to scan (increase for monorepos)
  "max_depth": 8 // Directory traversal depth
}

License

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