RPG OS

Boundless imagination. Negotiable details. One enduring core.

Persistent solo role-playing with an AI game master. Build a world, choose your character, play through conversation, and return to a campaign whose history lives in readable files.

Start your first campaign

New to GitHub or AI agents? Start here. No programming is required. RPG OS is a folder of instructions and campaign records. You talk to an AI game master; it uses those files to run the game and save your progress. There is no separate RPG OS application to launch.

Full beginner guide: download, setup, play, save and return — includes an example setup conversation and help with common problems.

Alternative: ask your AI agent to set it up

If you already use an AI agent, you can give it this repository link and ask for help with installation. An agent running Claude, GPT, or another capable model can read the instructions, help prepare the campaign folder, and guide you through setup. Paste:

Help me install RPG OS and create my first campaign:
https://github.com/croatianrdy2defend-create/RPG-OS

Read the repository README and DOCS/BEGINNER_GUIDE.md, and follow their
current installation instructions. Help me make a separate campaign copy
of the GAME folder and give this chat access to read and save its files.
Handle the setup steps you can, and walk me through anything I must do
myself. Keep any existing campaign files intact.

Once the folder is ready, open its OS/AGENTS.md and help me start a new
campaign using Quick start. Check file access and tell me clearly if
you cannot save changes.

What it can do directly depends on the app's browser, file and terminal access. It may prepare the files itself or guide you through downloading them and attaching the folder. More about agent-assisted installation. The manual walkthrough below remains available.

Download RPG OS v0.9.8 — game files only

This is the current game-only, universal and unbound v0.9.8 kit. It contains the playable RPG OS files with no preset world, character or campaign history; repository documentation, playtest archives and developer tooling stay outside the download. RPG OS is free to download; your AI application's access requirements and usage costs are separate.

1. Download and extract

Download the ZIP above. On Windows, right-click it and choose Extract All; on macOS, double-click it. Put the extracted RPG_OS_v0.9.8 folder somewhere you can find again, such as Documents. Open that folder, where OS, ADMIN, INSTANCE and MODULES appear together. That is your campaign folder. Keep the whole folder together and use a separate copy for each campaign.

2. Open that folder in an AI application

Use an AI application that can read and update local files. One concrete route is Codex on desktop. OpenAI's current documentation calls this Codex in the ChatGPT desktop app; older app versions may be labelled Codex. Install through the official desktop setup guide, sign in with an account that has Codex access, and select Codex if the app shows a product selector.

Add your extracted campaign folder as a local project and start a chat in that project. In the current interface, Edit project → Add folder attaches a folder; make the campaign folder primary if several are attached. A project is simply the app's way of giving chats access to your files. Official folder instructions.

Use that same folder for play and saving. Uploading a ZIP to an ordinary chat may provide reading access without the ability to update your campaign; the beginner guide explains the alternatives.

3. Paste this starting message

Open OS/AGENTS.md in this campaign folder. Help me start a new RPG campaign.
Follow ADMIN/NEW_GAME.md, including Neutrality before worldbuilding and
Campaign spirit, and use Quick start. Ask only what you need next.
Check the available file access and tell me if you cannot save changes here.

The AI should help you choose the world, character, rules, tone and what you want from play. Describe what interests you; you can also ask it to propose options. If you have no preferred rules, ask for the included Freeform engine. Review its setup summary, request changes or say you accept it, and let it finish and verify the initial save. Then say “Begin the campaign.”

4. Play by talking

Describe what your character says or tries: “I ask what happened,” “I look around,” or “I get ready and head to work.” The GM describes the world and resolves the response. You can ask for more detail, faster pacing, a rules explanation or a correction in ordinary language. You do not need to edit the files yourself.

5. Save, stop and come back

To save while continuing, say “Save the campaign” or SAVE. To finish playing, say END SESSION SAVE (or “End the session, take my feedback, and save the campaign.”). The GM stops play, waits for your feedback or explicit skip, incorporates permitted adjustments for next time, then saves automatically; no second SAVE command is needed. If you need it to save immediately without waiting for feedback, say so. Wait for confirmation that the files were written and checked before closing the chat. New campaigns default to a brief write-only PLAY note after each completed play response and an announced CHECKPOINT every 20 completed PLAY replies. You can disable or customize either during setup or recalibration. A note does not replace a verified save.

Next time, open the same updated campaign folder, start a new chat in its project and paste:

Open OS/AGENTS.md and continue my saved campaign. Resume from the saved point.

The GM gives a short command reminder at session start and end. During play you can use SAVE, CHECKPOINT (current records only), END SESSION SAVE, or ordinary OOC requests for corrections, pacing/rules and available commands.

Keep only one chat actively playing a campaign. After a verified save, copy the entire campaign folder to a separate backup location. Your progress lives in the updated folder; extracting another fresh kit starts with blank records.

Stuck? Read the step-by-step guide and troubleshooting. If asking for help, mention your AI app, model, the step you reached and the exact error or response.

Browse game files · Quick start · Installation · Game-only release and checksums

GitHub's green Code → Download ZIP downloads the whole development repository. Players normally want the current game-only ZIP instead. Earlier releases retain their original tags and assets.

Three separate places

Published playtest: 30 sessions, findings, and transcripts

The Ninth Sluice / Afterwater follows one campaign through ten initial sessions and twenty additional sessions: 30 condensed sessions and 260 recorded player/GM exchanges, using RPG OS v0.9.5 and Freeform.

Read the findings · Read all 30 sessions · Browse the evidence

The report covers successes, failures, deliberately corrupted saves, conversation-backed review, missed errors and recommendations. These were AI-authored, instrumented, non-blind tests—not human sessions or an independent-model study. They informed v0.9.6; they are not new campaign tests of v0.9.6. The publication contains all thirty play bodies and selected evidence, not every working save or audit bundle.

Learn more

Why I built RPG OS · Architecture · How the mechanics work · Host compatibility · Verification

Current software: v0.9.8. This release grounds NPC behavior in concrete personal lives and relationships, develops connected situations beyond the PC's immediate task, and preserves meaningful opportunities, routine expertise and quiet enjoyment. Consequential facts survive saves while genuinely open details remain authorable. The short write-only log and announced 20-reply checkpoint proposal for new campaigns remain. Release changes and limits · Game-only distribution · Package contents and checks.

For an existing campaign, keep a complete backup and use the protected upgrade procedure. Never overwrite live campaign records with blank installation templates.

Credits & acknowledgements

Project author and maintainer: croatianrdy2defend-create. Developed through iterative campaign work and LLM-assisted design and review. Contributing.

Design reference — Claude Corpus Engine by galliard5.

Comparing the two systems and exchanging design ideas informed RPG OS's optional preparation work in v0.7.2 and its later source-access and evidence-audit design in v0.9.0. Claude Corpus Engine's approach to navigating large campaign corpora provided useful lessons that RPG OS adapted within its own file structure and authority model.

Thanks to galliard5 for sharing his work and the constructive exchange. Both projects have incorporated lessons from the comparison; Claude Corpus Engine acknowledges RPG OS in turn. This credit recognizes design influence and discussion; the projects retain their own implementations.

Original protocol/documentation: CC BY 4.0; code and automation: MIT, with licenses included alongside the code. No rights in third-party game settings or content are granted.