Lib.rs

                                                                      
                                                                      
        #             ###    ###                                      
        #               #      #                                  #   
        #               #      #                                  #   
 :###:  #:##:   ###     #      #     ## #  #   #   ###   :###:  ##### 
 #: .#  #  :#     :#    #      #    #   #  #   #     :#  #: .#    #   
 #:.    #   #  #   #    #      #    #   #  #   #  #   #  #:.      #   
 .###:  #   #  #####    #      #    #   #  #   #  #####  .###:    #   
    :#  #   #  #        #      #    #   #  #   #  #         :#    #   
 #. :#  #   #      #    #.     #.   #   #  #:  #      #  #. :#    #.  
 :###:  #   #   ###:    :##    :##   ## #  :##:#   ###:  :###:    :## 
                                        #                             
                                        #                             
                                        #                             

You type hundreds of commands a day. ls, git push, cargo build. Every one disappears into the void -- no reward, no acknowledgment, just a prompt waiting for the next one.

shellquest hooks into your shell and turns every command into a game event. XP, loot, combat, bosses. You don't do anything differently. You just stop losing progress.

~/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 $ bad_command
  🪤 You stumble on a trap! Took 3 damage. HP: 44/47

~/projects $ grep -r "TODO" .
  ⚔️  A Lint Wraith appears! You dodge! Riposte for 14 damage. Victory! +19 XP

~/projects $ vim README.md
  🧘 You enter a meditative state. HP restored: 47/47. +6 XP

~/projects $ docker stop db
  ☠️  BOSS BATTLE: The Memory Corruption looms from the void! 95 HP. The fight begins.

Install

cargo install shellquest

Then add the shell hook:

sq hook --shell zsh >> ~/.zshrc   # or bash, fish
source ~/.zshrc

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

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

Quick start

sq init           # pick your class and race
sq status         # view your character sheet
sq journal        # read the adventure log
sq help arena     # learn how to play the arena

That's it. Just use your terminal.

Help & Manual

The sq CLI includes a built-in manual for every command.

• sq help — View the topic index
• sq help <topic> — View a specific command guide (e.g., sq help arena)
• sq --help — View standard CLI usage and flags

What you get

• 5 classes -- Wizard, Warrior, Rogue, Ranger, Necromancer
• 5 races -- Human, Elf, Dwarf, Orc, Goblin
• 150 levels with a scaling XP curve, titles from Terminal Novice to Root Overlord
• 15 subclasses -- unlocked at prestige
• 130+ items across 5 rarity tiers: Common (70%) down to Legendary (0.01%)
• 11 zones determined by your current directory, each with unique flavor and danger scaling
• Attrition combat — fights chip HP over time; dangerous zones can kill the unwary
• Elite encounters — rare Enraged variants break through with sharper attacks and richer rewards
• 5 named bosses, spawning at 1 in 1,000 commands
• Prestige system -- reset at 150, keep your gear, go again stronger
• Permadeath mode -- optional; standard death costs 15% of your gold and resets current-level XP

Classes

Each class earns +50% XP on affinity commands.

Bosses

Five named bosses roam the dungeon. They don't announce their arrival.

The Kernel Panic · Lord of /dev/null · SIGKILL Supreme · The Infinite Loop · The Memory Corruption

1 in 1,000 commands. d20 combat. No guarantees.

Prestige

Level 150. Choose a subclass. Reset. Go again stronger.

What resets: level and XP. What you keep: gold, gear, kills, inventory. What you gain: +2 to all stats per prestige tier, +10 max HP per prestige tier, one of 15 subclasses.

Level 150. You can stop. You won't.

Arena

The Arena is an interactive combat gauntlet where you face waves of increasingly difficult enemies for massive rewards.

• Risk vs Reward — Cash out early to keep your winnings, or push further for better loot.
• Interactive — After each auto-resolved fight, choose to Continue deeper or Cash Out with your current winnings.
• Tiers — Multiple difficulty tiers with level and prestige requirements.
• Limitations — Arena runs are not resumable. If you close your terminal or interrupt the process before finishing, the run rolls back to the pre-arena state (including your entry fee).

Commands

Contributing

PRs welcome. More monsters, more loot, more zones -- the dungeon is always hiring.

MIT -- do whatever you want with it.

Made with Rust and vibes.