PromptForge

A runtime that executes AI prompt pipelines defined in a single markdown file. The markdown is the program, the model is the CPU. YAML frontmatter for metadata, embedded Lua for logic, prose blocks for model instructions, and a credential-holding gateway that keeps vendor keys off the prompt process. Write a prompt, run it, get a result.

What you get

• 📄 Markdown prompts - frontmatter, one H1, H2 sections that run top to bottom
• 🔧 Lua control - bind tools and models, compute values, write the store, fan out work
• 🌐 Tools that ship - local web_fetch, gateway-backed web_search, semantic capability binding
• 🔌 Inference gateway - OpenAI-shaped chat, bearer auth, catalog at GET /v1/models
• 🛰️ MCP server - run prompts from an agentic harness over streamable HTTP or stdio

Quick example

---
name: greet
description: Greet the named input using a Lua-computed value
promptforge: 1
---

# Greet

```lua
models.always("writer", "A model suited for careful analysis, coding, and general assistance")
```

## Main

```lua
var.greeting = "Hello, " .. args .. "!"
```

Repeat exactly, with no extra words: {{ var.greeting }}

Prose goes to the model. Lua sets up the turn. The response is the run's result.

Quick start

cargo install promptforge-cli promptforge-gateway
promptforge-gateway serve gateway.toml &
promptforge run prompts/hello.md

Building from source:

git clone git@github.com:cppalliance/promptforge.git
cd promptforge
cargo build

The first build downloads the tool picker's embedding model (~130MB from Hugging Face, pinned and checksummed). Later builds reuse the cache.

Two processes: the gateway holds the vendor credential; the client points at it.

export ANTHROPIC_API_KEY=sk-ant-...
export PROMPTFORGE_GATEWAY_KEY=dev-secret
cargo run -p promptforge-gateway -- serve gateway.toml &

export PROMPTFORGE_GATEWAY_URL=http://127.0.0.1:8081/v1
cargo run -p promptforge-cli -- run prompts/hello.md

Interactive prompt work against an already-running gateway:

cargo run -p promptforge-dev -- prompts/greet.md "world" --watch

How it works

Parse a promptforge markdown file, bind the tools and models it needs, then execute each H2 section in order. Section Lua prepares state; prose becomes a model turn (with a tool loop when tools are in scope); results land in the store or become the run output.

flowchart LR
  MD[Markdown prompt] --> Parse[Parse and bind]
  Parse --> Sec[H2 sections]
  Sec --> Lua[Lua prologue]
  Lua --> Model[Model turn]
  Model --> Tools[Tools via gateway or local]
  Model --> Store[Store artifacts]
  Store --> Out[Run result]

Loading

Crates

Crate	Description	crates.io
promptforge-core	Parser, executor, Lua runtime, store, gateway client
promptforge-cli	promptforge run command-line binary
promptforge-gateway	Inference gateway with model catalog and credential isolation
promptforge-mcp-server	MCP server for agentic harnesses (Cursor, Claude Code)
promptforge-tool-picker	Semantic tool resolution via sentence embeddings
promptforge-webfetch	SSRF-safe web fetch tool for model-supplied URLs
promptforge-dev	Interactive prompt development with watch mode

Documentation

• PromptForge User Guide - full documentation
• User Guide source - progressive tutorial for writing prompts
• DEVELOPMENT.md - gateway config, store API, architecture, dev workflow
• design-core.md - core design notes

Minimum Rust Version

Rust 1.89 or later.

Contributing

Build, format, and test before you open a PR. CI runs cargo fmt --check, clippy -D warnings, and cargo test --workspace. See DEVELOPMENT.md for details.

License

Distributed under the Boost Software License 1.0.