DungeonAI Terminal Edition

A local-first, terminal-native rebuild of the DungeonAI experience. This CLI keeps the Gemini-driven gameplay loop, adds a persistent memory layer (SQLite + optional Redis semantic recall), and presents a focused slash-command interface for smooth keyboard play.

Prerequisites

• Node.js 20+
• npm 10+
• Gemini API key available as GEMINI_API_KEY
• (Optional) Redis Stack instance for semantic memory (REDIS_URL)

Setup

cd terminal
npm install --legacy-peer-deps
npm run build

Install from npm

npm install -g dungeonai-terminal
dg-terminal                # launch the CLI from anywhere

The binary is published as dg-terminal; it bootstraps the compiled build in dist/ so you can keep the repo and the global install in sync.

Create a .env file or run-time environment variables:

export GEMINI_API_KEY=your_google_gemini_key
export REDIS_URL=redis://localhost:6379 # optional

Running the Game

npm run dev        # start with live reload (tsx)
# or
npm start          # run compiled build after npm run build

On first launch the CLI will create ~/.dungeonai/config.json and ~/.dungeonai/terminal.db.

Slash Commands

• /roll [type] [notation] – perform dice rolls (e.g., /roll attack, /roll d12+3).
• /quests – list active and completed quests.
• /inventory – inspect equipped items and backpack contents.
• /memory <query> – run semantic search against Redis/SQLite memory.
• /config [key value] – view or update configuration (stored locally).
• /sessions – show recent session IDs.
• /log <sessionId> – dump recent audit log events.
• /model – inspect available Gemini models and switch the active one.
• /plan – generate, browse, or load story plans and templates. Loading a plan now resets the session, equips the YAML-defined gear, applies stat overrides (including custom stats), populates objectives as quests, and seeds the log so the narrative picks up in the right context.
• /help – quick command overview.

Project Scripts

• npm run dev – watch mode via tsx.
• npm run build – compile TypeScript to dist/.
• npm run start – execute compiled CLI (dist/index.js).
• npm run lint / npm run test – linting and unit tests (placeholders for now).

Architecture Highlights

• TypeScript Strict – shared types for player state, rolls, quests, LLM tool payloads.
• LLM Orchestrator – Gemini Flash Lite for narration, tool calls drive state mutation, all validated and audited.
• Memory Layer – SQLite for canonical storage; Redis semantic recall boosts context quality (fallback to vector recall from SQLite when Redis is absent).
• Ink UI – streaming output, slash commands, recent rolls, and real-time stats rendered in terminal.
• Audit Logging – every roll, state patch, and LLM tool invocation is captured for replay/debugging.

Enjoy the DungeonAI terminal adventure!