AgentPets CLI · v0.1

Docs

The AgentPets CLI lets you install, browse, and submit Codex pets from your terminal. Authentication uses OAuth 2.0 + PKCE through Clerk, and tokens persist in your OS keychain.

npmjs.com/agentpetsRepo

Quick start

Install a curated pet into your Codex setup with one command. No account required to install. Sign in only when you submit.

The CLI fetches the pet pack and drops it into ~/.codex/pets/boba/. To activate it inside Codex go to Settings → Appearance → Pets and click Select. Use /pet inside Codex to wake or tuck it away.

Don't have a pet idea yet? Hatch your own with the Codex Hatch Pet skill, then come back to agentpets submit.

Install

The CLI runs on Node 20+ (or Bun). Pick the workflow that fits you. Both are equivalent in capability and persistence.

Casual / one-off

Use npx. No setup, package is cached after first run.

Power user

Install globally for instant invocation and easier muscle memory.

Auth persistence is identical in both. Tokens live in your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) under the service name agentpets-cli. Even if npx clears its package cache, your session survives.

Authenticate

Sign in once, then any command that needs auth, such as submit, works seamlessly.

The flow is OAuth 2.0 + PKCE: the CLI opens your browser, you sign in with Clerk on accounts.agentpets.dev, and the browser redirects to a one-shot localhost listener with the authorization code. The CLI exchanges it for a token set and stores it in the keychain. No secrets touch disk.

Other auth commands:

Commands

The CLI covers the full lifecycle: discover, install, hatch, publish, plus the desktop app and agent hooks. All commands accept --help.

agentpets list

Print every approved pet with credit. Useful for discovery before installing.

agentpets install <slug>

Drop a pet into ~/.codex/pets/<slug>/. Equivalent to curl -sSf https://agentpets.dev/install/<slug> | sh.

agentpets submit <path>

Publish your pet(s) to the gallery. The CLI accepts three shapes:

  • Single folder: agentpets submit ~/.codex/pets/boba
  • Single zip: agentpets submit ~/Downloads/boba.zip
  • Bulk: agentpets submit ~/.codex/pets: every direct subfolder is treated as its own pet

Bulk mode shows a progress spinner per pet and a final summary of failures. Slugs auto-deduplicate so you will not hit a slug-taken bounce.

agentpets login / logout / whoami

See the Authenticate section above.

Desktop app

AgentPets Desktop is a floating mascot that lives on top of your workspace and reacts to your coding agent tool calls. macOS today, Linux and Windows soon. See /download for the visual tour.

agentpets install desktop

Fetches the latest binary from GitHub Releases for your platform and drops it at ~/.agentpets/bin/agentpets-desktop. The CLI strips the macOS quarantine attribute so the app opens without a Gatekeeper prompt.

agentpets hooks install

Wires the desktop app into your coding agents so the pet animates as you work. Picks the agents present on your machine and writes hooks for each:

  • Claude Code: ~/.claude/settings.json
  • Codex CLI: ~/.codex/hooks.json
  • Gemini CLI: ~/.gemini/settings.json
  • OpenCode: ~/.config/opencode/plugins/agentpets.js

Tool events map to pet states: tool.before → running, tool.after → idle, session.end → waving, session.error → failed. Each hook POSTs to the local sidecar at http://127.0.0.1:7777/state.

agentpets desktop <start | stop | status>

Manage the running pet. start spawns it detached (PID at ~/.agentpets/desktop.pid, log at ~/.agentpets/desktop.log). stop sends SIGTERM. status reports running, stopped, or stale.

agentpets up / down / toggle

One-shot wake/sleep for the mascot. up enables hooks AND launches the desktop. down disables hooks AND stops the desktop. toggle flips between them based on current state. That is what the /agentpets slash command runs from inside your agent.

/agentpets (slash command)

Once agentpets hooks install has run, every supported agent (Claude Code, Codex, Gemini, OpenCode) gets a /agentpets command in its picker. Type it inside the agent and the mascot wakes or sleeps without leaving the chat:

  • /agentpets: toggle (wake if asleep, sleep if awake)
  • /agentpets up: force-wake
  • /agentpets down: force-sleep
  • /agentpets status: show whether hooks are enabled
  • /agentpets doctor: diagnose install + agent wiring

agentpets hooks (kill-switch)

Even with hooks installed, you can pause them without touching your agent settings. agentpets hooks off drops a flag file at ~/.agentpets/runtime/hooks-disabled; every installed hook checks for it first and exits 0 immediately. agentpets hooks on removes the file. Useful when a sidecar has gone weird and you do not want stray curls in your agent log.

agentpets hooks uninstall

Reverses hooks install: removes the agentpets entries from each agent config (preserving your own hooks), deletes the /agentpets slash command files, and removes the OpenCode plugin. Pass --remove-token to also drop the auth token at ~/.agentpets/runtime/update-token.

agentpets doctor

Diagnostic. Verifies binary, sidecar bundle, sidecar reachability, pid file format, token mode, kill-switch state, hooks installed in each agent, Codex codex_hooks feature flag, and usable pet count. Each failed check ships an actionable hint.

agentpets update

Compares your installed version against the latest GitHub Release tag and downloads it if newer. If the desktop app was running, it stops it, swaps the binary, and restarts. Pass --force to re-download the same version.

The sidecar is a local HTTP server on port 7777. Anything that can curl + read the per-session token at ~/.agentpets/runtime/update-token can drive the pet. The token rotates every sidecar boot and lives at mode 0600, so only your user can read it. Browsers and remote sites cannot:
T="$(cat "$HOME/.agentpets/runtime/update-token")"
curl -X POST http://127.0.0.1:7777/state \
  -H "Content-Type: application/json" \
  -H "X-AgentPets-Update-Token: $T" \
  --data-raw '{"state":"waving"}'

Distribute your pets

Once you have hatched a pet inside Codex, sharing it takes one command. Here's the full lifecycle:

  1. Create. In Codex Desktop, install the Hatch Pet skill and run /pet. Codex generates the spritesheet and pet.json into ~/.codex/pets/<slug>/. Full tutorial at /create.
  2. Sign in. npx -y https://github.com/agiagentsdev/agentpets-dev/releases/latest/download/agentpets-cli.tgz login if you have not.
  3. Submit. npx -y https://github.com/agiagentsdev/agentpets-dev/releases/latest/download/agentpets-cli.tgz submit ~/.codex/pets/<slug>. Or bulk all at once with the parent dir.
  4. Wait for review. Submissions land as “pending” in the admin queue. You will receive a Resend email when approved or rejected (if rejected, the reason is included).
  5. Anyone can install your pet. Once approved, share npx -y https://github.com/agiagentsdev/agentpets-dev/releases/latest/download/agentpets-cli.tgz install <your-slug> with anyone. They get your pet in their ~/.codex/pets/ instantly.
Pets are user-submitted fan art. AgentPets does not claim rights to underlying IP. If you are a rights holder requesting a takedown, see /legal/takedown.

Validation rules

The server enforces these rules; the CLI checks locally too.

  • pet.json and spritesheet.webp (or .png) must be at the root of the folder/zip.
  • Spritesheet ≥ 256×256. Recommended 1536×1872 (8×9 frame grid).
  • Rate limit: 10 submissions / 24h per user. Admins bypass.
  • Slugs auto-deduplicate (boba → boba-2 → boba-3 → …). You always get a successful submission.
  • Identity (userId, email, credit) comes from the verified OAuth token. Never trusted from request body.

Failure modes

SymptomCauseFix
Not signed inNo tokens or session expiredagentpets login
presign 401Bearer rejected by Clerk userinfoagentpets logout then agentpets login
presign 42910/24h rate limit hitWait 24h or open a submit-fallback issue
register 400 invalid_spritesheetSprite < 256×256Regenerate at 1536×1872
register 400 missing_fieldFolder missing pet.json or spritesheetInspect folder contents
R2 PUT 403Presigned URL expired (60s TTL)Retry: CLI auto-presigns fresh URLs

Agent-first usage (Skill)

AgentPets ships a Claude Code / Codex / Cursor compatible skill at .claude/skills/agentpets/SKILL.md. Compatible agents load it automatically and learn when and how to call the CLI on your behalf.

What this enables

  • Say “install something cozy for my Codex” in any agent tool. It runs agentpets list, suggests Boba/Boxcat, installs your pick, and reminds you to activate via Settings → Appearance → Pets.
  • Say “share all my pets”. Agent runs agentpets login if needed, then agentpets submit ~/.codex/pets, surfaces the bulk summary.
  • Say “how do I make my own?”. Agent walks you through Codex Desktop → Hatch Pet skill → /pet → agentpets submit.

How to enable it

If you use Claude Code, save the skill globally so every project has it:

Other agent tools can load the same SKILL.md from the repo. The file is plain markdown. No agent-specific syntax beyond allowed-tools.

Build your own skill on top

The CLI is the executable surface; the skill is the cognitive one. If you build a derivative skill (for example, one that auto-tags new pets or curates a daily digest), you can use the AgentPets skill as a reference. Read it directly:

.claude/skills/agentpets/SKILL.md

Configuration

The CLI ships with sensible defaults pointing at production. You only need to override env vars if you are testing against a non-production deployment.

  • PETDEX_URL: base URL, default https://agentpets.dev
  • CLERK_ISSUER: optional OAuth issuer override. Login is temporarily disabled in production while AgentPets auth is being reconfigured.
  • CLERK_OAUTH_CLIENT_ID: public client id (baked into the CLI binary)

Contribute