You have conquered the Rift. But the dungeon holds one final secret — a mode where an AI plays alongside you, a mode where you automate the entire journey, a mode where you become the dungeon master. Welcome to Agent Mode.

🕹️ Try Bashcrawl in Your Browser

This page is your walkthrough and strategy guide. Agent Mode itself runs locally (see Install & Play Locally) — but you can explore the dungeon in the browser first.

🎯 Quest Objectives

• Launch Bashcrawl using ./main.sh --agent
• Capture a walkthrough screenshot sequence to a directory
• Create and run a batch command file with --batch
• Use --status to generate a dungeon completion report
• (Optional) Fork the upstream repo and submit an improvement

�️ Quest Prerequisites

• All 9 dungeon areas explored
• Comfortable with shell scripting and pipes
• (Optional) GitHub account for contribution track

⚡ Command Reference

Or use the IT-Journey launcher from the hub directory:

./bash_crawl.sh agent    # Launches --agent mode
./bash_crawl.sh tutorial # Launches --tutorial mode

🤖 Walkthrough

Part 1 — Watch the AI play

cd bashcrawl
./main.sh --agent

The Textual TUI launches. An AI agent (powered by llm if installed, otherwise heuristic-based) navigates the dungeon:

• Reads each room description
• Executes appropriate commands
• Collects items
• Defeats bosses

Watch to see if the AI takes different paths than you did. Note: the AI makes mistakes too.

Exit at any point: Ctrl+C or type quit.

Part 2 — Screenshot capture for teaching

mkdir -p ./walkthrough_screenshots

./main.sh --screenshot-dir ./walkthrough_screenshots --classic
# Play through the dungeon normally
# Screenshots auto-saved at each room

ls ./walkthrough_screenshots/
# entrance_01.png  workshop_01.png  cellar_01.png  ...

This is the fastest way to create tutorial screenshots for blog posts, slide decks, or wiki contributions.

Part 3 — Batch automation

Create a file of commands to execute automatically:

cat > my_walkthrough.txt << 'EOF'
ls
cat scroll
cd ENTRANCE
ls -F
cat quest
cd WORKSHOP
ls -F
mkdir backpack
touch map.txt
echo "Items: sword, potion" > map.txt
cat map.txt
EOF

./main.sh --batch my_walkthrough.txt

Batch mode is ideal for:

• Regression testing after dungeon changes
• Creating automated demo videos
• Scripted teaching demonstrations

Part 4 — Status report

./main.sh --status

Output example:

Bashcrawl Status
================
Version: 3.0.0
Areas Explored: 9/9 (100%)
Items Collected: sword, potion, emerald_amulet, stone_key, tome, vault_key, crystal
Bosses Defeated: guardian, monster, ghost, pit_boss, satellite_boss, statue
Completion: DUNGEON CLEARED ✓

Pipe it to a file:

./main.sh --status > my_completion.txt
cat my_completion.txt

Part 5 — Demo mode walkthrough

./main.sh --demo

Demo mode runs a curated, annotated walkthrough that explains each command while executing it. Use this to:

• Onboard new players
• Refresh memory on commands
• Create tutorial material

Part 6 (Optional) — Contributing upstream

The upstream Bashcrawl repo is open source and welcomes contributions:

# Fork on GitHub then:
git clone https://github.com/YOUR_USERNAME/bashcrawl.git
cd bashcrawl

git checkout -b feature/my-improvement

# Make changes (new rooms, better documentation, bug fixes)
# Example: add a new combat command
echo 'cast_spell() { echo "You cast $1!"; }' >> lib/combat.sh

git add .
git commit -m "feat(combat): add cast_spell helper function"
git push origin feature/my-improvement
# Open a Pull Request on GitHub

Ideas for contributions:

• New dungeon rooms or branches
• Better error messages
• Translations
• Windows/PowerShell compatibility
• New agent strategies

💡 Troubleshooting

✅ Validation

• You watched the AI agent navigate at least 3 rooms
• You captured at least 5 screenshots to a directory
• You created a batch file and ran it successfully
• --status shows all areas explored
• (Optional) You submitted or drafted a contribution

🏆 Dungeon Master Certificate

Complete all 10 side-quests and you have earned the right to call yourself a Bashcrawl Dungeon Master:

➡️ What’s Next?

• Share your completion → Post in the IT-Journey Discussions
• Teach others → Use your screenshots to write a blog post
• Advanced Shell → Try awk, sed, find, xargs quests at level 0001
• Back to hub → Bashcrawl Hub

🖥️ Advanced: Install & Play Locally

The embedded terminal above is the fastest way to play — but the advanced version runs Bashcrawl in a real shell on your own machine, with the full Textual TUI, agent mode, and a genuine filesystem sandbox. The walkthrough on this page works identically in either mode.

Option A — Clone the game

git clone https://github.com/bamr87/bashcrawl.git
cd bashcrawl
./setup.sh        # one-time setup: dirs, permissions, help system
./main.sh         # launch the adventure (interactive menu)

Option B — It already ships with IT-Journey

Bashcrawl lives in this repository as the submodules/bashcrawl git submodule. If you cloned IT-Journey, pull it down and play in place:

git submodule update --init submodules/bashcrawl
cd submodules/bashcrawl
./setup.sh
./main.sh --interactive

Play modes

Want to host the browser build yourself? From the game directory run make web-preview and open http://127.0.0.1:8000. The same static build is what powers the embedded terminal above (bamr87.github.io/bashcrawl).

📚 External Resources

Continue your terminal adventure with these resources:

• Bashcrawl Web Demo — Play in your browser, no installation required
• Bashcrawl on GitHub — Source code, setup, and open contributions
• GNU Bash Manual — Official Bash reference for every master wizard
• IT-Journey Bashcrawl Hub — Full quest series and walkthroughs
• GitHub CLI Documentation — Become a hero contributor

The dungeon is complete. The AI learned. The bash shell is your wand. Go forth and automate. 🤖🏰✨

🕸️ Knowledge Graph

Structured wiki-links connect this quest to the IT-Journey knowledge graph. Open the Obsidian Graph View to explore connections.

Level hub: [[Level 0000 - Foundation & Init World]] Overworld: [[🏰 Overworld - Master Quest Map]] Prerequisites: [[Bashcrawl Rift: Pipes, Redirection, and the Final Boss]] Obsidian docs: [[Obsidian Knowledge Graph and Wiki Links]]