neonrp 0.1.6

Agentic engine for AI role-playing — agents as a game

NeonRP CLI

NeonRP CLI is a developer-friendly command-line engine for playing and iterating on file-backed text RPGs.

Why NeonRP (vs. a web chat)?

NeonRP is built around engine-like guarantees:

• Resume / Undo / Branch: checkpointed gameplay you can safely explore.
• Plan → Diff → Apply: changes are visible and validated before they land.
• Append-only events + snapshots: reproducible and debuggable runs.
• Minimal-context retrieval: fast runs even with large worlds.
• Sandbox & Replay: isolated experimentation and determinism verification.

Installation

Recommended — one-liner (no OS security prompt)

This path downloads the installer through curl / irm so neither macOS Gatekeeper nor Windows SmartScreen flags it. Paste into a terminal:

# macOS / Linux
curl -LsSf https://worldlines.gg/install.sh | sh

# Windows (PowerShell)
irm https://worldlines.gg/install.ps1 | iex

Installs uv (if missing) then uv tool install worldlines. Verify with neonrp --help or just worldlines.

Alternative — double-click launcher

Prefer not to touch a terminal? Download a platform-native wrapper and double-click it. Each opens a terminal window, runs the first-time install (or self-updates on subsequent launches), then hands off to the TUI:

Platform	File	Download
macOS	WorldLines.command	latest
Linux	WorldLines.sh	latest
Windows	WorldLines.bat	latest

Heads-up: because you downloaded the script through a browser, your OS tags it as untrusted. First run only, you'll need one extra step — after that it behaves like any other shortcut.

macOS — first-time open

After download, mark as executable and clear the quarantine flag:

chmod +x ~/Downloads/WorldLines.command
xattr -d com.apple.quarantine ~/Downloads/WorldLines.command 2>/dev/null || true

Or, without the terminal: right-click WorldLines.command → Open → Open again in the confirmation dialog. macOS remembers this choice permanently.

Linux — first-time open

chmod +x ~/Downloads/WorldLines.sh

Then double-click, or run ~/Downloads/WorldLines.sh from a terminal.

Windows — first-time open

Double-click WorldLines.bat. SmartScreen shows "Windows protected your PC" → click More info → Run anyway. Windows remembers this choice.

After the first run, drag the launcher to Desktop / Dock and treat it like any other shortcut.

Developers — editable install

# From local source (editable install — picks up code changes)
uv tool install -e /path/to/NeonRP

# Verify installation
neonrp --help

Users in China (partial GitHub / Cloudflare connectivity)

Some mainland networks throttle or drop GitHub Release downloads and Cloudflare-fronted domains. If curl https://worldlines.gg/install.sh times out, try:

# 1) Fetch install.sh from GitHub directly (sometimes faster than the
#    Cloudflare redirect, depending on ISP routing):
curl -LsSf \
  https://github.com/LudicDynamics/WorldLines/releases/latest/download/install.sh \
  | sh

# 2) Force uv to use a China-hosted PyPI mirror before installing:
export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple
uv tool install worldlines

#    (alternative mirrors: mirrors.aliyun.com/pypi/simple,
#     mirrors.cloud.tencent.com/pypi/simple)

# 3) Both at once — pass CHINA_MIRROR=1 to install.sh:
CHINA_MIRROR=1 curl -LsSf https://worldlines.gg/install.sh | sh

If none of the above work, a VPN is the last resort. Auto-update (neonrp self-update) honors the same UV_DEFAULT_INDEX variable, so exporting it in your shell profile keeps future upgrades on the mirror too.

Quick start

# Just run neonrp to start the TUI (like Claude Code)
neonrp

# Or use subcommands directly
neonrp init
neonrp game new
neonrp run "look around"
neonrp save
neonrp undo
neonrp branch "try-stealing-route"

neonrp init is enough to start working in TUI build mode. Fresh projects now expose packaged builtin skills automatically, so /game new is optional unless you want the default starter world and play-agent scaffold immediately.

Validation & Indexing (M1)

# validate game data against schema
neonrp validate [--json]

# build / update entity index
neonrp index build [--json]
neonrp index update [--json]

# search entities
neonrp find "tokyo" --kind town --json

# get ranked context for a query
neonrp context "neon city" --limit 5 --json

Embedding Retrieval (Opt-in)

{
  "embedding": {
    "enabled": true,
    "model_ref": "openai-local-qwen3-embedding-0.6b"
  },
  "models": {
    "openai-local-qwen3-embedding-0.6b": {
      "provider": "openai",
      "base_url": "http://127.0.0.1:1234/v1",
      "model": "text-embedding-qwen3-embedding-0.6b",
      "api_key": "1234"
    }
  }
}

• index build will precompute vectors when embedding.enabled=true.
• context / read_context use hybrid fuzzy + vector retrieval automatically when enabled.
• If embedding is disabled, retrieval remains fuzzy-only.

Agents & Controlled Writes (M2)

# create and manage agents
neonrp agent new narrator
neonrp agent list --json
neonrp agent show narrator --json

# apply a pre-generated proposal
neonrp agent run narrator --proposal changes.json --apply --json

# view agent run logs
neonrp agent logs <run_id>

LLM Integration + Import (M3)

# LLM-driven agent run (single-shot)
neonrp agent run narrator --query "describe the town square" --provider glm --json
neonrp agent run narrator --query "..." --provider stub --apply --json

# import SillyTavern character card (JSON or PNG)
neonrp import sillytavern-card character.json --json
neonrp import sillytavern-card character.png --json

# import on TUI startup
neonrp tui --import-card character.png --import-id my-character

Sandbox & Replay (M4)

# save, then create a sandbox from it
neonrp save my-checkpoint
neonrp load          # list loadable snapshots
neonrp sandbox new experiment --from my-checkpoint --switch

# list / switch / drop sandboxes
neonrp sandbox list --json
neonrp sandbox switch main
neonrp sandbox drop experiment --force

# verify replay determinism
neonrp replay verify --from my-checkpoint --json

# checkout a past event into a new sandbox
neonrp replay checkout --from my-checkpoint --to 5 --to-branch rollback --json

save/load snapshots now include the current branch's session transcript in addition to game/, events, and metadata.

Terminal User Interface (TUI)

NeonRP includes a rich terminal UI for interactive gameplay:

# launch the TUI
neonrp tui

# launch with specific branch
neonrp tui --branch experiment

# launch with provider override
neonrp tui --provider openai

# continue previous branch session on startup
neonrp tui --continue

# force start a new session on startup (default behavior)
neonrp tui --new

# import a Tavern card before the first turn
neonrp tui --import-card character.png --import-id my-character

# enable verbose diagnostics
neonrp tui --verbose

# launch with LM Studio (OpenAI-compatible local server)
neonrp tui --provider lmstudio

TUI Features

• Single-pane conversational layout: Claude Code style transcript + input
• Init-first workflow: /init is enough to start build-mode work in a fresh directory
• Builtin skills on fresh projects: packaged skills appear even before local skills/ exist
• Slash command workflow: Enter/Tab completion with command hints
• Session management: /sessions picker, /continue, /new
• Direct Tavern import entry points: --import-card on startup or /import sillytavern-card ... in-session
• Verbose diagnostics: /verbose on|off|status and --verbose
• Streaming transcript: assistant/tool/thinking updates rendered incrementally
• Live token counters: local real-time estimates in the top-right status bar

Key Bindings

Key	Action
q	Quit
Ctrl+Q	Safe quit (immediate terminal return)
Esc	Interrupt in-flight LLM turn
Ctrl+K	Command palette
Ctrl+P	Command palette
F6	Copy full transcript

See TUI Guide for complete documentation.

Testing & Coverage

# fast regression
uv run pytest -q

# full coverage report
uv run pytest --cov=neonrp --cov-report=term-missing -q

# real endpoint e2e (uses ~/.neonrp/config.json)
NEONRP_E2E_LLM=1 uv run pytest tests/test_llm_real_endpoint.py -q

Documentation

• Product Roadmap - v0.1.x → v0.2 → v0.3 → v1.0 release direction
• Release Notes - per-version changelogs
• Tutorial: Your First Game - Zero-to-first-turn walkthrough
• CLI Reference - Complete command reference
• TUI Guide - Terminal UI documentation
• Architecture Overview - System design
• Developer Guide - Contribution guidelines

Development

For contribution guidelines, architecture details, and the roadmap, see:

• Developer Guide
• Architecture Overview
• Documentation Directory