From Repository to Roguelike: Your Step-by-Step Guide to Building a Codebase Dungeon with GitHub Copilot CLI

By ✦ min read

Introduction

Ever wondered what your codebase would look like as a dungeon? With the help of GitHub Copilot CLI, you can transform any repository into a playable roguelike adventure. This guide walks you through the process, from setting up your environment to exploring procedurally generated rooms and corridors. By the end, you’ll have a terminal-based game where each commit reshapes the dungeon layout—and where permadeath means every run counts.

What You Need

• Go (version 1.18 or later) – The game is written in Go, so you’ll need the language installed. Download from golang.org.
• GitHub CLI (gh) – Required to authenticate and interact with repositories. Install via brew install gh or from cli.github.com.
• GitHub Copilot CLI – This is the secret sauce. Install the Copilot CLI extension for your terminal. Run gh extension install github/gh-copilot.
• A Git repository to convert – Any local repo works. The dungeon layout is seeded by the latest commit SHA, so different repos produce unique maps.
• Terminal emulator with color support – For rendering rooms and enemies. Most modern terminals (iTerm2, Windows Terminal, GNOME Terminal) work fine.

Step-by-Step Guide

1. Set Up Your Project Directory

   Create a new folder for your dungeon generator and initialize a Go module:

   mkdir github-dungeons
   cd github-dungeons
   go mod init github.com/yourusername/github-dungeons

   This isolates your code and makes it easy to manage dependencies.

2. Generate the Core Utilities with Copilot CLI

   Open a terminal and use Copilot CLI to scaffold basic functions. For example, ask it to create a function that reads the latest commit SHA from a repository:

   gh copilot suggest "Write a Go function that returns the SHA of the latest commit in the current git repo"

   Copilot will produce code you can copy into your main.go. Accept or modify as needed. Use the /yolo flag (short for /allow-all) to auto-accept all suggestions if you’re feeling adventurous. Remember: in roguelike spirit, /yolo means you only live once!

3. Implement Binary Space Partitioning (BSP) for Dungeon Layout

   The dungeon rooms and corridors are generated using a classic algorithm: Binary Space Partitioning. BSP recursively splits a rectangular area into smaller rectangles, creating rooms and connecting them with corridors. Here’s how to seed the algorithm with your repo’s commit SHA:

   • Use the commit SHA as a random seed (rand.NewSource() in Go).
   • Define a leaf node class that holds a rectangle (x, y, width, height).
   • Recursively split leaves until they reach a minimum size (e.g., 6×6).
   • For each leaf, carve a room (slightly smaller inside the rectangle).
   • Connect sibling leaves with an L-shaped corridor.

   Copilot CLI can help you write the BSP logic. Try: “Write a Go function that performs BSP on a given rectangle and returns a list of rooms.”

4. Design the Player, Enemies, and Permadeath Mechanics

   Roguelikes need a hero, monsters, and the risk of permanent death. Define structures for player stats (HP, position), enemy types (bugs, code smells), and a game loop.

   • Player: Start with 10 HP. Move with arrow keys. Colliding with an enemy reduces HP.
   • Enemies: Spawn randomly in rooms not adjacent to the player. Each enemy deals 1–3 damage.
   • Permadeath: When HP reaches 0, display a game-over message and exit. No continues.

   Use Copilot to generate the input handling: “Write Go code that reads arrow keys and updates player position.”

   

5. Render the Dungeon in the Terminal

   You’ll need to draw walls (#), floors (.), the player (@), and enemies (E). Use a 2D array of runes and print it after each move. For a polished look, clear the screen between frames (use ANSI escape codes or the clear command).

   Copilot suggestion: “Create a Go function that prints a 2D character array to the terminal with clear screen.”

6. Wire Everything Together and Test

   Now integrate the pieces: main function reads the repo’s latest commit SHA, seeds the BSP generator, builds the map, spawns player and enemies, then starts the game loop. Test with different repositories to ensure the dungeon changes with each commit.

   Run your extension: go run . inside your repo. Navigate with arrow keys, fight bugs, and find the exit (a special tile that ends the level).

7. Package as a GitHub CLI Extension (Optional)

   To share your creation, package it as a gh extension. Create a new GitHub repo with your code, then run:

   gh extension create github-dungeons

   Place your Go binary in the repository root and follow the extension manifest guidelines. Now others can install it with gh extension install yourusername/github-dungeons.

Tips and Tricks

• Start simple – Get a single room working before adding corridors and enemies. Iterate using Copilot’s suggestions to fill in details.
• Embrace /yolo but be ready to debug – Copilot CLI’s auto-accept mode is great for rapid prototyping, but always review generated code for logic errors.
• Use commit SHAs creatively – You can also seed random functions for enemy placement, item drops, or treasure locations. Every commit becomes a unique adventure.
• Optimize rendering – For large repositories, limit dungeon size to keep the game responsive. A 40×20 grid works well.
• Learn from the classics – Study the Berlin Interpretation of roguelikes for inspiration: permadeath, turn-based movement, procedural generation, and resource management.
• Have fun with flavor – Name enemies after common code bugs (“NullPointer”, “Typo Gremlin”). Rename rooms after modules or files.

Now go forth and explore your codebase like never before. Happy dungeon crawling!