How to use Codex pets without guessing at the broken part.

Enable a Codex pet, then wake the overlay.

The shortest path is to type /pet in the Codex composer. The command wakes or tucks away the floating pet overlay. Choosing a pet and showing the overlay are separate actions: Settings decides which companion is active, while /pet controls whether that companion is currently visible.

To change the selected companion, open Codex Settings, choose Appearance, find Pets and select a built-in or custom entry. If /pet is missing from the command menu, confirm that the desktop app is current before changing local files. A missing feature gate or app-level overlay problem cannot be repaired by rebuilding a spritesheet.

• Wake or hide the current companion with /pet.
• Choose the companion under Settings → Appearance → Pets.
• Use Refresh custom pets after adding a new local package.
• Test one built-in pet before blaming a custom atlas.

Keep a custom pet package boring and predictable.

A local pet package should contain a small manifest and a sprite atlas in one dedicated folder. pet.json identifies the pet and points to spritesheet.webp. Keep the folder name, manifest id and sprite path aligned. Do not hide JavaScript, shell commands, remote loaders or model settings inside a decorative pet package.

The documented v1 atlas is 1536 × 1872 pixels: eight columns, nine rows and 192 × 208 pixel cells. Some community tools also use a taller v2 atlas. Treat that as a versioned community contract, not permission to mix dimensions. When the installed Hatch Pet workflow reports a newer contract, verify its output instead of silently stretching an older sheet.

• Use a transparent PNG or WebP atlas that matches its declared version.
• Keep effects attached to the character so frames do not appear clipped.
• Review idle, running, waiting, failed and ready states at actual overlay size.
• Run local validation before copying the package into the Codex pets folder.

~/.codex/pets/my-companion/
├── pet.json
└── spritesheet.webp

If a Codex pet is not showing, split discovery from rendering.

Start with one question: does the custom pet appear in Settings? If it does not, the app has not discovered the package. Check the active Codex home folder, the manifest filename, the manifest id, spritesheetPath and the actual image filename. Refresh custom pets and restart the desktop app only after those values agree.

If the pet appears in Settings but /pet shows nothing, test a built-in companion. A built-in pet failing in the same way points toward the overlay window, display scaling or an app feature gate. Rebuilding custom artwork will only waste time because the renderer is failing before your package becomes the differentiating variable.

• Missing from Settings: inspect folder location and manifest references.
• Visible in Settings, absent on screen: test /pet and a built-in companion.
• Only one custom pet fails: inspect its dimensions, transparency and frame bounds.
• Every pet fails: update Codex and treat it as an app or display issue.

A cropped pet can be a clean atlas inside a clipped window.

Several desktop reports describe built-in and custom pets being clipped together, especially near screen edges, on scaled displays or with more than one monitor. That evidence matters: when both classes fail, the atlas is not the common cause. Move the overlay away from an edge, test the main display and update the app before changing artwork.

When only one custom pet is cropped, inspect every frame for content touching the 192 × 208 cell boundary. A little transparent breathing room is safer than shrinking the whole atlas or patching the signed application bundle. Never edit app.asar just to resize a pet; it couples a visual workaround to signatures and future updates.

• Compare the same state on checker, light and dark backgrounds.
• Test smooth artwork for forced pixel-resampling artifacts.
• Keep important facial detail readable at the rendered overlay size.
• Preserve the atlas dimensions while adjusting transparent margins inside cells.

On Windows and WSL, trust the Codex home the app is actually using.

Windows native mode and a WSL-backed Codex session can resolve different home directories. Two valid-looking copies of the same pet may therefore exist while the running app reads only one. Use the Pets settings folder action when available, place the package under that active home, refresh and verify before duplicating files elsewhere.

Do not solve a path disagreement by scattering copies through Windows and Linux homes. That makes later updates impossible to reason about. Record one active package location and one package id, then switch execution modes only after the native path works. Current community reports show this is a loader-path problem, not a reason to change the sprite contract.

• Confirm whether Codex is running in Windows native or WSL mode.
• Open the pets folder from the running app when that control is available.
• Keep pet.json and spritesheet.webp together under one pet id.
• Retest after changing execution mode because the active home may change.

Personal is memorable; rights-clear is publishable.

Your own dog, cat or original mascot creates the strongest story because the viewer understands the relationship immediately. A recognizable partner can work only with explicit creation and sharing consent. Celebrity photos, game characters, sports logos and nostalgic product chrome remain protected even when the resulting pet is technically easy to generate.

A safe public package contains visual data and a manifest, not executable behavior. Keep the original reference private unless its owner approved publication. Show the finished states, explain that the pet is an unofficial status layer and link to a reviewable install path. Curiosity earns the click; transparent boundaries earn the install.

• Separate private creation consent from public redistribution consent.
• Use original mascots for paid packs and long-term character building.
• Do not bundle third-party logos merely to trigger nostalgia.
• State clearly that the pet does not change Codex behavior or capability.

Measure the handoff, not just the viral view count.

A high-view post can still be commercially empty. The useful funnel is concept selected, Codex brief opened, atlas validated, install link created and checkout started. Each step answers a different question: did the hook attract the right person, could they make the asset, did the technical contract work and was the paid shortcut worth buying?

Run one hook per post and preserve the landing URL in the caption. Compare dog, cat, Y2K messenger and original-character hooks on the same distribution channel before changing price or rebuilding the product. If views rise while brief opens stay flat, the creative is entertaining but misaligned. If briefs open and atlases fail, improve the workflow before buying more reach.

• Leading signal: pet-maker visits that select a concept.
• Activation signal: visitors that open the prepared Codex brief.
• Quality signal: local atlases that pass validation.
• Revenue signal: checkout starts and paid Stripe events by product.