🏡 Liltown

A cozy terminal village where AI characters live, chat, and build relationships — all powered by your own LLM.

Watch 8 unique villagers go about their day in a beautiful terminal scene. They chat, work, and form friendships — all generated by your LLM. It's like a cozy screensaver for your terminal, but alive.

✨ Features

• 🎨 Beautiful Terminal UI — Rich-powered ASCII art village with live updates
• 👥 8 Unique Characters — Librarian, musician, baker, mail carrier, blacksmith, herbalist, village elder, and a newcomer
• 💬 AI-Powered Conversations — Characters autonomously chat using your LLM (DeepSeek, OpenAI, or any compatible API)
• ❤️ Relationship System — Characters form friendships, with relationship scores that affect dialogue
• 🌤️ Dynamic World — Weather changes, seasons pass, day/night cycle
• 🧠 Offline Mode — Works without API key using cozy pre-generated dialogue

🚀 Quick Start

# Install
pip install liltown

# Run (offline mode — pre-generated cozy dialogue)
liltown

# Run with AI-powered conversations
export LLM_KEY="sk-your-api-key"
liltown

# Or pass directly
liltown --api-key sk-your-api-key

That's it! A terminal village appears. Characters will start chatting every few seconds.

🎮 Usage

liltown [OPTIONS]

Options:
  -k, --api-key KEY     LLM API key (or set LLM_KEY env var)
  -e, --endpoint URL    API endpoint (default: DeepSeek)
  -m, --model MODEL     Model name (default: deepseek-chat)
  -i, --interval SEC    Seconds between ticks (default: 5)
  -q, --quiet           Offline mode (pre-generated dialogue)

Press Ctrl+C to exit. The village will miss you.

👥 The Villagers

Character	Role	Personality
🍁 Maple	Librarian	Gentle and bookish, always has a recommendation
🎵 Piper	Musician	Free-spirited, plays flute in the town square
🐦 Finch	Mail Carrier	Cheerful, knows everyone's business but keeps secrets
🍀 Clover	Baker	Warm and nurturing, shows love through food
🌿 Elder Moss	Village Elder	Wise, speaks in gentle riddles
🔥 Ember	Blacksmith	Gruff exterior, heart of gold
🌙 Sage	Herbalist	Mysterious, sometimes speaks to plants
⭐ Nova	Newcomer	Curious, just moved to the village

🎨 What It Looks Like

┌─────────────────────────────────────────────────────────────┐
│                 🏡 Liltown — A Cozy Terminal Village         │
├──────────────────────────────┬──────────────────────────────┤
│         🌙                   │ 👥 Villagers                  │
│     🌲   ___     🏠          │                              │
│    /🌳\ |___|   ┌──┐        │ ● 🍁 Maple      Librarian    │
│   /   \  | |    │🏪│        │ ○ 🎵 Piper      Musician     │
│  🌲     ┌┴─┴┐  └──┘        │ ● 🐦 Finch      Mail Carrier │
│                              │ ○ 🍀 Clover     Baker        │
│   ☀️ Sunny | Day 3 | Spring  │ ○ 🌙 Sage       Herbalist    │
├──────────────────────────────┴──────────────────────────────┤
│ 💬 Recent Happenings                                        │
│ Day 3 08:00 Maple: *waves warmly* Good morning!             │
│ Day 3 08:00 Finch: Better now that I've seen you!           │
│ Day 3 09:00 🌙 Sage is tending the garden...                │
└─────────────────────────────────────────────────────────────┘

🔧 API Setup

Supports any OpenAI-compatible API:

• DeepSeek (default): https://api.deepseek.com/v1
• OpenAI: https://api.openai.com/v1
• Local LLM: http://localhost:1234/v1

🤝 Contributing

git clone https://github.com/xvcenh/liltown.git
cd liltown
pip install -e .

Ideas:

• More villagers and locations
• Seasonal events (festivals, holidays)
• Player interaction (you as a visitor)
• Sound effects
• Web viewer

📝 License

MIT © xvcenh

---

⭐ Star this repo if it brings you joy!
_{Built with ❤️ + 🍵}