Start here

A short tour for new players. Every game word on this site stands for something real in Claude Code or Codex.

What this site is

Hero: your agent
Spell: an add-on
Foe: a problem

VibeRPGSimulator is a big book of add-ons for coding agents. Each add-on is a spell.

Your agent is the hero. A problem in your work is a foe. The right spell helps the hero beat it.

Every spell is a real add-on you can install. Its page says what it does.

The words

Hero: Your coding agent: Claude Code or Codex.
Spell: A skill, plugin, MCP server or subagent your agent can use. Skills are scrolls, plugins relics, MCP servers orbs and subagents summons.
Foe: A problem a spell deals with, like a bug or a flaky test.
Class: A kind of task. Video editing is one, and its hero is the Bard.
Weapon: The model your agent uses, such as Claude Opus 5.5 or GPT-6 Astra.
Charge: Reasoning effort. More charge means more thinking, more tokens and slower turns.
Loadout: A full setup for one task: a hero, a weapon, a charge and up to twelve spells. Copy its setup and paste it into your agent or a terminal.
Combo: A few spells cast one after another, in order, for one task.

Getting around

The menu at the top has 11 stops. Here they are from left to right.

Spellbook: Every spell in the library. Open one to see what it does and watch it fight.
Play: The Practice Grounds. Pick the spell that beats each foe, win gym badges and collect medals.
Loadouts: Full setups for one task. Copy one, build your own, or vote for the ones that work.
Combos: Spells cast in order for one task, with the source for each combo and whether it was tested.
Classes: The kinds of task, from frontend design and testing to video and game development, with the spells for each.
Tavern: What people star, post and talk about on GitHub, X and Reddit, today and this week.
Trials: The Proving Grounds. Spells are tested on fixed quests next to an Unarmed run with no spells, to see what they add.
Hall: Ladders from those tests: which setups clear each quest most reliably, and what they cost.
Records: How often the curator used each spell and combo in their own sessions.
Submit: Tell the curator about a spell you tested, or craft a new one. The plugin's install commands are here too.
Guide: The full rules, the bestiary of foes and where every number comes from. This page is part of the Guide.

The rules

Battles on spell pages

Each spell page has a short battle that plays itself. Watch it, or step through it.

The hero's bar is Context. That is the agent's context window, the room it has to read and think. When it runs low, the hero compacts it and keeps going with fewer details.

Foes hit back. Spells answer them: fresh docs burn away the Fog Wraith's haze, and tests pin a slippery foe in place.

Summons are subagents. Each is a helper agent with its own Context bar, and it comes back with a short report.

Every step has a plain line that says what really happens. These battles explain how a spell works. They are not recordings of real sessions, and their numbers are not test results.

Practice battles

At the Practice Grounds you pick the moves. A battle has 3 rounds with one foe each.

Each round you get 4 spells and an Unarmed button. One spell fights this foe, one is weak against it and two fizzle.

Super effective: The spell was made for this foe. It hits for 60.
Weak: The spell is from the right row, the one most of this foe's spells come from, but it was made for another foe. It hits for 30.
Fizzled: The spell doesn't help here. It does 0 damage, and the lesson names a spell in your hand that would have worked.
Unarmed: No spell at all. It costs no mana and hits for 20.

Each foe has 100 HP. Your hero has 100 Context and 150 Mana for the whole battle. Neither refills between rounds.

After each move, a foe that is still standing hits back. It takes 6 to 18 Context, depending on the foe. At 0 Context your hero retreats.

Losing costs nothing. Try again gives you the same battle.

Mana is a spell's measured cost. It comes from the Proving Grounds: how much more mana (cost at API list prices) runs used with the spell than the same runs Unarmed. A spell without trial data costs 15 and says "not measured". You can't cast a spell that costs more mana than you have left.

Cast spells in work order for a combo: Scout, Craft, Test, then Ship. A spell from a later row than the last spell you cast hits for 10 more, even across rounds. Fizzles get no bonus, and Unarmed moves don't break the chain.

After every move you get a lesson: what the spell does in real work, with a link to its page.

The exact numbers

Damage: super effective 60, weak 30, fizzle 0, Unarmed 20, plus 10 for a combo. A foe hits back for 1.25 times its attack in spell-page battles, rounded.

Mana: a spell whose measured upkeep is p% costs 10 plus p divided by 4, rounded, and never less than 5 or more than 40. A spell measured at 60% costs 25. Spells without trial data cost 15. Unarmed costs 0.

Upkeep is the median extra mana per run compared with Unarmed, from quests where both runs report a cost.

Quest rounds: when Unarmed is wise

Some gyms end with a quest round. It comes from a real Proving Grounds quest where Unarmed runs cleared every time and the spells didn't raise the clear rate. They only added cost.

The foe has 50 HP. Every move hits for 25, Unarmed too, and there are no combos. Spells still cost their measured mana.

Win that round with Unarmed moves only to earn the Wise Restraint medal.

Gyms and today's battle

Each of the 23 classes has a gym. Its first two rounds are the foes that class meets most. The third is a quest round when trials found one, or else another foe. Win it for a bronze badge.

Today's battle has 3 foes, the same for everyone that day (by UTC). A new one comes the next day, and nothing counts how many days you played. If you win, you can copy a share line with counts only, so it spoils nothing.

Medals

Medals reward results, never counts. No medal is for sessions, tokens, installs or how many spells you used.

Every medal is on the Practice Grounds from the start, with its exact rule. Ones you haven't earned are greyed and say "Not yet".

There are no streaks or daily rewards. You don't need a medal to keep playing, and losing never takes one away.

You can hide any medal you earned from your trainer card. It stays in your save.

Practice: Won at the Practice Grounds, like First Victory or a gym medal.
Your sessions: Found in your agent's own logs by the plugin. Bug Slayer is one: a test fails and later passes with the same runner. It shows a fix happened, not that a spell caused it.
Your quests: From Proving Grounds quests you run on your machine. True Buff is one: clear a quest with spells where your Unarmed run of the same setup failed.

Rarity, level and stars

Rarity is the curator's opinion: S is Legendary, A Epic, B Rare and C Uncommon. A question mark means nobody has rated the spell yet.

Level shows how often the curator used the spell in their own sessions. 1 session reaches level 2, 3 sessions level 3, 7 sessions level 4 and 15 sessions level 5.

Stars and downloads show popularity. They set the spellbook's default order, but they never change a rarity or a level. Proving Grounds results never change rarity, level or the order of cards.

Posting loadouts

Anyone can post a loadout, with no account. Posts can't contain links. A network can post five an hour, and the curator removes spam.

You get one vote per loadout per network, and you can take it back.

Play while you code

Practise at the Practice Grounds any time. It runs in your browser, and you don't need to install anything.

For a local battle that follows your real agent session, install Expeditions.

Real medals from your own sessions

Install the spell-report plugin in Claude Code or Codex. The install commands are on the Submit page.
Ask your agent: "check my medals".
The plugin reads your session logs and quest results on your machine, then shows a medal card.
Open the link it gives you. The Practice Grounds add those medals to your save.

The scan stays on your machine and sends nothing. The link holds only medal names, days and library spell names. Names of spells that aren't in the library stay on your machine. The medals command needs Node 20.12 or newer.

Gold gym badges

Winning a gym in practice gives a bronze badge. Gold needs a real quest.

Use the plugin's proving-grounds skill to run a Proving Grounds quest on your machine. Clear a quest of that class with a spell equipped, and with your agent opening it. Then ask "check my medals" again. The link turns that gym gold and adds the class's Proven medal.

Trials need macOS and Node 22 or newer, and every run uses your own plan allowance.

Only classes with Proving Grounds quests can go gold so far. The Trials page lists the quests.

Your save and your privacy

There are no accounts. Nothing you do at the Practice Grounds is uploaded.

Your save lives in this browser. After you first open the Practice Grounds, opening a spell page marks it Seen in your Spelldex.

Your save code is your whole save as one line of text. Copy it or download it, then load it in another browser to move your save. Loading adds to a save and never removes anything. Reset erases the save in this browser.

A card link shows your trainer card to anyone you send it to. It also holds your Spelldex lists, including the spells your agent used in real sessions, and the day you earned each medal. Hidden medals stay out of it. Friends can put up to 6 card links together to see what their party covers. Nobody is ranked.

Links from the plugin and card links carry their data after the # sign. That part never goes to the server, and the page removes it from the address bar once it has read it.

Safari may delete your save after 7 days without a visit, and private windows lose it when they close. Keep your save code somewhere safe.