Monkegotchi — Plan

A Tamagotchi-style virtual pet for the MonkeDAO community, with an optional AI agent companion via Telegram. Mobile-first, mass-market for the pet, motivated users for the agent.

Context

Build a Tamagotchi-style virtual pet ("Monkegotchi") for the MonkeDAO community. The pet is the visible vessel for a Telegram-based AI agent ("OpenClaw") the user is also building. Two surfaces: a Telegram Mini App + a standalone mobile-first web page. Audience is mass-market for the pet, motivated users for the optional agent companion.

Goal of v1: ship a hatchable, evolving, agent-coupled pet that any user can care for, with optional SMB-trait personalization for holders. Reuse OSS where it accelerates us; build the state machine ourselves since it's small (~300–600 LOC TS).

Product shape — two halves, three entry points

Monkegotchi is two complementary products that share one identity + state layer. Users enter from any of three doors and converge to the same end state:

   ┌─ Anonymous Web Pet ─┐
   │  (local-only)       │
   └────────┬────────────┘
            │ opt-in: claim with email or TG login
            ▼
   ┌─────────────────────┐
   │  Linked Pet         │
   │  (no agent)         │
   └────────┬────────────┘
            │ opt-in: BotFather wizard
            ▼
   ┌─────────────────────┐
   │  Pet + Agent        │ ◄── /hatch from
   │  (full experience)  │     agent-first user
   └─────────────────────┘
            ▲
            │ opt-in: hatch a pet
   ┌─────────────────────┐
   │  Agent only         │ ◄── existing multi-user-openclaw user
   └─────────────────────┘

• Pet half — mini-app + tick worker + D1 + image-gen. Has standalone value as a web game.
• Agent half — existing multi-user-openclaw infra + a new monkegotchi-skill. Has standalone value as a personal AI agent.
• Glue — a single D1 row keyed by tg_user_id (anonymous pet → claimed via Telegram-Login-Widget on the web).

The embodiment moment. When an agent-first user hatches their first pet, the skill fires a one-shot "soul-arrived" event the agent reacts to ("Whoa. I feel… different. There's something here. It's small. And it's hungry."). Tentpole UX moment — design + write copy explicitly.

Key decisions (locked)

Tier matrix

Launch sequencing

1. Phase 1 — Pet (standalone): mini-app + web, anonymous + email auth, tick worker, image gen, care loop, evolution, Matrica + pedigree tiers, social profiles + visits. No agent required.
2. Phase 2 — Agent coupling: monkegotchi-skill, BotFather wizard onboarding, soul-arrived event, /hatch tool inside the agent.
3. Phase 3 (post-v1): on-chain NFT, mini-games, hardcore permadeath, breeding, payments, multi-pet, localization.

Game mechanics (v1)

All numbers below are tunable starting points — they live in one config file (packages/shared/src/mechanics.ts) and ship as the "Casual" preset. Easy to retune from playtest without code changes elsewhere.

Stats & decay

Pacing target: once-a-day check-in keeps a casual player's pet happy. Coma takes ~3 days of total neglect. Tick runs every 5 min on a CF Cron Worker; offline catch-up is deterministic (now − lastTickAt), not LLM-decided.

Care actions

Shop foods (pizza, cake, spicy) have larger hunger gains + unique agent reactions, cost bananas, share the Feed cooldown.

Mood derivation (single source of truth)

mood_score = avg(hunger, happiness, energy, hygiene)

if any stat == 0 for >6h   → coma
else if mood_score < 25    → sick
else if mood_score < 45    → grumpy
else if mood_score < 70    → neutral
else                        → happy

Mood drives both the portrait overlay (sad tear / ZZZ / sparkle / etc.) and the agent's tone register.

Stages & evolution

Poor care → pet stays in current stage longer instead of failing forever. Evolution is one-way. Adult branches (Cheerful / Sassy) are deferred to v1.5 — v1 ships a single Adult stage.

Coma + revive

• Enters coma when any stat hits 0 and stays there for 6h, OR mood_score < 10 for 12h.
• Visual: portrait washed out + dim, agent shifts to mourning register ("she's not responding…").
• Revive paths: (a) free smelling-salts with 24h cooldown, (b) shop smelling-salts (no cooldown), (c) 30 min of sustained care (3 successful care actions in a row).
• Lineage logged: every episode appended with timestamp + days-since-last-revival. Profile surfaces them ("survived 2 comas").

Adventure XP

• Care action → +1 XP · Friend visit → +1 XP · 7-day care streak → +10 XP · Coma → −5 XP (mild penalty)
• Levels: 1→2 = 10 XP, then ×1.5 each (10, 15, 22, 33, 50…). Levels unlock shop tiers + cosmetics.

Agent contract (what the skill injects per message)

The openclaw skill reads pet_state and pulls exactly 3 derived values for the system-prompt prefix — keep it short, cache in KV:

1. mood_band (happy / neutral / grumpy / sick / coma) → tone register
2. stage (baby / teen / adult) → vocabulary register
3. last_event ("just ate cake 12min ago" / "in coma 4h" / "evolved 2h ago") → conversational color

What we explicitly defer past v1

• On-chain pet NFT mint
• Touch mini-game / earn loop
• Hardcore permadeath mode (opt-in)
• Breeding between two pets
• Real-money items / Stars / TON payments
• Multi-pet ownership
• Localization beyond English

Open questions for after v1

• Monetization: coins-only forever, or TG Stars / TON for premium items?
• Should the agent gain wallet-interaction capabilities for SMB holders?
• Breeding / multi-pet — is there demand?
• Should pet death after N coma relapses exist as a soft permadeath?

Design

Visual identity, screens, flows, microinteractions, and copy. This section is iterating — most areas are placeholders until we work through them.

Art direction

MiniMax generates every pet from a style reference sheet. Each card below shows two samples per direction: Cold = prompt only, no SMB reference. SMB-grounded = same prompt + subject_reference pointing at SMB #1012. Open the prompt block to see exact text.

A · Pixel SMB Heritage

Pixel SMB Heritage

retroOG-respectfulreadablenostalgic

Chunky pixel sprites, flat colors, no anti-aliasing. Faithful continuation of SMB's 24×24 aesthetic, scaled to a 32×32 or 48×48 baby variant.

+ Instant SMB lineage. + Cheap to animate frame-by-frame. + Easy MiniMax consistency.

− Limited expressive range. − Feels "indie game" not "premium product."

Refs: SMB · Aavegotchi · Stardew Valley · Loot Project

Cold prompt

pixel art baby monkey companion character, 32x32 chunky pixel sprite, flat colors no anti-aliasing, retro 16-bit videogame style, deep purple background, tan fur with brown details, big simple square eyes, single character portrait centered, NES SNES aesthetic, Solana Monkey Business inspired baby version

SMB-grounded prompt (ref: SMB #1012)

baby version of the reference monkey character, same chunky 32x32 pixel art SMB style, flat colors no anti-aliasing, retro 16-bit aesthetic, big simple square eyes, small baby proportions, pastel pink background, single character portrait centered

B · Soft Illustrated Plush

Soft Illustrated Plush

tendercozyexpressivepremium

Painterly, hand-drawn feel. Soft gradients, gentle outlines, big expressive eyes, plush rounded silhouette, watercolor textures.

+ Maximum emotional range. + Reads as a real product. + Plays well with AI portraits.

− Departs from SMB heritage. − Highest style-drift risk.

Refs: Studio Ghibli · Tamagotchi On · Pikmin Bloom · Neko Atsume

Cold prompt

hand-drawn painterly baby monkey companion character, soft watercolor textures, warm cream and tan palette with sage green accents, big expressive eyes, plush rounded silhouette, gentle hand-drawn outlines, Studio Ghibli inspired, cozy tender mood, single character portrait centered on warm cream gradient background

SMB-grounded prompt (ref: SMB #1012)

baby version of the reference monkey character reimagined in soft painterly Studio Ghibli style, watercolor textures, warm cream and tan palette with sage accents, plush rounded silhouette, big expressive eyes, cozy tender mood, single character portrait centered on cream gradient background

C · Cyberpunk Banana

Cyberpunk Banana

edgyweb3-nativepremiumnocturnal

Dark backgrounds, neon outlines, holographic shimmer, occasional CRT/glitch artifacts. Pet reads as a digital spirit projected into your phone.

+ Strong differentiation. + Reads as "AI agent in a vessel." + Marketable to crypto.

− Alienates casual mass-market. − Cyberpunk is over-used in Web3.

Refs: Cyberpunk 2077 UI · Hyper Light Drifter · Aavegotchi · Vaporwave

Cold prompt

cyberpunk baby monkey digital spirit companion character, glowing neon magenta and cyan outlines, holographic shimmer effect, dark void background with subtle CRT scanline glitch artifacts, bright banana yellow accents, single character portrait centered, vaporwave futuristic spirit-projection aesthetic, hologram vibe

SMB-grounded prompt (ref: SMB #1012)

baby version of the reference monkey character reimagined as a cyberpunk digital spirit, glowing neon magenta and cyan outlines, holographic shimmer, dark void background with subtle CRT scanline artifacts, banana yellow accents, single character portrait centered, vaporwave hologram aesthetic

D · Vector Toon

Vector Toon

boldplayfuliconicversatile

Bold black outlines, flat fills, limited palette, slightly off-balance shapes. Sticker-pack friendly, animation-ready.

+ Reads great at any size. + Universal appeal. + Easiest MiniMax consistency.

− Less emotionally subtle than B. − Less SMB-heritage than A.

Refs: Cult of the Lamb · Untitled Goose Game · Adventure Time

Cold prompt

bold vector toon baby monkey character, thick black outlines, flat fills with limited 5-color palette of warm browns and sunny yellow, sunny yellow gradient background, cream face, simple expressive black dot eyes, slightly off-balance asymmetric shape, modern indie videogame sticker style, Cult of the Lamb inspired, single character portrait centered

SMB-grounded prompt (ref: SMB #1012)

baby version of the reference monkey character reimagined in bold vector toon style, thick black outlines, flat fills, limited 5-color palette of warm browns and sunny yellow, sunny yellow gradient background, simple expressive black dot eyes, Cult of the Lamb sticker aesthetic, single character portrait centered

E · Direct Baby SMB (no stylistic reinterpretation)

The minimalist option: take an SMB ref + ask for a "baby version" with no style override. Comparison across runs — Parent · Run 03 (loose prompt) · Run 04 (strict pixel-art prompt).

Parent: SMB #627 (headphones)

Parent: SMB #1012

Parent: SMB #3756 (cap + suit)

Parent: Jemmy (sombrero)

Known issues with these runs: "pilot" look comes from the model confusing over-ear headphones with aviator goggles + projecting pilot iconography. Pixel-art quality is soft because MiniMax image-01 is a general diffusion model and doesn't natively produce true indexed-color sprites at any prompt strength. To fix: per-parent accessory prompts ("pink over-ear headphones, NOT aviator goggles") + either a post-process pixelation pass or switching to a pixel-art-tuned model for this direction.

Pixel art sprite portrait of a baby version of the reference monkey character. Render in identical 8-bit / 16-bit chunky pixel art style as the reference: hard-edged pixels, flat indexed colors, zero anti-aliasing, zero gradients, zero painterly textures, zero illustration shading. Preserve every accessory, every color, every trait from the reference exactly — same hat, same headphones, same clothing pattern, same jacket, same fur color, same eye color and shape, same mouth, same skin tones. The ONLY differences from the reference: slightly larger head relative to body (cute baby proportions), slightly smaller torso, slightly rounder face. Background is a single solid pastel color (no gradient). Composition matches the reference: head and shoulders portrait, centered.

Decision pending. Hybrids welcome — e.g. "D's outline + B's painterly shading," or "E's faithfulness with B's emotional polish on tentpole moments." Next: pick a direction, then iterate on the house style reference sheet.

Inspiration · virtual-pet UI references

Curated set of strong virtual-pet / tamagotchi / cozy-creature UIs. Click any tile to open its source. Image files cached locally so the gallery doesn't break if a CDN moves. Initial gather had several misidentified products — labels and links below have been visually verified.

Tamagotchi Forever · HomeCharacter mid-screen + bottom action tray + top counters. Canonical care-pet layout. Tamagotchi Forever · FeedCare action with a banner line at top ("Bon appétit!"). Bottom tray persists. Tamagotchi Forever · Character lineupWireframe → finished character maturation. Reference for evolution stages. Tamagotchi · ARCB concept (Behance)Award-quality modern reimagining: Home + Time-to-Level-Up + Level-Unlocked. Best ref for Hatch + Evolution. Finch · HomePet in landscape + Adventure progress bar + daily goals list. Closest tonal + structural analog. Finch · CollectMicropet collection grid (12/30). Reference for Friends · Discover tab + lineage display. Neko Atsume · CatbookCollected vs un-collected (silhouette + ???). Model for the hatched-Monke roster. Neko Atsume · YardPet-in-scene composition with minimal UI chrome over the creature. Neko Atsume · ShopCard grid with bought-state, price, description-on-selection. Shop tab reference. Talking Tom · HomeTop-left circular level + bottom action tray + currency counter. Cleanest care-pet baseline. Pou · KitchenTop-row stat icons (food / health / clean / energy) + bottom-corner room nav. Compact stat strip. Pou · BathroomCare-action with the pet mid-action, chrome stays at edges, focus is the action. Pikmin Bloom · Decor collectionCollection grid with silhouettes for un-discovered items. Strong roster pattern. Pikmin Bloom · AR placementCharacters in real-world scene + caption banner. Photo-share moment composition. Sky: Children of the LightPainterly Ghibli-adjacent moment, minimal UI — exact mood target for Soft Illustrated Plush.

15 references · re-verified 2026-05-26 · index at research/inspiration/index.json. Filenames preserved from initial gather; labels and source links corrected after visual verification.

Wireframes (v2 — incorporating inspiration learnings)

Mobile-first sketches of the four core screens, rewritten after the inspiration audit. Key changes from v1: pet lives IN a painterly scene (not floating on void), stat ring replaced with a single Adventure bar + agent-voiced needs line, persistent currency on Home, friends as a 2-col collection grid, lineage as Catbook-style silhouettes, dedicated 3-screen Evolution tentpole sequence. v1 wires preserved at the bottom for diff.

Shop · v1 (in-game currency only)

Five categories. No real money in v1. Items earned at ~5–8 🍌/day passive + 1 🍌 per friend visit (rate-limited).

Held for post-v1: accessories (hats / glasses — needs portrait overlay system), pedigree-exclusive items (Gen2 OG aura), profile-frame cosmetics, TG Stars / TON premium currency.

Tentpole · Evolution sequence (3 screens)

Per the ARCB Behance concept, evolution is its own multi-screen moment — not a single in-place transition. Designed as: a building-up Home → an announcement → the reveal. Same pattern reused for Hatch (egg crack → name → first portrait) and Coma+Revive (sick portrait → mourning agent line → revived portrait + lineage update).

v2 decisions, summarized:

• Pet lives in a painterly scene, not floating on void. Background tint reflects mood + time of day.
• One Adventure progress bar + one agent-voiced needs line, instead of 4 stat meters.
• Notification chip top-right (unread agent DMs) replaces the gear icon. Settings move to Profile.
• Currency persistent bottom-left on Home.
• Action tray icons only; copy ("Bon appétit!") appears as a top banner during the action itself.
• Friends = 2-col collection grid (Finch / Catbook), not contact list. Last tile is "+ invite."
• Lineage on Profile = 2x2 Catbook grid with silhouettes for future generations.
• Tentpole moments (Evolution, Hatch, Coma+Revive) are 3-screen sequences with a building-up Home → announcement takeover → reveal pattern.

Onboarding flows

Tentpole moments

Tone of voice & copy

Tech Details

Architecture, components, file layout, risks, and verification.

Architecture

   ┌────────────────────────────────────────┐
   │   ONBOARDING (Cloudflare Pages)        │
   │   Guided BotFather wizard              │
   │   Matrica OAuth link (optional)        │
   │   Submits to provision-agent           │
   └────────────────┬───────────────────────┘
                    ▼
   ┌────────────────────────────────────────┐
   │   provision-agent (VPS, loopback)      │
   │   admin.sh create <username>           │
   │   → Docker container + .env (bot tok)  │
   │   → init.sh runs `openclaw onboard`    │
   │   → mounts shared skills/ dir          │
   └────────────────┬───────────────────────┘
                    ▼
   (one container per user, one bot per user)
   ┌───────────────────────────────────────────────┐
   │  USER CONTAINER  (openclaw, Telegram channel) │
   │  ┌─────────────────────────────────────────┐  │
   │  │  monkegotchi-skill  (read-only mount)   │  │
   │  │  • fetch pet state from D1 per message  │  │
   │  │  • inject mood/stage/lineage into prompt│  │
   │  │  • expose /pet, /feed, /play tools      │  │
   │  └─────────────────────────────────────────┘  │
   └───────────┬─────────────────────┬─────────────┘
               │ read pet state      │ write care
               ▼                     ▼
   ┌────────────────────────────────────────┐
   │   SHARED D1 (Cloudflare)               │
   │   reuses multi-user-openclaw's D1      │
   │   + pets, pet_state, lineage, visits   │
   └────────────────┬───────────────────────┘
                    ▲
                    │ reads + writes
   ┌────────────────────────────────────────┐
   │   MINI-APP / WEB  (CF Pages + Workers) │
   │   TMA React template                   │
   │   • care → POST /api/care              │
   │   • portrait + overlays                │
   │   • social: profiles, visits, friends  │
   └────────────────────────────────────────┘

   ┌────────────────────────────────────────┐
   │   TICK WORKER (CF Cron, every 5min)    │
   │   decay stats, transition stages       │
   └────────────────────────────────────────┘

   ┌────────────────────────────────────────┐
   │   IMAGE GEN (MiniMax image-01)         │
   │   at hatch + each evolution, → R2      │
   └────────────────────────────────────────┘

Components

1. Mini-app / web client (one codebase, two surfaces)

• Base template: Telegram-Mini-Apps/reactjs-template (Vite + React + TS + react-router + @tma.js/sdk).
• UI library: shadcn/ui + Tailwind CSS — copy-paste components owned in repo, painterly-brand friendly.
• Data layer: TanStack Query (React Query) for pet state fetching, caching, and optimistic updates on care actions.
• Animation: Framer Motion for overlay layers (idle bob, blink, ZZZ, sparkle, sad tear, eating-banana, evolution glow). Portrait stays static.
• Routing: detect TMA context via initData; same routes/components serve the public web page when accessed standalone.
• Screens: Hatch · Home · Profile · Friends · Shop. Bottom tab nav.
• Auth: in TMA — initData HMAC-verified server-side. On web — anonymous local-only by default, email magic-link or Telegram-Login-Widget on upgrade.
• Pedigree unlock (optional): "Link MonkeDAO" → Matrica OAuth → callback returns wallets + NFTs → server filters for SMB Gen2/Gen3 → assigns tier. No wallet adapter, no signing.

2. Agent service — reuses multi-user-openclaw

• One container per user, one Telegram bot per user.
• New monkegotchi-skill mounted read-only into every container.
• On every inbound message: skill fetches pet state from D1, injects mood/stage/lineage as a system-context line.
• TG user ID is the join key between agent and pet state.
• Agent capabilities (Solana questions, tasks) never depend on pet state — only persona does.

3. Backend (Cloudflare Workers + D1 + KV + R2)

• D1: users, pets, pet_state, lineage, friendships, visits.
• KV: session tokens, rate limits, hot pet snapshots.
• R2: generated portraits + overlay sprites.
• Workers: api (REST for mini-app), tick (cron decay), image-gen (MiniMax wrapper).

4. Agent ↔ Pet contract

• Mood band: happy / neutral / grumpy / sick / coma → tone register.
• Stage: egg-not-hatched (silent/curious) → baby (eager) → teen (sassy) → adult (witty).
• Hunger / energy: color willingness to do tasks.
• Lineage memory: coma episodes occasionally surface in agent responses.

5. Image generation

• MiniMax image-01 REST API, called from the image-gen Worker.
• House style sheet at assets/style-ref.png passed as reference for family resemblance.
• Prompt template: baby-monke companion, transparent BG, single portrait, traits from SMB if pedigree.
• Cached forever at R2 key pet/{pet_id}/{stage}.png.

6. Social (in v1)

• Public profile route /m/:handle rendering portrait + stats + lineage + recent visits.
• Visit action: any user can visit another pet → small mood boost on visited, small coin reward to visitor. Rate-limited per pair per day.
• Friends list seeded from Telegram contacts who have also hatched.

AI-tamago reference — what we borrow vs skip

Repo: ykhli/AI-tamago. We don't fork. Their stack (Next.js + Supabase + Inngest + Clerk) doesn't match ours. What's worth copying are a few patterns; most of the code is over-engineered or single-tenant by construction.

Borrow

Skip / avoid

• LLM as physics engine. They ask GPT to compute new stat values every 5 min. ~288 calls/pet/day, expensive, non-deterministic, hard to balance. We do all decay/mood/stage math in pure TypeScript (testable, free, instant) and only call the LLM for narration.
• Inngest + waitForEvent ceremony. Over-engineered on CF Workers — just await inline.
• Module-level mutable state. let status = "" at the top of route files — breaks on serverless cold starts and across users. We key everything by chat_id from day one.
• Single-tenant schema. Their DB has no user_id anywhere. Our schema has tg_user_id as primary key on every table.
• Their stage / evolution system. Doesn't exist in code (just an unused age counter). We're building our own (see Game mechanics in Plan tab).
• Their death system. Also doesn't exist — just a line in the prompt that says "you die when…" with no code to enforce it. We have explicit coma + revive.
• Their interact/route.ts. Their team flagged it as messy; don't read for ideas.

Files worth a direct read in their repo

• src/app/utils/state.ts — the whole update loop, ~120 LOC
• supabase/migrations/20231029050944_init_tables.sql — schema in 30 lines
• src/inngest/functions.ts — tick shape (port to CF Cron)

Risks + mitigations

• Image-gen style drift between pets — strict reference image + prompt template; manually review first 50 pets.
• Telegram Mini App iOS webview quirks — test on real iPhone early; lean on @tma.js/sdk viewport helpers.
• Tick loop scale — only iterate pets touched within 30d.
• Agent persona inconsistency — snapshot-test prompt assembly against canned pet states.
• Empty cold-start — 60s hatching cinematic + immediate first DM.

Verification plan

1. Hatch flow (non-Web3): open mini-app → name pet → see hatching → portrait in ~5s → first agent DM lands.
2. Care updates agent tone: feed=happy=enthusiastic; neglect=grumpy=snippy. Snapshot-test prompt assembly.
3. Evolution: fast-time multiplier in dev → stage transitions + new portrait + vocabulary expands.
4. Coma + revive: neglect → sick visuals → mourning tone → revive → lineage records episode.
5. Matrica pedigree: Gen2/Gen3/none each set correct tier, visuals, agent voice.
6. Three entry paths: (a) anon web → email-claim merges. (b) Pet-first → BotFather wizard → skill enabled with existing pet_id. (c) Agent-first → /hatch → soul-arrived event → next reply has the "I feel different" moment.
7. Social: two test accounts visit each other; rate-limit holds.
8. Cross-platform parity: all flows pass on mobile Safari + Chrome.
9. Tick loop survives restart: redeploy → no double-decays.