Pup — A Prompt Engineering Toolkit

Build clean, structured prompts for Cursor, Copilot, Claude, ChatGPT and Gemini — without leaving your editor.

Install · Quick Start · Features · Why It Matters · Contributing

✨ Why Pup?

LLMs respond better to structured prompts — role, context, task, constraints, output format. Most developers freestyle into a chat window, get mediocre output, then iterate forever.

Pup is a form-based prompt compiler. Fill out sections → Pup compiles them into Markdown / JSON / XML / plain text. Save once, reuse forever. No accounts. No telemetry. No AI calls inside the extension.

[!IMPORTANT] Zero outbound requests. Zero API keys. Zero telemetry. Your prompts never leave your machine. Pup is a pure compiler — your prompt, your model, your editor.

🎯 Why Format Matters

Different model vendors are trained against different prompt structures. Matching the format their training data used measurably improves output quality. Pup compiles the same prompt into all four — pick the one your model prefers.

Vendor	Preferred Internal Format	Key Delimiters
Anthropic (Claude)	XML	`<tag>Content</tag>`
OpenAI (GPT-4 / GPT-5)	Markdown / JSON	`### Header`, `"""`, `{"key": "value"}`
Google (Gemini)	Markdown / JSON	`### Header`, structured JSON
Cursor / Copilot Chat	Markdown	`### Header`, fenced code

[!TIP] Targeting Claude? Switch the format dropdown to XML. Hitting the OpenAI API programmatically? Pick JSON. One toggle, no rewriting.

🚀 Features


🎯 Role-based presets	Bug Fix · New Feature · Refactor · Code Review · Research · Agentic Task · Custom
📝 Four output formats	Markdown · JSON · XML · plain text — switch with one click
🔍 `@`-mention any file	Fuzzy file picker inside any text field. Inserts path-only, ready for Cursor / Claude Code / Copilot Chat
📊 Live token counter	Char/word-blended estimator (±10–15%). Pick your model to see context-window usage in real time
💾 Round-trip save	Saves to `.prompts/` as `.md` with embedded frontmatter. Re-open via right-click → Open Selected .md as Prompt
🧪 Minimize hallucination	Optional toggle: appends an `<investigate_before_answering>` directive forcing the model to read referenced files before answering
🦴 Caveman mode	Optional toggle: appends a directive that strips filler from the model's reply (~75% fewer output tokens)
🌓 Native theming	VS Code CSS variables — dark / light / high-contrast all just work
🌐 Remote-ready	Works in Remote-SSH, Codespaces, dev-containers, virtual workspaces
🔒 Hardened	Strict CSP, deep-validated `postMessage`, sandboxed save path, symlink-safe

📦 Install

VS Code

code --install-extension alimalik.pup

Cursor

cursor --install-extension alimalik.pup

Or open the Extensions panel (Cmd/Ctrl+Shift+X), search Pup, click Install.

Marketplace listing: marketplace.visualstudio.com/items?itemName=alimalik.pup

Sideload from .vsix or build from source

# Sideload
pnpm install
pnpm run package
code --install-extension pup.vsix

# Develop
git clone https://github.com/alimalikali/pup-prompt-engineering-toolkit.git
cd pup-prompt-engineering-toolkit
pnpm install
pnpm run watch          # esbuild watch (host + webview)
# In VS Code: press F5 to launch the Extension Development Host

No pnpm? Enable Corepack: corepack enable pnpm.

🧭 Quick Start

Open the builder — Cmd/Ctrl+Shift+P → Pup: Open Builder
Pick a preset — e.g. Bug Fix. Sections come pre-populated with hint text.
Fill the sections — type @ inside any field to fuzzy-search workspace files.
Toggle format / model — preview updates live with token usage.
Copy or save — bottom action bar. Saved prompts round-trip on re-open.

That's it. No accounts, no logins, no setup.

📤 Output Formats

Pup compiles the same PromptDoc into any of four formats. Pick whichever your downstream tool likes best.

Markdown — readable, ideal for chat UIs and OpenAI

## Role
You are a senior TypeScript engineer.

## Context
Refactoring an Express API to Fastify.

## Task
Migrate `src/routes/users.ts` while preserving behavior.

## Constraints
- No new runtime dependencies
- Maintain the existing OpenAPI spec

XML — Anthropic / Claude friendly

<role>You are a senior TypeScript engineer.</role>
<context>Refactoring an Express API to Fastify.</context>
<task>Migrate src/routes/users.ts while preserving behavior.</task>
<constraints>
  - No new runtime dependencies
  - Maintain the existing OpenAPI spec
</constraints>

JSON — programmatic pipelines

{
  "role": "You are a senior TypeScript engineer.",
  "context": "Refactoring an Express API to Fastify.",
  "task": "Migrate src/routes/users.ts while preserving behavior.",
  "constraints": ["No new runtime dependencies", "Maintain the existing OpenAPI spec"]
}

Plain text — minimal, token-efficient

ROLE: You are a senior TypeScript engineer.
CONTEXT: Refactoring an Express API to Fastify.
TASK: Migrate src/routes/users.ts while preserving behavior.
CONSTRAINTS:
- No new runtime dependencies
- Maintain the existing OpenAPI spec

⌨️ Commands & Settings

Command	Description
`Pup: Open Builder`	Opens the prompt builder in a new editor tab
`Pup: Open Selected .md as Prompt`	Re-opens a saved prompt (right-click any `.md` inside `.prompts/`)

Setting	Default	Purpose
`pup.savedPromptsDir`	`.prompts`	Where saved prompts live (workspace-relative)
`pup.defaultOutputFormat`	`markdown`	Format used on first open
`pup.fileSearch.maxResults`	`20`	Max items in `@`-mention dropdown
`pup.fileSearch.excludeGlobs`	`node_modules`, `.git`, `dist`, `out`, `build`	Globs excluded from file search

🔒 Security

🛡️ Strict CSP — default-src 'none', scripts only via per-render nonce
🚪 Sandboxed save path — traversal-checked + symlink-safe via realpath
🧾 Deep message validation — every postMessage runs through isValidPromptDoc
📏 Bounded reads — openFromFile rejects files larger than 1 MiB
🌐 Cross-environment IO — uses vscode.workspace.fs.* everywhere
🔇 No telemetry, no network

Found an issue? Email rohan.codeller@gmail.com instead of opening a public issue.

🧪 Develop

pnpm install
pnpm run watch            # esbuild watch (host + webview)
pnpm run compile          # tsc --noEmit
pnpm test                 # node:test against shared + host validators
pnpm run package          # builds and writes pup.vsix

🗺️ Roadmap

[ ] Variable substitution ({{name}} → runtime fill)
[ ] Prompt linting (warn on missing role/task, oversized context)
[ ] Snippet library (community-shared .prompts/)
[ ] Multi-file context bundling
[ ] CLI companion for non-VS Code users
[ ] JetBrains port

Have a request? Open an issue.

🤝 Contributing

PRs welcome — typo fixes, new presets, roadmap items.

Before opening a PR: pnpm run compile && pnpm test && pnpm run build.

Three rules to keep in mind:

src/shared/ stays pure TypeScript (no vscode, no node built-ins, no DOM).
Every host↔webview message goes through the unions in src/shared/types.ts.
New logic in src/shared/ or src/host/validate.ts ships with a test.

📜 License

If Pup saves you time, ⭐ star the repo — helps others find it.

Pup - A Prompt Engineering Toolkit

Ali Malik