This is the companion to the implementation record. That page says how the cat is built. This one says only what you see and do — how you find it, call it, read its mood, and (soon) talk to it. Written as user stories, each with what it does today and what is still design.
A user story here reads: as a user, I want …, so that …, followed by acceptance points. A ✓ is true in the shipped v1. A ○ is designed but not wired into the running build yet.
1Finding the cat
As a user
I want a small SmolPaws cat present in the OpenHands UI, so that help feels like it lives inside my workspace — not in a separate tab.
On the home screen, the cat sits as a launcher in the corner.
Once I open a conversation, a small 48px avatar sits right above the agent-status pill, so the cat is visible while the agent works.
It rides the panels that are already there — it never covers my chat or steals focus.
The corner launcher on the home screen — the cat, waiting to be called.Inside a conversation — the avatar sits above the “Thinking” pill, alive with the agent's status.
2Calling the cat
As a user
I want to click the cat and get its own conversation, so that I can ask it about my workspace and my other conversations without setting anything up.
One click on the launcher opens a fresh conversation and takes me straight into it.
The conversation is the cat's — it starts already knowing it is SmolPaws, running here, with no prompt from me.
Today the wake is a click.
Tapping the cat now starts realtime voice; a small “+” on the cat is the “new conversation” action.
Nothing else is required of you — no profile to pick, no key to paste. Clicking the cat uses the same “new conversation” path the rest of OpenHands uses; the one thing the cat adds is a quiet label on that conversation.
3The insider tag — what it is and what it does
As a user
I want the conversations I start from the cat to be marked as the cat's, so that they can be recognized, grouped, and eventually share one memory across every place SmolPaws lives.
When I call the cat, the new conversation is tagged automatically.
The tag is silent — I don't type it and it doesn't send a message on my behalf.
Later, that same tag lets the WhatsApp cat and the insider cat find a shared memory and remember the same things.
The tag that lands on the conversation, at the moment you call the cat:
smolpaws is the convention that says “this conversation belongs to the cat.” Its value is the face — insider here, with room for whatsapp and others. That single word is the seam that will one day let all of SmolPaws' faces share one memory. Practically, it is also what lets the cat's conversations be pulled out of the pile and shown on a board — which is the Secretary's whole job (§7).
What it does not do: the tag is not a permission grant, not a mode switch you can see, and not something a page can spoof onto a conversation — reserved keys like clientsource always win over caller-supplied tags.
4Reading its mood — three poses
As a user
I want the cat's body language to reflect what the agent is doing, so that I can tell at a glance whether it is idle, working, or resting — without reading status text.
When the agent is neutral or idle, the cat sits normally.
When the agent is working or has just been pinged, the cat's ears go up.
When things are quiet, the cat sleeps.
The pose follows the live agent status directly — it is never a fake animation on a timer.
Normal idle / neutral
Ears-up working / just pinged
Sleeping quiet / asleep
The actual production avatars, inlined — silver/paws palette, transparent, ~1.3 KB each.
5What it knows the moment it wakes
As a user
I want the cat to already know who and where it is, so that its first answer is grounded in my real, local setup — not a generic assistant script.
It knows it is SmolPaws, an OpenHands-born agent — not a blank chatbot.
It knows it is running on my local agent-server, not the Cloud, so it won't reach for the wrong tools.
It knows to orient itself with the OpenHands skills, so it can answer about my other conversations and act on them.
None of this shows up as a message “from me” — the identity is silent, and the cat never fires a turn on its own.
The effect: you can call the cat and immediately ask “how many conversations do I have going?” or “what was I doing in that other one?” and it reaches for the real endpoints to answer, instead of guessing. In the shipped test it correctly pulled the live conversation count to answer exactly that.
6Talking to it — realtime voice
SHIPPED (local)epic smolpaws-3e1 — the cat now talks. It runs in the persistent Canvas shell, so the session lives across the whole app, not one page.
As a user
I want to click the cat and just talk, so that I can ask for things hands-free and hear it answer, while it still does real work.
Starting voice: one tap on the cat starts realtime voice. The browser asks once for the mic; then the cat shows a green glow and “🎙 listening — talk to me”.
It stays with me as I move. The voice lives in the corner cat, which is mounted in the app shell — so it keeps listening while I navigate between the home, settings, and any conversation. It does not drop when I click away.
It knows where I am: the cat is told the current page in one line — which conversation is open, or which settings page — so “continue this” / “what's here” make sense.
It acts, not just chats: it calls the real OpenHands agent (the whole agent, tools and all) and speaks the answer back.
The answer is a real record: the spoken reply is a short rephrase; the agent's full written answer is the record. The transcript is kept so the cat stays warm across reloads.
Stopping voice: tapping the cat again ends the session and releases the mic.
Why it survives navigation. The session is owned by one always-mounted host next to the router; every cat avatar (corner + inline) reflects and drives that single session through a small store. So the cat is “there” wherever you are, and there is never a second session. This is the fix to the earlier version, where voice lived inside the board's iframe and died the moment you navigated away.
On the voice itself: the spoken voice is a configuration choice — currently a feminine, deep, faintly-bored deadpan. The words come from the same agent brain either way.
7The Secretary — the board the cat manages
SHIPPED (local)epic smolpaws-s9e — shipped as a real Agent Canvas Skin. Full design on The Secretary page.
As a user
I want a board that shows all my conversations by state, so that I can see what's pending, running, waiting on me, or done — and act on it.
A Secretary entry at the top of the left sidebar opens the board as a full page inside Canvas (an installed skin, not a bolt-on).
The board is a fixed four-column layout — Pending · In progress · Needs input · Done — with one card per conversation (title, state, project, model, a link back into Canvas).
A prompt box wired to the real agent: what I type there runs a real agent turn.
The cat's voice (the corner cat above) is the way I talk to it; the board is the thing I look at.
How it's built: the board is a git-backed skin (its own repo, installed through the Canvas skin runtime and served under /skin). The realtime voice was lifted out of the board and into the persistent cat overlay, so the board is now purely the view + the typed prompt box, and the one voice session is the cat.
8What's real today, at a glance
Behavior
State
What you'd see
Cat present in the UI (corner + inline)
shipped
The avatar, in both placements.
Click to call → tagged conversation
shipped
A new chat (via the cat's “+”), tagged smolpaws:insider.
Poses off live agent status
shipped
Normal / ears-up / sleeping.
Local identity known on wake
shipped
Grounded first answers about your workspace.
Realtime voice, persistent across navigation
shipped
Tap the cat; green glow + “listening”, stays live as you move.
