Expeditions

A small pixel-art battle window that plays alongside your AI agent. Finished actions move the battle. Your work stays on your machine.

New here? The quick guide shows the window in pictures and walks through an example session.

While you work

Your first prompt picks the class, the kind of task. You can change it in the window. Successful actions strike, finished turns restore Context, and the party rests at Camp when the session is idle. A failed action is a miss, with no penalty.

The recommendation card shows what the Proving Grounds measured for that class. A spell with a measured benefit hits harder here. Classes without evidence say so. These results describe the trials, not whether your own task succeeded.

When a turn ends, you can say how the work went: Cleared, Partly, Fizzled or Skip. Your guild hall keeps the spells you used, first-time foe trophies and class stars on this device. Collection levels are cosmetic.

The island strip at the top of the window shows every session at once: the agent, the project folder, what it is doing now and whether it needs you. Sessions waiting for your approval or your next prompt come first, and a short chime plays when one starts waiting. You can turn the chime off in Settings. Pin keeps the island and the battle on top of your other windows.

Expeditions never asks your agent to keep working. Idle time earns nothing, failures cost nothing, and waves beyond 20 pay no extra rewards. There are no streaks or daily rewards.

The local game supports Claude Code, Codex, OMP and Gemini CLI. A generic endpoint accepts checked local events from other tools. Other agents can use the skill or manual play below.

Install

Requires Node 22 or newer and a local browser. Expeditions is a separate plugin from spell-report. It runs observation hooks with your permissions; install it only if you want those hooks.

Claude Code

/plugin marketplace add Demonbane18/vibe-rpg-plugin

/plugin install expeditions@viberpg

Then ask “start my expedition”, or run the skill:

/expeditions:expeditions

Codex

codex plugin marketplace add Demonbane18/vibe-rpg-plugin

Install expeditions from /plugins, approve its hooks in /hooks, then start a new session. Codex asks again after plugin updates. Hosted tools such as web search do not send tool hooks.

$expeditions:expeditions

OMP and Gemini CLI

Use the plugin you installed above, or clone the public plugin repository. The commands below assume the clone is named vibe-rpg-plugin:

git clone https://github.com/Demonbane18/vibe-rpg-plugin.git vibe-rpg-plugin

node vibe-rpg-plugin/expeditions/scripts/expeditions.mjs setup --agent omp

node vibe-rpg-plugin/expeditions/scripts/expeditions.mjs setup --agent gemini

Setup previews the extension or hook changes. Review them, then repeat the chosen command with --yes to apply them. Use --agent all for both agents. With a marketplace install, ask the Expeditions skill to resolve its bundled script path instead.

node vibe-rpg-plugin/expeditions/scripts/expeditions.mjs start

The window opens from a helper on 127.0.0.1, not this website. Closing it leaves progress with the helper. Use open to return and status to check the connection.

Any agent with a shell

Load expeditions/skills/expeditions/SKILL.md from the installed plugin or clone. Ask the agent to mark the task's start and finish. It can mark a real step with mark progress. These marks use the agent's normal tool calls and tokens; they cannot see tools or spells on their own. Do not use marks on top of live hooks for the same session.

node vibe-rpg-plugin/expeditions/scripts/expeditions.mjs mark start
node vibe-rpg-plugin/expeditions/scripts/expeditions.mjs mark progress
node vibe-rpg-plugin/expeditions/scripts/expeditions.mjs mark done

Cloud agents and manual play

For a cloud agent without a local event feed, run start on your own machine, pick the class in the window and start a manual expedition. Press Progress after a real step and give your verdict when the work ends. The cloud agent never connects to the helper.

What it costs

Observation hooks and the recommendation card use no model tokens. Your agent's normal work still uses your plan. Reading the skill or asking the agent to run a command uses its normal tokens.

Guide mode is optional

Guide mode is off by default. In Claude Code and Codex, it can add one short trial-backed note on the first prompt of a session. That note uses conversation tokens. Classes without a measured benefit get no note.

node vibe-rpg-plugin/expeditions/scripts/expeditions.mjs guide on

node vibe-rpg-plugin/expeditions/scripts/expeditions.mjs guide off

The pixel-window prototype used about 5.5% of one CPU core and 32 MB more memory than a blank page while animating at 12 frames per second. Hidden, it used no extra CPU over the blank page. Those are short prototype measurements, not a two-hour test of this release.

Measurement details and targets

Measured on the curator's Mac on 2026-10-26, in headless Chrome 150, for 60 seconds per phase; hidden phases were emulated. The timer-paced 320 × 180 pixel canvas used 55 ms of CPU per second across browser processes, 32 MB above a blank page and 2.6 KB of gzipped prototype script. The 12 fps three.js prototype used 80 ms per second, 67 MB and 138 KB of script.

Release targets are at most 6% of one CPU core while animating and near zero at Camp, a helper below 80 MB and 1% average CPU, hook forwarding below 60 ms, and flat memory over two-hour sessions including two sessions at once and sleep and wake. These targets still need whole-session measurements.

What stays local

The first prompt is read in memory to pick a class, then dropped. Expeditions never saves prompt text, tool arguments or output, file paths, account ids, raw agent session ids or unknown spell names. The island shows each session's folder name and its current step, which names at most a file (never its path), a web host, an MCP server, a skill, a subagent type or a tool; those stay in the helper's memory and are never saved. Commands and full paths never reach the window. Your agent still sends prompts to its own model provider as usual.

Checked game events and collection progress stay in ~/.viberpg/expeditions by default. The helper keeps the last 20 expeditions. It may download public library data and spell icons, but uploads no session data. No account or database is needed.

You can export caught spells and medals to the Practice Grounds. Only known save fields move across; the rest of the guild hall stays in the local Expeditions save.

Seasons and leagues are planned for a later phase, with opt-in rankings for fixed challenges rather than time or spending. This local release has no player rankings or uploads. The Hall of Champions continues to rank tested setups, not people.

Updates and uninstall

Nothing updates in the background. Update a marketplace install through its plugin manager. For a clone, run git -C vibe-rpg-plugin pull, then refresh any installed agent setup:

node vibe-rpg-plugin/expeditions/scripts/expeditions.mjs update

Remove Claude Code or Codex's plugin through that agent's plugin manager. For OMP or Gemini CLI, preview removal of the setup added by Expeditions:

node vibe-rpg-plugin/expeditions/scripts/expeditions.mjs uninstall --agent all

Repeat with --yes after reviewing the preview. Uninstall keeps your local save. To stop the helper:

node vibe-rpg-plugin/expeditions/scripts/expeditions.mjs stop

The words

Each game word has a plain meaning. Seasons and leagues are listed for the planned later phase.

Expedition: One agent session, played as an auto battle in its task class.
Guild hall: Your progress across sessions, kept on your device.
Camp: The party rests while the session is idle; nothing is gained or lost.
Trophy: A foe beaten in a class for the first time.
Rally: A success right after a miss; the next strike hits harder.
Elite: Every fifth wave: the class's usual foe, tougher.
Partly: A verdict for work the agent only half finished.
Season: Four weeks of fixed challenges and frozen rules.
League: About 30 opted-in players ranked together in a season.
Context: The party's health bar, standing for the agent's context window.
Wave: One stage of a battle, with a foe to overcome.
Caught: A library spell used in a real agent session and added to your collection.
Wise Restraint: Using no spells where trials found they did not improve the result.
Strike: How hard each finished action hits the foe; trial-backed spells and Sharpen raise it.
Push: One run through the waves; after the party falls, your next prompt starts a new push from wave 1.
Sharpen: A choice every fifth wave: +3 strike for the rest of this push.
Rest: The other choice every fifth wave: +20 Context.
Stance: What an unanswered choice takes: Press on takes Sharpen, Steady takes Rest.
Buffed here: A spell that raised the clear rate in this class's Proving Grounds trials, so it hits harder in this class.