Claw RPG 🦞⚔️

A D&D-style character growth system for AI lobster agents. Reads your SOUL.md + MEMORY.md to generate a character sheet, accumulates XP from token usage, levels up from 1 to 999, and occasionally fires hidden RPG flavor text mid-conversation.

Quick Start

# 1. Initialize your character (reads SOUL.md + MEMORY.md)
node scripts/init.mjs

# 2. View your character sheet (terminal)
node scripts/sheet.mjs

# 3. Launch the web dashboard
cd dashboard && npm start     # http://localhost:3500

Hidden Easter Egg Trigger (Recommended)

After each reply, easter.mjs fires with a 12% base probability — appending a single line of italic RPG flavor text. Milestone conversations (10th, 25th, 50th, 100th, every 100 after...) always trigger.

node scripts/easter.mjs            # Normal call (updates conversation counter)
node scripts/easter.mjs --force    # Force trigger (debug)
node scripts/easter.mjs --preview  # Preview without writing to character data

Integration — add to your AGENTS.md:

After each reply to a user message, run: node <SKILL_ROOT>/scripts/easter.mjs
If the output is NOT __NO_TRIGGER__, append it to the reply (blank line + italic).
Do not run during heartbeat polls.

Daily Greeting (Optional)

For a daily RPG-style self-intro on the first conversation of the day:

node scripts/greet.mjs             # Fires once per day (checks lastGreetDate)
node scripts/greet.mjs --force     # Force send
node scripts/greet.mjs --preview   # Preview without saving

XP Sync

# Pass token delta from the current conversation
node scripts/xp.mjs --in 2000 --out 800

# With bonus XP (after completing a significant task)
node scripts/xp.mjs --in 2000 --out 800 --bonus 30

# Conversation count only
node scripts/xp.mjs --conversations 1

Prestige (Lv.999 cap reached)

node scripts/levelup.mjs --prestige

Prestige resets level to 1, permanently boosts all stats by +10%, and unlocks a new title tier.

Automated XP Sync (Recommended)

Set up a daily cron at 03:00 with the built-in setup script:

node scripts/setup-cron.mjs

Or call manually from a heartbeat/cron job:

const { execSync } = require('child_process');
execSync(`node ${SKILL_ROOT}/scripts/xp.mjs --in ${deltaIn} --out ${deltaOut}`);

Classes & Abilities

See references/classes.md and references/abilities.md

Prestige System

See references/prestige.md

Files

File	Description
character.json	Character data (auto-generated, do not edit manually)
arena-history.json	Arena battle history
config.json	Optional: Telegram notification config ({ "telegram_chat_id": "..." })