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 + your chosen AI CLI — 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

_{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](SPRITE-SPEC.md)** for the asset format and TinyRoommate pipeline. ## Contributing If you're contributing or reviewing changes, start with **[Contributing](.github/CONTRIBUTING.md)**. For the current product and interaction specs, use **[docs/README.md](docs/README.md)**. ## 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](https://nodejs.org/) (v18+), [Rust](https://rustup.rs/), and either [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Gemini CLI](https://github.com/google-gemini/gemini-cli) for the AI brain. ```bash 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](https://nodejs.org/) v18+ - [Rust](https://rustup.rs/) - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Gemini CLI](https://github.com/google-gemini/gemini-cli) — for the AI brain (optional — pet still runs without it, just can't think or talk)

Screen Recording permission (needed for screen-aware behavior)

For the pet to "see" your screen: **System Settings → Privacy & Security → Screen Recording** → enable your terminal app → restart terminal. Without this, TinyRoommate still runs, talks, and reacts — it just can't see what you're doing or make screen-aware observations.

Linux dependencies

```bash 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 On first launch, pick **Claude Code** or **Gemini CLI**. Right-click → **Settings** any time to change names, character, or AI provider. For deeper customization, edit `.pet-data/config.md`: ```yaml --- pet_name: Cooper owner_name: Alex sprite: golden_retriever ai_provider: gemini --- # 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 / Gemini CLI}
_{MIT License}