# Chrome extension The Chrome extension puts ShappyChat in the Chrome side panel. The chat can read the page in the current tab and act on it. ## Install the extension The extension needs Chrome 141 or newer. It is not in the Chrome Web Store. Download `shappychat-extension-.zip` from the release. Unzip the file and go to step 1. Or, build the extension from the source checkout: ```bash node scripts/build.mjs ``` 1. In Chrome, open `chrome://extensions`. 2. Turn on **Developer mode**. 3. Click **Load unpacked**. Select the unzipped folder, or the `dist/` folder of the checkout. 4. Click **Details** on the ShappyChat extension. 5. Turn on **Allow user scripts**. The chat cannot act on pages without this permission. 6. Optional: turn on **Allow access to file URLs**. ## Sign in When you open the extension for the first time, it shows **Sign in to ShappyChat**. Choose where your chats are kept. | Choice | Models and history | Setup | | --- | --- | --- | | Use in this browser (default) | This browser keeps the chats (IndexedDB). You do not need a server. | Sign in to an AI provider. | | Connect to a backend | Shappy Backend keeps the models and the conversation history. | Connect the extension to a running backend. | You can change the choice later in **Settings**. Each choice keeps its own chat history. A change does not move or delete chats. ### Use in this browser Select one of these options: - **Continue with Claude** or **Continue with ChatGPT**: sign in with your account in the provider's sign-in window. - **API key**: paste a Claude (`sk-ant-`), OpenAI (`sk-`) or Gemini (`AIza`) key. - **Local model**: the extension finds LM Studio on port 1234 or Ollama on port 11434 on your computer. Load a chat model first. The sign-in details and the chats stay in this browser. To remove the sign-in, open **Settings** and click **Sign out**. Your chats stay. ### Connect to Shappy Backend 1. Start Shappy Backend and configure a model. See [Shappy Backend](/docs/backend). 2. On the sign-in page, click **Connect to a backend**. The form shows the extension origin, for example `chrome-extension://`. 3. In the backend, open **Connected apps**. Add an app with this exact origin. 4. Grant the MCP connections that the chat needs. Grant host UI permission if the chat must act on pages. 5. Copy the app credential. In the extension, enter the backend URL and the credential. The extension keeps the credential and the current conversation in extension storage. ## Choose the page that the chat uses The page control above the message field has three options: | Option | Behaviour | | --- | --- | | Current browser tab (default) | Before each message, the chat finds the active tab. It sends the page title and URL to the model as context. | | Pinned page | The chat always uses the page that you select. | | Chat only | The chat does not read or change any tab. | When a reply starts, the chat stays on its page until the reply is complete. If you change tabs during a reply, the work does not move to the new tab. ## Choose the chat appearance Open the appearance menu in the chat header. | Appearance | Description | | --- | --- | | Side panel | The chat is beside the current website. | | Floating | A compact chat window over the website. | | Touch Island (default) | A message bar on the website with a conversation that you can expand. | To close the Touch Island, click a different area of the website. The island becomes a faint ghost. To open it again, click the ghost. Your unsent text stays when you change the appearance. Floating and Touch Island chats stay on the tab when you go to another page, open or closed as before. ### Attach files Use the paperclip, paste an image or drop files on the message field. If the model can read images, the extension sends the images. For other models, attach documents, for example PDF, Word, PowerPoint, Excel or text files. The extension sends these documents as text. If you connected LM Studio or Ollama before this version, sign out. Then choose **Local model** again. Vision models then accept images. ## Keyboard - **Command + Shift + K** (macOS) or **Ctrl + Shift + K** opens the chat and puts the cursor in the message field. It works on any website. Command or Ctrl + K stays free for the website. - **Command + Shift + S** (macOS) or **Ctrl + Shift + S** opens or closes the side panel. - To change the key, open `chrome://extensions/shortcuts`. ## Permissions and data The extension asks for these Chrome permissions: - storage and unlimited storage - active tab, scripting and user scripts - side panel - declarative net request - access to http and https sites The browser tools use these permissions. - Page content that the chat reads goes to the model provider that you configured. - When you use the extension in this browser, the history stays in this browser. - When you connect to a backend, the backend keeps the conversation history. - A connection to an MCP server does not copy the extension history to that app. ## Limits - The chat can run browser JavaScript and use tagged page controls. - The chat can call MCP tools. With a backend, it uses the tools that the backend grants. In this browser only, it uses the MCP connections of the classic extension. - **Stop** cancels the reply. Stop cannot undo a script that already ran.