A desktop pet companion: an always-on-top animated character plus a chat panel, a watch list, an appearance gallery, and an autonomous "owner loop" that plans moves/moods, checks watched items, and delivers notifications. The pet windows render only in the Kiro Crew desktop (Electron) shell; the dashboard page is a browser-visible status/watch/plan surface.
defaultEnabled: false and platform.requiresDesktopApp: true — it appears in
the App Store, is opt-in, and its window surfaces need the Electron shell.
permissions: api, storage, events, cron, spawn.
The desktop pet keeps polling the gateway while disabled so enabling Mochi in the App Store takes effect without restarting the shell. Probe diagnostics are deduplicated per outcome for one minute, including alternating HTTP errors and disabled responses; actual enabled-state changes still log immediately.
A non-answer never creates a pet. Every probe the reconcile tick makes is
tri-state (enabled / disabled / unknown), including the remote instance's
own Mochi flag (instanceGate.remoteEnabledState). unknown means keep
whatever is on screen: it never tears a pet down, and it never opens one. With
the host's Mochi disabled, a pet is created only on a definite enabled from
the remote named by the shell's petInstance pointer; on a non-answer it is
kept only if a pet window already exists, and a teardown resets the shown
pointer to self. The pet overlay is a full-display window pinned at the
screen-saver level on every Space, so an opaque page in it covers the whole
machine with nothing to dismiss: a main-frame did-fail-load (gateway
unreachable) and any >=400 navigation both hide and latch the overlay, and
the reconcile tick re-arms it once a target answers.
| Path | What it is |
|---|---|
src/kiro_crew/apps/builtins/mochi/app.json |
manifest (backend.routes, backend.hooks, top-level mcpServers, ui.pages, agents, permissions, platform.requiresDesktopApp) |
.../hooks.py |
the owner loop — MochiRuntime, the on_startup/on_shutdown lifecycle hooks, the poller/idle/watchlist callback bags, and the notify path |
.../queue_file.py, .../queue_poller.py |
the behaviour queue (planned moves/moods/reminders) + the poller that executes it — a file-based scheduler that lives beside core cron.py, not on top of it |
.../watchlist_file.py, .../watchlist_service.py |
watch items (add/cancel/remove/update), cross-process-locked RMW |
.../pinned_files_service.py, .../stats_service.py, .../idle_manager.py |
pinned-file tracking, companion stats, idle/presence |
.../notification_gate.py |
leading-edge notify gate (merge window, silent mode, critical bypass) |
.../agent_policy.py |
builds the per-agent MCP policy (grants + neutralize) |
.../soul_loader.py |
persona text + rendered agent prompt |
.../mcp_server.py |
the stdio mochi:mochi MCP server (get/update plan, perform_pet_action, watchlist, pins, read_mochi_file) |
.../redact.py |
shared credential/exfiltration-URL redactor for agent-authored data |
.../backend/routes.py |
the dashboard/panel HTTP surface (gated + validated) |
.../agents/mochi.json, .../agents/mochi-bg.json |
the two shipped agent specs (chat + background) |
.../agents/context/, .../agents/skills/ |
the behaviour prompt + bundled skills |
website/src/apps/mochi/ |
vendored renderer (ChatPanel, WatchlistPanel, GalleryPanel, SettingsPanel, pet overlay) + the mochiApi seam |
website/electron/mochi/ |
the Electron main-process shell (pet overlay windows, panel/settings/avatar windows, global shortcuts, multi-instance) |
website/src/apps/mochi/src/renderer/ChatPanel.tsx is the chat panel's one import
path: ChatApp.tsx, the capture harnesses and the specs import from it, and it
re-exports PinnedSidePanel, Bubble, fixStreamingFences, parseApproval and
externalApprovalApproved from the owners that define them. It keeps the panel
component (header, transcript, composer, slash commands, the send-failure line and
the context ring). Owners never import it, and nothing outside the panel's own
files, bar its specs, imports an owner.
| Owner | Holds |
|---|---|
ChatPanelPinnedFiles.tsx |
the pinned-files side panel (PinnedSidePanel) and its file chips |
ChatPanelMarkdown.tsx |
message markdown: the remark and rehype chains, the element overrides (inline file chips, local images) and the streaming renderer (StreamingMarkdown, fixStreamingFences) |
ChatPanelBubble.tsx |
one transcript message (Bubble): the approval card and its scoped-trust rows, parseApproval, externalApprovalApproved and the relative timestamp |
New work for a responsibility in the table goes to its owner; anything else starts
in ChatPanel.tsx. A fix ported from upstream Mochi's ChatPanel.tsx lands in
whichever of the four files holds that code. ChatPanel.owners.test.tsx pins the
owner set, the re-exports and the import direction.
The desktop shell rate-limits repeated instance-resolution diagnostics per outcome for one minute. Alternating unanswered and resolved polls do not flood the log, while a confirmed target change (including a new port) logs immediately.
- Reserved
mochichat slot. The chat panel is backed by a dedicated core chat slot keyedmochi. It is the app's identity for streaming/approvals; do not repurpose it. - First
backend.hookslifecycle consumer. Mochi is the first builtin to use the App Kiton_startup/on_shutdownlifecycle hooks.on_startupis async — it loads persisted stats/pins off the event loop viaasyncio.to_thread(the lifecycle dispatcher awaits a coroutine-returning hook), so enabling/disabling Mochi never blocks gateway requests or heartbeats. - MCP neutralize policy.
agent_policy.pygrants the app's own tools and neutralizes every ungranted ambient MCP server — including an unprobed one (empty tool list) — by handing the bridge adisabled: trueserver-level entry. Deferring the unprobed case would be a fail-open that leaks ambient access. The shipped agent templates carry noallowedTools(that would skip the PreToolUse gate); tools live intoolsand are gated per call. - File-based scheduler beside
cron.py. The behaviour queue + poller are a separate, app-owned scheduler (moves/moods/reminders onnextCheckAfter), not a layer over core cron. Theupdate_watchlistMCP schema must advertise every op the poller/prompts send (add/cancel/update/remove, plushistoryEntry/notified/nextCheckAfter) or a watch-check write is rejected and the item re-spawns forever. - Agent-authored data is redacted at every browser sink. notify/mood/
watchlist/chat-push/pins all pass through
redact.redact_tree(or_redact_plan_tree) before reaching the browser. - Mutating routes are owner-only for dashboard subjects. Every POST/DELETE
handler in
backend/routes.pycalls_owner_deniedfirst: a caller with an empty or missingappclaim must passrequire_owner_dashboard_requestor gets the shared 403owner_only, before any body read or runtime use. An app token keeps the scopetoken_authalready granted it. GET routes are not owner-gated. Pinned bytest/test_mochi_owner_gate.py.
- The vendored
ChatPanel/panelBridgeare a deliberately owned fork, not a convergence-pending copy. The product intentionally keeps Mochi's original chat surface rather than adopting the dashboard'sChatEmbed. Consequence, accepted: an approval-flow or widget-protocol change made in the dashboard chat must be ported to Mochi's panel too — the two surfaces are maintained in parallel on purpose. Do not replaceChatPanelwithChatEmbed. - The Electron main-process code under
website/electron/mochi/is a first-party exception, not a precedent that third-party builtins may ship main-process code. App Kit apps are renderer + backend only; Mochi's shell windows exist because it is a first-party desktop pet.
Pending dropped attachments display the basename of Windows drive and UNC
producer paths in the chip, tooltip and accessible labels. Display calculation
uses pathBasename (the shared separator-aware basename helper); the staged
attachment path stays unchanged for removal and send serialization. POSIX
filenames containing a literal backslash retain that character.
Shortcut hints resolve CommandOrControl for the current platform via
website/src/apps/mochi/src/shared/shortcut.ts (⌘ on macOS, Ctrl on
Windows/Linux) — the pet's Hide hint is the only recovery path once hidden, so a
wrong glyph there strands the user. Route/pageUrl and window discovery are
generic App Kit mechanisms (/app-windows/<app>/<name>.html), carrying no
mochi-specific branching in core.