Getting started

Set up Passback with your agent

Your coding agent can set Passback up for you. Open Claude Code, Codex or Cursor in your project and paste this prompt:

Set up Passback for local development in this repo.
Detect from the repository whether it uses Vite or Next.
If it is Vite, add passback and @passback/vite-plugin as dev dependencies.
If it is Next, add passback and @passback/next as dev dependencies.
Run npx passback init --apply.
Report the next steps it prints.

The agent runs the steps below. You can run them yourself just as well.

Before you start

A project that runs on Vite 7 or 8, or on Next.js 15.3 or 16 with the App Router.
Node 22 or later.
Claude Code, Codex or Cursor, opened in the project.

What the agent does

It detects the framework from the repository and adds the matching packages. For Vite:
```
npm i -D passback @passback/vite-plugin
```
For Next:
```
npm i -D passback @passback/next
```
It runs init with --apply in the project folder:
```
npx passback init --apply
```
Init sets the project up:
- In Vite it adds passback() and its import to the plugins of your Vite config. In Next it wraps your Next config in withPassback(…), adds the route under app/api/passback, and adds <Passback /> to your root layout. If it cannot edit a file safely, it leaves the file as it is and prints the lines to add by hand. Applying a plan does not guarantee that an unsupported config or layout can be rewritten.
- By default, init sets up only the agents detected in your repository; if none are detected, it sets up Claude Code. Explicit agent names override detection: the agent runs npx passback init --agents claude --apply (or codex, cursor, several joined by commas). npx passback init --agents all --apply restores the previous behavior of setting up Claude Code, Codex and Cursor regardless of existing folders.
- It adds a short Passback block to AGENTS.md, creates .passback/inbox and .passback/outbox, and adds .passback/ to .gitignore.
- If .mcp.json, .cursor/mcp.json or the Passback block in AGENTS.md is broken, it leaves that file as it is and prints what to fix. Repair it, then run applied init again.
Init ends with one start hint for each agent it wired, in the order of the selection, followed by one line for other agents. They are your part. With the default three agents they read:
```
Claude Code: Restart Claude Code in the project, approve the passback server in /mcp, then type /passback.
Codex: Restart Codex in the project, approve project trust if prompted, then type $passback.
Cursor: Restart Cursor in the project, enable passback in Settings > MCP and approve any connection prompt, then type /passback.
Other agents: Add the MCP server npx passback dev, then ask your agent to call passback_wait.
```
Init prints only the hints of the agents it wired. The last line is always there, for an agent init does not set up. If files are still only planned, init prints just the line that tells you to run npx passback init --apply, and no start hints.

Plan and apply

Init installs no dependencies. Bare npx passback init only plans: on a fresh project it creates .passback/inbox and .passback/outbox, updates .gitignore, and prints the remaining proposed writes as "not written (add --apply to write it)". A plugin configuration that is already wired can still be updated without --apply, so this is not a side-effect-free preview. --apply writes the full list below.

Your part

Restart your agent in the project, as the hint for your agent says, so it loads the Passback server.
Then approve the passback server the way the hint says: /mcp in Claude Code, project trust in Codex, Settings > MCP in Cursor.
Start your dev server, open your site, and type /passback in Claude Code or Cursor, $passback in Codex. The agent waits for your first comment.
If your agent is not one init sets up, follow the last line: add the MCP server npx passback dev in your agent's MCP configuration, then ask it to call passback_wait.

Running init again is safe: it leaves what is already set up as it is. The page Your first comment shows what to do next.

Hosted: comments from staging to your tracker

On a staging or preview site, comments go to Linear, Plane, GitHub, Azure DevOps, GitLab, Trello, Notion, Asana, Jira or ClickUp instead of to your agent. Paste this prompt:

Set up Passback hosted for this repo.
File comments to Linear.

The agent runs three commands in the project folder:

It signs you in. The command prints a short code and opens your browser; click Approve. Your first sign-in creates your account. The sign-in is kept in your user config folder, never in the project.
```
npx passback login
```
It creates the site for this repository and writes the site key, the endpoint and one mode line into the passback() options of your Vite config, or into the Passback tag of your Next root layout.
```
npx passback init --site --apply
```
The mode line looks like this, in Vite and in Next. The snippets show the options as they stand after init:
```
passback({
  mode: process.env.NODE_ENV === 'production' ? 'relay' : 'agent',
  siteKey: '…',
  endpoint: '…',
});
```
```
<Passback
  mode={process.env.NODE_ENV === 'production' ? 'relay' : 'agent'}
  siteKey="…"
  endpoint="…"
/>
```
Comments go to your agent while you develop and to your tracker from deployed builds. Change the mode line to choose: 'agent' sends comments to your coding agent, 'relay' to your tracker, 'off' shows no widget.
It connects the tracker. The command opens your browser, where you approve Passback in Linear (for Jira, you approve Passback in Atlassian; for GitHub, you install the Passback GitHub App on the repository). It then files a test comment and says where comments go. Plane and Azure DevOps need a token you give it; the page Connect a tracker says where Plane and Azure DevOps keep it. Trello needs two pasted values, an API key and a token, from Trello; the same page says where to find them.
```
npx passback connect linear
```

Your part is the approvals in the browser. Comments are accepted only from the site's allowed origins; check them in the dashboard under Install. To remove the site with its key and its tracker connection, run npx passback site delete <name> with the site name; it asks you to type the name again to confirm.

Next: Install with Vite + React