Prompt Studio

AI-powered prompt engineering workbench — analyze, score, optimize, and store prompts with a terminal-style UI and a FastAPI backend backed by PostgreSQL + pgvector.

Overview

Prompt Studio gives you a structured workflow for writing better prompts:

• Analyze — paste a prompt and get instant feedback on structure, clarity, and completeness
• Score — 7-dimension quality breakdown with a letter grade
• Optimize — rule-based improvement pass that adds missing persona, format, example, and constraint directives
• Compress — strip filler tokens without losing semantic content
• Token counter — estimate input/output tokens and per-call USD cost across 7 models
• Context map — see how your prompt fits across every supported model's context window
• Model compatibility — cross-model evaluation matrix with format adaptation notes
• Adaptive wizard — 7-question guided flow that auto-generates a well-structured prompt
• History — persistent session history backed by PostgreSQL; semantic search via pgvector
• Lean persona layer — ponytail-style prompt injection: one SKILL.md, mode-filtered (lite/full/ultra), served through per-provider adapters with Anthropic prompt-cache markers
• lean-mcp — MCP stdio server exposing the same ruleset as a prompt + tool for MCP hosts
• Benchmarks — Python harness comparing baseline / caveman / lean-{lite,full,ultra} arms across LOC, tokens, cost, latency

Quickstart

Local (no Docker)

Backend

pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
# API docs → http://localhost:8000/docs

Frontend

cd frontend
npm install
npm run dev
# UI → http://localhost:3000

The frontend works fully offline — all scoring, issue detection, and wizard generation fall back to local TypeScript implementations when the API is unreachable.

Docker (full stack)

# Start PostgreSQL (pgvector), API, and Next.js frontend
docker compose -f docker-ignore.yml up --build

# API    → http://localhost:8000
# UI     → http://localhost:3000
# DB     → localhost:5432

Migrations run automatically on API container startup (alembic upgrade head). Manual migration commands live in CONTRIBUTING.md.

API Reference

Scoring Dimensions

Each prompt is evaluated across 7 dimensions (0–100), producing an overall score and a letter grade (A–F):

Prompt Modes

Supported Models

Lean Persona Layer

Prompt-Studio ships a ponytail-inspired Lean persona (skills/lean/SKILL.md) that reduces LLM output size, cost, and latency. One source of truth, filtered per intensity by app/services/skills.py::get_lean_instructions(mode) and injected in the system slot by per-provider adapters in app/services/formats.py.

from app.services.formats import build_messages

msgs = build_messages(
    text="Write a Python function that validates emails.",
    model_id="claude-3-5",
    intensity="full",   # "lite" | "full" | "ultra"
)
# msgs[0] → system slot with LEAN persona + cache_control: ephemeral
# msgs[1] → user turn

The system slot is marked cache_control: ephemeral so the persona charges once per Anthropic prompt-cache TTL, not per turn. If SKILL.md cannot be read, a hardcoded fallback ships instead — the layer never fails silent.

lean-mcp

Standalone MCP stdio server (lean-mcp/) that serves the same Lean ruleset for MCP hosts whose only injection point is the prompt menu.

cd lean-mcp && pip install -e .
python server.py

Client config:

{ "mcpServers": { "lean": { "command": "python", "args": ["lean-mcp/server.py"] } } }

Exposes prompt lean and tool lean_instructions, both accepting mode. Zero drift with the FastAPI adapters — both call get_lean_instructions().

Benchmarks

benchmarks/ measures the Lean persona's impact on LOC / tokens / cost / latency across five arms: baseline, caveman, lean-lite, lean-full, lean-ultra.

# Local, no API key
python benchmarks/benchmark.py --backend ollama --model llama3.2 --repeat 3

# Anthropic
ANTHROPIC_API_KEY=sk-ant-... python benchmarks/benchmark.py \
    --backend anthropic --model claude-haiku-4-5-20251001 --repeat 5

Includes the standard five tasks (email, debounce, csv-sum, countdown, rate-limit) plus two Prompt-Studio-specific tasks that exercise the per-provider adapters (chatml2xml, cost-est). Agentic sub-harness (benchmarks/agentic/) runs the arms as full Claude Code sessions against a real repo.

Statusline (optional)

Show the active Lean level in your Claude Code statusline. A plugin can't self-register a statusline, so point ~/.claude/settings.json at the script:

{ "statusLine": { "type": "command", "command": "bash /ABS/PATH/hooks/lean-statusline.sh" } }

Windows: pwsh -File C:\ABS\PATH\hooks\lean-statusline.ps1. It prints [LEAN] for full, [LEAN:LEVEL] otherwise (amber for ultra), and stays silent when Lean is off. It reads the same project-scoped .lean-active flag the hooks write.

Install as an Agent Plugin

Prompt-Studio ships adapters for the major agent hosts. Each one injects the Lean persona from the same skills/lean/SKILL.md — one source of truth, zero drift across hosts.

The Python hooks (hooks/lean_*.py) run on SessionStart, SubagentStart, and UserPromptSubmit, so python3 needs to be on PATH. Nix/nvm users: it must be on the non-interactive shell's PATH too.

Claude Code

/plugin marketplace add utk2103/Prompt-Studio
/plugin install prompt-studio@prompt-studio

Two separate prompts. Start a new session; the ruleset lands in system context on SessionStart.

Local clone:

/plugin marketplace add /path/to/Prompt-Studio
/plugin install prompt-studio@prompt-studio

Codex

codex plugin marketplace add utk2103/Prompt-Studio
codex plugin add prompt-studio@prompt-studio

Run codex, open /hooks, trust the two lifecycle hooks, start a new thread. Same install covers the Codex desktop app after restart.

GitHub Copilot CLI

copilot plugin marketplace add utk2103/Prompt-Studio
copilot plugin install prompt-studio@prompt-studio

Or the slash equivalents inside an interactive Copilot session:

/plugin marketplace add utk2103/Prompt-Studio
/plugin install prompt-studio@prompt-studio

Copilot CLI namespaces plugin commands: /prompt-studio:lean ultra, /prompt-studio:compress <path>.

Devin CLI

devin plugins install utk2103/Prompt-Studio

Skills expose as /prompt-studio:lean, /prompt-studio:compress, etc.

Qoder

# per-project
cp -r .qoder /path/to/your-project/

Qoder auto-loads AGENTS.md and .qoder/rules/*.md as always-on context. For full plugin-tier support (auto mode activation + ruleset injection on every prompt), add the hooks from hooks/qoder-hooks.json to your .qoder/settings.json and set PROMPT_STUDIO_DIR to the checkout path.

Cursor / Windsurf / Cline / Aider / Kiro / Zed (instruction-only)

Copy the rules file into the target host's rules directory:

cp .cursor/rules/*.mdc /path/to/project/.cursor/rules/       # Cursor

For Windsurf / Cline / Kiro, drop skills/lean/SKILL.md at:

• Windsurf: .windsurf/rules/lean.md
• Cline: .clinerules/lean.md
• Kiro: .kiro/steering/lean.md (or ~/.kiro/steering/ global)

These paths keep always-on guidance; they don't add mode switches or hooks.

JetBrains / VS Code Copilot Chat / Amp / Jules / CodeWhale / Antigravity

All read AGENTS.md from the repo root. Running from a Prompt-Studio checkout works with no setup. For a global install, drop the file at ~/.copilot/copilot-instructions.md (Copilot Chat) or the equivalent home path per host.

Slash commands (all hosts that support skills)

Short form (/lean lite, stop lean) also works — the UserPromptSubmit hook parses the raw prompt even when the slash-command menu doesn't recognize the un-namespaced form.

Mode persists in ~/.claude/.lean-active across turns. Subagents spawned via Task inherit the ruleset through the SubagentStart hook — no drift.

Troubleshooting

• /lean shows "command not found" → use /prompt-studio:lean; the short form works if you submit it as a plain message.
• Hooks don't fire → confirm python3 is on PATH (which python3).
• Nothing in system context after SessionStart → run python3 hooks/lean_activate.py from the plugin dir; if it prints the ruleset, the manifest is wired correctly and the issue is at the host's hook layer.

Uninstall

Then rm -f ~/.claude/.lean-active to clear the mode flag.

Versioning

SemVer 2.0.0 across the monorepo. All seven version-carrying files ship in lockstep — the API, frontend, Claude Code plugin, Codex adapter, Devin adapter, Qoder adapter, and MCP server all share one version.

pdm run check_versions   # verifies alignment

Bump workflow: edit all seven files, git tag vX.Y.Z, push. See scripts/check_versions.py.

Database Schema

Two tables, managed by Alembic:

prompts — full prompt records with vector embeddings

• Stores prompt text, mode, model, all 7 score dimensions, issues JSON, recommendations JSON
• embedding column — vector(1536), populated when an embedding model is wired in
• ivfflat cosine index for approximate nearest-neighbour semantic search

history — lightweight session entries

• Preview text, mode, model, overall score
• FK to prompts.id for drill-down

Embedding dimension defaults to 1536 (OpenAI text-embedding-3-small). Change EMBEDDING_DIM in app/db/models.py and generate a new migration to use a different model (e.g. 384 for all-MiniLM-L6-v2).

Environment Variables

Create a .env file at the project root:

DATABASE_URL=postgresql://promptstudio:promptstudio@localhost:5432/promptstudio

FAQ

Can I use it with caveman? Yes. Caveman compresses what the agent says; Lean shrinks what it builds. No overlap — Lean stays out of your prose, Caveman leaves code byte-for-byte exact.

Does it need a config file? No. ~/.claude/.lean-active is written by the hook itself; nothing else is required.

Which hosts support the mode switch? Any host with SessionStart + UserPromptSubmit hook events: Claude Code, Codex, Copilot CLI. Cursor / Windsurf / Cline / Kiro get the always-on ruleset but not the runtime mode knob.

Where does the persona actually live? skills/lean/SKILL.md. Everything else — plugin, MCP, benchmark arms, FastAPI adapters — reads from that one file via app/services/skills.py::get_lean_instructions().

How do I bump the version? pdm run check_versions first to confirm alignment, edit all seven files (three JSON adapter manifests, three TOML/JSON project files, one frontend package.json), tag vX.Y.Z.

Lean Plugin Deep Dive

How the Lean plugin actually activates, where it stores state, and known bugs.

Activation flow (Claude Code / Codex host)

Plugin manifest: hooks/claude-codex-hooks.json. Three hook events wired:

Ruleset text comes from a single source: skills/lean/SKILL.md, filtered per-mode by app/services/skills.py::get_lean_instructions(mode). The plugin, the lean-mcp server, and the FastAPI adapters (app/services/formats.build_messages) all call the same builder — zero drift.

Mode lifecycle for a single prompt:

user types "/lean ultra"
        ↓
Claude Code fires UserPromptSubmit hook with JSON on stdin
        ↓
lean_mode_tracker.py:
  read_stdin_json() → {"prompt": "<command-name>/lean</command-name>..."}
  _unwrap() reconstructs "/lean ultra"
  _CMD regex matches → arg = "ultra"
  write_mode("ultra")          # persists to state file
  emit_prompt_submit(
     systemMessage="LEAN MODE → ultra",
     additionalContext=get_lean_instructions("ultra")
  )
        ↓
Claude Code merges additionalContext into this turn's system context

Next session, SessionStart reads the same flag and re-emits the ruleset — no manual reactivation required in the ideal case.

State / "history" storage

There is no session history log. The plugin persists only the current mode as a single flag file.

Path (from hooks/_lean_common.py):

{CLAUDE_STATE_DIR | CLAUDE_CONFIG_DIR | ~/.claude}/.lean-active-<sha1(project)[:8]>

Where <project> is the first non-empty of CLAUDE_PROJECT_DIR, then PWD. If neither is set, the suffix is omitted and the flag becomes global (~/.claude/.lean-active). This per-project scoping (ponytail #662) exists so concurrent sessions in different repos do not clobber each other's mode.

File contents: literal string, one of lite, full, ultra, off. Max 64 bytes. Written atomically (O_CREAT|O_EXCL temp + os.replace) with mode 0600. Reader refuses symlinks and oversize files (silent fall through to default). Default when the flag is missing or invalid: value of LEAN_DEFAULT_MODE env var if valid, otherwise full.

"Off" is stored as the literal string off rather than deleting the flag — so stop lean persists across new sessions (#488). To fully reset: rm -f ~/.claude/.lean-active*.

Conversation history, previous prompts, or per-turn diffs are not recorded anywhere by this plugin. If you want that, it does not currently exist.

Bug 1 — token savings display (FIXED)

Was: no /lean-stats command, no skill, no wired hook. hooks/lean_usage_probe.py was a self-labeled TEMP probe never registered in claude-codex-hooks.json.

Fix: hooks/lean_stats.py reads the current session's JSONL transcript (from session_id/transcript_path in the hook payload, or the most-recent file under ~/.claude/projects/<slug>/) and aggregates message.usage.{input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens}. lean_mode_tracker.py recognises /lean-stats (raw or via <command-name> envelope) and emits the formatted stats as a systemMessage. commands/lean-stats.toml registers the slash command. Estimated savings use the Lean-vs-baseline output-token median from benchmarks/ (~65%) — shown as an estimate, not a per-session measurement.

Example output:

LEAN STATS (full) — session 088f0104
  Turns:              143
  Input tokens:       4,977
  Cache read:         13,818,871
  Cache creation:     1,013,683
  Output tokens:      458,928
  Est. output saved:  ~852,295 (baseline ~1,311,223, benchmark median 65%)

Trigger with /lean-stats or /prompt-studio:lean-stats. Self-check: python3 hooks/lean_stats.py.

Bug 2 — reactivation required after logout/login (FIXED)

Was: two contributing causes.

1. Non-stable project key. _project_scope() hashed the raw CLAUDE_PROJECT_DIR/PWD. Symlinks, trailing slashes, and Finder-vs-terminal launches all produced different hashes for the same repo, so the flag lookup missed and fell back to default full.
2. Write-back of the default. lean_activate.py called write_mode(read_mode()) unconditionally on SessionStart. When the read fell back to default full because of reason (1), that default got persisted under the new drifted hash key — orphaning the user's real ultra under the old key.

(Host-level plugin state loss on account switch is a Claude Code UX issue and outside this repo's scope. Recovery there is /plugin marketplace add ... + /plugin install ... again.)

Fix:

• hooks/_lean_common.py::_project_scope() now normalizes via os.path.realpath() and strips trailing separators before hashing. All three of /repo, /repo/, and /symlink-to-repo collapse to one key.
• hooks/_lean_common.py::read_mode() now checks the project-scoped flag first, then falls through to the global ~/.claude/.lean-active. Any pre-normalization or ambiguous-cwd preference is still honoured.
• hooks/_lean_common.py::has_persisted_mode() (new) reports whether either flag file actually exists on disk.
• hooks/lean_activate.py now only calls write_mode() when has_persisted_mode() is true. On a fresh launch nothing is written — the ruleset is still injected, but the default no longer pins a drifted key.

Long-term follow-up: a committable .lean.toml in the project root would survive host-level state loss entirely. Not built yet — YAGNI unless the host-state problem recurs after these fixes.

Diagnostics

Quick checks to run when Lean seems inactive:

# Is the flag file present and what does it contain?
ls -la ~/.claude/.lean-active*
cat ~/.claude/.lean-active* 2>/dev/null

# Does the SessionStart hook produce output when run directly?
python3 hooks/lean_activate.py

# Simulate a /lean ultra prompt through the tracker.
echo '{"prompt": "/lean ultra"}' | python3 hooks/lean_mode_tracker.py

# What project hash is the current shell computing?
python3 -c "import hashlib, os; p=os.environ.get('CLAUDE_PROJECT_DIR') or os.environ.get('PWD'); print(hashlib.sha1(p.encode()).hexdigest()[:8], p)"

If lean_activate.py prints the full ruleset, the plugin code is fine — the issue is at the host's hook wiring or plugin registration.

Contributing

See CONTRIBUTING.md.

License

Apache License — see LICENSE.