<p align="center">
<h1 align="center">shellquest (sq)</h1>
<p align="center">
<strong>A passive RPG that lives in your terminal. Your shell is the dungeon.</strong>
</p>
<p align="center">
<a href="https://crates.io/crates/shellquest"><img src="https://img.shields.io/crates/v/shellquest?style=flat-square&color=orange" alt="Crates.io"></a>
<a href="https://crates.io/crates/shellquest"><img src="https://img.shields.io/crates/d/shellquest?style=flat-square&color=blue" alt="Downloads"></a>
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License: MIT"></a>
<a href="https://github.com/duysqubix/shellquest"><img src="https://img.shields.io/github/stars/duysqubix/shellquest?style=flat-square&color=yellow" alt="Stars"></a>
</p>
</p>
---
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)
```bash
cargo install shellquest
```
### One-liner (auto-setup)
```bash
Clones, builds, installs `sq`, detects your shell, and adds the hook automatically.
### From source
```bash
git clone https://github.com/duysqubix/shellquest.git
cd shellquest
cargo install --path .
sq hook --shell zsh >> ~/.zshrc # or bash/fish
```
> **Requires:** [Rust](https://rustup.rs) (cargo)
---
## Quick Start
```bash
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)
```bash
__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:
| `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
| `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:
| 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.
| `~` | 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.
```bash
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):
| 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
| `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.