shellquest 1.5.2

A passive RPG that lives in your terminal — your shell is the dungeon
shellquest-1.5.2 is not a library.

Every command you run has a chance to trigger an encounter. Your character gains XP, finds loot, fights monsters, and levels up -- all while you're just doing your normal work. Zero effort. Zero interruption. Pure vibes.

~/projects $ git push
  🏆 Quest complete! You pushed your code to the realm! +21 XP +8 gold

~/projects $ cargo build
  💎 ★·.· The forge burns hot! You crafted: ★Vorpal Pointer★ (+18 Weapon) [Epic] ·.·★

~/projects $ docker compose up
  🏆 The orchestration ritual completes! A symphony of microservices plays! +23 XP +9 gold

~/projects $ cat README.md
  🐾 You befriend a friendly daemon! It heals you for 5 HP. HP: 47/47

~/projects $ rm -rf node_modules
  ⚔️  A Dependency Hell Hound appears! You strike true! Victory! +22 XP

~/projects $ bad_command
  🪤 You stumble on a trap! Took 3 damage. HP: 44/47

Install

From crates.io (recommended)

cargo install shellquest

One-liner (auto-setup)

curl -fsSL https://raw.githubusercontent.com/duysqubix/shellquest/main/install.sh | bash

Clones, builds, installs sq, detects your shell, and adds the hook automatically.

From source

git clone https://github.com/duysqubix/shellquest.git
cd shellquest
cargo install --path .
sq hook --shell zsh >> ~/.zshrc   # or bash/fish

Requires: Rust (cargo)

Quick Start

source ~/.zshrc          # reload shell (or restart terminal)
sq init                  # create your character
                         # ...now just use your terminal!
sq status                # check your stats anytime

How The Tick Works

The magic behind shellquest is a shell hook -- a tiny function that runs invisibly after every command you type.

The Flow

You type a command
        |
        v
  Command executes normally
        |
        v
  Shell hook fires (precmd / PROMPT_COMMAND)
        |
        v
  sq tick --cmd "your cmd" --cwd "/your/path" --exit-code 0
        |       (runs in background with & disown)
        v
  ┌─────────────────────────────────────────┐
  │  1. Load save from ~/.shellquest/       │
  │  2. Increment commands_run              │
  │  3. Check exit code (!=0 = trap!)       │
  │  4. Match command to event table        │
  │  5. Roll dice for event trigger         │
  │  6. Run event (combat/loot/xp/travel)   │
  │  7. Passive heal check (25% chance)     │
  │  8. Atomic save back to disk            │
  └─────────────────────────────────────────┘
        |
        v
  Output appears on stderr (never pollutes pipes)
  Total time: <1ms

What the hook looks like (zsh)

__sq_hook() {
    local exit_code=$?                    # capture exit code
    local cmd=$(fc -ln -1)                # grab last command from history
    sq tick --cmd "$cmd" \                # pass command text
            --cwd "$PWD" \                # pass current directory
            --exit-code "$exit_code" \    # pass success/failure
            2>/dev/null &                 # background, silence errors
    disown 2>/dev/null                    # detach from shell
}
precmd_functions+=(__sq_hook)

Why it's invisible

  • Runs in the background (&) -- never blocks your prompt
  • Detached (disown) -- won't die with your shell
  • Output goes to stderr -- ls | grep foo still works perfectly
  • Completes in <1ms -- faster than your terminal can redraw
  • No network calls -- everything is local file I/O

Event probability

Not every command triggers something. Each command type has its own trigger chance:

Trigger Chance
git commit (craft) Always
git push (quest) Always
cargo build (forge) Always
docker compose (orchestra) 1 in 3
rm (angry spirit) 1 in 3
kill (banish) 1 in 3
sudo (power surge) 1 in 4
ssh/curl (portal) 1 in 4
grep (scrying) 1 in 4
cat/less (familiar) 1 in 6
vim/nvim (meditation) 1 in 5
Everything else ~15% (3 in 20)
Failed command (trap) Always

Command Events

Command What Happens
git commit Craft XP from committing to the archives
git push Quest completion -- XP + gold
cargo build / npm build Forge -- chance to craft weapons & armor
docker build Container forge -- high-quality loot
docker compose Orchestration ritual -- big XP + gold
docker pull Summon image from the Cloud Registry
docker stop / docker rm Banish container to the void
rm / del Angry spirits attack
cat / less / bat Befriend a familiar (heals HP)
sudo Power surge -- raw energy XP
vim / nvim / emacs Editor meditation -- heals + XP
kill / pkill Banish a rogue process -- combat XP + gold
grep / rg Scrying -- find hidden loot or patterns
tar / zip Open a treasure chest -- guaranteed loot
man / tldr Study ancient tomes -- knowledge XP
ssh / curl / wget Open a portal to remote realms
python / node / ruby Cast an interpreted incantation
pip / gem Alchemy -- transmute packages into power
chmod / chown Enchant files with new permissions
cp / mv / rsync Telekinesis -- move files with your mind
top / htop Omniscience -- peer into the process table
echo / printf Echo spell -- resonance heals HP
Failed commands Traps -- take damage
Everything else ~15% random encounter (combat, loot, gold, heal, or XP)

Character System

┌──────────────────────────────────────────┐
│  Ferris the Goblin Assassin Rogue  (Lvl 42 [P1])
│
│  HP: ████████████████░░░░ 89/110
│  XP: ████████░░░░░░░░░░░░ 2340/5660
│
│  STR: 52  DEX: 68  INT: 47
│  Gold: 1,847
│
│  Weapon: ✦ Mass Migration Blade of the Kernel ✦ (+31) [LEGENDARY]
│  Armor:  ★ Warplate of Kubernetes ★ (+16) [Epic]
│  Ring:   Band of the Borrow Checker (+9) [Rare]
│
│  Kills: 312  Deaths: 7  Cmds: 14,203
│  Title: Prestigious Daemon Slayer
└──────────────────────────────────────────┘
  • 5 Classes: Wizard, Warrior, Rogue, Ranger, Necromancer
  • 5 Races: Human, Elf, Dwarf, Orc, Goblin
  • Stats: STR (attack), DEX (dodge + crit), INT (class power)
  • 150 Levels with scaling XP curve
  • 15 Titles from Terminal Novice to Root Overlord

Loot

150+ dev-themed items across 5 rarity tiers with realistic drop rates:

Rarity Drop Rate Visual Example
Common 70% plain white Rusty Pipe, Hoodie of Comfort, Potion of Coffee
Uncommon 25% gray ~ Sword of Regex, Cape of CI/CD, Brew of Debugging
Rare 4% green ~~ Blade of Sudo, Crown of CloudFormation
Epic 0.99% purple ★stars★ Excalibash, Aegis of the Load Balancer
Legendary 0.01% gold boxed frame Mass Migration Blade of the Kernel

Items span weapons, armor, rings, and potions -- all dev/tech themed. Good luck finding a legendary.

Zones

Your current directory determines the biome. Higher danger = tougher monsters but better loot.

Path Zone Danger Flavor
~ Home Village 1 The safety of your home directory...
src / lib The Source Sanctum 2 Lines of power flow through structured halls...
test The Proving Grounds 2 Assertions echo through the arena...
/etc The Config Archives 2 Ancient scrolls of configuration line the walls...
/tmp The Wasteland 3 A desolate land where files come to die...
/var The Variable Marshes 3 Shifting logs and pools of data...
.git The Time Vaults 3 Echoes of past commits whisper around you...
/dev The Device Caverns 4 Strange devices hum with raw power...
node_modules The Abyss 5 An infinite void of dependencies...

Prestige System

At level 150, you've mastered the terminal. But the journey doesn't end -- it ascends.

sq prestige

  ✨ PRESTIGE ✨
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  You will reset to level 1 but gain:
  • +2 to all stats per prestige tier
  • A subclass with unique stat bonuses
  • +10 max HP per prestige tier
  • You keep your gold, gear, kills, and inventory

  Choose your subclass:
    1. Assassin — STR:+1 DEX:+3 INT:+0
    2. Hacker   — STR:+0 DEX:+2 INT:+2
    3. Shadow   — STR:+1 DEX:+3 INT:+0

15 subclasses (3 per base class):

Class Subclasses
Wizard Archmage, Chronomancer, Datamancer
Warrior Berserker, Paladin, Warlord
Rogue Assassin, Hacker, Shadow
Ranger Beastmaster, Sniper, Scout
Necromancer Lich, Plaguebearer, Soul Reaper

Prestige title tiers: Prestigious > Exalted > Transcendent > Mythical > Godlike

Commands

Command Description
sq init Create a new character
sq status View your character sheet
sq inventory Check your gear and potions
sq journal Adventure log (last 20 events)
sq shop Browse the shop (must be in home directory)
sq buy <number> Buy item by number from sq shop list
sq equip <name> Equip armor or ring from inventory
sq wield <name> Wield a weapon from inventory
sq drink <name> Drink a potion to restore HP
sq drop <name> Permanently drop an item from inventory
sq prestige Ascend with a subclass (requires level 150)
sq hook --shell zsh Print shell hook code
sq update Update sq to the latest version via cargo
sq reset Permanently delete your character

Design
Binary Single Rust executable, ~1.6MB
Tick latency <1ms -- never slows your shell
State ~/.shellquest/save.json (atomic writes)
Output stderr only -- never pollutes pipes
Permissions ~/.shellquest/ is 0700 (owner-only)
Concurrency Atomic write-then-rename prevents corruption
Colors MUD-style rich inline formatting via colored crate
Dependencies clap, colored, dirs, rand, serde, chrono

Contributing

PRs welcome! Some ideas:

  • More monsters, loot, and events
  • Achievement system
  • Multiplayer leaderboards (shared server)
  • ASCII art boss encounters
  • Sound effects via terminal bell

License

MIT -- do whatever you want with it.

Made with Rust and vibes.