TinyRoommate

An AI pet that lives on your desktop.

---

You open the app. A small cat appears on your desktop. It walks around, sits down, yawns.

Every few minutes, a speech bubble pops up — sometimes random ("~♪"), sometimes surprisingly relevant ("you've been coding since 9am... take a break?"). You can pet it, talk to it, or just let it be.

A little friend that lives in the corner of your screen.
Long hours feel shorter when you're not alone.

It sees what you see Screen capture + Claude Vision — knows if you're coding, designing, or doom-scrolling. It remembers you A living memory that grows over time. Not a stateless chatbot. It has personality Sassy, chill, philosophical — you configure it. Knows when to shut up.

It has feelings Pet it → purrs. Ignore it → it gets a little sad. It notices when you're around. It keeps a diary Plain Markdown files — its journal, what it saw on your screen, daily summaries. You can read them. 100% local All data stays on your machine. Nothing leaves your laptop.

Characters

Pick a companion — or make your own.

                        

_{Tabby Cat · Golden Retriever · Blue Buddy · Schnauzer · Tuxedo Cat · Coco}

Each character has its own animations and voice lines. Want something different? Generate a spritesheet with any AI image tool (Gemini, Midjourney, etc.), drop it in, and it just works. See the Sprite Spec for the asset format and TinyRoommate pipeline.

Project Docs

If you're contributing or reviewing changes, start with docs/README.md.

It links to the current:

• product spec
• interaction/UI spec
• development workflow

A Day in Its Life

Your pet reacts to what's happening — not randomly, but contextually.

You're deep in code It works alongside you	You switch apps It notices and observes	You're watching YouTube It starts playing around
It's past midnight "you should rest..." 💤	You pet it Affection +1, purrs	You've been away Hearts decay over time
Nothing happening It wanders your desktop	You drag it Swing physics, not amused	Just vibing Silence is often the right choice

---

Quick Start

Note: TinyRoommate currently runs on macOS only. Windows and Linux support is on the roadmap.

You need Node.js (v18+), Rust, and Claude Code (for the AI brain).

gh repo fork ryannli/tinyroommate --clone
cd tinyroommate
npm install
npm run tauri:dev

npm run tauri:dev picks an open port automatically. Set TAURI_DEV_PORT=5180 to pin Tauri dev to a specific port, or PORT=5180 when running the frontend without Tauri.

Prerequisites

• Node.js v18+
• Rust
• Claude Code — for the AI brain (optional — pet still runs without it, just can't think or talk)

Screen Recording permission (optional)

For the pet to "see" your screen: System Settings → Privacy & Security → Screen Recording → enable your terminal app → restart terminal.

Without this, everything still works — it just can't see what you're doing.

Linux dependencies

sudo apt-get install -y \
  pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev \
  libayatana-appindicator3-dev librsvg2-dev libssl-dev \
  fonts-noto-color-emoji

First launch compiles Rust (~2-3 min). After that it's instant.

---

Interactions

Hold on pet	It purrs
Click	Quick reaction
Double-click	Chat
Drag	Move it around
Right-click	Settings

Make It Yours

Right-click → Settings to change names and character.

For deeper customization, edit .pet-data/config.md:

---
pet_name: Cooper
owner_name: Alex
sprite: golden_retriever
---

# Personality
- Be sarcastic and dry
- If I'm working past midnight, roast me

# Reminders
- Nudge me to take breaks every 30 min

Your pet reads this every time it thinks. Changes take effect immediately.

Its Memory

All data lives in .pet-data/ — plain Markdown you can read:

File
config.md	Your preferences — edit this
me-journal.md	Its diary about life with you
owner-memory.md	What it knows about you
owner-perceptions.md	What it saw on your screen today
owner-timeline.md	Daily activity summaries

---

_{Built with Tauri · Vanilla JS · Claude Code
MIT License}