Jan 7, 2026

Your Prompts Deserve Version Control Too

You’ve probably version-controlled your code for years. But what about your prompts?

If you’re building with LLMs, you know the pain: prompts drift over time, there’s no audit trail, and iterating means copy-pasting into a notes file somewhere. When something breaks, good luck figuring out what changed.

r9s agents solve this. Let me show you how a simple vocabulary tutor evolves from a quick hack to a production-ready, versioned agent.

Getting Started

First, install r9s and set up your credentials:

pip install r9s

Create a .env file in your project:

R9S_API_KEY=sk-your-api-key
R9S_BASE_URL=https://api.r9s.ai/v1
R9S_MODEL=gpt-5-mini

That’s it. r9s automatically loads .env from your current directory.

Step 1: Create Your First Agent

Let’s build a vocabulary tutor. First, write the prompt in a file:

cat > vocab-tutor.md << 'EOF'
You are an English vocabulary tutor. When given a word:

1. **Definition**: Clear, simple explanation
2. **Pronunciation**: IPA notation
3. **Example sentences**: 2-3 natural examples
4. **Synonyms**: 3-5 related words with nuance differences
5. **Common collocations**: Frequently paired words
6. **Etymology**: Brief origin (if interesting)

Keep explanations concise.
EOF

Now create the agent:

r9s agent create vocab-tutor \
  --instructions @vocab-tutor.md \
  --model gpt-5-mini

The @filename syntax loads instructions from a file—just like curl. This makes prompts easier to edit and version control.

Try it out:

r9s chat --agent vocab-tutor
You> ephemeral

**ephemeral** /ɪˈfem.ər.əl/

**Definition**: Lasting for a very short time; transitory.

**Example sentences**:
- The ephemeral beauty of cherry blossoms draws millions each spring.
- Social media fame is often ephemeral—here today, gone tomorrow.

**Synonyms**:
- transient (more formal)
- fleeting (emphasizes speed)
- momentary (very brief)

**Collocations**: ephemeral nature, ephemeral beauty, ephemeral moment

**Etymology**: From Greek *ephēmeros* "lasting only a day"

tokens: 45 in / 186 out

Step 2: Add Template Variables

Your tutor works, but it’s hardcoded for English. What if you want to teach German? Or French? Instead of creating separate agents, add variables:

r9s agent update vocab-tutor \
  --instructions 'You are a {{target_language}} vocabulary tutor for {{native_language}} speakers at {{level}} level.

When given a word:
1. **Definition**: Explain in {{native_language}}, show the {{target_language}} word
2. **Pronunciation**: IPA notation + phonetic hints for {{native_language}} speakers
3. **Example sentences**: {{example_count}} sentences with translations
4. **Related words**: Synonyms and antonyms
5. **Memory tip**: Mnemonic connecting to {{native_language}} sounds'

Now use it for German:

r9s chat --agent vocab-tutor \
  --var target_language=German \
  --var native_language=English \
  --var level=beginner \
  --var example_count=2

You> Schmetterling

**Schmetterling** /ˈʃmɛtɐlɪŋ/
(English: butterfly)

**Pronunciation tip**: "shmet-ter-ling" - stress on first syllable

**Example sentences**:
- Der Schmetterling fliegt im Garten. (The butterfly flies in the garden.)
- Ich sehe einen bunten Schmetterling. (I see a colorful butterfly.)

**Related words**:
- die Raupe (caterpillar) - what it starts as
- die Motte (moth) - nocturnal cousin

**Memory tip**: Think "smash + butter + fling" - imagine a butterfly flinging butter!

tokens: 67 in / 189 out

Same agent, different languages. Variables make agents reusable.

Step 3: Version and Iterate

Your vocab-tutor is working great for language learners. But now you want to serve a different audience: native speakers aiming for The Economist-level precision.

This is a major change. Let’s version it properly:

r9s agent update vocab-tutor \
  --instructions 'You are a vocabulary consultant for advanced English users seeking precision and sophistication.

When given a word:

1. **Core meaning**: Precise definition with connotation (positive/negative/neutral)
2. **Register**: Where this word belongs (academic, journalistic, literary, conversational)
3. **Precision vs alternatives**: How it differs from near-synonyms
4. **Sophisticated usage**: 2 examples from quality writing
5. **Pitfalls**: Common misuses, even among educated speakers
6. **Power move**: One sentence showing the word used effectively

Target audience: Native speakers, graduate students, professionals.' \
  --bump major \
  --reason "Redesigned for advanced users: added register, precision analysis"

Check the version history:

r9s agent history vocab-tutor
# v1.0.0 (2025-01-05) - Initial beginner version
# v2.0.0 (2025-01-06) - Redesigned for advanced users [CURRENT]

Compare what changed:

r9s agent diff vocab-tutor 1.0.0 2.0.0

Try the advanced version:

r9s chat --agent vocab-tutor
You> nuance

**nuance** /ˈnjuː.ɑːns/

**Core meaning**: A subtle distinction or variation in meaning, expression,
or response. *Connotation*: Positive—suggests sophistication and careful thought.

**Register**: Academic, journalistic, literary. Signals educated discourse.
Avoid overuse in casual speech (can sound pretentious).

**Precision vs alternatives**:
- *subtlety*: Broader; nuance specifically implies fine gradations
- *distinction*: More binary; nuance suggests a spectrum
- *shade*: Informal equivalent ("shades of meaning")

**Sophisticated usage**:
- "The diplomat's response was full of nuance, acknowledging grievances
   without assigning blame."
- "Her analysis captured nuances that the quantitative study missed entirely."

**Pitfalls**:
- Don't use as a verb ("to nuance an argument")—controversial and criticized
- Avoid "very nuanced" (redundant; nuance already implies degree)

**Power move**: "His objection wasn't opposition—it was nuance, a refinement
that strengthened the proposal."

tokens: 72 in / 234 out

Step 4: Production Governance

Your agent is ready for the team. Mark it as approved:

r9s agent approve vocab-tutor --version 2.0.0

Check usage and audit trails:

r9s agent audit vocab-tutor --last 50
# execution_id  | timestamp           | model      | tokens_in | tokens_out
# exec_a1b2c3   | 2025-01-06 14:23:01 | gpt-5-mini | 72        | 234
# ...

Something wrong with v2? Roll back instantly:

r9s agent rollback vocab-tutor --version 1.0.0

Key Features

Feature	Description
Instructions	System prompt defining agent behavior
Variables	`{{custom}}` placeholders for runtime customization
File injection	`@{path}` to include file contents
Versioning	Semantic versioning (major.minor.patch)
Audit trail	Full execution history with token counts
Status workflow	DRAFT → APPROVED → DEPRECATED
Team sharing	Export/Import as JSON

Get Started

pip install r9s

Your prompts deserve the same rigor as your code. Version them. Audit them. Iterate boldly, rollback safely.

Links: