UniPet

中文文档

UniPet is a Universal Desktop Pet for AI coding agents.

Think Codex Pet, but for every agent. UniPet turns invisible agent work into a small animated desktop companion, so you can see when your agent is thinking, running tools, waiting for input, failing, or ready for review. It is powered by a lightweight local protocol that any agent can speak without patching its core code.

npm install -g uni-pet
unipet start
unipet agent add codex

Why UniPet

• Universal agent status layer for Codex, Claude Code, Hermes, OpenClaw, DeepSeek-TUI, and custom agents.
• Visual feedback for real work: idle, running, waiting, failed, and review states.
• Simple local protocol: drive UniPet from hooks, plugins, config blocks, CLI, HTTP, or WebSocket.
• Zero-intrusion: integrate with agents without modifying their source code.
• Local-first: listens on localhost and keeps events on your machine.
• Lightweight: Node.js + Electron; UniPet itself does not require Python.
• Codex-compatible pets: install, switch, and remove skins from the CLI.

Quick Start

For most users:

npm install -g uni-pet
unipet start

Connect only the agents you use:

unipet agent add codex
unipet agent add claude-code
unipet agent add hermes
unipet agent add openclaw
unipet agent add deepseek-tui

Update later with:

npm update -g uni-pet

Supported Agents

| Agent | Setup | Integration | | --- | --- | --- | | Codex | unipet agent add codex | Codex hooks | | Claude Code | unipet agent add claude-code | Claude Code hooks | | Hermes | unipet agent add hermes | Hermes plugin | | OpenClaw | unipet agent add openclaw | OpenClaw plugin | | DeepSeek-TUI | unipet agent add deepseek-tui | lifecycle hooks | | Custom agents | unipet state ... or HTTP | UniPet local protocol |

Daily Use

Start, inspect, and stop UniPet:

unipet start
unipet status
unipet doctor
unipet stop

Send a manual test event:

unipet state running "Running tests"
unipet state review "Ready for review"
unipet clear

The local bridge listens on:

HTTP  http://127.0.0.1:8768
WS    ws://127.0.0.1:8769/ws

Universal Protocol

Any tool can update the pet through the same event shape:

unipet state running "Running tests" --source my-agent
unipet state waiting "Waiting for approval" --source my-agent --ttl 2m
unipet state review "Ready for review" --source my-agent

For direct integrations, send local HTTP or WebSocket events with source, state, message, action, and ttl. See Protocol.

Pets

Browse and install online pets:

unipet pet search
unipet pet search cat
unipet pet info anby
unipet pet install anby --use

Manage local pets:

unipet pet list
unipet pet current
unipet pet use anby
unipet pet remove anby

Installed pets and user config live under ~/.unipet.

Agent Management

Use agent to add, inspect, disable, or remove UniPet integrations:

unipet agent list
unipet agent status
unipet agent add codex
unipet agent disable codex
unipet agent remove codex

You can replace codex with claude-code, hermes, openclaw, deepseek-tui, or all.

How It Works

Agent hook/plugin
      -> UniPet localhost bridge
      -> state/event engine
      -> desktop pet renderer

Connectors translate agent lifecycle events into a small local event payload: source, state, message, action, and ttl. The renderer then maps those events into Codex Pet-style states, bubbles, and small companion motions.

Platforms

• Node.js 18+
• npm
• Windows, macOS, Linux, Unix, or WSL

UniPet can run on Windows, macOS, Linux, Unix, or WSL. Agent integrations are optional; connect only the agents you actually use.

For Developers

npm install
npm run check
npm start

npm run check runs the overlay tests and connector tests for OpenClaw, DeepSeek-TUI, Codex, and Claude Code.

UniPet/
|-- overlay/                         Node.js/Electron desktop runtime
|   |-- main.js                      Electron app + local HTTP/WS bridge
|   |-- core.js                      event normalization + state store
|   |-- cli.js                       global unipet command
|   |-- market.js                    Codex pet market client
|   |-- pets.js                      local pet library
|   |-- renderer.js                  spritesheet animation renderer
|   |-- life/                        companion behavior layer
|   |-- renderers/                   renderer adapters
|   |-- tests/                       Node test suite
|   `-- assets/default/              bundled default pet
|-- connectors/codex/                Codex hook connector
|-- connectors/claude-code/          Claude Code hook connector
|-- connectors/hermes/               Hermes plugin connector
|-- connectors/openclaw/             OpenClaw hook plugin
|-- connectors/deepseek-tui/         DeepSeek-TUI hook connector
|-- docs/                            design notes
|-- install.ps1                      Windows installer
`-- install.sh                       Unix installer

Troubleshooting

• Run unipet doctor first. It checks the local bridge, runtime file, current pet, and command setup.
• If 127.0.0.1:8768 is already in use, run unipet stop, then unipet start.
• After installing a connector, restart the related agent session, gateway, or TUI.

Docs

• Architecture
• Protocol
• Connectors

License

MIT