Agent self-setup

This is the agent path

Doing it by hand instead? See the human Quickstart. Once set up, see Workflow modes for how the agent runs day to day.

Instead of clicking through the dashboard, hand your coding agent a setup token and one setup skill. The agent configures the project end-to-end over the REST API — widget design, channels, URL matching — then mints a narrow operational key, writes a patchrooms-feedback skill for ongoing work, and revokes the setup token. You end with a configured project and a repo that can pull & fix feedback.

How it works

• Setup token — a short-lived pr_sk_… key with the wildcard * scope, minted in the dashboard. It can do anything the API allows, for one project, until its TTL lapses. The agent revokes it the moment setup finishes.
• Operational key — a narrow feedback:read + feedback:write key the agent mints during setup and leaves in .env. This is what stays in your repo.

The setup token is powerful and temporary

Treat the * setup token like a one-time password: paste it into your agent’s environment, let it run, and it self-revokes. It is never embedded in the app — only the public pr_… project key goes into the widget.

1. Create the project + setup token

1. In the dashboard, create a project (or open an existing one).

2. Open Integrations → Create setup token. Copy the pr_sk_… value — it is shown once — and note the TTL (default 1 hour).

3. Export it where your agent runs:

   export PATCHROOMS_SETUP_TOKEN=pr_sk_...

2. Install the setup skill and run it

Drop this into .claude/skills/patchrooms-setup/SKILL.md (or your agent’s skills directory) and tell the agent: “Set up Patchrooms for this project.”

---
name: patchrooms-setup
description: One-time Patchrooms setup. Use when the user asks to set up / configure / install Patchrooms on this project. Provisions widget, channels and URL matching over the REST API using the setup token, mints a narrow operational key, leaves a patchrooms-feedback skill, then revokes the setup token.
---

# Patchrooms: provision this project

Run once. The setup token is in `$PATCHROOMS_SETUP_TOKEN` (scope `*`, short-lived).
Base URL: `https://room.patchrooms.com/api/v1`. Never print the token.

## 1. Resolve the project

```bash
curl -s -H "Authorization: Bearer $PATCHROOMS_SETUP_TOKEN" \
  https://room.patchrooms.com/api/v1/me
```

Returns `keyId`, `projectId`, `projectKey`, `scopes`. Keep `projectId` (PID),
`projectKey` and `keyId` for the steps below.

## 2. Configure widget + URL matching (scope project:write)

Ask the user for the mascot/look and which URLs to capture, then:

```bash
curl -s -X PATCH -H "Authorization: Bearer $PATCHROOMS_SETUP_TOKEN" \
  -H "Content-Type: application/json" \
  https://room.patchrooms.com/api/v1/projects/<PID> \
  -d '{"urlPatterns":["/app/*"],"defaultChannelKey":"bug","widgetConfig":{"mascot":"fox","anchor":"middle-right"}}'
```

`widgetConfig` is a full replacement — omitted fields fall back to defaults.

## 3. Create channels (scope channel:write)

The project ships with `bug` / `idea` / `question`. Add or rename as the
user wants:

```bash
curl -s -X POST -H "Authorization: Bearer $PATCHROOMS_SETUP_TOKEN" \
  -H "Content-Type: application/json" \
  https://room.patchrooms.com/api/v1/projects/<PID>/channels \
  -d '{"key":"polish","name":"Polish","color":"#bd93f9","mascot":"cat"}'
```

## 4. Embed the widget

Add the per-project loader just before `</body>` in the app's HTML entry point
(`index.html` for Vite/React, the root layout for SSR). Use `projectKey`, not the
secret:

```html
<script src="https://room.patchrooms.com/v1/patchrooms/<projectKey>.js"></script>
```

## 5. Mint the operational key (scope apikey:write)

```bash
curl -s -X POST -H "Authorization: Bearer $PATCHROOMS_SETUP_TOKEN" \
  -H "Content-Type: application/json" \
  https://room.patchrooms.com/api/v1/projects/<PID>/keys \
  -d '{"name":"feedback agent","scopes":["feedback:read","feedback:write"]}'
```

The response `key` is the plaintext operational secret — shown once. Write it to
`.env` as `PATCHROOMS_API_KEY=...` (never commit it).

## 6. Leave the operational skill

Write `.claude/skills/patchrooms-feedback/SKILL.md` (the operational skill from the
Patchrooms docs) so future sessions can pull & triage feedback with the narrow key.

## 7. Revoke the setup token

```bash
curl -s -X DELETE -H "Authorization: Bearer $PATCHROOMS_SETUP_TOKEN" \
  https://room.patchrooms.com/api/v1/projects/<PID>/keys/<keyId>
```

`<keyId>` is from step 1. After this the setup token is dead; only the narrow
`feedback:*` key remains.

## 8. Summarise

Print what was configured (channels, URL patterns, widget), confirm the widget tag
is embedded, and that the operational skill + `.env` key are in place.

Prefer a script over raw curl?

The same calls are wrapped in scripts/pr-setup.py in the Patchrooms repo (whoami / configure / create-channel / mint-key / revoke-self). Copy it in if your agent would rather call one helper than build curl commands.

Reviewing AI-generated builds per branch?

If the widget rides on preview deploys or a per-branch dev menu, load it in artifact-review mode with a stable artifact.id (branch name, preview id) so each build’s feedback isolates into its own Room instead of piling into one stream.

3. The operational skill it leaves behind

This is what stays in the repo after setup — narrow key, ongoing pull & fix:

---
name: patchrooms-feedback
description: Pull Patchrooms feedback filed on this app and fix it. Use when the user says "pull feedback" / "check patchrooms", or when driven on a loop. Reads new reports over the API and updates their status.
---

# Patchrooms feedback → fix

Operational key is in `.env` as `PATCHROOMS_API_KEY` (`feedback:read`+`feedback:write`).
Read it at runtime; never print it. MCP endpoint: `https://room.patchrooms.com/mcp`.

## Pull

```bash
curl -s -X POST https://room.patchrooms.com/mcp \
  -H "Authorization: Bearer $PATCHROOMS_API_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_reports","arguments":{"status":"new"}}}'
```

## Procedure

1. List `new` reports. If none, stop.
2. For each: `get_report` → read the text, the page URL (which screen), and any
   screenshot/selection block (the DOM anchor locates the element).
3. Map the URL to code, confirm the issue, fix following repo conventions, run the
   project's type-check/lint.
4. `set_status` → `in-progress` while working, `closed` when done (or after the user
   confirms the diff — pick a mode at the start).

See the [MCP reference](/reference/mcp/) for the full tool list and a no-MCP `curl`
fallback.

Verify

1. After the agent runs, open the app — the launcher should appear.

2. File a test comment; it lands in the dashboard for that project.

3. Confirm the setup token no longer appears under Integrations → API keys (it self-revoked) and a narrow feedback agent key remains.