PromptThread

Git for prompts, but actually for prompts. Version control + performance tracking, because guessing doesn't work.

Part of the Thread Suite open-source tools to stop your AI agents from failing quietly.

(Learn more at threadsuite.netlify.app)

---

Here's the thing

You change a prompt. Maybe it's a tiny tweak. Maybe it's a full rewrite.

What broke? What got better? Which version actually worked best?

Right now? Nobody knows. You just push the change and hope.

PromptThread fixes that. It's like Git, but for prompts plus it tracks how each version actually performs.

---

What it does (plain English)

• Saves every version — change a prompt, it's committed. Like Git.
• Tracks performance — pass rate, latency, cost per version.
• Compares versions — which one actually did better?
• Rollback — restore any old version instantly.
• Shows diffs — exactly what changed between versions.

---

Quick start

Python

pip install promptthread

from promptthread import PromptThread

pt = PromptThread("https://prompt-thread.onrender.com")

# Create a prompt
prompt = pt.create_prompt(
    name="summarizer-v1",
    content="You are a summarizer. Return a 3-sentence summary.",
    tags=["summarizer"]
)

prompt_id = prompt["id"]

# Log a run
pt.log_run(
    prompt_id=prompt_id,
    prompt_version=1,
    input="Long text here...",
    output="Summary here...",
    latency_ms=340.5,
    cost_usd=0.000021,
    passed=True,
    metadata={"model": "gpt-4o"}
)

# Get stats
print(pt.get_stats(prompt_id))

# Update prompt — version increments automatically
pt.update_prompt(prompt_id, "You are a summarizer. Return a 2-sentence summary.")

# See what changed
print(pt.diff(prompt_id, 1, 2))

# Roll back to version 1
pt.rollback(prompt_id, version=1)

JavaScript

npm install promptthread

const PromptThread = require("promptthread");

const pt = new PromptThread("https://prompt-thread.onrender.com");

const prompt = await pt.createPrompt(
  "summarizer-v1",
  "You are a summarizer. Return a 3-sentence summary.",
  "First version",
  ["summarizer"]
);

await pt.logRun(prompt.id, 1, {
  input: "Long text here...",
  output: "Summary here...",
  latencyMs: 340.5,
  costUsd: 0.000021,
  passed: true,
  metadata: { model: "gpt-4o" }
});

console.log(await pt.getStats(prompt.id));

---

API reference

Base URL: https://prompt-thread.onrender.com

Live Dashboard: https://prompt-thread-dashboard.lovable.app

Interactive docs: https://prompt-thread.onrender.com/docs

Prompts

Endpoint	Method	Description
/prompts/	POST	Create a new prompt
/prompts/	GET	List all prompts
/prompts/{id}	GET	Get a prompt by ID
/prompts/{id}	PUT	Update prompt, auto-increments version
/prompts/{id}/history	GET	Get all previous versions
/prompts/{id}/rollback/{version}	POST	Roll back to a version
/prompts/{id}/diff/{v1}/{v2}	GET	Compare two versions

Runs

Endpoint	Method	Description
/runs/	POST	Log a run
/runs/prompt/{id}	GET	Get all runs for a prompt
/runs/prompt/{id}/stats	GET	Get pass rate, latency, cost
/runs/compare/{id}/{v1}/{v2}	GET	Compare versions by performance

---

The Thread Suite

Three open-source tools that together give you a reliability layer for AI agents.

Tool	What it does
Iron-Thread	Validates AI output structure before it hits your database
TestThread	Tests whether your agent behaves correctly across runs
PromptThread	Versions and tracks prompt performance over time
ChainThread	agent handoff protocol and verification infrastructure.

---

Self-hosting

git clone https://github.com/eugene001dayne/prompt-thread.git
cd prompt-thread
pip install -r requirements.txt
cp .env.example .env
# Add your SUPABASE_URL and SUPABASE_KEY to .env
python -m uvicorn app.main:app --reload

---

License

MIT. Use it, break it, send a PR.

---

Built by Eugene Dayne Mawuli. If you've ever changed a prompt and had no idea if it helped or hurt, this is for you.