{"id":50706020,"url":"https://github.com/tranhuuhuy297/agentpet-linux","last_synced_at":"2026-06-09T12:01:09.039Z","repository":{"id":363280586,"uuid":"1260119850","full_name":"tranhuuhuy297/agentpet-linux","owner":"tranhuuhuy297","description":"An ambient desktop pet + tray monitor that shows your AI coding agents (Claude Code, Codex) at a glance — working, done, or waiting for you. Rust + GTK4, Linux.","archived":false,"fork":false,"pushed_at":"2026-06-08T08:18:08.000Z","size":2358,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T09:09:50.471Z","etag":null,"topics":["ai-agents","claude-code","codex","coding-agent","desktop-pet","developer-tools","gnome","gtk4","linux","productivity","rust","system-tray"],"latest_commit_sha":null,"homepage":"https://tranhuuhuy297.github.io/agentpet-linux/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tranhuuhuy297.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-05T07:11:58.000Z","updated_at":"2026-06-08T08:18:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tranhuuhuy297/agentpet-linux","commit_stats":null,"previous_names":["tranhuuhuy297/agentpet-linux"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tranhuuhuy297/agentpet-linux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tranhuuhuy297%2Fagentpet-linux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tranhuuhuy297%2Fagentpet-linux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tranhuuhuy297%2Fagentpet-linux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tranhuuhuy297%2Fagentpet-linux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tranhuuhuy297","download_url":"https://codeload.github.com/tranhuuhuy297/agentpet-linux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tranhuuhuy297%2Fagentpet-linux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34105565,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","codex","coding-agent","desktop-pet","developer-tools","gnome","gtk4","linux","productivity","rust","system-tray"],"created_at":"2026-06-09T12:00:29.230Z","updated_at":"2026-06-09T12:01:09.021Z","avatar_url":"https://github.com/tranhuuhuy297.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AgentPet for Linux\n\nA native **Rust + GTK4** app for **Ubuntu 22.04+**, inspired by\n[AgentPet](https://github.com/ntd4996/agentpet) (macOS). Watch your AI coding agents (Claude Code and\nCodex) running in parallel and see — at a glance — which one is **working**,\nwhich is **done**, and which is **waiting for your input**, via a tray monitor\nand a desktop pet per agent (run Claude Code and Codex together and you get two\npets, each reflecting its own state).\n\n\u003e Status: **working.** Core logic, CLI/daemon, the GTK pet + monitor + settings,\n\u003e the local Petdex pet picker, notifications, and packaging are all implemented and\n\u003e validated on GNOME Wayland (via XWayland).\n\n## How it works\n\nAgents call a tiny `agentpet hook` CLI from their hook configs. Each call sends\none JSON event over a Unix socket (`~/.agentpet/agentpet.sock`) to a daemon —\nor, if the daemon is down, drops it in `~/.agentpet/queue/` to be replayed on\nstartup. The daemon normalises every agent's events into a common state machine\nand drives the tray icon, the monitor window, desktop notifications, and the\npet's mood.\n\n```\nagent hook → `agentpet hook …` → Unix socket → daemon (SessionStore)\n                                                  ├── tray (ksni): paw + count\n                                                  ├── monitor window: live timers\n                                                  ├── desktop pets: one per active agent\n                                                  └── notifications + sound\n```\n\nAny other CLI agent can be wrapped: `agentpet run -- \u003ccommand\u003e` reports\nworking while it runs and done when it exits.\n\n## Display-server strategy\n\nLike [`cliccy`](https://github.com/tranhuuhuy297/cliccy), the app forces\n`GDK_BACKEND=x11` so its windows run under **XWayland** as normal keep-above\nwindows that GNOME maps reliably (works on both Ubuntu X11 and Wayland\nsessions). The floating pet's always-on-top / skip-taskbar / sticky\n(all-workspaces) / click-through bits are set via raw X11 (`x11rb`) on the\nwindow XID, since GTK4 removed those WM hints. The tray uses\n**StatusNotifierItem** (`ksni`) and requires the GNOME **AppIndicator**\nextension.\n\n## Install\n\nOne command (Ubuntu 22.04+) — downloads the prebuilt binary from the latest\nrelease into `~/.local`, no build and no Rust toolchain (`sudo` only if the\nGTK4 runtime is missing):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/tranhuuhuy297/agentpet-linux/main/install.sh | bash\n```\n\nPrefer to build from source? Clone and run `./install.sh` — when run inside the\ncloned repo it **auto-detects the checkout and builds from source** (installing\nany missing build deps, compiling the release into `~/.local`):\n\n```bash\ngit clone https://github.com/tranhuuhuy297/agentpet-linux \u0026\u0026 cd agentpet-linux \u0026\u0026 ./install.sh\n```\n\nForce either mode with `./install.sh --source` (always build) or\n`./install.sh --binary` (always download the prebuilt release).\n\nLaunch **AgentPet** from your app menu, or run `agentpet`. On first launch it\nopens Settings — flip on the agents you use (writes their hook configs) and pick\na pet on the **Pet** tab. Pets are installed with the official\n[Petdex](https://petdex.dev) CLI; the Pet tab lists what you've installed and\nlets you assign one per agent (see [Pets](#pets) below).\n\n- **Codex needs the hook trusted.** Codex only runs hooks you've explicitly\n  trusted, so enabling it in Settings isn't enough on its own. In a **new**\n  Codex session run `/hooks` and trust `agentpet hook --agent codex` — until you\n  do, Codex reports no state and its pet never appears.\n- **Tray icon** needs the GNOME *AppIndicator and KStatusNotifierItem Support*\n  extension. Without it the app still runs; reopen the Monitor by clicking the\n  AgentPet dock/app-grid icon again (or right-click the pet), and reach\n  Settings/Quit from there.\n- **Portable build:** `./scripts/build-appimage.sh` produces an AppImage that\n  bundles GTK4/libadwaita for older distros.\n- **Update:** `agentpet update` pulls the latest GitHub release.\n\n### Uninstall\n\n```bash\n./uninstall.sh              # or: ./install.sh uninstall\n```\n\nThe exact inverse of install: `agentpet uninstall` strips AgentPet's own hook\nentries from every agent config (foreign hooks untouched) and disables\nlaunch-at-login; then the installed files (binary, desktop entry, icons) and\n`~/.agentpet` are removed.\nPass `--keep-data` to preserve `~/.agentpet` (the replay queue). Installed pets\nlive in `~/.petdex/pets` (managed by the Petdex CLI) and are left untouched.\n\n## Usage\n\n- **Claude Code, Codex:** toggle them on in Settings → General (installs the\n  hook). Each agent gets its own pet that reflects its real state, including\n  \"waiting for input\"; pick a per-agent pet on the Settings → Pet tab.\n- **Any other CLI agent:** `agentpet run -- \u003ccommand\u003e` (e.g. `agentpet run -- aider`).\n\n## Pets\n\nAgentPet hosts no art of its own and downloads nothing — it shows the pet packs\nyou install with the official [Petdex](https://petdex.dev) CLI. Browse pets at\n[petdex.dev](https://petdex.dev), then install one (or several):\n\n```bash\nnpx petdex@latest install snow-plum-lillia\n```\n\nThe CLI writes each pack to `~/.petdex/pets/\u003cslug\u003e/` (a `pet.json` + spritesheet).\nOpen Settings → **Pet**, hit **Refresh**, and your installed pets appear in the\nlist — assign one to each agent with **Use**. If nothing is installed yet, the\ntab shows the install command and your pets fall back to a simple coloured blob.\n\n## Workspace layout\n\n```\ncrates/\n  agentpet-core/   # pure, GTK-free, unit-tested domain logic\n  agentpet/        # platform binary: clap-free dispatch, tokio IPC daemon,\n                   # GTK pet/monitor/settings, ksni tray, Petdex client\n  pet-spike/       # Phase-0 click-through window feasibility spike\n```\n\nRun the core test suite (no display server needed):\n\n```bash\ncargo test -p agentpet-core -p agentpet\n```\n\n## Credits\n\nThis project takes its idea from [AgentPet](https://github.com/ntd4996/agentpet)\nby [@ntd4996](https://github.com/ntd4996) — the original macOS app that defined\nthe concept, agent hook integrations, and pet/monitor UX — and builds an Ubuntu\nversion of it. All credit for the original idea and design goes to that project.\n\n## License\n\nMIT. Application code only; pet assets are owned by their submitters (served via\n[Petdex](https://github.com/crafter-station/petdex)).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftranhuuhuy297%2Fagentpet-linux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftranhuuhuy297%2Fagentpet-linux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftranhuuhuy297%2Fagentpet-linux/lists"}