AgentCat

Agent Cat

An animated desktop companion for AI agents.

English · 简体中文

Agent Cat brings AI agent activity to life through animated desktop pets and real-time status updates. It is designed as an agent- and platform-independent companion, with Codex, Claude Code, and DeepSeek Harness integrations on macOS and Windows.

> Current status: Agent Cat is under active development. The current version supports macOS 12 or later and Windows 10 or later, and integrates with Codex, Claude Code, and DeepSeek Harness. Support for more agents and operating systems is planned.

Download

Download the latest build from [GitHub Releases](https://github.com/LRainner/AgentCat/releases/latest).

The current macOS build is not notarized with an Apple Developer ID. If macOS blocks the first launch, right-click Agent Cat and choose Open, or allow it from System Settings → Privacy & Security. Only install builds downloaded from this repository.

The current Windows build is not code-signed. Windows SmartScreen may show a warning on first launch; only continue when the installer was downloaded from this repository.

Highlights

• Animated desktop pets with click, double-click, drag, idle, and pointer-following reactions
• Real-time agent state displayed beside the pet without expanding its clickable area
• Configurable size, opacity, always-on-top behavior, mouse passthrough, and position locking
• System tray controls, launch at login, a settings window, and an animation debugger
• Codex-compatible v1 and v2 pet packs, including all nine standard animations and 16 v2 look directions
• Pet discovery from installed ChatGPT/Codex apps, ~/.codex/pets, and user-selected directories
• On-demand access to locally installed pet assets without copying or redistributing them
• A built-in original fallback pet when no compatible pet pack is available

Agent integrations

Codex

Agent Cat can react to Codex sessions through command hooks. The settings window can install, repair, test, and remove the integration while preserving hooks owned by other tools.

The integration currently recognizes session start/end, prompt, tool, subagent, compaction, permission, completion, and interrupted-turn events. Live status and task summaries can be enabled independently.

Claude Code

Agent Cat installs command hooks into ~/.claude/settings.json without replacing existing Claude Code settings or hooks. It observes 13 state-relevant events covering sessions, prompts, tools and tool failures, subagents, compaction, permission requests, turn completion and API failures. The integration can be installed, tested, paused, repaired, and removed independently from Codex.

DeepSeek Harness

Agent Cat reacts to DeepSeek Harness through the bundled [dsh-session-agent-cat](plugins/dsh-session-agent-cat/README.md) plugin (Settings → Agents → DeepSeek Harness → Connect). It forwards only sanitized lifecycle metadata locally — tool arguments, file contents, and terminal output never leave the harness process. Restart DeepSeek Harness after the first install or an update; see the [plugin README](plugins/dsh-session-agent-cat/README.md) for details.

Pet packs

Each pet lives in its own directory and contains a pet.json manifest plus a PNG or WebP spritesheet:

{
  "id": "my-pet",
  "displayName": "My Pet",
  "description": "An optional description",
  "spriteVersionNumber": 2,
  "spritesheetPath": "spritesheet.png"
}

The current renderer supports the Codex-compatible sprite layout:

• Cell size: 192 × 208
• v1 sheet: 8 × 9 cells (1536 × 1872)
• v2 sheet: 8 × 11 cells (1536 × 2288)
• spriteVersionNumber may be 1 or 2; omitting it selects v1

Place custom packs in ~/.codex/pets or add another directory from Settings.

Development

Requirements

• macOS 12 or later, or Windows 10 or later
• Node.js 20.19 or later
• A stable Rust toolchain
• Xcode Command Line Tools on macOS
• Microsoft Edge WebView2 Runtime on Windows (the installer can download it when needed)

Run locally

npm install
npm run tauri -- dev

Right-click the pet to open Settings. Auxiliary windows can also be opened from the command line:

agent-cat --settings
agent-cat --pet-debug

Test and build

Install Playwright Chromium once before running the browser tests or regenerating screenshots:

npx playwright install chromium

npm test
npm run test:e2e
npm run screenshots
npm run build
cargo test --manifest-path src-tauri/Cargo.toml
npm run tauri -- build

npm run screenshots regenerates the deterministic product images in docs/images with mocked local data.