Install Perch with an AI coding agent

Do not write the integration by hand and do not add a skill file. Run the command. It is deterministic: no network, no model, plain file edits inside the project folder.

Prompt to give your agent

Add the Perch mascot to this site. Run `npx perch-pet detect` to see what it found, then `npx perch-pet` to install. If it lists several places, rerun with `--file <path>`. Open the dev server and check that the creature stands on the page elements and points at the main button.

Commands

npx perch-pet detect                 # JSON: every place it found, which is recommended, what is installed
npx perch-pet --dry                  # preview the exact change
npx perch-pet                        # install
npx perch-pet --file app/layout.tsx  # install into this file (repeat --file for several)
npx perch-pet --yes                  # several places and no one to ask: take the recommended one
npx perch-pet set stickiness=0.8     # change options, validated against schema.json
npx perch-pet options                # every option, type and limit as JSON Schema
npx perch-pet --remove               # undo

What detect returns

{
  "framework": "next-app",
  "layoutFile": "app/(site)/layout.tsx",
  "publicDir": "public",
  "installed": false,
  "options": {},
  "needsChoice": false,
  "candidates": [
    { "id": 1, "kind": "next-app", "label": "Next.js layout (route group)",
      "file": "app/(site)/layout.tsx", "publicDir": "public", "recommended": true, "installed": false }
  ]
}

Exit codes

0 done.
1 nothing found. The message says how to point at a file with --file.
2 several equal places and no terminal to ask in. The output lists a ready-to-run command for each. Pick one, or add --yes.

Check your work

Start the dev server. On localhost, a gear button appears at the bottom left. Open it, switch on “Show floors”: blue lines are floors, green boxes are call-to-action spots. If it points at the wrong thing, run npx perch-pet set goal=".selector" or ignore=".selector".

Machine-readable docs

/llms.txt: index for LLMs
/llms-full.txt: everything in one text file
/schema.json: JSON Schema for every option
/AGENTS.md: install and contribute notes

What is Perch? GitHub