Getting started

Install with Astro

Passback adds a small button to your site while you develop. Click it, click anything on the page, and write what should change. The comment goes to the coding agent you already have open.

Before you start

• An Astro project.
• Node 22 or later.
• One of Claude Code, Codex or Cursor, opened in the project.

Install

1. In your project folder, add the two packages:

   npm i -D passback @passback/vite-plugin

   Copy

2. Set the project up:

   npx passback init --apply

   Copy
   • Init does: detects that this is an Astro project, safely edits a recognised Vite config to add the plugin, and prints the Astro head instructions below. It installs no packages and never edits your layout.
   • You do: find the layout that renders your <head> (for example src/layouts/Layout.astro), apply the printed instructions to its frontmatter and head while keeping everything it already has, and restart your dev server.

   .: manually edit your layout's <head> (for example src/layouts/Layout.astro); pages show the widget only after this helper call.
   .: import { passbackHeadHtml } from '@passback/vite-plugin/head' in the frontmatter; add <Fragment set:html={passbackHeadHtml()} /> inside <head>.

   Copy

3. Add the plugin to astro.config.mjs yourself. Init only recognises vite.config files, so it does not edit this file. Put passback() under vite.plugins:

   // astro.config.mjs
   import { defineConfig } from 'astro/config';
   import passback from '@passback/vite-plugin';
   
   export default defineConfig({
     vite: {
       plugins: [passback()],
     },
   });

   Copy

   If your config already has a vite block, add passback() to its plugins list.

4. Add the helper to the layout that renders your <head>. Merge the import into the layout's existing frontmatter and the fragment into its existing head, and keep everything else the layout has:

   ---
   import { passbackHeadHtml } from '@passback/vite-plugin/head';
   ---
   
   <head>
     <Fragment set:html={passbackHeadHtml()} />
   </head>

   Copy

5. Start your dev server as usual, or restart it if it was running. The Passback button appears in the bottom right corner.

6. Restart your agent in the project and approve the passback server when it asks. Then start a session: type /passback in Claude Code or Cursor, $passback in Codex. The agent waits for your first comment.

What a comment carries

• The element you marked, your note and the page it was on.
• No Astro component names, source files or line numbers.

Compare frameworks in What a comment carries.

Comments from a build

In development a comment goes to the coding agent. In a staging build configured with mode: 'relay', a siteKey, an endpoint and stagingModes, comments go to the hosted relay:

passback({
  mode: 'relay',
  siteKey: '…',
  endpoint: '…',
  stagingModes: ['staging'],
});

Production builds outside stagingModes ship nothing because the helper returns nothing. The tags the helper writes follow the plugin's widget and screenshot settings. For the options, see Install with Vite.

Without the plugin, see Where the tag goes in your framework.

Next: Install with Nuxt