# Optional AI text suggestions

Patchpin works without AI. To generate text alternatives inside the editor:

1. Install Node.js 22.22.2 or newer and a current supported CLI. Sign into it normally: `codex login`, `claude auth login`, or `agent login` for Cursor.
2. Download `patchpin-companion.mjs` alongside the Chrome release ZIP. From source, use `scripts/patchpin-companion.mjs` instead.
3. Open Patchpin Settings. Choose Codex, Claude Code, or Cursor CLI, and copy the companion command. Run it from the folder containing the downloaded companion. From source: `node scripts/patchpin-companion.mjs --extension YOUR_CHROME_EXTENSION_ID --provider codex`.
4. Leave that terminal open. Paste its pairing code in Settings and click Connect AI tool. Allow the requested local connection permission.
5. On a website, select a text element, enter an optional rewrite direction, then Suggest replacements. Use an option to preview it. Click Add change to save.

The companion listens only on `127.0.0.1:43187`, requires a fresh random pairing code, checks extension origins, and accepts only bounded text-rewrite requests. Restarting changes the code; reconnect in Settings. Disconnect revokes the extension’s local permission. Stop the companion with Ctrl+C.

Your chosen provider still processes the text and its normal usage limits apply. This is not an offline language model. ChatGPT account use is through the signed-in Codex CLI; Patchpin does not automate the ChatGPT or Claude desktop app. No account session or provider API key is copied into the extension. The companion runs each rewrite in an empty temporary folder and requests no source-code changes.

Use current CLIs: Codex needs `exec --ignore-user-config --ignore-rules --ephemeral` and the shell-tool feature switch; Claude Code needs `--safe-mode`, `--tools`, and `--no-session-persistence`; Cursor uses its `agent` CLI with ask mode, sandboxing and project deny rules. Older versions fail with an actionable message rather than falling back to broader permissions.

The companion adapters and extension flow are covered by automated tests with deterministic responses. Codex/Claude/Cursor availability and account authorization depend on the user’s own installation. If generation fails, confirm the CLI is installed and signed in, update it, restart the companion, and reconnect. Port already in use means another companion is running.

Prompt handoff also offers Open prompt in Cursor through its documented desktop link. Links over 10,000 encoded characters fall back to copying/exporting. Screenshots remain ZIP attachments.

Primary references: [Codex non-interactive mode](https://learn.chatgpt.com/docs/non-interactive-mode), [Claude CLI reference](https://code.claude.com/docs/en/cli-reference), [Cursor parameters](https://cursor.com/docs/cli/reference/parameters), [Cursor permissions](https://cursor.com/docs/cli/reference/permissions), [Cursor prompt links](https://cursor.com/docs/reference/deeplinks).

## Connection recovery

If Patchpin reports a different installation or “Extension origin rejected”, stop the companion with Ctrl+C and copy its command from the Settings page of the extension you are currently using. Run that exact command and paste its fresh pairing code. Unpacked folders and Chrome profiles can have different extension IDs. Version 0.2.1 verifies the installation during pairing and provides persistent repair steps in the editor. Update both the extension and `patchpin-companion.mjs`; old companions need replacement. Settings → Check connection tests the running companion without sending any text to AI.

## Agent inbox (MCP)

The same companion lets coding agents pick up your changes without copy and paste.

1. Start and pair the companion as above.
2. Add Patchpin to your agent once:
   - Claude Code: `claude mcp add --transport http patchpin http://127.0.0.1:43187/mcp`
   - Cursor, in `~/.cursor/mcp.json`: `{"mcpServers":{"patchpin":{"url":"http://127.0.0.1:43187/mcp"}}}`
   - Codex, in `~/.codex/config.toml`: `[mcp_servers.patchpin]` then `url = "http://127.0.0.1:43187/mcp"`
3. Turn on “Share change sets with the agent inbox” in Settings, or click “Send changes to your agent inbox” in the composer.
4. Ask your agent: “Watch Patchpin and implement changes as they arrive.”

Tools: `patchpin_list_changes` (open changes on every shared page, optionally filtered by URL), `patchpin_watch` (waits for new or updated changes and returns a cursor to continue), `patchpin_get_screenshot` (returns an image by ID), and `patchpin_resolve` (marks changes done with a summary; their pins turn green in the browser). The MCP endpoint needs no token because it only accepts local, non-browser requests: requests carrying browser `Origin` or `Sec-Fetch-Site` headers and non-local `Host` headers are refused.