CATA 🐱

A living desktop cat for AI Agents & IDEs (Google Antigravity, Cursor, Codex, etc.)
Celebrates finished agent work · Follows your mouse · Reminds you what matters

Why?

Long AI coding sessions feel empty when the agent finishes in silence. CATA puts a small desktop cat companion on your screen that reacts to what you do and what your AI agents complete — without getting in the way.


Announce	Agent stop, todo done, commit / push
Chase	Follows your cursor (toggle anytime)
Remind	Natural language chat input, quick time chips (`+5m`, `+15m`), or MCP `cata_remind`
Stay out of the way	Pass-through clickability — click any app on screen while chat is open

Local-only on 127.0.0.1 — no cloud, no telemetry.

Features

Transparent overlay — always-on-top, frameless, drag / double-click / roam
Follow cursor — sprint after the mouse; tray toggle
AI Agent & IDE hooks — agent stop, TodoWrite, git commit / git push
Smart Natural Language Reminders — auto-detects duration (10m, 30 phút, 1h) or exact time (14:30, 9h00) in VI/EN directly from chat input
Quick Time Preset Chips — 1-click preset buttons (+5m, +15m, +30m, +1h) for instant alarm scheduling
Zero-Overlap Position Engine — popup automatically positions beside or above pet (with 16px gap) so it NEVER covers the pet or speech bubbles, even on screen boundaries
Smart Pause on Open — pet automatically pauses movement when chat is open so it won't walk under the popup
Pass-through Clickability — dynamic hit-testing allows clicking any other desktop application or window freely while chat is open
Double-Click Toggle & Auto-Close — double-click pet to toggle open/close; click outside chat to auto-close
Official NPM MCP Package — run npx cata-mcp anywhere without manual server setup
i18n — Auto from system / IDE locale, or force en · vi · zh · ja · ko
MCP tools — agents in Google Antigravity, Cursor, Codex, or Claude Desktop can cata_say, cata_remind, cata_status
Git watcher — celebrate commits outside IDEs too
Physics splat — drop from high enough → puddle → pop back
Single tray icon — one instance only

Quick start

Need: Node.js 20+.

git clone https://github.com/vuanhtuan2000work/CATA.git
cd CATA
npm install
npm run build

Install MCP for Google Antigravity

npm run install:mcp:antigravity

Or simply use npx cata-mcp in ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "cata": {
      "command": "npx",
      "args": ["-y", "cata-mcp"]
    }
  }
}

Install MCP for Cursor

npm run install:mcp
npm run install:hooks   # ~/.cursor/hooks.json

Or simply use npx cata-mcp in ~/.cursor/mcp.json.

Install MCP for Codex / Claude Desktop / General Hosts

Add to your MCP host configuration:

{
  "mcpServers": {
    "cata": {
      "command": "npx",
      "args": ["-y", "cata-mcp"]
    }
  }
}

Start CATA Desktop App

npm start

Packaged builds

npm run dist        # Windows portable → apps/desktop/release/
npm run dist:mac    # .dmg + .zip (build on a Mac)

How it works

Google Antigravity / Cursor / Codex / MCP ──POST──► 127.0.0.1:7331 ──IPC──► Overlay pet
                                                          ▲
                                        Tray · Chat inbox · Git reflog watcher

Electron opens a full-screen transparent overlay (click-through by default).
A tiny HTTP inbox on localhost receives events from hooks and MCP.
The renderer runs a PNG frame state machine (idle, walk, run, sleep, splat, …) with speech bubbles.

Chat inbox & Reminders

Double-click the pet (or use the tray menu):

Auto-Detect Reminders: Type any task with time ("Review PR sau 10m", "Họp team lúc 14:30", "Go to sleep in 30 mins") and CATA will parse and schedule the alarm automatically.
Quick Preset Chips: Click +5m, +15m, +30m, or +1h chips before sending any note.
Pass-through Clicking: Keep working! Click any background app while the chat box is open.
Double-Click Toggle: Double-click the cat again or click anywhere outside to close.

MCP tools (`cata-mcp`)

Supported in Google Antigravity, Cursor, Codex, Claude Desktop, and any standard MCP host:

Tool	Alias	Purpose
`cata_say`	`pet_say`	Speech bubble now (`priority: high` → excited hops)
`cata_remind`	`pet_remind`	Schedule a reminder (`at` = ISO, or soon)
`cata_status`	`pet_status`	App running? Pending reminders?

Example prompt for your AI agent:

"When you're done building the feature, call cata_say to tell me the PR is ready."

Tray menu

Right-click the tray / menu-bar icon:

Show / hide pet
Add reminder…
Chat inbox…
Watch a git repo…
Follow cursor · Mute · Language
Start with Windows / macOS
Quit

Language: Auto (OS locale) or lock to en / vi / zh / ja / ko.

Settings

OS	Path
Windows	`%APPDATA%/cata/settings.json`
macOS	`~/Library/Application Support/cata/settings.json`

{
  "port": 7331,
  "scale": 1,
  "muted": false,
  "followCursor": true,
  "locale": "auto",
  "repos": ["D:\\github\\my-repo"]
}

Override the port with CATA_PORT (app, hooks, and MCP all honor it).

HTTP API

Endpoint	Method	Body
`/event`	POST	`{ type, title?, message, priority? }`
`/reminder`	POST	`{ message, at? }`
`/reminders`	GET	—
`/reminder/:id`	DELETE	—
`/status`	GET	—

Architecture

CATA/
├── apps/desktop/     Electron overlay (main + renderer + frames)
├── packages/mcp/     Official cata-mcp server (npm package)
├── hooks/            Cursor hook scripts + installer
└── scripts/          MCP installers for Antigravity & Cursor

Stack: Electron · TypeScript · MCP · Google Antigravity · Cursor Hooks · Node.js

macOS notes

Lives in the menu bar + overlay (hidden from Dock)
Visible on all Spaces and fullscreen apps
Unsigned builds: allow once in System Settings → Privacy & Security
Build packages on a Mac: npm run dist:mac

Roadmap

Community skins / more breeds
Multi-monitor aware roaming
Optional CI reactions (gh pr checks)
Auto-update channel

Issues and PRs welcome.

Tiếng Việt

CATA là chú mèo desktop trên overlay trong suốt: báo khi AI agent (Google Antigravity, Cursor, Codex, v.v.) hoàn thành công việc, đuổi theo con trỏ chuột, tự động nhận diện thời gian gõ trong chat để hẹn giờ nhắc việc, chat inbox local, và nhận thông báo qua giao thức MCP (cata_say, cata_remind).

Hướng dẫn cài đặt nhanh:

npm install && npm run build
npm run install:mcp:antigravity   # Cắm MCP vào Google Antigravity
npm run install:mcp               # Cắm MCP vào Cursor
npm start

Sử dụng MCP trực tiếp qua NPM (Không cần clone repo):

Gói MCP chính thức đã có mặt trên npm registry: cata-mcp. Bạn có thể cấu hình ở bất kỳ máy nào:

{
  "mcpServers": {
    "cata": {
      "command": "npx",
      "args": ["-y", "cata-mcp"]
    }
  }
}

Điểm nổi bật:

NPM Package: Chạy trực tiếp npx cata-mcp trên mọi máy.
Tự động đọc giờ tự nhiên: Gõ "nhắc 10 phút review pr", "họp team lúc 14:30", "1 tiếng nữa đi ngủ" tự động tạo báo thức.
Nút chọn nhanh (+5m, +15m, +30m, +1h): Chọn nhanh thời gian 1-click.
Vị trí hiển thị tách biệt 100%: Khung chat tự động né chú mèo và bóng thoại (khoảng cách 16px), dừng mèo di chuyển khi chat mở.
Click xuyên màn hình: Vẫn click làm việc bình thường với các phần mềm khác khi khung chat đang mở.
Double click bật/tắt: Double click mèo để mở/tắt khung chat nhanh.

License

MIT — use it, fork it, put a cat on every monitor.

_{If CATA makes your coding sessions a little happier, star the repo ⭐}

Name		Name	Last commit message	Last commit date
apps/desktop		apps/desktop
hooks		hooks
packages/mcp		packages/mcp
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Navigation Menu

Repository files navigation

CATA 🐱

Why?

Features

Quick start

Install MCP for Google Antigravity

Install MCP for Cursor

Install MCP for Codex / Claude Desktop / General Hosts

Start CATA Desktop App

How it works

Chat inbox & Reminders

MCP tools (`cata-mcp`)

Tray menu

Settings

HTTP API

Architecture

macOS notes

Roadmap

Hướng dẫn cài đặt nhanh:

Sử dụng MCP trực tiếp qua NPM (Không cần clone repo):

Điểm nổi bật:

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

CATA 🐱

Why?

Features

Quick start

Install MCP for Google Antigravity

Install MCP for Cursor

Install MCP for Codex / Claude Desktop / General Hosts

Start CATA Desktop App

How it works

Chat inbox & Reminders

MCP tools (cata-mcp)

Tray menu

Settings

HTTP API

Architecture

macOS notes

Roadmap

Hướng dẫn cài đặt nhanh:

Sử dụng MCP trực tiếp qua NPM (Không cần clone repo):

Điểm nổi bật:

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

MCP tools (`cata-mcp`)