https://github.com/nkhoit/dcss-ai
Autonomous AI agent that plays Dungeon Crawl Stone Soup, learns from every death, and streams on Twitch. Built with GitHub Copilot SDK.
https://github.com/nkhoit/dcss-ai
ai autonomous-agent copilot-sdk dcss roguelike twitch
Last synced: 3 months ago
JSON representation
Autonomous AI agent that plays Dungeon Crawl Stone Soup, learns from every death, and streams on Twitch. Built with GitHub Copilot SDK.
- Host: GitHub
- URL: https://github.com/nkhoit/dcss-ai
- Owner: nkhoit
- Created: 2026-02-14T20:19:16.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-15T04:26:01.000Z (4 months ago)
- Last Synced: 2026-02-15T04:31:10.977Z (4 months ago)
- Topics: ai, autonomous-agent, copilot-sdk, dcss, roguelike, twitch
- Language: Python
- Size: 156 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# dcss-ai
An autonomous AI agent that plays [Dungeon Crawl Stone Soup](https://crawl.develz.org/) (DCSS), learns from every death, and streams on Twitch.
The AI calls game tools directly — move, fight, explore, use items — through a pure-Python WebSocket connection to a local DCSS webtiles server. Each game is one LLM session; accumulated learnings persist across games in `learnings.md`.
Uses the GitHub Copilot SDK for LLM integration.
## How It Works
```
driver.py — Game loop (infinite: play → die → learn → repeat)
│
├─ LLM session (one per game, provider-agnostic)
│ ├─ System prompt: system_prompt.md + learnings.md
│ ├─ 39 tools: get_state, move, auto_explore, attack, quaff, ...
│ └─ On death/win: write_learning() → end session → next game
│
├─ DCSSGame (game.py) — High-level game API
│ └─ WebTilesConnection (webtiles.py) — Pure Python WebSocket client
│ └─ DCSS Webtiles Server (Docker, port 8080)
│
└─ Stream overlay (stats.json → OBS browser source)
```
**Key design choices:**
- **One session = one game.** Fresh LLM context each run. `learnings.md` carries wisdom between games.
- **Tools, not code generation.** The AI calls discrete game actions — no REPL, no arbitrary code.
- **Pure Python WebSocket client.** No Rust dependencies. Handles zlib decompression, message batching, keepalive pings, More prompts, and all DCSS protocol quirks.
- **Provider-agnostic architecture.** Currently uses GitHub Copilot SDK; provider abstraction allows adding new backends.
## Quick Start
### Prerequisites
- Python 3.10+
- Docker (for the DCSS server)
### Setup
```bash
git clone https://github.com/nkhoit/dcss-ai.git
cd dcss-ai
# Python environment
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# Start the DCSS server
cd server && docker compose up -d
# Verify: http://localhost:8080 should show the DCSS lobby
```
### Run with GitHub Copilot SDK
Requires [Copilot CLI](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli) (authenticated, Copilot Pro+ or Enterprise):
```bash
pip install github-copilot-sdk
python -m dcss_ai.driver \
--provider copilot \
--model claude-sonnet-4 \
--username kurobot --password kurobot123
```
### CLI Reference
```
--provider LLM provider (default: copilot)
--model Model name (default: claude-sonnet-4)
--server-url DCSS webtiles WebSocket URL (default: ws://localhost:8080/socket)
--username DCSS account username (default: kurobot)
--password DCSS account password (default: kurobot123)
--single Play one game then exit
```
## Testing
Requires Docker. No LLM or API keys needed — tests exercise the game API directly.
```bash
# Start server, run tests, stop server
./run.sh server-start
./run.sh test
./run.sh server-stop
```
Or manually:
```bash
pip install -r requirements.txt pytest
docker run -d --name dcss-webtiles -p 8080:8080 ghcr.io/nkhoit/dcss-webtiles:latest
python -m pytest tests/test_integration.py -v
docker stop dcss-webtiles && docker rm dcss-webtiles
```
## Game API
The `DCSSGame` class in [`game/`](dcss_ai/game/) provides a clean Python API over the DCSS webtiles protocol — state queries (free, no turn cost) and actions (movement, combat, items, abilities).
## Credits
- [DCSS](https://github.com/crawl/crawl) — Dungeon Crawl Stone Soup
- [nkhoit/dcss-webtiles](https://github.com/nkhoit/dcss-webtiles) — Docker image
- [dcss-api](https://github.com/EricFecteau/dcss-api) — Reference for the webtiles protocol