promptforge

A compiler for the text you reuse. Your prompts and snippets live as plain markdown files. promptforge gives them variables with defaults, file injection, and composition, then renders the finished text to your clipboard. You stop re-typing the same context for every agent or task, and you stop paying tokens to rebuild it. No dependencies, no AI.

It is closer to a small build system for prompts than a snippet box. One prompt can include another, pull in the contents of a file, and fill in variables at the moment you use it.

Install

npm install -g @bobfromarcher/promptforge
# the command is pf (promptforge also works)

A two-minute tour

# create a reusable header, reading the body from stdin
echo "You are reviewing for {{project|de Montfort LLC}}." | pf add preamble

# create a prompt that composes the header and injects a file
pf add code-review --tag dev,review
# body:
#   {{include preamble}}
#
#   Review this {{lang|JS}} file for bugs and simplifications:
#
#   {{file {{path}}}}

# compile it and copy the result to the clipboard
pf use code-review --var path=src/auth.js --var lang=TypeScript

The clipboard now holds the header, the instruction with TypeScript filled in, and the full contents of src/auth.js. Paste it wherever you work.

Template syntax

| Token | Meaning | | --- | --- | | {{name}} | A variable, supplied with --var name=value | | {{name\|default}} | A variable with a fallback if you do not pass one | | {{include other}} | Compose another stored prompt, recursively | | {{file ./path}} | Inject a file's contents. The path may itself use {{vars}} | | {{date}}, {{date iso}}, {{date time}} | The current date or time |

Cycles between includes are detected, and any variable you forget is reported so nothing renders silently wrong.

Commands

| Command | What it does | | --- | --- | | pf ls [--tag t] | List prompts | | pf find <query> | Fuzzy search by name, tag and description | | pf show <name> | Print a prompt with its frontmatter | | pf add <name> [--tag a,b] [--desc "..."] | Create from stdin or $EDITOR | | pf edit <name> | Open in $EDITOR | | pf rm <name> | Delete | | pf vars <name> | List the variables a prompt needs | | pf use <name> [--var k=v ...] [--print] | Compile and copy to the clipboard | | pf stats | Your most-used prompts | | pf where | Print the store directory |

Where it lives

Prompts are markdown files in ~/.promptforge (override with PROMPTFORGE_DIR). Because they are plain files, you can keep the directory in a git repo or a synced folder and carry your whole library between machines.

Clipboard support uses clip on Windows, pbcopy on macOS, and wl-copy, xclip or xsel on Linux. With --print it writes to stdout instead, so it pipes anywhere.

Development

git clone https://github.com/bobfromarcher/promptforge
cd promptforge
node test/test.js

The frontmatter parser, the template engine and the argument parser are all pure functions with the resolvers injected, so the compiler is fully tested without touching the filesystem. CI runs on Node 18, 20 and 22 across Linux, macOS and Windows.

License

MIT, bobfromarcher.