README
¶
FileSystem Ghost
A Cyberpunk Command Learning Game
Welcome, Ghost
"In the digital shadows, we are invisible. In the system, we are everywhere."
— Ghost Protocol Manifesto
The year is 2077. Mega-corporations control the digital infrastructure. Privacy is extinct. Freedom is a memory.
You are a Ghost. Not a hacker, not a criminal — a digital freedom fighter. Part of an elite collective that operates in the shadows of cyberspace, dismantling corporate tyranny one system at a time.
Your latest mission: Infiltrate a high-security corporate server. You've materialized as a rogue process deep in their infrastructure. Your objective is clear — escalate privileges, retrieve classified data, and ghost out before security traces you.
But there's a catch: You must master the Unix command line. Every command is a tool. Every directory is a battlefield. Every file could be your salvation... or your detection.
Are you ready to join the Ghost collective?
About the Mission
FileSystem Ghost is not just a game — it's your training ground. An immersive, cyberpunk-themed terminal experience where you learn real Linux commands through high-stakes stealth missions.
As a Ghost operative, you'll:
- Infiltrate secured systems using authentic Unix commands
- Evade AI security processes that hunt intruders
- Navigate complex file structures to find classified intel
- Crack permissions and escalate to Root access
- Execute flawless exfiltrations before they lock you down
This is hands-on learning disguised as a cyberpunk heist. By the time you complete Ghost Protocol, you'll command the terminal like a pro.
Mission Features
- Immersive Hacker Interface - Full cyberpunk aesthetic with real-time glitch effects and terminal animations
- Real Skills, Real Commands - Master 20+ authentic Linux commands that work in actual systems
- Stealth-Based Gameplay - Evade AI sentinels, avoid detection, stay invisible
- 9 Escalating Levels - From rookie infiltrations to elite Ghost Protocol missions
- Smart Command Assist - Fish-style autocompletion helps you learn faster
- Dynamic Objectives - Crack vaults, decode files, manipulate permissions, eliminate threats
- 6 Visual Themes - Red Hacker, Green Matrix, Cyan Tron, Amber Retro, Magenta CP77, Blue Neon
- Customizable Difficulty - Adjust alert speeds, hints, and challenge levels
- Progressive Skill Tree - Unlock new commands as you prove your worth
- Responsive Design - Adapts to any terminal size from 80x24 to ultrawide
- Ambient Music System - Optional cyberpunk soundtrack with customizable playback (random, sequential, or specific track)
The Ghost Collective
Who Are We?
We are Ghost — a decentralized collective of digital freedom fighters operating in the shadows of cyberspace. No leaders. No headquarters. Just skilled operatives united by a common cause: dismantling corporate surveillance and restoring digital freedom.
The Ghost Code
1. LEAVE NO TRACE — Ghost in, ghost out. Invisible.
2. ESCALATE PRIVILEGES — From guest to root. Always.
3. KNOWLEDGE IS POWER — Master the terminal. Own the system.
4. ADAPT OR DIE — Every system is different. Learn fast.
5. THE MISSION COMES FIRST — Extract data. Expose corruption.
Your Training Path
| Level | Codename | Mission | Skills Unlocked |
|---|---|---|---|
| 1 | Awakening | First infiltration | ls, cd, pwd, cat |
| 2 | The Archive | Data mining | grep, File navigation |
| 3 | Infiltration | Stealth operations | mkdir, touch, rm, mv, cp |
| 4 | The Firewall | System takeover | chmod, ps, kill, Root access |
| 5 | Data Center | Complex navigation | find, head, tail, wc |
| 6 | The Network | SSH exploitation | echo, env, Advanced search |
| 7 | The Honeypot | Deception detection | diff, file, Pattern analysis |
| 8 | The Crypt | Permission hacking | stat, Permission mastery |
| 9 | Ghost Protocol | Ultimate challenge | All skills, Maximum stealth |
Complete all 9 levels to become a certified Ghost operative.
Join the Collective
Initiate Ghost Protocol (One Command)
go install github.com/sazardev/filesystem-ghost/cmd/ghost@latest
Congratulations, Ghost. You're in. Now activate your terminal:
ghost
Note:
go installonly installs the binary. For music support, see the Music Setup section below.
First time? The game includes a built-in tutorial. Just select "New Game" and follow the missions.
From Source (Recommended - Includes Music)
# Clone the repository
git clone https://github.com/sazardev/filesystem-ghost.git
cd filesystem-ghost
# Install with script (includes music assets)
./install.sh
# Or with make
make install
Script Install (Alternative)
curl -sSL https://raw.githubusercontent.com/sazardev/filesystem-ghost/main/install.sh | bash
This method automatically installs music assets to ~/.local/share/filesystem-ghost/music/.
Requirements
- Go 1.21+ (for building from source)
- Terminal with 256-color support
- Minimum size: 80x24 characters (recommended: 120x40)
Supported Platforms
| Platform | Architecture | Status |
|---|---|---|
| Linux | amd64, arm64 | Fully Supported |
| macOS | amd64, arm64 | Fully Supported |
| Windows | amd64 | Experimental (use WSL) |
🎵 Music System
The game includes 6 cyberpunk ambient tracks embedded directly in the binary. No additional setup required!
Music Controls (In-Game)
Access music settings from the main menu: Settings → Music
| Setting | Options |
|---|---|
| Music Mode | OFF, RANDOM, SEQUENTIAL, SINGLE |
| Music Track | Select specific track (for SINGLE mode) |
| Music Volume | 0% - 100% |
Using Custom Music (Optional)
If you want to use your own MP3 files instead of the embedded tracks, place them in one of these directories:
~/.local/share/filesystem-ghost/music/~/.config/filesystem-ghost/music/~/Music/filesystem-ghost/
External music files take priority over embedded tracks.
Operative Training
Terminal Controls (Memorize These)
| Key | Action |
|---|---|
Enter |
Execute command |
Tab |
Autocomplete / Cycle suggestions |
→ |
Accept inline suggestion |
↑/↓ |
Navigate command history |
Ctrl+C |
Quit game |
Essential Commands (Your Toolkit)
# RECONNAISSANCE
ls # Scan directory contents
ls -la # Reveal hidden files (critical for finding keys)
pwd # Confirm your location
# NAVIGATION
cd <folder> # Move to target directory
cd .. # Retreat one level
cd / # Return to root
# INTELLIGENCE GATHERING
cat <file> # Read file contents (intel, keys, clues)
grep <pattern> # Search for keywords in files
# FILE MANIPULATION (Advanced)
mkdir <name> # Create directories (hideouts)
touch <file> # Create decoy files
rm <file> # Delete files (cover your tracks)
mv <src> <dst> # Move files (plant evidence)
cp <src> <dst> # Copy files (backup intel)
# SYSTEM CONTROL (Expert)
chmod <mode> <file> # Change permissions (break locks)
ps # List running processes (identify threats)
kill -9 <PID> # Terminate hostile processes
# MISSION COMMANDS
status # Check your infiltration progress
inventory # View acquired keys and intel
disconnect # Complete current objective and exfiltrate
help # Access command database
Ghost Survival Guide
┌─────────────────────────────────────────────────────────────┐
│ RULE #1: RECONNAISSANCE IS EVERYTHING │
│ → Always 'ls -la' first. Hidden files contain keys. │
│ │
│ RULE #2: READ ALL INTEL │
│ → 'cat' every file. Clues are everywhere. │
│ │
│ RULE #3: STEALTH IS SURVIVAL │
│ → Watch your alert level. High noise = detection = failure.│
│ │
│ RULE #4: ADAPT YOUR TACTICS │
│ → Each level requires different strategies. Think. │
│ │
│ RULE #5: SECURE THE KEY BEFORE EXFIL │
│ → Find all keys before 'disconnect'. No second chances. │
└─────────────────────────────────────────────────────────────┘
Pro Operative Tips
- Hidden directories start with
.— always check withls -a - Multiple keys may be required per level — explore thoroughly
- Hostile processes increase detection — eliminate or avoid them
- Noise level builds up — minimize unnecessary commands
- Save progress by returning to menu with
disconnect --menu
Mission Briefing
Training Progression
| Phase | Operation | Available Tools | Primary Objective |
|---|---|---|---|
| Phase 1 | Awakening | ls, cd, cat, pwd |
Learn navigation & reconnaissance |
| Phase 2 | The Archive | + grep, advanced search |
Intelligence gathering & pattern analysis |
| Phase 3 | Infiltration | + mkdir, touch, rm, mv, cp |
File manipulation & stealth tactics |
| Phase 4 | The Firewall | + chmod, ps, kill |
System control & threat elimination |
| Phase 5-9 | Elite Ops | All commands unlocked | Master-level infiltrations |
Skill Development Path
Rookie Ghost → Learn basic navigation
↓
Junior Operative → Master file reconnaissance
↓
Field Agent → Execute stealth operations
↓
Senior Infiltrator → Control system processes
↓
Elite Ghost → Complete Ghost Protocol
Why Join Ghost?
For Beginners
"I've never used a terminal before"
Perfect. Ghost teaches you from absolute zero. By Level 3, you'll be navigating like a pro. By Level 9, you'll be a command-line warrior.
For Students
"I need to learn Linux for school/work"
Stop watching tutorials. Start hacking. Ghost makes Linux commands stick through immersive gameplay and real-world scenarios.
For Developers
"I want to sharpen my Unix skills"
Challenge yourself with 9 progressively complex missions. Master file permissions, process management, and system navigation under pressure.
For Gamers
"I want a real hacking experience"
This isn't a point-and-click adventure. Every command is typed. Every decision matters. Get detected, lose. Master stealth, win.
Development
Build Commands
make help # Show all available commands
make build # Build for current platform
make dev # Build with debug info
make run # Build and run
make test # Run tests
make clean # Clean build artifacts
make release # Build for all platforms
make install # Install system-wide (sudo)
make uninstall # Remove from system
Project Structure
filesystem-ghost/
├── cmd/ghost/ # Main entry point
├── internal/
│ ├── adapter/
│ │ ├── commands/ # Command handler
│ │ ├── filesystem/ # Virtual filesystem
│ │ └── ui/ # TUI components
│ ├── application/
│ │ └── levels/ # Level definitions
│ └── domain/
│ └── entity/ # Game entities
├── Makefile # Build automation
├── install.sh # Quick install script
└── README.md
Tech Stack
- Bubble Tea - TUI framework
- Lip Gloss - Terminal styling
- Bubbles - TUI components
- Afero - Virtual filesystem
Join the Community
Become a Contributor
The Ghost collective is always recruiting talented operatives. Whether you're a coder, designer, or security expert — we need you.
Ways to contribute:
- Report bugs and security vulnerabilities
- Suggest new levels or game mechanics
- Design new terminal themes
- Improve documentation and tutorials
- Translate to other languages
- Star the repo to support the mission
# Fork and clone
git clone https://github.com/YOUR_USERNAME/filesystem-ghost.git
cd filesystem-ghost
# Create a feature branch
git checkout -b feature/your-ghost-operation
# Make your changes and commit
git commit -m "feat: Add new stealth mechanic"
# Push and create PR
git push origin feature/your-ghost-operation
Share Your Success
Completed Ghost Protocol? Share your victory!
- Tweet with
#FileSystemGhostand#LinuxLearning - Share screenshots of your favorite levels
- Help other operatives in GitHub Discussions
- Create video walkthroughs or tutorials
License
This project is licensed under the MIT License - see the LICENSE file for details.
Free to use. Free to learn. Free to hack.
Credits & Acknowledgments
Built by Ghosts, for Ghosts.
- Technology: Charm.sh for exceptional TUI libraries
- Inspiration: The Linux community and the eternal pursuit of digital freedom
- Aesthetic: Cyberpunk culture, hacker ethics, and terminal art
Special Thanks
To every developer who ever said "just use the command line" without explaining how. This game is the explanation they never gave.
Stay Connected
- Website: github.com/sazardev/filesystem-ghost
- Issues: Report bugs or request features
- Discussions: Join the community
- Star: Show support and track updates
GHOST PROTOCOL ACTIVE
Leave no trace. Master the terminal. Own the system.
Ready to infiltrate? Type `ghost` and begin your mission.
Built with terminal commands | 2026 | MIT License
Directories