README.md

June 18, 2026 · View on GitHub

CoPet

A living desktop companion for every AI Agent.

Powered by Codex-compatible pet packages, CoPet reacts in real time to Claude Code, Codex, Antigravity, OpenCode, Cursor, Copilot CLI, Pi, and Gemini, turning prompts, tool use, waiting, and completions into lively pet reactions on your desktop.

简体中文

Built with Tauri, Rust, and React. Lightweight, local-first, no cloud.

Built-in pets

_{CoPet Neo}	_{CoPet Nia}	_{CoPet Mecha}	_{DJ Fuzz}	_{Lucky Dog}
_{Azure Dragon}	_{Waddly Duck}	_{Cloud Goat}	_Goku	_{Chestnut Horse}
_{Clever Monkey}	_{Orange Cat}	_{Cream Ox}	_Panda	_{Blush Pig}
_{White Rabbit}	_{Pearl Rat}	_{Golden Rooster}	_{Jade Snake}	_{Striped Tiger}

Features

Real-time pet reactions to Agent prompts, tool use, waiting, completion, and errors.
Integrations for Claude Code, Codex, Antigravity, OpenCode, Cursor, Copilot CLI, Pi, and Gemini.
Built-in pets plus import support for Codex-compatible pet packages.
Rich pet interactions: hover, click, double-click, rapid-click petting, long-press, drag reactions, and native context menu.
Global and per-pet sound packs for interactions and Agent states.
Settings and tray controls for pet size, pet launch animation on app startup, Agent message display mode, hooks, sounds, language, visibility, and window position.
Agent messages can show only the latest update or keep multiple Agent updates visible at once.
Local-first data model in ~/.copet, with safe hook backups, atomic writes, and no telemetry.

Installation

Platform	Download
macOS (Universal)	CoPet-macos-universal.dmg
Windows x64	CoPet-windows-x64.exe

All releases

macOS

Drag CoPet.app into /Applications. The build is not notarized, so run once to clear the quarantine flag:

sudo xattr -rd com.apple.quarantine /Applications/CoPet.app

Windows

Windows builds are not code-signed. SmartScreen may warn on first launch — click More info → Run anyway.

Customize your pet

CoPet is not limited to built-in pets. The CoPet Skill series helps you turn a character idea, team mascot, or personal avatar into your own desktop companion:

copet-gen generates and installs custom CoPet pet packages with pet.json and spritesheet.webp, so your own pet can react to Agent activity.
copet-sound creates matching 11-clip MP3 sound packs for clicks, gestures, waiting, success, and error states.

Install CoPet Skills into Codex with either method.

From a terminal:

npx skills add ChanceYu/CoPet --skill '*' -a codex

Inside Codex:

$skill-installer install all CoPet skills from https://github.com/ChanceYu/CoPet/tree/main/skills

Restart Codex if the newly installed Skills do not appear.

Codex only. copet-gen delegates pet generation to the upstream $hatch-pet / $imagegen chain, which depends on Codex's built-in image_gen tool. Claude Code, Cursor, and other agents do not ship this tool, so the Skill is not supported there.

Supported agents

Agent	Integration	Default config path
Claude Code	JSON hooks	`~/.claude/settings.json`
Codex	JSON hooks + trusted hook hashes	`~/.codex/hooks.json`, `~/.codex/config.toml`
Antigravity	JSON hooks	`~/.gemini/config/hooks.json`
OpenCode	JS plugin + config entry	`~/.config/opencode/plugins/copet.js`, `~/.config/opencode/opencode.json`
Cursor	JSON hooks	`~/.cursor/hooks.json`
Copilot CLI	JSON hook file	`~/.copilot/hooks/copet.json`
Pi	TypeScript extension	`~/.pi/agent/extensions/copet/index.ts`
Gemini	JSON hooks	`~/.gemini/settings.json`

Getting started

Prerequisites: Rust, Node.js with pnpm. Runs on macOS (primary), Windows, and Linux.

git clone https://github.com/ChanceYu/CoPet.git
cd CoPet
pnpm install
pnpm tauri:dev          # development
pnpm tauri:build        # production bundle

Project layout

src-tauri/ — Rust core, agent adapters, runtime server.
src/ — React frontend (pet window + settings center).
src-tauri/assets/pets/ — built-in pet packages bundled with the app.
src-tauri/assets/sounds/ — built-in global sound packs bundled with the app.
skills/ — optional CoPet Skill docs for generating pets and 11-clip sound packs.
docs/architecture.md — technical architecture and design.
AGENTS.md — contributor guide and testing instructions.

Security

Event server binds only to 127.0.0.1, requires a bearer token, rate-limits requests, and drops unknown payloads.
All hook config changes are backed up before write and use atomic file ops.
Pet and sound packages are treated as untrusted data and validated before use.
assetProtocol.scope whitelists exactly which pet, sound, preview, and bundled resource directories the webview can read.

Contributing

Issues and PRs welcome. Start with AGENTS.md for setup and conventions, and docs/architecture.md for the system design.