Skip to content
gutternote

Quickstart

You need a project, a list of sites that can use it, and one script tag.

1. Create a project

  1. Sign in at app.gutternote.com.
  2. Open the project menu at the top of the sidebar and choose New project.
  3. Name it and select Create project.

2. Copy the snippet

Open the project’s Install page and choose Add the code yourself. Select Copy snippet. The snippet already holds your project key, which looks like pk_live_…. The key is safe to put in your page source.

3. Add your sites

Open Configure and find Sites that can use the widget. Add each address where the widget should run, then select Save websites:

https://*-acme.vercel.app
https://*.staging.acme.com
http://localhost:3000

A * covers the changing part of a preview address. The widget doesn’t load on a site that isn’t on the list. See Sites and access.

4. Add the widget

Paste the snippet before </body>, on the pages you want feedback on:

<script
  src="https://cdn.gutternote.com/v1/widget.js"
  data-gutternote-key="pk_live_..."
  defer
></script>

Load it only in the environments you want, such as local, preview and staging.

If your site sends a Content Security Policy, see Content Security Policy.

5. Tag preview builds

On preview and staging builds, add the branch, commit and pull request the build came from:

<meta name="gutternote:branch" content="fix-nav" />
<meta name="gutternote:commit" content="9f2c1ab000000000000000000000000000000000000" />
<meta name="gutternote:pr" content="128" />

The tags are metadata. Publishing new preview feedback also needs the GitHub App to verify the repository, PR and full head commit. Notes still save when verification is unavailable. See Build context.

6. Leave a note

  1. Open your site at an address on the list.
  2. Select the Gutternote button in the corner of the page.
  3. Select the element you want to comment on.
  4. Sign in or enter a name, if the widget asks.
  5. Write the note and send it.

7. Check the install

Open Install and select Check again. It shows Installed once the widget has reached Gutternote from your site. Detection can take up to two minutes. If it still says Not installed yet, see The widget does not appear.

Or let your coding agent do it

Claude Code can do the steps above in your repository. Run the installer from the repository of your site:

Terminal window
curl -fsSL https://gutternote.com/install.sh | sh

Then start Claude Code in the same folder and run:

/gutternote:set-up

The agent adds the script tag and the build tags, and asks which environments should load the widget. It can’t save a site address on its own. When it asks, a project owner opens the link it gives and selects Allow origin. Review the diff before you commit.

Next steps

  • Connect GitHub to see notes on the pull request.
  • If the GitHub App is available on the deployment, a new project can save the GitHub feedback and agent-push settings off before connecting.
  • Set up agents to send notes to a coding agent.