PromptX

The Prompt-as-Code Specification
Where natural language meets programming. Where the AI is the runtime.

🚀 Try It Now • Specification • Quick Start • Samples • Primitives • Patterns • Contributing

---

Try It in 30 Seconds

No setup. No installation. No account needed.

1. Open any file in ready-to-run/
2. Copy the entire contents
3. Paste into Claude, ChatGPT, Gemini, or any capable AI — and press send

That's it. Here are some to start with:

Want to...	Use this
Draft an email in 3 different tones	email-drafter.promptx
Turn messy meeting notes into action items	meeting-notes.promptx
Get a 30-day learning plan for any skill	learning-plan.promptx
Evaluate your startup idea from 5 expert angles	startup-evaluator.promptx
Debug code with root cause analysis	code-detective.promptx
Understand anything explained 4 ways	eli5-explainer.promptx

➡️ See all 10 ready-to-run programs →

---

What is PromptX?

PromptX is a provider-agnostic specification for writing structured, executable programs in natural language — where the AI model itself is the runtime.

No compiler. No interpreter. No SDK. No vendor lock-in.

@program: hello_world
@version: 1.0.0
@description: The simplest PromptX program.

@pipeline {
  @step(1): Greet the World
    @tool: create
    @instruction: |
      Say hello to the world in 5 different programming languages,
      but write each greeting as a poem instead of code.
    @output -> @final
}

Paste that into any AI chat — Claude, ChatGPT, Gemini, Llama, Mistral — and it runs.

Why PromptX?

Every programming paradigm emerged from the same insight: the machine can do more if we speak to it better.

Era	Abstraction	Runtime
1950s	Assembly over binary	CPU
1970s	C over assembly	OS
1990s	Python over C	Interpreter
2020s	Prompts over Python	AI Model

Existing "prompt programming" tools (LangChain, LMQL, DSPy) bolt programming constructs around the model using external code. PromptX encodes programming constructs into the prompt itself, leveraging the model's intelligence as the execution engine.

Feature	LangChain	LMQL	AWS SOPs	PromptX
No external runtime needed	❌	❌	❌	✅
Provider agnostic	❌	❌	Partial	✅
Pure natural language	❌	❌	✅	✅
Control flow (loops, branches)	✅	✅	Partial	✅
State management	✅	✅	❌	✅
Context window management	❌	❌	❌	✅
Error handling	✅	Partial	❌	✅

Quick Start

Option A: Instant (no reading required)

1. Browse ready-to-run/ — 10 pre-built programs that work with zero modification
2. Copy any file's contents
3. Paste into your AI and send

Option B: Learn the basics (5 minutes)

Read docs/QUICK-START.md for a step-by-step intro.

Option C: The full power

1. Copy the contents of templates/runtime.promptx into your AI's system prompt (or paste it at the start of a conversation) — this gives the AI explicit execution rules
2. Write your own programs using templates/program.promptx as a starter
3. Reference docs/SPECIFICATION.md for the full language

Example Program

@program: summarize_and_critique
@version: 1.0.0

@variables {
  $topic = "the impact of remote work on software engineering productivity"
}

@pipeline {
  @step(1): Research
    @tool: recall
    @input: $topic
    @instruction: |
      Gather everything you know about $topic.
      Organize into: key findings, debates, and gaps in knowledge.
    @output -> $research

  @step(2): Summarize
    @tool: create
    @input: $research
    @instruction: |
      Write a 3-paragraph executive summary suitable for a CTO.
    @output -> $summary

  @step(3): Critique
    @tool: verify
    @input: $summary
    @instruction: |
      Challenge the summary. What's oversimplified? What's missing?
      What would a skeptic say?
    @output -> $critique

  @step(4): Final Draft
    @tool: compose
    @input: $summary, $critique
    @instruction: |
      Revise the summary to address the strongest points
      from the critique. Keep it to 3 paragraphs.
    @output -> @final
}

No installation. No dependencies. No API keys to configure. The AI reads your program and executes it.

Core Concepts

Cognitive Primitives

PromptX treats AI reasoning capabilities as callable tools:

Primitive	Purpose	Analogy
@think	Deep reasoning, chain-of-thought	analyze()
@decide	Evaluate conditions, route logic	if/else
@recall	Retrieve from training knowledge	database.query()
@search	External tool-augmented retrieval	fetch()
@create	Generate new content	render()
@verify	Self-validate, fact-check	assert()
@transform	Reshape data between formats	map()
@compose	Merge multiple inputs	reduce()

Control Flow

PromptX supports the constructs you'd expect from any programming language:

• Sequential — steps execute in order
• Branching — @if / @elif / @else with natural language conditions
• For-each loops — iterate over collections
• While loops — repeat until a condition is met
• Parallel branches — independent reasoning paths that merge
• Subroutines — reusable @define blocks with @call

State Management

@variables {
  $input    = @input("user-provided value")
  $counter  = 0
  $items    = []
  $history  = @stack
}

@set $counter = $counter + 1
@append $items: $new_result
@push $history: $current_state

Context Window Management

The frontier feature — programs that manage their own memory:

@config {
  context_budget: 70%
}

@step(N): Checkpoint
  @tool: transform
  @instruction: |
    Compress all state into a minimal representation.
    Preserve variable values, decisions, and pending work.
    Discard intermediate reasoning.
  @output -> $checkpoint
  @context_action: compress_to($checkpoint)

Programs

Ready-to-Run (copy-paste, zero modification)

Program	What You Get
email-drafter.promptx	Same email in 3 tones — professional, casual, direct
meeting-notes.promptx	Raw notes → action items, decisions, summary
learning-plan.promptx	30-day structured learning plan for any skill
startup-evaluator.promptx	Idea evaluated from 5 expert perspectives
standup-generator.promptx	Bullet notes → polished standup report
eli5-explainer.promptx	Any concept explained at 4 depth levels
debate-simulator.promptx	Both sides argued rigorously + moderator synthesis
code-detective.promptx	Root cause analysis: why code breaks + fix strategy
interview-coach.promptx	Tailored questions + model answers for any role
recipe-planner.promptx	5-day meal plan from your ingredients + shopping list

Annotated Samples (learn the syntax)

Level	Sample	Description
🟢 Basic	hello-world.promptx	Your first PromptX program
🟢 Basic	summarizer.promptx	Summarize any topic with quality verification
🟢 Basic	translator.promptx	Multi-language translation with cultural adaptation
🟡 Intermediate	code-review.promptx	Multi-perspective code review with parallel branches
🟡 Intermediate	decision-matrix.promptx	Weighted decision analysis with nested loops
🟡 Intermediate	blog-writer.promptx	End-to-end blog generation with iterative refinement
🔴 Advanced	research-report.promptx	Comprehensive research with verification and context management
🔴 Advanced	multi-expert.promptx	Chain-of-experts consultation with subroutines
🔴 Advanced	self-refining.promptx	Self-improvement loop with quality convergence

Documentation

• Specification — The full PromptX language specification
• Quick Start — Get running in 2 minutes
• Cognitive Primitives — Deep dive into @think, @decide, @create, etc.
• Control Flow — Branching, loops, parallel execution
• Patterns — Advanced patterns and recipes
• Provider Compatibility — Testing results across AI providers
• FAQ — Common questions answered

Tested On

Provider	Model	Status
Anthropic	Claude Opus / Sonnet	🟢 Excellent
OpenAI	GPT-4o / GPT-4.5	🟢 Excellent
Google	Gemini 2.0	🟢 Good
Meta	Llama 3.x (70B+)	🟡 Good (complex programs may need simplification)
Mistral	Large / Medium	🟡 Good

Note: Results improve with model capability. PromptX programs with complex control flow work best on frontier models. Simpler programs run well on most instruction-following models.

Project Status

PromptX is currently at v0.1.0 — the foundational specification.

Version	Status	Focus
v0.1	✅ Current	Core spec: sequential, branching, loops, variables, error handling
v0.2	🔜 Next	Subroutine library, community-contributed reusable blocks
v0.3	📋 Planned	Multi-agent patterns spanning multiple AI instances
v0.4	📋 Planned	Formal context management and continuation protocol
v0.5	📋 Planned	Testing framework with @test blocks
v1.0	🎯 Goal	Stable specification with community consensus

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Ways to contribute:

• Test across providers — Run samples on different AI models and report results
• Write programs — Create new .promptx programs for real-world tasks
• Propose directives — Suggest new @ directives with clear semantics
• Build tooling — Syntax highlighting, linters, VS Code extensions
• Improve docs — Better explanations, more examples, translations

License

PromptX is released under the MIT License. Use it, extend it, build on it.

---

PromptX: Because the highest form of abstraction is the one where you just say what you mean.

Created by @benkimz