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.

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.

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.

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.