Codex Pets is a community gallery, command-line tool (CLI), and MCP service for Codex-compatible animated pet packages (pets). The project is based on YDB storing assets, and provides a public site, a local account system, manual review, public generation requests, and public detail pages for approved and pending pets. The public site address is https://pets.ydb-qdrant.tech/ .
Main uses Provide searchable, installable animated pet packages for AI coding agents (such as Codex). Provide a public MCP service so that coding agents can search, inspect, install, and share approved pet packages. Provide the CLI install command: npx @astandrik/codex-pets install <slug> . Allow users to request the generation of new pets through a website form or remote MCP. Generate and manage public metadata, badges, embed cards, and more for pet packages.
Main capabilities Public gallery: a crawlable HTML gallery is located at the root path / , with pagination using /?page=2 , /?page=3 , etc. Legacy /pets directory URLs permanently redirect to the corresponding homepage URLs, and pet details remain at /pets/<slug> . Public MCP tools: search_pets: discover approved pets; use when candidates are needed or the exact slug is missing. get_pet: retrieve a single public pet card; use when an approved slug is already available. get_install_instructions: retrieve the install command without incrementing metrics. get_badge_code: generate a README badge snippet for a known slug. get_embed_code: generate an iframe embed snippet for a known slug. get_card_code: generate an animated GIF snippet for a known slug, defaulting to sprite-sheet-only mode. get_pet_request_info: learn about the public new pet request workflow, but does not submit or check private requests. HTTP fallback routes: including /api/openapi.json , /guides/best-codex-pets-for-ai-coding-agents , /guides/best-codex-pets-for-ai-coding-agents.md , /api/manifest.toon , /api/pets/<slug> , /api/pets/<slug>.toon , /pets/<slug>/markdown , /api/pets/<slug>/share , /badge/<slug>.svg , /card/<slug>.gif , etc. API pagination: /api/pets and /api/pets.toon accept optional page and pageSize parameters. Providing either parameter enables an additional pagination metadata object; not providing them preserves the old response shape. In a paginated response, the top-level total is the number of pets returned, and pagination.totalItems is the full filtered count. Generation requests: the website form /generate and remote MCP share one queue. Generation is disabled by default and can be used via the website form and remote MCP. The npm CLI and browser WebMCP retain only catalog tools. Generation limits: 200 accepted tasks globally per day, 10 per IP by default, one active task and five waiting tasks, calculated by the Moscow calendar day. Waiting expires after 30 minutes, and failed tasks consume quota. Generation flow: generate_pet accepts a text prompt (1–2000 characters), an optional displayName (up to 80 characters), and a new random UUID requestId. Poll get_pet_generation(generationId) every 5 seconds. Completed tasks return unlisted previews and downloads: pet.json, lossless spritesheet.webp, and pet.zip. Format v2 is 1536×2288, with 9 animation states and 16 orientations. Results expire 24 hours after acceptance; idempotency hashes are retained for 7 days. Metadata editing: completed new tasks include editable name/description/tags. Private previews save description changes atomically to pet.json and the ZIP; tags are stored for gallery submission. Saving does not call the provider, keeps spritesheet bytes unchanged, requires the current metadata revision, and is disabled after submission. Submit for review: before expiration, use "Submit for review" on the private result page to save a permanent gallery package and a pending submission, or upload a ZIP via /submit. Submission retries return the same receipt. Tech stack: Next.js 16 App Router, React 19, TypeScript strict, Gravity UI + SCSS/BEM, local-ydb / YDB native gRPC via ydb-sdk, app-owned email+password authentication with YDB-based users and sessions, pet assets as binarylarge objects stored in YDB, dynamic robots.txt, sitemap.xml, llms.txt, llms-full.txt, and OpenAPI JSON, agent-facing HTTP access via llms.txt / llm.txt, /llms-full.txt, /mcp, JSON routes, and TOON mirrors, optional read-only browser WebMCP tools, Yandex Metrika, JSZip + Sharp for package validation.
Usage Install the CLI: npx @astandrik/codex-pets install <slug>. Run the stdio MCP server locally to proxy the public gallery. Public MCP endpoint: https://pets.ydb-qdrant.tech/mcp . Public manifest: https://pets.ydb-qdrant.tech/api/manifest . LLM discovery: https://pets.ydb-qdrant.tech/llms.txt . Best guide: https://pets.ydb-qdrant.tech/guides/best-codex-pets-for-ai-coding-agents . Local development: open http://localhost:3000 . The local YDB monitoring UI is http://127.0.0.1:8765 . Deployment: The public gallery renders without secrets. Account login, submissions, moderation, and metrics require YDB_PETS_ENDPOINT, YDB_PETS_DATABASE, and authentication environment variables. Optional server-side MCP metrics require YANDEX_METRIKA_MP_TOKEN and YANDEX_METRIKA_MP_CLIENT_ID. Optional IndexNow notifications are enabled via INDEXNOW_KEY. Semantic search: Optional semantic search uses Yandex AI Studio text embeddings and exact cosine ranking in YDB. The query mode defaults to PET_SEARCH_MODE=lexical; shadow computes semantic ranking without changing the public order; hybrid combines lexical and text semantic ranking. A separate PET_SEARCH_VISUAL_MODE=off|shadow|hybrid adds offline visual caption ranking from four fixed sprite sheet frames. Configure YANDEX_AI_STUDIO_FOLDER_ID, YANDEX_AI_STUDIO_API_KEY_FILE, and PET_SEARCH_MODEL_REVISION=yandex-text-embeddings-v2-768-2026-07. The v2 runtime uses the 768-dimensional hosted text-embeddings-v2-doc/query models. Set PET_SEARCH_VISUAL_MODEL_REVISION=yandex-text-embeddings-v2-768-pet-vision-qwen3.6-v1 to use the compatible Qwen visual ranking. Legacy 256-dimension revisions are retained for rollback. API keys are only accepted via secret file setup. Provider failures and timeouts fall back to lexical results; visual-only failures preserve the text hybrid order.
Applicable scenarios When an AI coding agent needs to discover, install, or share Codex-compatible animated pet packs. When a developer wants to add animated pet badges, embed cards, or GIFs to a project. When a user wants to generate a new animated pet from a text prompt and submit it to the community gallery. When a public, crawlable, LLM-oriented pet registry is needed.
Limitations Generation is disabled by default and must be explicitly enabled via the website form or remote MCP. Generation results expire after 24 hours, history is retained for 7 days after expiration; expired entries cannot be opened. Clearing browser data removes the history list but does not reset quotas or cancel tasks. There is no IP-based ownership lookup, account sync, server-side history enumeration, or new database schema. History, form, and result pages are excluded from analytics and search indexing; history has private/no-store and no-referrer headers. Private links and IDs must be kept confidential; anyone holding a private link can open the corresponding result or submit once. The website form and remote MCP share a queue and are subject to global and per-IP limits. Submitting a saved pack does not call the generation provider and does not change the generation quota. Text and visual backfill require an explicit --dry-run or --apply; visual --force is only valid together with --apply. When PET_RELATED_PREAPPROVAL_ENABLED is not exactly true, approval fails closed instead of publishing pets missing the current V24 input.
