⚡prompt-pilot
v0.4.0 MIT License No server · no binary · no MCP

Stop shipping rough prompts.
Ship precise ones.

PromptPilot turns rough, vague prompts into precise, context-enriched prompts — inside your AI coding agent session. Read-only exploration, real @file/paths, and a human checkpoint before anything runs.

Install → View on GitHub

01 · The problem

"buggy login thing fix it"

AI coding agents are only as good as the prompts they receive — and most real-world prompts look like that. When an agent gets a vague prompt, three things go wrong:

ERR_01

It guesses.

Without concrete file paths or symbol names, the agent explores blindly, often lands on the wrong files, and confidently implements the wrong fix.

ERR_02

Context is wasted.

Searching and implementing happen in one long session — a large share of the context window is burned on exploration before any real work starts, degrading the quality of the actual change.

ERR_03

There is no checkpoint.

The agent jumps straight from vague words to code changes; you never get to confirm what it is about to do before it does it.

The obvious cure — writing a precise prompt yourself — requires already knowing which files, functions, and constraints are involved. That is exactly the knowledge you were hoping the agent would dig up for you.

02 · How it works

Separate understanding from acting

The implementation run starts from precise, verified context instead of guesses: fewer wrong turns, fewer wasted tokens, and a human checkpoint on intent before any code changes.

1

Explore, read-only

The agent — delegating to a subagent where the platform supports it, keeping the main context clean — investigates the codebase with read-only tools. No edits, no commands.

2

Rewrite

Your rough prompt is restructured into WHAT / WHERE / HOW / CONSTRAINTS / VALIDATION, with real @file/paths and concrete symbols woven in.

3

Approve, then run

The optimized prompt is shown to you first. Nothing executes until you reply run — or you refine it with follow-up notes and it is re-optimized.

Before — what you type

"buggy login thing fix it"

After — what the agent gets

WHAT fix session-expiry bug in login flow WHERE @src/auth/login.ts @src/auth/session.ts HOW guard refreshToken() for expired sessions; reuse AuthError type CONSTRAINTS don't touch token storage format VALIDATION auth test suite green

// illustrative example — the real output is built from your codebase

03 · Features

Pure instructions, real guarantees

Pure-instruction command

No server, no binary, no MCP. The command is plain instructions — your agent's own tools do all the work.

Read-only guarantee

Exploration uses Read/Grep/Glob only. PromptPilot never implements the task itself — it only rewrites the prompt.

Clean main context

Exploration is delegated to a subagent where the platform supports it, so file reads never pollute your main conversation context.

@path seeding

@path mentions in your prompt seed the exploration; without them, relevant files are inferred from keywords.

Multi-agent support

Ships as a Claude Code plugin and as native custom commands for Codex CLI, OpenCode, Gemini CLI, and Cursor.

Human approval checkpoint

The optimized prompt is a proposal, not an action. You reply run to execute — or iterate on it first.

04 · Install

Three ways in

Claude Code plugin

Two commands, run one at a time. First add the marketplace:

/plugin marketplace add savasturkoglu1/promptpilot-plugin

Then install the plugin:

/plugin install prompt-pilot@promptpilot

Then just use it:

/prompt-pilot "buggy login thing fix it"

Codex skill

No clone needed — installed as a skill, works in the CLI, IDE extension and desktop app.

mkdir -p ~/.agents/skills/prompt-pilot
curl -fsSL https://raw.githubusercontent.com/savasturkoglu1/promptpilot-plugin/main/agents/codex/prompt-pilot/SKILL.md -o ~/.agents/skills/prompt-pilot/SKILL.md

Then in Codex:

$prompt-pilot "buggy login thing fix it"

Other agents script

OpenCode · Gemini CLI · Cursor — clone the repo, run the installer (it covers Codex too).

git clone https://github.com/savasturkoglu1/promptpilot-plugin.git
cd promptpilot-plugin
scripts/install-agents.sh

Or pick agents / install into the current project only:

scripts/install-agents.sh codex opencode     # only these
scripts/install-agents.sh --project          # .agents/ .opencode/ .gemini/ .cursor/ in cwd
AgentInstalled toInvoke
Codex (CLI · IDE · desktop)~/.agents/skills/prompt-pilot/SKILL.md$prompt-pilot <rough prompt>
OpenCode~/.config/opencode/command/prompt-pilot.md/prompt-pilot <rough prompt>
Gemini CLI~/.gemini/commands/prompt-pilot.toml/prompt-pilot <rough prompt>
Cursor~/.cursor/commands/prompt-pilot.md/prompt-pilot <rough prompt>

05 · Usage & flags

One command, eight flags

Flags can appear anywhere in the prompt and can be combined. Every approved prompt is logged to your prompt history.

/prompt-pilot "make the parser faster"
/prompt-pilot "add error handling to @src/auth/login.ts"
/prompt-pilot "hata yönetimi ekle -turkce"
/prompt-pilot "refactor the auth flow -plan -safe"
/prompt-pilot "fix the login bug and add dark mode -split"
Language flag

Choose the output language of the optimized prompt:

  • -turkce / -dutch / any language name → rewrite in that language
  • -o → keep the original prompt's language
  • no flag → English (best results with coding agents)
-loop flag

Appends a LOOP HARNESS section to the optimized prompt:

  • a measurable exit condition
  • a verify-fix iteration loop with objective checks
  • a bounded iteration budget & explicit stop conditions
  • an honest exit report

Use it for tasks like "make all tests pass" where one-pass execution isn't enough.

-plan flag

Appends a PLAN GATE section to the optimized prompt:

  • a file-by-file implementation plan before any edit
  • an approval gate — nothing runs until you say so
  • no silent deviation from the approved plan
-safe flag

Appends a SAFETY RAILS section to the optimized prompt:

  • minimal diff — no drive-by refactors
  • no new dependencies, no destructive operations
  • reversible changes; stop-and-ask on ambiguity
-quick flag

Skips codebase exploration entirely:

  • no subagent, no file reads
  • fixes language and structure only
  • for prompts that don't depend on the codebase
-ask flag

Clarify before optimizing:

  • up to 3 short questions when the prompt leaves open decisions
  • answers become explicit requirements in the rewritten prompt
  • without it, assumptions are stated inside the prompt instead
-split flag

One rough prompt, several tasks:

  • splits bundled tasks into self-contained optimized prompts
  • one parallel subagent per task, ordered by dependency
  • reply run for all in order, or run 2 for one
-issue flag

Rewrites the prompt as a GitHub issue:

  • title, context, task, constraints, acceptance-criteria checklist
  • run → execute locally · publish → open the issue on your remote via gh
  • hand precise work to your team instead of running it yourself
Prompt history

Always on — no flag needed:

  • every approved prompt is appended to .promptpilot/history.md
  • a reusable log of your best prompts (date · raw · optimized)
  • ask "show my prompt history" to list past entries