Find your next open-source project

Search by name, purpose, or keyword — or paste a GitHub repository URL

qianyiai/kurocat

System Tools

A transparent always-on-top desktop pet that shows your typing and mouse clicks, with switchable cat skins and MCP customization.

122
24
TypeScript
MIT
1 day old

What it does

KuroCat is a transparent, always-on-top desktop companion for Windows and macOS. It reflects keyboard and mouse activity on screen: key bubbles appear above the cat while you type, and the left, right, and middle mouse buttons are highlighted separately with 3D press shadows and small LMB/RMB bubbles. The pet tilts its head to the rhythm of your typing and curls the idle paw.

It ships with six hand-drawn cat skins (classic black, ragdoll, orange tabby, calico, tuxedo, and Siamese) and can switch between a 65% compact layout and a full 108-key layout, with a "facing viewer" or "facing cat" orientation. A built-in MCP server lets AI clients create or modify skins by describing colors, patterns, ear shape, eye color, tail, white gloves, highlight color, and custom marks, and the changes hot-reload onto the desktop.

It is built with Tauri v2 (Rust global native hooks plus an HTML5 Canvas renderer) and claims zero external runtime dependencies.

Getting started

On Windows 10/11, download and run the v4.6.2 x64 installer from the Releases page. The installer creates a desktop shortcut, Start menu entry, and uninstaller. If an older Windows 10 or LTSC image is missing WebView2, run Microsoft's WebView2 bootstrapper with administrator rights; Windows 7 is not supported.

On macOS 11+, download the v4.5.0 universal DMG, drag KuroCat.app into Applications, and launch it. Because the app is not notarized, the README says to run xattr -cr /Applications/KuroCat.app once if macOS reports that the app cannot be verified or is damaged. Then grant KuroCat both Accessibility and Input Monitoring permissions under System Settings → Privacy & Security.

To connect an AI client after the app is running:

  1. Right-click the cat, enable MCP extension, and click Copy MCP config.
  2. Paste the config into Claude Desktop, Cursor, Antigravity, Windsurf, or Cline.
  3. For stdio mode, point command at the installed executable with args: ["--mcp"].
  4. For HTTP mode while the pet is running, use the local endpoint http://127.0.0.1:27420/mcp.

Example stdio configuration:

{
  "mcpServers": {
    "kurocat": {
      "command": "C:\\Users\\<your-username>\\AppData\\Local\\KuroCat\\KuroCat.exe",
      "args": ["--mcp"]
    }
  }
}

Then ask the AI to add a cat, for example with upsert_cat, and it should appear without restarting. Custom skins are stored in %APPDATA%\kuro-cat-pet\cats.json on Windows and ~/Library/Application Support/kuro-cat-pet/cats.json on macOS, and manual edits are hot-reloaded.

Build from source

You need Windows 10/11 or macOS 11+, Node.js 18+, and a Rust toolchain with cargo. Clone the repository, then run:

npm install
npm run tauri:dev    # development with hot reload
npm run tauri:build  # release executable and installer

Usage constraints

  • Windows 10/11 and macOS 11+ are supported. macOS builds are universal for Apple Silicon and Intel. Windows 7 is explicitly unsupported.
  • On macOS, keyboard and mouse monitoring requires Accessibility and Input Monitoring permissions; after an in-place upgrade, the entry may need to be removed and re-added.
  • Full-screen or borderless games can require lock mouse pass-through and use Alt to unlock, while strong kernel anti-cheat titles may require pausing monitoring from the tray.
  • The MCP HTTP server listens locally on 127.0.0.1:27420 and only works while the desktop pet is running.
  • The project is MIT licensed.

HotRepo's take

KuroCat entered the HotRepo TypeScript new-project list on 2026-11-22, with 117 stars and 14 stars gained in the roughly one-hour window from 16:16 to 17:16 UTC; the recorded star samples move from 111 to 117 within half an hour. That is a very short observation window, so it shows early interest rather than a sustained trend. The project's distinguishing technical choice is putting the MCP server inside the desktop app rather than in a separate process, letting existing AI clients customize the pet while it runs. The main practical caveat is distribution: the primary downloads are prebuilt executables, and the materials available here do not establish the publisher's identity or the correspondence between those binaries and this source tree.

Written by AI from the project's public information and HotRepo's records, updated . The project's own docs are the source of truth.

You might also like

  1. QCYTSN/dsh-dafeiyuA desktop pet for DeepSeek Harness that shows real agent status in an always-on-top transparent window.JavaScript624
  2. ayangweb/BongoCatA Live2D desktop cat for Windows and macOS that animates your typing, mouse and gamepad input on screen.Rust24,177
  3. PC2005-cloud/dsh-petA transparent animated desktop pet that lives in DeepSeek Harness, with an AI-driven pipeline for generating your own pet assets.TypeScript3,915