Whitespace Zork

A Zen Koan for the unknowing mind.

A text adventure game inspired by Zork, written entirely in Whitespace - an esoteric programming language where the only meaningful characters are spaces, tabs, and newlines.

The Twist

The human collaborator on this project cannot read Whitespace. Neither can anyone else - the code is literally invisible in most editors. This project was built entirely through human-AI collaboration, with the human providing creative direction and testing while the AI (Claude) handled all the programming.

Playing the Game

python3 ws.py zork.ws

Then type commands like:

• look, inventory, north, south, east, west
• open mailbox, take lamp, light lamp
• help or ? for a full command list

How This Was Built: A Collaboration Story

Timeline

This entire project was built in a single session of ~1 hour - from "Can you help me write something in Whitespace?" to a working, tested game pushed to GitHub.

Based on file timestamps:

• 13:17 - First Whitespace file created
• 13:23 - Custom assembler written
• 13:31 - Custom interpreter written
• 13:53 - Final game compilation
• 14:03 - Pushed to GitHub

That's ~52 minutes from first code to working repository.

Note: The human operator was multitasking throughout - participating in a Slack huddle and working on other things. A focused session would have been even faster. Actual human attention was minimal, demonstrating the value of autonomous AI iteration.

During that session, Claude:

• Designed the game architecture
• Created a custom assembler (wsasm.py) to compile readable code to Whitespace
• Created a Whitespace interpreter (ws.py) to run the game
• Wrote ~1,800 lines of assembly that compiles to 82,398 characters of Whitespace
• Debugged multiple parser, interpreter, and game logic issues
• Completed a full playthrough, collecting the treasure:

> take treasure
Taken.
You feel a sense of accomplishment!

> inventory
You are carrying:
  A leaflet
  A brass lantern (lit)
  An elvish sword
  A rusty key
  A golden treasure

The Challenge

The human collaborator came to Claude with a simple request: "Can you help me write something in Whitespace?"

The challenge: build something non-trivial in a language where:

• All code is invisible (only spaces, tabs, newlines)
• The human cannot read, write, or debug any code
• Traditional code review is impossible

The Process

1. Ideation (Human-Led)

The human collaborator drove the creative vision:

• Rejected simple examples in favor of something "complicated"
• Chose a text adventure game inspired by Zork
• Insisted on authentic Zork-like features: full word parsing, room descriptions, puzzles
• Pushed back on shortcuts: "harder is a YOU problem claude"

2. Architecture (AI-Led)

Claude designed the technical architecture:

• Memory layout (heap addresses for game state, inventory, input buffer)
• Room connection graph (10 interconnected locations)
• Command parser (handles both N and north, O MAILBOX and open mailbox)
• Game mechanics (light/dark, troll puzzle, item interactions)

3. Development Toolchain

Since Whitespace is unreadable, Claude created an entire toolchain from scratch:

The Assembler (wsasm.py):

• Invented a human-readable assembly format (.wsa)
• Supports labels, subroutines, all Whitespace instructions
• Added a prints "string" macro for easier text output
• Compiles to pure Whitespace (spaces, tabs, newlines only)

The Interpreter (ws.py):

• Full Whitespace implementation (stack, heap, arithmetic, I/O, flow control)
• Initially had bugs (wrong instruction parsing for arithmetic, end instruction)
• Debugged by tracing through invisible code
• The pip-installable whitespace interpreter couldn't handle our 82K program (recursion limit), so we needed our own

The human collaborator asked: "Do you even need the .wsa file? Can't you just write .ws directly?"

Claude's answer: Technically yes (the whitespace characters ARE visible when reading the file), but it would be like editing machine code in hex - possible but impractical. The assembler made development 100x faster.

4. Testing & The Feedback Loop

The human collaborator tested once and reported:

> open mailbox
Open what?

"This isn't working..."

Then came the key insight: "Can you run it and test it yourself?"

This created an autonomous feedback loop where Claude could:

1. Run the game
2. See the actual output
3. Identify bugs from behavior
4. Fix the code
5. Recompile and test again
6. Repeat until working

The human stepped out of the loop. Claude self-tested dozens of iterations:

• Parser looking at fixed character positions → rewrote word-finding logic
• end instruction consuming wrong number of newlines → fixed interpreter
• Lowercase commands not recognized → added full lowercase support
• LIGHT command routing to LOOK → fixed command disambiguation
• Game showing "Congratulations" on quit → fixed flag logic

The human only returned to verify the final result worked. This rapid, autonomous iteration - AI testing its own output - was crucial to completing a complex project quickly.

5. Debugging Invisible Code

When bugs occurred, Claude had to:

• Trace through the Whitespace instruction sequences
• Add debug output to the interpreter
• Identify issues like the end instruction consuming wrong number of newlines
• Fix the assembler/interpreter compatibility issues

The human never saw a line of Whitespace code - only the game's behavior.

Key Insights

What worked well:

• Human as "product owner" - clear vision, quality standards, initial direction
• AI as "developer" - architecture, implementation, debugging, AND testing
• Autonomous feedback loop - AI runs code, sees results, iterates without human intervention
• Speed through self-testing - dozens of iterations happened while human was hands-off
• The .wsa intermediate format - essential for AI to work effectively

What was challenging:

• Debugging parser issues when input format varied (O MAILBOX vs OPEN MAILBOX)
• Interpreter bugs that caused silent failures
• Initial tooling (pip's whitespace interpreter hit recursion limits)

What this demonstrates:

• AI can handle implementation details in languages humans can't read
• Creating a feedback loop is more valuable than staying in the loop - the human's job was to establish the pattern, then step back
• Effective collaboration doesn't require the human to understand the code
• Testing through behavior (running the game) is sufficient for quality
• The human's role shifts from "writing code" to "defining success criteria and enabling autonomous iteration"

Technical Details

File Structure

├── zork.ws      # The game (82,398 characters of invisible Whitespace)
├── zork.wsa     # Human-readable assembly source
├── ws.py        # Whitespace interpreter
├── wsasm.py     # Whitespace assembler (.wsa → .ws)
└── README.md

Game Features

• 10 rooms with descriptions and connections
• 6 collectible items (leaflet, lamp, sword, key, food, treasure)
• Light/dark mechanics (grue!)
• Troll puzzle (feed or fight)
• Full word command parsing
• Help system

Whitespace Language

Whitespace uses three characters:

• Space - binary 0, stack operations
• Tab - binary 1, arithmetic/heap/IO
• Newline - flow control

Everything else is a comment (ignored).

The zork.ws file looks empty in most editors but contains:

• ~11,000 instructions
• ~120 labels
• Complete game logic

Running Tests

There's no traditional test suite. Testing was done by playing:

# Quick smoke test
echo -e "help\nquit" | python3 ws.py zork.ws

# Full playthrough
printf "open mailbox\ntake leaflet\nnorth\neast\ndown\ntake lamp\ntake food\ndown\ntake sword\nopen trapdoor\nlight lamp\ndown\ntake key\nnorth\nfeed troll\nnorth\neast\ntake treasure\ninventory\nquit\n" | python3 ws.py zork.ws

Credits

• Game Design & Orchestration: Human operator
• Implementation & Testing: Claude (AI)
• Original Zork Inspiration: Infocom (1980)
• Whitespace Language: Edwin Brady and Chris Morris (2003)
• "Zen Koan for the unknowing mind": Thanks to @sighup for the words

License

MIT

---

Built with invisible code and visible collaboration.