# perch-pet

> A pixel creature for websites. One script tag adds an animated mascot that stands on the page's real elements (headings, text, cards, buttons, forms), rides them while scrolling and points at the call to action. Deterministic setup with `npx perch-pet`, no LLM and no network calls at runtime. On localhost a gear button opens a tuner to swap creatures, draw your own, and see which elements count as floors.

To add it to a site, run `npx perch-pet` in the project folder. Do not write the integration by hand and do not create a skill file. Check what it found first with `npx perch-pet detect` (JSON). Change options with `npx perch-pet set key=value`. Undo with `npx perch-pet --remove`.

## Docs

- [Website](https://gettheperch.com): what it is, guides for Next.js, Astro and plain HTML, agent guide
- [README](https://github.com/mishanefedov/perch#readme): install, options, tuner, frameworks, limits
- [Full docs as one text file](https://raw.githubusercontent.com/mishanefedov/perch/main/llms-full.txt): everything an agent needs, no images
- [Options schema](https://raw.githubusercontent.com/mishanefedov/perch/main/schema.json): JSON Schema with every option, type, limit and default
- [AGENTS.md](https://raw.githubusercontent.com/mishanefedov/perch/main/AGENTS.md): how to install it for a user and how to work on this repo

## Commands

- `npx perch-pet detect`: JSON with every place it found (candidates), the recommended one, needsChoice, installed or not, current options
- `npx perch-pet --dry`: preview the change
- `npx perch-pet --file <path>`: install into this exact layout or page (repeat for several); `--yes` takes the recommended place; exit code 2 means several equal places and a choice is needed
- `npx perch-pet`: install (copies perch.js and the localhost tuner, adds one script tag)
- `npx perch-pet set stickiness=0.8 creature=cat`: change options, validated against the schema
- `npx perch-pet creature ./creature.json`: use a creature drawn in the tuner
- `npx perch-pet options`: print the options schema
- `npx perch-pet --remove`: undo

## Optional

- [Source](https://github.com/mishanefedov/perch/tree/main/src): engine, scanner, creatures, tuner
- [Changelog](https://raw.githubusercontent.com/mishanefedov/perch/main/CHANGELOG.md)

## Website

- [Home](https://gettheperch.com/): what it is, install, FAQ
- [Browser extension](https://gettheperch.com/extension/): a creature on any website you visit
- [For agents](https://gettheperch.com/agents/): commands, JSON output, flags, exit codes
- [Next.js guide](https://gettheperch.com/nextjs/)
- [Astro guide](https://gettheperch.com/astro/)
- [HTML, WordPress, Webflow, Shopify](https://gettheperch.com/html/)