PromptAstra
A system-tray prompt enhancer. Press a global hotkey anywhere on your computer to turn rough prompts into precise ones — works in any app where you can select text.
Built with Tauri 2 + Rust + React + TypeScript.
What it does
- Select rough prompt text in any app (Notepad, Brave, VS Code chat, terminal, anywhere).
- Press the global hotkey (default
Ctrl+Alt+E on Windows, Cmd+Option+E on macOS).
- PromptAstra captures the selection and runs the Smart Question Engine (see below). The result is pasted back over your selection.
Think Wispr Flow, but for written prompts to coding agents (Claude Code, Cursor, ChatGPT) instead of voice.
Two paths after the hotkey
PromptAstra scores the captured input for "enhancement ambiguity" and branches:
- Silent fast-path (
score < threshold, or question_mode = Silent, or Shift+hotkey): one LLM call, a small "Enhancing…" pill near your cursor, the enhanced text replaces your selection in ~2–3 seconds.
- Question-card path (
score ≥ threshold, or question_mode = Always ask): a 360px floating card appears with 2–4 chip questions about audience / tone / goal / constraints / format. Pick the most defensible answers (Enter submits, Escape skips, arrow keys navigate), and the enhanced prompt — informed by your answers — replaces your selection.
The card's questions are generated by a small Groq model (llama-3.1-8b-instant) in parallel with the window opening, with a hard 3-second budget. If generation fails, times out, returns fewer than 2 valid items, or malformed JSON, the card falls back to a domain-specific static question bank so you always see questions within the latency budget.
v1 status
| Phase | Status |
|---|
| 1 — Tray icon + Quit | done |
2 — Global hotkey (Ctrl+Alt+E) | done |
| 3 — Clipboard capture / replace | done |
| 4 — LLM integration (Groq + Llama 3.3 70B) | done |
| 5 — Floating "Enhancing…" status pill | done |
| 6 — Settings window (API key, hotkey rebind, test connection) | done |
| 7 — Smart Question Engine (scorer + LLM-generated question card + static fallback) | done |
| 8 — Cross-platform polish, code-signing, auto-update | partial / future |
The core round-trip works on Windows for both the silent fast-path (Ctrl+Alt+E on well-constrained inputs) and the question-card path (ambiguous inputs trigger a 360px chip card that gathers context before enhancement). macOS support exists in code but is untested. See docs/eval-protocol.md for the V1 quality eval that should be run before public ship.
Apps confirmed working on Windows
- Notepad (Windows 11)
- Brave (address bar, page text)
- VS Code chat panel (BLACKBOX AI / Claude Code extensions)
Apps known not to work / unconfirmed
The synthetic-input dispatch may be blocked by Electron-based apps that debounce or filter WM_KEYDOWN events. Running PromptAstra as administrator can sometimes work around UIPI-related blocks. To be expanded with real-world data once more users test it.
Setup
Prerequisites
- Windows 10/11 or macOS 12+ (Linux deferred to v2)
- Rust stable toolchain — install via rustup
- Node.js 20+ and npm
- Windows only: Visual Studio Build Tools 2022 with the "Desktop development with C++" workload (rustup will offer to install this for you)
- A Groq API key (free, no credit card) — get one at console.groq.com/keys
Install dependencies
The repository is split into three top-level folders:
| Folder | Contents |
|---|
frontend/ | The React/Vite desktop UI + all Node tooling (this is where you run npm commands). |
backend/ | The Rust/Tauri core (backend/src-tauri/), the system backend/prompts/, the Supabase cloud backend (supabase/), and scripts/. |
landing/ | The marketing/landing site deployed to Vercel (was web/). |
git clone https://github.com/Lakshmiyadav65/Perfectprompt.git
cd Perfectprompt/frontend
npm install
All npm / tauri commands are run from frontend/. The tauri script
transparently switches into backend/ to find the Rust project, and Tauri's
beforeDevCommand builds the frontend back in frontend/.
Provide your Groq API key
Create a .env file at the project root (or copy .env.example) and paste your key:
GROQ_API_KEY=gsk_your_key_here
The .env file is gitignored — your key never gets committed.
You can also set the key via the Settings window after launching the app — it gets stored in settings.json under the app's config directory (%APPDATA%\com.promptforge.app\ on Windows). The env var takes precedence if both are set.
Run in dev mode
cd frontend
npm run tauri dev
The first build is slow (~2 minutes — pulling and compiling Rust dependencies). Subsequent rebuilds are 5–30 seconds.
You should see:
- A small PromptAstra tray icon appear in the system tray.
- Console output:
[env] loaded …/.env and [hotkey] registered: CommandOrControl+Alt+E.
Use it
- Select some rough prompt text in any app (e.g., type
fix the dashboard in Notepad and select it).
- Press
Ctrl+Alt+E.
- Depending on how ambiguous PromptAstra thinks your input is:
- For specific inputs (e.g. "refactor the user service to use async/await instead of promise chains"): a small "Enhancing…" pill appears near your cursor, and your selection is replaced with the rewrite in 1–3 seconds.
- For ambiguous inputs (e.g. "fix the dashboard"): a 360px question card appears with 2–4 chip questions. Pick the most defensible answers (Tab between fields, arrow keys between chips, Space to select, Enter to submit, Escape to skip), and the enhanced prompt — informed by your answers — replaces your selection.
- Hold
Shift while pressing the hotkey to skip the card for a single invocation, regardless of mode.
Watching latency in dev mode
npm run tauri dev prints structured timing lines to the console — handy when measuring the PRD §12 targets:
[capture] 17 chars captured in 280ms
[pipeline] score=0.70 mode=Adaptive threshold=0.60 → card
[latency] card path hotkey→shown=420ms (PRD §12 target <600ms)
[latency] fetch_question_card_session ready in 1850ms (source=llm, 3 question(s), PRD §12 target <3s)
[clarify] submit_question_card_answers: 2 answer(s)
[latency] submit→pasted=2210ms (PRD §12 latency budget for the enhance call is 1.5–3s)
Fire the hotkey 10–20 times across a range of inputs and grep the dev console for [latency] lines to estimate p95. The full quality + latency eval protocol is in docs/eval-protocol.md.
Build a release binary
cd frontend
npm run tauri build
Output:
- Windows:
backend/src-tauri/target/release/perfectprompt.exe plus an MSI installer in backend/src-tauri/target/release/bundle/msi/.
- macOS:
.app bundle and .dmg in backend/src-tauri/target/release/bundle/.
The binary is not code-signed — Windows SmartScreen / macOS Gatekeeper will warn on first run. v1 ships unsigned by design; signing is deferred to v2.
How it works (architecture)
frontend/src/
├── components/
│ ├── StatusIndicator.tsx + .css ← Phase 5: floating "Enhancing…" pill (silent path)
│ ├── Settings.tsx + .css ← Phase 6: API key, hotkey, Smart Question Engine UI
│ └── QuestionCard.tsx + .css ← Phase 7: 360px chip card (Smart Question Engine)
└── App.tsx ← hash routing: #/status, #/settings, #/question-card
backend/src-tauri/src/
├── main.rs ← entry point
├── lib.rs ← plugin registration + setup hook + AppState
├── tray.rs ← Phase 1: system tray icon + menu
├── hotkey.rs ← Phase 2: registers main combo AND Shift-bypass combo
├── clipboard.rs ← Phase 3: capture/replace via Win32 SendInput
├── enhance.rs ← single LLM call (call_llm), bundled prompt loader
├── pipeline.rs ← orchestrator — Stages A→B→C→D→E→F
├── intake.rs ← Stage A: normalize, length gate, adversarial regex
├── cache.rs ← Stage B: LRU keyed on intake fingerprint
├── router.rs ← Stage C: domain + complexity + ambiguity → route
├── validate.rs ← Stage E: strip preambles/fences, reject bad output
├── trace.rs ← Stage F: JSONL log to <app_data>/traces/YYYY-MM-DD.jsonl
├── status_window.rs ← position pill near cursor
├── settings.rs ← persist & expose Tauri commands
├── question_bank.rs ← domain classifier + complexity scorer + static bank
├── generation.rs ← parallel LLM question generation (llama-3.1-8b)
└── clarify.rs ← question-card IPC + [CONTEXT] block assembly
backend/prompts/
├── code-enhancer.md ← system prompt for the Code route (~340 words)
├── writing-enhancer.md ← system prompt for the Writing route (~390 words)
├── generic-enhancer.md ← system prompt for the Generic route (~290 words)
└── questions-system-prompt.md ← dedicated prompt for parallel question generation
The capture/replace pipeline
When the user presses the hotkey:
-
Capture (clipboard.rs::capture_selection) — the trickiest part on Windows:
- Save the current clipboard contents.
- Plant a unique sentinel string on the clipboard so we can later verify whether the synthetic Ctrl+C produced a real copy.
- Poll
GetAsyncKeyState(VK_CONTROL) and GetAsyncKeyState(VK_MENU) for the user's hotkey modifiers to release. Real users hold the hotkey for 250–450 ms after pressing, and a fixed-time settle delay isn't long enough.
- Once both are released, call
SendInput directly (the Windows path bypasses enigo because Key::Unicode produces WM_CHAR, which doesn't trigger the Ctrl+C shortcut).
- Wait briefly for the OS clipboard to settle, then read.
- If the clipboard still contains our sentinel, the copy didn't happen — we surface a clear error.
- Restore the original clipboard contents.
-
Show indicator (status_window.rs) — show the "Enhancing…" pill near the cursor. Window is hidden until needed.
-
Pipeline (pipeline.rs) — runs the six-stage pipeline (intake → cache → router → LLM → validate → deliver). The LLM stage is a single call via enhance.rs::call_llm to Groq's OpenAI-compatible endpoint with a route-specific system prompt and the captured text wrapped in <input> tags. 30s timeout.
-
Replace (clipboard.rs::replace_selection) — write the enhanced text to the clipboard and synthesize Ctrl+V.
-
Hide indicator — fired in a finally-style branch regardless of success or failure.
Hard-won lessons
- Synthetic Ctrl+C requires real virtual-key events on Windows.
enigo's Key::Unicode('c') sends WM_CHAR (text input), not WM_KEYDOWN with VK_C. With Ctrl held, only the latter triggers a Copy shortcut. We bypass enigo on Windows and call SendInput directly.
- Modifier-release polling is non-negotiable. A fixed
tokio::time::sleep(250ms) looks fine in isolated testing but breaks for many real users who hold their hotkey for 300–500ms while reading the screen.
- Sentinel-based capture verification is essential. Without it, a failed synthetic Ctrl+C silently returns the previous clipboard contents, making it look like capture worked when it didn't.
Configuration
Settings window
Open via the tray menu → Settings.
- Groq API Key — paste your key, click Save. Stored in
settings.json.
- Test Connection — pings Groq with the active key (env or keychain). Reports round-trip latency.
- Global Hotkey — click the field, press your desired combo (e.g.,
Ctrl+Shift+Space), click Save. The new shortcut is registered immediately and persisted, along with its Shift+-modified bypass variant.
- Smart Question Engine:
- Mode:
Adaptive (default — show the card only when the complexity score crosses the threshold), Always ask (card on every hotkey), or Silent (never show the card, go straight to enhance + paste).
- Ambiguity threshold (only in Adaptive mode): slider 0.00–1.00. Lower = ask more often. Default 0.60.
- The privacy note links to Groq's data policy — question text, your answers, and the assembled
[CONTEXT] block are kept in memory only by PromptAstra, but they are sent to Groq as part of the LLM call.
Shift+hotkey bypass — hold Shift while pressing the hotkey to skip the card for a single invocation, regardless of mode. Same effect as Silent for that one call.
Settings storage location
Settings live in:
- Windows:
%APPDATA%\com.promptforge.app\settings.json
- macOS:
~/Library/Application Support/com.promptforge.app/settings.json
The file is plain JSON, only readable by the current user (standard file ACLs). Same security model as .env. Schema:
{
"hotkey": "CommandOrControl+Alt+E",
"api_key": "gsk_...", // omit / null to fall back to $GROQ_API_KEY
"question_threshold": 0.6, // [0.0, 1.0]; only used in Adaptive mode
"question_mode": "adaptive", // "adaptive" | "always_ask" | "silent"
"remembered_contexts": {} // reserved for V2 cross-session memory
}
Missing fields fall back to the defaults shown above, so older settings.json files keep loading.
The .env file overrides the saved API key when both are set — useful for development where you want the key in the project directory rather than the user-config directory.
The system prompts
The actual product lives in backend/prompts/. Everything else is plumbing.
Three route-specific prompts (one is loaded per LLM call by the orchestrator, based on the router's decision):
backend/prompts/code-enhancer.md — Code route. Rewrites rough coding requests into precise prompts for a coding agent. Tightens explicit asks; redirects vague verbs to "investigate first". Never invents filenames, libraries, or APIs.backend/prompts/writing-enhancer.md — Writing route (emails, blog posts, tweets). Dominant rule: placeholder discipline. Missing facts ({recipient_name}, {reasons_team_chose_postgres}, {company_one_liner}) stay as placeholders rather than getting invented.backend/prompts/generic-enhancer.md — catch-all route (summarise, translate, explain). Critical rule: never perform the task; only rewrite the request as a spec.
Plus one prompt for the parallel question-generation call:
backend/prompts/questions-system-prompt.md — emits 2–4 clarifying-question JSON for the question-card. Loaded by generation.rs; out of scope for the enhancement pipeline.
The Step 7 conflict resolution between the brief's "delete the old meta-prompt" rule and the "don't touch the parallel question-gen call" rule produced this dedicated questions prompt. See docs/migration-report.md for the full decision trail. docs/eval-protocol.md is the script to validate any rewrite empirically.
Known limitations (v1)
- Not code-signed. Windows SmartScreen and macOS Gatekeeper will warn on first run. Click "More info" → "Run anyway" on Windows; on macOS, right-click the app and choose Open.
- No auto-updates. New versions require manual redownload.
- No Linux support.
- macOS untested. Code paths exist (cursor positioning, Cmd+Option+E modifier) but no integration testing yet. The question-card window's focus model has not been verified on macOS — PRD §13 Q5 flags this as a release blocker.
- Quality eval not yet run. The Smart Question Engine ships with a heuristic scorer and a placeholder meta-prompt. docs/eval-protocol.md defines the 30-input rubric that should be run on real Groq calls before this is considered V1-shippable. The acceptance bar from PRD §13 Q3 has not yet been validated empirically.
- Free Groq tier limits. ~30 requests/minute on
llama-3.3-70b-versatile. The question card adds one extra llama-3.1-8b-instant call per non-silent invocation, so plan accordingly when running the eval.
- Persistent memory is V2. Session-scoped answer memory works (PRD §5.1.6), but it dies when the tray app exits. The
remembered_contexts field in settings.json is reserved for the V2 persistent variant.
- Some Electron / WinUI apps may block synthetic input. The pipeline surfaces a clear error message — you'll see "synthetic Ctrl+C produced no copy" in the dev console.
- Apps with sandboxed renderers may block the synthetic Ctrl+V even if Ctrl+C worked. Workaround: paste manually using the "Copy raw input" button surfaced in the card's error state.
Contributing
This is a personal project, but if you want to:
- Try it and report which apps it works in — open an issue with the app name + Windows version.
- Improve the meta-prompt — share rough prompts you typed into a coding agent recently; help us calibrate.
- Port the macOS path —
clipboard.rs has a non-Windows branch that uses enigo. Will need real testing on Apple Silicon and Intel.
License
Proprietary — All Rights Reserved. See LICENSE.
