prompy

Prompy

Minimal, non-blocking prompt improvement for Claude Code. Grades your prompts on 5 dimensions, detects the use-case, and either nudges you (co-pilot) or silently rewrites and annotates (auto-pilot) — all in one inline line per intervention.

Strong prompts pass through untouched. Weak prompts get a single-line note. The full report card is one slash command away when you want it.

---

What it does

Every time you submit a prompt to Claude Code, Prompy silently:

1. Scores the prompt on 5 dimensions (Clarity, Specificity, Context, Actionability, Mode-fit)
2. Detects the use-case (coding / writing / creative / strategy / other)
3. Decides whether to intervene based on the grade and your mode

Then, in one line at the top of Claude's response:

Co-pilot mode (default)

✦ Prompy [co-pilot] — C: Specificity 2/5 — no file or expected behavior named. Improved: "In src/auth/login.ts, fix the JWT expiry check so it throws AuthError when verification fails." — Run improved (y/enter), use original (n), or edit?

Reply y to run the improved prompt, n to use the original, or edit [changes] to refine.

Auto-pilot mode

✦ Prompy [auto-pilot] — rewrote "fix the bug…" → enriched (added file: src/auth/login.ts, expected behavior). Type "use original" to revert.

[Claude's response continues, answering the improved version]

Zero approval friction. If the rewrite missed, just type use original.

Strong prompts pass through silently

If your prompt grades A or B (75+/100), Prompy stays silent and Claude responds normally. No trace, no overhead, no Prompy mention.

---

Three modes

Mode	What happens on weak prompts	What happens on strong prompts
co-pilot (default)	One-line nudge + improved version, waits for y/n/edit	Silent passthrough
auto-pilot	One-line trace + silent rewrite, runs improved version	Silent passthrough
off	Nothing — hook is disabled entirely	Silent passthrough

The deep-dive /prompy:prompy skill works in all three modes.

---

Install

In Claude Code, run:

/plugin marketplace add navarroangelo/prompy
/plugin install prompy@prompy
/reload-plugins

Then quit Claude Code (Cmd+Q on macOS) and relaunch. The SessionStart hook activates on the next launch.

Requirements

• Claude Code installed
• python3 on PATH (used by the hook for JSON encoding)
• bash (default on macOS and Linux)

For contributors (local development)

git clone https://github.com/navarroangelo/prompy ~/Dev/prompy

Then point Claude Code at the local clone:

/plugin marketplace add ~/Dev/prompy
/plugin install prompy@prompy
/reload-plugins

Edits to ~/Dev/prompy/ are picked up on the next Claude Code restart.

---

Usage

Automatic (the main interface)

Just use Claude Code normally. Prompy runs in the background and surfaces only when a prompt scores C or below.

Switching modes

/prompy:mode auto-pilot    # silent rewrites + annotation
/prompy:mode co-pilot      # one-line nudge with approval (default)
/prompy:mode off           # disable the hook
/prompy:mode               # show current mode

The mode persists across sessions (stored in ~/.claude/prompy-mode).

Deep-dive on demand

When you want the full report card and edit-iteration loop:

/prompy:prompy fix the bug
/prompy:prompy --writing write a welcome email
/prompy:prompy

The deep-dive shows a fenced before/after report card with what changed, why each change traces to a Claude prompting principle, and one transferable lesson.

Bypass

Prefix your prompt with * to skip Prompy entirely for that one message:

* this is intentionally vague, just do your best

---

Configuration

You can override the mode for the current shell session with an env var:

export PROMPY_MODE=auto-pilot   # overrides ~/.claude/prompy-mode

Precedence: PROMPY_MODE env var → ~/.claude/prompy-mode file → default (co-pilot).

---

The 5 scoring dimensions

1. Clarity — Is the ask unambiguous?
2. Specificity — Are constraints, scope, and target named?
3. Context — Does the prompt bring necessary background?
4. Actionability — Can Claude act without follow-up questions?
5. Mode-fit — Is the prompt structured right for its use-case?

Each scores 1–5; weighted by use-case to produce a 0–100 grade. See skills/prompy/references/scoring-rubric.md for the full rubric.

---

The 5 use-cases