convez.ai
AgenteProdutividadeIntermediário
tranhuuhuy297

AgentPet Linux

tranhuuhuy297/agentpet-linux

Mascote desktop que monitora agentes IA em paralelo no Linux

Ver no GitHub
InicialPluginScore · de 0 a 100

Monitor nativo em Rust + GTK4 que exibe o estado de seus agentes IA de coding (Claude Code, Codex) via um mascote desktop e ícone de bandeja. Mostra em tempo real quem está trabalhando, pronto ou aguardando entrada, com notificações e som.

Instalação

$npx convez-ai tranhuuhuy297/agentpet-linux

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.13.1
Issues abertas
2
Contribuidores
1

Casos de uso

  • Monitorar múltiplos agentes de coding rodando simultaneamente
  • Acompanhar estado de execução do Claude Code e Codex de forma visual
  • Receber notificações de mudança de estado dos agentes

Veredito

Ferramenta bem implementada em Rust com foco em DevEx: integra hooks Unix socket, UI nativa GTK4 e estratégia Wayland sólida. Preenche lacuna de monitoramento visual para fluxos multi-agent no Linux, mas requer setup inicial de hooks em cada agente (Claude Code e Codex).

README

A tradução para o português deste README ainda está na fila.

AgentPet for Linux

A native Rust + GTK4 app for Ubuntu 22.04+, inspired by AgentPet (macOS). Watch your AI coding agents (Claude Code and Codex) running in parallel and see — at a glance — which one is working, which is done, and which is waiting for your input, via a tray monitor and a desktop pet per agent (run Claude Code and Codex together and you get two pets, each reflecting its own state).

Status: working. Core logic, CLI/daemon, the GTK pet + monitor + settings, the local Petdex pet picker, notifications, and packaging are all implemented and validated on GNOME Wayland (via XWayland).

How it works

Agents call a tiny agentpet hook CLI from their hook configs. Each call sends one JSON event over a Unix socket (~/.agentpet/agentpet.sock) to a daemon — or, if the daemon is down, drops it in ~/.agentpet/queue/ to be replayed on startup. The daemon normalises every agent's events into a common state machine and drives the tray icon, the monitor window, desktop notifications, and the pet's mood.

agent hook → `agentpet hook …` → Unix socket → daemon (SessionStore)
                                                  ├── tray (ksni): paw + count
                                                  ├── monitor window: live timers
                                                  ├── desktop pets: one per active agent
                                                  └── notifications + sound

Any other CLI agent can be wrapped: agentpet run -- <command> reports working while it runs and done when it exits.

Display-server strategy

Like cliccy, the app forces GDK_BACKEND=x11 so its windows run under XWayland as normal keep-above windows that GNOME maps reliably (works on both Ubuntu X11 and Wayland sessions). The floating pet's always-on-top / skip-taskbar / sticky (all-workspaces) / click-through bits are set via raw X11 (x11rb) on the window XID, since GTK4 removed those WM hints. The tray uses StatusNotifierItem (ksni) and requires the GNOME AppIndicator extension.

Install

One command (Ubuntu 22.04+) — downloads the prebuilt binary from the latest release into ~/.local, no build and no Rust toolchain (sudo only if the GTK4 runtime is missing):

curl -fsSL https://raw.githubusercontent.com/tranhuuhuy297/agentpet-linux/main/install.sh | bash

Prefer to build from source? Clone and run ./install.sh — when run inside the cloned repo it auto-detects the checkout and builds from source (installing any missing build deps, compiling the release into ~/.local):

git clone https://github.com/tranhuuhuy297/agentpet-linux && cd agentpet-linux && ./install.sh

Force either mode with ./install.sh --source (always build) or ./install.sh --binary (always download the prebuilt release).

Launch AgentPet from your app menu, or run agentpet. On first launch it opens Settings — flip on the agents you use (writes their hook configs) and pick a pet on the Pet tab. Pets are installed with the official Petdex CLI; the Pet tab lists what you've installed and lets you assign one per agent (see Pets below).

  • Codex needs the hook trusted. Codex only runs hooks you've explicitly trusted, so enabling it in Settings isn't enough on its own. In a new Codex session run /hooks and trust agentpet hook --agent codex — until you do, Codex reports no state and its pet never appears.
  • Tray icon needs the GNOME AppIndicator and KStatusNotifierItem Support extension. Without it the app still runs; reopen the Monitor by clicking the AgentPet dock/app-grid icon again (or right-click the pet), and reach Settings/Quit from there.
  • Portable build: ./scripts/build-appimage.sh produces an AppImage that bundles GTK4/libadwaita for older distros.
  • Update: agentpet update pulls the latest GitHub release.

Uninstall

./uninstall.sh              # or: ./install.sh uninstall

The exact inverse of install: agentpet uninstall strips AgentPet's own hook entries from every agent config (foreign hooks untouched) and disables launch-at-login; then the installed files (binary, desktop entry, icons) and ~/.agentpet are removed. Pass --keep-data to preserve ~/.agentpet (the replay queue). Installed pets live in ~/.petdex/pets (managed by the Petdex CLI) and are left untouched.

Usage

  • Claude Code, Codex: toggle them on in Settings → General (installs the hook). Each agent gets its own pet that reflects its real state, including "waiting for input"; pick a per-agent pet on the Settings → Pet tab.
  • Any other CLI agent: agentpet run -- <command> (e.g. agentpet run -- aider).

Pets

AgentPet hosts no art of its own and downloads nothing — it shows the pet packs you install with the official Petdex CLI. Browse pets at petdex.dev, then install one (or several):

npx petdex@latest install snow-plum-lillia

The CLI writes each pack to ~/.petdex/pets/<slug>/ (a pet.json + spritesheet). Open Settings → Pet, hit Refresh, and your installed pets appear in the list — assign one to each agent with Use. If nothing is installed yet, the tab shows the install command and your pets fall back to a simple coloured blob.

Workspace layout

crates/
  agentpet-core/   # pure, GTK-free, unit-tested domain logic
  agentpet/        # platform binary: clap-free dispatch, tokio IPC daemon,
                   # GTK pet/monitor/settings, ksni tray, Petdex client
  pet-spike/       # Phase-0 click-through window feasibility spike

Run the core test suite (no display server needed):

cargo test -p agentpet-core -p agentpet

Credits

This project takes its idea from AgentPet by @ntd4996 — the original macOS app that defined the concept, agent hook integrations, and pet/monitor UX — and builds an Ubuntu version of it. All credit for the original idea and design goes to that project.

License

MIT. Application code only; pet assets are owned by their submitters (served via Petdex).

Ver o original no GitHub

Bom para

Relacionados