https://github.com/andrewdmaclean/cyc-tinysnake
Companion repo for “Goodbye World, Hello Battlesnake” talk at the 2025 Commit Your Code Conference
https://github.com/andrewdmaclean/cyc-tinysnake
javascript ollama qwen3 tinyhttp
Last synced: about 1 month ago
JSON representation
Companion repo for “Goodbye World, Hello Battlesnake” talk at the 2025 Commit Your Code Conference
- Host: GitHub
- URL: https://github.com/andrewdmaclean/cyc-tinysnake
- Owner: andrewdmaclean
- License: mit
- Created: 2025-09-24T23:59:54.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-25T00:16:08.000Z (9 months ago)
- Last Synced: 2025-09-25T02:32:41.531Z (9 months ago)
- Topics: javascript, ollama, qwen3, tinyhttp
- Language: JavaScript
- Homepage: https://bit.ly/hello-battlesnake
- Size: 9.77 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
Companion repo for **“Goodbye World, Hello Battlesnake”** (Commit Your Code Conference)
This project shows how to build a tiny [tinyhttp](https://github.com/tinyhttp/tinyhttp) Battlesnake server, then add **strategy control over WebSockets** using **Twilio Conversation Relay** and a **local LLM (Ollama)**.
---
## What you need
- **Node.js 18+**
- **pnpm** (preferred): `npm i -g pnpm`
- **ngrok** (to expose `localhost:3000`)
- **Twilio** (Programmable Voice + **Conversation Relay**)
– a Twilio account and a voice-enabled phone number
- **Ollama** (for local LLM):
– run `ollama serve` and pull the required model:
```bash
ollama pull qwen2.5:1.5b
```
Create a `.env` (based on `.env.example`):
```env
NGROK_URL=https://your-subdomain.ngrok.app
```
> `NGROK_URL` is used to form public callback / WS URLs for Twilio & Battlesnake.
---
## Install
```bash
pnpm install
```
---
## Run the demos
Each file in `demo/` is standalone and builds on the previous one:
```bash
# Demo 1: Hello Battlesnake (basic server)
npm run 1
# Demo 2: LLM Move (creative strategy interpretation with qwen2.5:1.5b)
npm run 2
# Demo 3: Voice Control (Twilio voice updates strategy)
npm run 3
# Demo 4: Full Snake (voice + colors + streaming commentary)
npm run 4
# or
npm start
# Development mode (auto-reload)
npm run dev
```
Servers listen on **http://localhost:3000**.
---
## Expose with ngrok
```bash
ngrok http 3000
```
Copy the **https** URL into `.env` as `NGROK_URL`.
---
## Project structure
```
.
├─ demo/
│ ├─ 1-hello.js - Basic Battlesnake server
│ ├─ 2-llmmove.js - LLM-powered movement
│ ├─ 3-voicesnake.js - Voice control via Twilio
│ └─ 4-fullsnake.js - Full implementation with streaming commentary
├─ package.json
├─ .env
└─ README.md
```
## Features
### Demo 4 (Full Snake) includes:
- **Voice-controlled strategy**: Say "go towards where the sun sets" and the LLM interprets it
- **Voice-controlled colors**: Say "Color blue" to change your snake's color
- **Streaming commentary**: AI-generated sports commentary streamed in real-time after each game
- **Educational logging**: Clean emoji-based logs showing what's happening
## Model Used
- **qwen2.5:1.5b**: Handles all tasks - movement strategy, color conversion, and sports commentary generation