ao-mud is a spellbook of well-commented atomic bash scripts that each do one thing. we are building semantic building blocks for an autonomously-evolving digital spellcasting language.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

14 KiB


ao-mud is a project to make the terminal easier for novice users by narrativizing it as a Multi-User Dungeon, or M.U.D.


  • story first - make the world make sense, and that will tell us what to code
  • playtest-driven development - try to use it, fail fast and iterate; it has to be fun
  • POSIX-compatible scripts - maximally compatible across platforms and weird nested environments
  • immanence - the game is here, a meaningful virtual space in the terminal
  • immediacy - the game is everywhere, not a separate mode
  • pedagogy - collecting best practices and making them easy to use, learn, remember, and teach/share in well-commented bash scripts
  • sharpen the saw - gradually improving the architecture of the tech stack
  • smarter conventions - we can evolve the terminal and make it easier to teach by migrating to higher-order semantics (new words)
  • semantic evolution - we can evolve bash from a pidgin to a creole with rigorously one-function apps plus a recursive parser


ao-mud is also ao-bash, an attempt to immanentize the AO to the terminal for a native un-AO experience that requires no database.

Some architectural guidelines:

  • Make many small, atomic scripts that are almost as atomic as possible
  • The smallest logical size is a semantic unit: (e.g., read-magic handles both reading all attributes or one named attribute, could abstract read-all-magic and read-all-magic but it's semantically parsimonious to combine them)
  • Make each script work either sourced or executed by using the BASH_SOURCE idiom (will be included after conversion to POSIX)

The Beginning of Your AO Adventure...

What is the Autonomous Organization, what does it mean? This mystery drives your quest.

We all sense something is wrong with the world. We all want to ask the same question.

The AO is the answer to this question.

Along the way, you will learn to use the Unix terminal, and you will gain special terminal upgrades. Most people don't believe that UI upgrades can be game-changing, but with cybernetics and a little magic, anything is possible.

Three Paths of Knowledge

On your AO adventure, there are three different tutorials which gradually unlock the powers of the terminal. Choose your class wisely:

  • Sorcerer: The Path of Sorcery is the path of casual power. Sorcerers learn how to wield powerful spells early on, but they don't know how they work. Sorcerers trade words and understanding and remember this knowledge in their memory.

  • Wizard: The Path of Wizardry is a path of careful learning. Wizards start by learning the true names of bash commands, and learn to assemble spells gradually. Wizards trade spells on pages (bash scripts) and save them in their spellbook (spells folder).

  • Alchemist: The Path of Art is an oral tradition. Find a bash alchemist who can teach you the elements and the ways of alchemy.

Loading Saved Games

ao-mud contains unlockable menus and terminal shortcuts that make using the terminal easier and more fun. To skip ahead and turn some of these features on without unlocking them in tutorial mode, you can use a Save Code that you received from an earlier playthrough. To use a Save Code, open the AO main menu, select "Load Saved Game", enter your Save Code, and press Enter.

Folder Structure

The structure of this project right now is simple. There is a spells folder containing spells you can cast. This folder has a subfolder called cantrips, which contains tiny spells that are used to compose larger spells that aren't meant to be used on their own.


  1. As a naming convention, spells that use hypens (-) in their name instead of spaces are set up to be run as scripts in the terminal (even if they are cantrips that will merely inform you not to do so). Spells that include a function that is not accessible by executing the script in the terminal are named with underscores (_) in their names. Open these (or any) spells in a text editor to see what they contain.

  2. Terminal commands that simply output a single value should output the bare value by default. A --verbose or -v flag should be included on all such functions to include a description field such as "Cursor X:".

  3. Cantrips should be so atomic so as to include a single value, if possible. This reduces parsing that must be done by those using the cantrip.

How to Cast a Spell

To cast a spell, cd into the spells directory. Then, the first time you cast the spell, chmod +x spellname. Then ./spellname to cast.

How to Begin

To access the mud main menu, run chmod +x mud and then ./mud in this directory.

A tutorial is coming soon. For now, explore the ./spells directory. Try reading or running the rosetta-stone script or the jump script.

Potential Suite Inclusions

This is a list of projects that (as far as we can tell so far) follow free software principles and do something interesting or useful in terms of 1) doing basic computer functions on a UNIX system; 2) making basic computer tasks easier to do or teaching people about UNIX; 3) cryptography: or onboarding people to cryptography and privacy best practices for personal communications; or 4) decentralization: peer-to-peer infrastructure or 5) GUIs for helping people to self-organize politically or organize themselves or their community's information in a post-colonial way; 6) self-host content in an increasingly integrated way; or 7) form ad-hoc mesh networks.

The first projects that will be integrated are: tor, bitcoin, lightning, and SimpleX (in that order). After that, the next features and tools added to the suite will be chosen by popular demand, in close collaboration with specific partner communities. This list is similar to awesome-free-software or awesome-selfhosted but more selective and integrated into a whole vision of a free software suite.

We are very open to new suggests or critiques or existing items on this list. This is just a public place to collect research on the best free software and non-commercial open-source projects, so that they can be integrated into the ao-bash suite for easy, replicable installation and use by an increasingly large user base.

Similar software is grouped together under one bullet. This list does not represent an endorsement; it represents the state of current research for potential endorsement.

Basic Computer Tasks

  • SimpleX Chat is encrypted chat with no logins at all (Why not Signal?)
  • BorgBackup is a deduplicating backup suite that encrypts traffic during transit.
  • Timeshift for Linux is an application that provides functionality similar to the System Restore feature in Windows and the Time Machine tool in Mac OS
  • Notational Velocity is an impressive-looking notes-taking app that attempts to optimize the notes-taking interface in ways similar to ao-3.

UNIX Convenience & Education

Cryptography & Cryptocurrency

  • tor is a well-tested solution for anonymizing internet traffic. The more people use it, the faster and more secure it is.
  • bitcoin and lightning (clightning implementation) are a fully-functioning alternative currency system that can be a basis for individual financial independence.
  • Dark Crystal social key management allows your friends to back up your keys
  • Tribler is a tor-onion-routing-like bittorrent client

Decentralized Hosting Infrastructure

  • Zion is a bitcoin social network / bitcoin layer three.
  • Matrix-CRDT allows you to use Matrix as the backend for local-first applications.
    • Aphrodite is meant to make local software easy to make (project not usable yet)
    • @localfirst/auth enables decentralized yet local-first auth using a "conflict-free replicated state container based on a signature chain".
    • Solid is a specification for decentralized data storage.
    • The Local-First SDK is new and not working yet but I like the philosophy.
  • PouchDB is a JavaScript that syncs unproblematically.
  • slskd is a self-hosted web-based client for the soulseek p2p network.
  • EarthStar is a low-to-the-ground distributed storage protocol
  • CODA Protocol allows truly decentralized computation (not usable yet) (CCP GitHub)
  • IPFS is a capable platform and addressing system for distributing responsibility for self-hosting a file on a case-by-case basis.
  • IPS is the main alternative to tor.
  • btrfs filesystem with compression plus duperemove to synchronize (home) directories.

Decentralized Social Networking

  • AO GUI for community forum and decision making in a way immanent to the UNIX operating system.
  • Crabgrass is a p2p social networking software
  • Dual Power App is a new attempt to create a platform co-op for black communities
  • Lemmy and Ramble are quality reddit alternatives.
  • Syndie is an app to syndicate data that can access I2P, Tor, and Freenet (stalled since 2016)
  • freedit is "the safest and lightest forum, powered by rust"
  • webmentions (standard)
  • ActivityPub (standard)

Self-Hosting Content

  • youtube-dl can download archival copies of videos from YouTube and most other video websites.
    • Horahora - YouTube alternative - locally archive, browse, and share videos from nearly any site.
    • PeerTube is another alternative that includes plugins and monetization options
  • Mail-in-a-Box is an easy-to-deplay mail server in a box
  • Immich is a self-hosted Google Photos replacement
  • is a blog platform for hackers
  • Etherpad for shared text editing
  • Cryptpad is a self-hosted Google Drive alternative that works great
  • TiddlyWiki, a self-hostable wiki

Ad-Hoc & Mesh Networking

  • freespace is a new addressing paradigm for p2p UNIX-based networking
  • tuntox "forwards TCP connections over the Tox protocol, which allows low-latency access to distant machines behind NAT you can't control or with a dynamic IP address."
  • Reticulum, a prepper version of the internet
  • nostr is Notes and Other Stuff Transmitted by Relays
    • awesome-nostr is a list of nostr-related software
    • nostrgram is a Telegram clone written in plain JavaScript.
    • ArcadeCity has a nostr app
    • Lightning.Pub is an LND-based nostr lightning thing
    • bija is a Flask-based nostr client
    • StackerStan is a good example of a nostr-based AO-like wiki thing (but written in Go)
    • Nodestr is a nostr relay implementation in Node.js
    • Nvote is a nostr-powered reddit clone
    • more-speech is a desktop Nostr client


  • Project Cambria translates your data with lenses
  • DeepL translator (non-Google)
  • is an open-source, standards-based web annotations solution!
  • DALLE2-pytorch
  • Podman is a drop-in replacement for Docker that doesn't require a background service.
  • CardConjurer is a site and apparently open-source repo to make printable Magic card templates. Art assets in this repo I think.
  • Penpot is a prototyping/diagramming tool
  • Bootstrap is a nice set of generic icons and other mobile-first web elements for quickly prototyping a project
  • Whonix for securite hosting; NixOS for reliable environment reproduction.
  • bulk-downloader-for-reddit allows downloading of reddit posts via the command line