codeguessr 0.1.0

A GeoGuessr-style browser game for code

CodeGuessr

A GeoGuessr-style browser game for code. Point it at any local repository and try to identify which file a code snippet came from — before all the clues run out.

The UI is styled to look like VS Code.

---

How it works

Each game consists of several rounds. In every round, a random file from your project is selected and a snippet is shown. The snippet starts almost completely hidden and progressively reveals more code as you make wrong guesses. Click a file in the explorer to guess — the faster you identify it, the more points you earn.

Reveal progression

Wrong guesses	What you see
0	Entire file, all characters replaced with █
1	1 line visible (centered on a key line)
2	7 lines visible
3	17 lines visible
4	31 lines visible
5	Full file, no obscuring

Scoring

Guess attempt	Points
1st (no wrong guesses)	1000
2nd	800
3rd	600
4th	400
5th	200
6th (last chance)	100

---

Supported languages

TypeScript · JavaScript · Python · Go · Rust · Java · C++ · C · Ruby · Swift · Kotlin · C# · PHP

---

Installation

Requirements: Python 3.11+, Node.js 18+

# 1. Clone the repo
git clone <repo-url>
cd codeguessr

# 2. Build the frontend and install the package
make install

# or manually:
cd client && npm install && npm run build -- --output-path=../src/codeguessr/static
cd ..
pip install -e .

---

Usage

# Run against the current directory
codeguessr

# Run against a specific project
codeguessr /path/to/your/project

# Use a different port (default: 4200)
codeguessr --port 8080 /path/to/your/project

The browser opens automatically at http://localhost:4200.

---

Settings

Before each game, a VS Code-style settings screen lets you configure:

Setting	Default	Description
Rounds	5	Number of rounds per game (1–20)
Guesses per round	6	Wrong guesses allowed before the round ends (1–10)
Min lines per file	10	Files shorter than this are excluded (1–500)
Min chars in highlighted line	1	Ensures the focal line has meaningful content (0–200)
Include pattern	(empty)	Regex — only matching file paths are included
Ignore pattern	(empty)	Regex — matching file paths are excluded

Settings are saved to localStorage and restored on next visit.

The include/ignore patterns are applied to relative file paths (forward-slash separated). The game also respects any .gitignore files found in the scanned directory.

---

Development

codeguessr/
├── src/codeguessr/
│   ├── game.py      # Core logic: file scanning, game state, scoring
│   ├── server.py    # FastAPI app — API routes + Angular SPA catch-all
│   ├── cli.py       # Click CLI entry point
│   └── static/      # Built Angular output (generated by make build)
├── client/          # Angular 17 standalone app
│   └── src/app/
│       ├── settings/    # Landing/settings screen
│       ├── game/        # Main game screen
│       └── results/     # End-of-game summary
├── tests/
│   ├── test_game.py # Unit tests for game logic
│   └── test_api.py  # Integration tests for the FastAPI endpoints
├── Makefile
└── pyproject.toml

Running in development

# Terminal 1 — backend (auto-reload)
CODEGUESSR_DIR=/path/to/project uvicorn codeguessr.server:app --reload

# Terminal 2 — frontend (dev server with proxy)
cd client && npm start

Running tests

pip install -e ".[dev]"
pytest

Rebuilding after frontend changes

make build

---

How the backend works

• scan_directory walks the project tree, skips pruned directories (node_modules, .git, __pycache__, etc.), respects .gitignore files at every directory level using pathspec, and returns a sorted list of qualifying relative file paths.
• GameSession holds the round state for one game. Each round stores a randomly chosen file and a "highlight line" picked from the middle 80% of the file. The session lives in an in-memory dict keyed by a UUID.
• /api/game/new re-scans the directory with the settings from the request body, creates a session, and returns the first round's payload.
• /api/game/{id}/guess checks the guess, updates the round state, and returns an updated code display with more lines revealed.
• The Angular SPA is served via a catch-all route registered after the API routes.