Architecting Procedural Worlds: How GitHub Dungeons Uses BSP and Agentic Workflows

The intersection of software engineering and game design often yields unexpected results. In a recent experiment, Lee Reilly utilized the GitHub Copilot CLI to build "GitHub Dungeons," a terminal-based roguelike where the game world is not designed by hand, but generated algorithmically from the structure of a Git repository. This project serves as a practical case study in two distinct technical domains: procedural content generation (PCG) and agentic developer workflows.

The Engine: Binary Space Partitioning (BSP)

At the core of any roguelike is the dungeon. To avoid the pitfalls of pure randomness—which often results in disconnected rooms or impassable walls—GitHub Dungeons employs Binary Space Partitioning (BSP).

BSP is a method of recursive subdivision. Instead of placing rooms randomly on a grid, the algorithm starts with a single large container representing the entire playable area. It then splits this container into two smaller rectangles, either horizontally or vertically. This process repeats recursively for each new sub-region until the areas reach a predefined minimum size.

This creates a tree structure of "leaf" nodes. Each leaf represents a potential room. To ensure the dungeon feels organic rather than a rigid grid, the implementation introduces slight randomness in the size and position of the rooms within those leaves. Finally, the algorithm traverses the tree to connect sibling nodes with L-shaped corridors, guaranteeing that every room is reachable from any other room.

This approach offers several architectural advantages:

• Guaranteed Connectivity: Because the corridors follow the tree structure, the map is mathematically certain to be navigable.
• Structured Chaos: The combination of recursive splitting and randomized room placement prevents the layout from feeling predictable.
• Deterministic Seeding: By using the latest repository commit SHA as the seed for the random number generator, the dungeon becomes a functional representation of the code. The same commit always produces the same map, but a single new commit reshapes the entire architecture.

The Workflow: Agentic Development with /delegate

Beyond the algorithm, the development of GitHub Dungeons highlights a shift in how software is built when using agentic AI tools. Rather than traditional line-by-line coding, the project utilized the /delegate command within the Copilot CLI.

In a standard IDE experience, a developer provides autocompletion suggestions. In an agentic workflow, the developer describes a high-level behavior and hands the task to a cloud-based coding agent. For example, the developer could issue a command like: /delegate Make each level progressively harder by increasing enemy density and decreasing health potion frequency.

This shifts the developer's role from a writer of syntax to a reviewer of intent. The agent operates asynchronously, performing the heavy lifting of scaffolding, implementing logic, and eventually opening a pull request. This allowed the creator to maintain a "game design mindset," focusing on balance and player experience while the agent handled the boilerplate of Go implementation and YAML configuration.

Trade-offs and Implementation Risks

While the project demonstrates the power of these tools, it also highlights the risks of tightly coupling development tools with destructive actions. The project includes a "crazy mode" that uses a Git pre-commit hook to delete uncommitted changes if the player fails to beat the dungeon.

From an architectural standpoint, this is a high-risk integration. While it creates a compelling (if punishing) loop for a game, in a production environment, such automation can lead to irreversible data loss. It serves as a reminder that as we move toward more autonomous, agent-driven workflows, the guardrails around "write" operations must remain strictly defined.

Getting Started

For those interested in seeing their own repository transformed into a dungeon, the extension can be installed via the GitHub CLI:

gh extension install leereilly/gh-dungeons

Once installed, running gh dungeons will initiate the generation process, turning your current directory into a playable, terminal-based adventure.